Calls

Start a callCopy Anchor Link

Copy an agent ID from the dashboard and choose an active phone number belonging to the workspace. fromNumber and toNumber must be E.164 numbers. The calling agent must belong to the same workspace. Existing plan, credit and simultaneous-call limits apply.

curl -X POST "https://api.usevoicelink.co/v0/calls/outbound" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"agentId":"11111111-1111-4111-8111-111111111111","fromNumber":"+14165550100","toNumber":"+14165550101","context":"Follow up on the appointment request."}'

For an immediate call, a 201 response means the provider accepted submission. It does not mean the destination answered. Save data.call.id and poll GET /v0/calls/{id} for status.

Schedule a callCopy Anchor Link

Include scheduledAt in the outbound request to schedule a one-time agent call. Use a future ISO 8601 timestamp with Z (UTC) or a timezone offset, for example 2030-01-15T10:30:00+01:00. Omit this field to call immediately.

curl -X POST "https://api.usevoicelink.co/v0/calls/outbound" \
  -H "apikey: YOUR_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"agentId":"11111111-1111-4111-8111-111111111111","fromNumber":"+14165550100","toNumber":"+14165550101","scheduledAt":"2030-01-15T10:30:00+01:00"}'

The response returns 201 with data.call.status set to scheduled, scheduledAt normalized to UTC, and startedAt: null. Save the call ID and poll its status as usual. Scheduling reserves the call, without starting it or reserving live-call capacity. Start times are best effort and may be delayed.

When the call is due, your workspace membership, plan, credit balance, agent, calling number and available capacity are checked again. A blocked call becomes failed; it is not automatically retried. To try again, create another outbound call.

To move a waiting call, send PATCH /v0/calls/CALL_ID/schedule with a JSON body containing the new scheduledAt. To cancel it, send DELETE /v0/calls/CALL_ID/schedule. Both return the updated call in data.call; cancellation sets its status to cancelled. Only calls still in the scheduled state can be changed; otherwise these endpoints return 409.

In the dashboard, choose Schedule for later when placing an agent call. Dates use the timezone shown beside the input. Open the scheduled call to reschedule or cancel it.

Call data and transcriptCopy Anchor Link

Each call includes its ID, status, caller details, duration, timestamps, summary, next steps and transcript. Transcript entries contain role, text and a timestamp in Unix milliseconds.

List calls with limit (default 50, max 200) and offset (default 0). Responses include calls, total, limit and offset; ordering is newest creation first, then descending ID. Offset pages can move when new calls arrive. Status filters include scheduled, cancelled, in-progress (pending or active), completed, and failed; the call itself retains its stored status.

Terminate a callCopy Anchor Link

Stop a pending or active call:

curl -X POST "https://api.usevoicelink.co/v0/calls/CALL_ID/terminate" \
  -H "apikey: YOUR_API_KEY"

The response contains the updated call in data.call. Terminated calls have status: "failed" and endReason: "killed". Calls that have already ended return 409.

RecordingsCopy Anchor Link

Replace CALL_ID with the ID of the completed call.

curl "https://api.usevoicelink.co/v0/calls/CALL_ID/recording" \
  -H "apikey: YOUR_API_KEY"

The call must be completed, otherwise the endpoint returns 409. data.url is a signed recording link or null when no recording is available, including while export finishes. If tracks is returned, synchronize its user, agent and optional human recordings on the same timeline to hear the full conversation. Links expire; request new links from this endpoint when necessary.