curl -X POST https://api.tracklysms.com/api/v1/voice/calls \
-H "X-Api-Key: trk_your_api_key_here" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: 8f2c1a9e-4b7d-4c3a-9e21-3f0a1b2c3d4e" \
-d '{
"to": "+14155551234",
"from": "+18005551234",
"connectTo": "+14155559876",
"record": true,
"customData": { "caseId": "abc-123" }
}'
{
"call": {
"id": "665f1e2a9c4b1a0012ab34cd",
"direction": "outbound",
"state": "calling",
"legKind": "primary",
"from": "+18005551234",
"to": "+14155551234",
"connectTo": "+14155559876",
"queueId": null,
"conferenceId": null,
"parentCallId": null,
"bridgedCallId": null,
"monitorRole": null,
"record": true,
"recordingState": "requested",
"recordingFileIds": [],
"customData": { "caseId": "abc-123" },
"error": null,
"startedAt": "2026-08-21T18:00:00.000000Z",
"answeredAt": null,
"endedAt": null,
"createdAt": "2026-08-21T18:00:00.000000Z"
}
}
Voice Calls (v1)
Place a Call
Place an outbound programmable voice call, optionally bridging to an agent on answer.
POST
/
v1
/
voice
/
calls
curl -X POST https://api.tracklysms.com/api/v1/voice/calls \
-H "X-Api-Key: trk_your_api_key_here" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: 8f2c1a9e-4b7d-4c3a-9e21-3f0a1b2c3d4e" \
-d '{
"to": "+14155551234",
"from": "+18005551234",
"connectTo": "+14155559876",
"record": true,
"customData": { "caseId": "abc-123" }
}'
{
"call": {
"id": "665f1e2a9c4b1a0012ab34cd",
"direction": "outbound",
"state": "calling",
"legKind": "primary",
"from": "+18005551234",
"to": "+14155551234",
"connectTo": "+14155559876",
"queueId": null,
"conferenceId": null,
"parentCallId": null,
"bridgedCallId": null,
"monitorRole": null,
"record": true,
"recordingState": "requested",
"recordingFileIds": [],
"customData": { "caseId": "abc-123" },
"error": null,
"startedAt": "2026-08-21T18:00:00.000000Z",
"answeredAt": null,
"endedAt": null,
"createdAt": "2026-08-21T18:00:00.000000Z"
}
}
Places an outbound call from one of your assigned numbers to a destination. When
connectTo is supplied, the destination and the connect target are bridged into a conference once the call is answered.
Requires the voice_calls.write scope and the Voice Calls product entitlement.
Body Parameters
string
required
Destination phone number in E.164 format (e.g.
+14155551234).string
required
The calling number in E.164 format. Must be a number that has been assigned to your account.
string
A number to bridge the call to once it is answered. Accepts either an E.164 number or the
id of a voice agent. The resolved destination is screened against your account’s compliance suppression (DNC, opt-out, quiet hours) before dialing.boolean
default:false
Whether to record the call from the moment it is answered. Recording may require caller consent — see call recording.
object
Arbitrary key/value metadata echoed back on the call object and forwarded to the provider. Values must be JSON-serializable.
Headers
string
A unique key to make the request idempotent. A retry with the same key returns the original call instead of placing a second one.
Response Fields
object
The created call.
Hide Call properties
Hide Call properties
string
The call’s unique identifier.
string
outbound for calls placed through this endpoint.string
Lifecycle state. A freshly placed call starts as
calling. See Call states.string
primary, bridge, or monitor. Calls placed here are primary.string
The calling number.
string
The destination number.
string | null
The resolved bridge target, if any.
string | null
The queue this call is parked in, if any.
string | null
The provider conference id once a bridge or monitor leg is attached.
string | null
For a bridge/monitor leg, the primary call it belongs to.
string | null
For a primary call, the currently bridged agent leg.
string | null
MONITOR or ADVISOR for a monitor leg.boolean
Whether recording was requested.
string | null
requested, started, stopped, ready, failed, or deleted.array
Provider file ids for completed recordings.
object
The metadata you supplied.
string | null
A machine-readable reason when the call failed.
string | null
ISO 8601 timestamp when the call was placed.
string | null
ISO 8601 timestamp when the call was answered.
string | null
ISO 8601 timestamp when the call ended.
string | null
ISO 8601 timestamp when the record was created.
Examples
curl -X POST https://api.tracklysms.com/api/v1/voice/calls \
-H "X-Api-Key: trk_your_api_key_here" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: 8f2c1a9e-4b7d-4c3a-9e21-3f0a1b2c3d4e" \
-d '{
"to": "+14155551234",
"from": "+18005551234",
"connectTo": "+14155559876",
"record": true,
"customData": { "caseId": "abc-123" }
}'
{
"call": {
"id": "665f1e2a9c4b1a0012ab34cd",
"direction": "outbound",
"state": "calling",
"legKind": "primary",
"from": "+18005551234",
"to": "+14155551234",
"connectTo": "+14155559876",
"queueId": null,
"conferenceId": null,
"parentCallId": null,
"bridgedCallId": null,
"monitorRole": null,
"record": true,
"recordingState": "requested",
"recordingFileIds": [],
"customData": { "caseId": "abc-123" },
"error": null,
"startedAt": "2026-08-21T18:00:00.000000Z",
"answeredAt": null,
"endedAt": null,
"createdAt": "2026-08-21T18:00:00.000000Z"
}
}
Error Codes
| Status | Code | Meaning |
|---|---|---|
| 403 | voice_not_entitled | Voice calling is not enabled for your account. |
| 403 | compliance_dnc / compliance_opted_out / compliance_suppressed / compliance_quiet_hours | The destination is blocked by a compliance rule. |
| 422 | from_not_owned | from is not a number assigned to your account. |
| 422 | missing_fields | A required field (to or from) is missing. |
| 422 | invalid_number | to or connectTo is not a valid E.164 number. |
| 404 | agent_not_found | connectTo is an agent id that does not exist. |
| 429 | concurrency_limit | Your account has too many concurrent calls in progress. |
| 502 | provider_error | The upstream telephony provider rejected the request. |