Create phone session
POST /v1/sessions/phone — place an outbound PSTN call backed by a Speko voice session.
Authorization
bearerAuth In: header
Header Parameters
Makes a retry safe. A repeat of the same request with the same key, from the same organization and credential within 24 hours, returns the first call's response (with X-Idempotent-Replay: true) and places no second call. While the first request is still running, a repeat gets 409 IDEMPOTENCY_KEY_IN_PROGRESS; retry shortly. A different body under a used key gets 409 IDEMPOTENCY_KEY_REUSED. A 4xx response frees its key, so a corrected retry can reuse it. If the first request ended in a 5xx or never finished, the key answers 409 IDEMPOTENCY_KEY_OUTCOME_UNKNOWN: check GET /v1/sessions before dialing again with a new key. Without the header, every request places a call.
1 <= length <= 256Request Body
application/json
TypeScript Definitions
Use the request body type in TypeScript.
Response Body
application/json
application/json
application/json
application/json
application/json
application/json
application/json
application/json
application/json
application/json
application/json
{
"sessionId": "string",
"callControlId": "string",
"roomName": "string",
"status": "dialing",
"to": "+12015551234",
"from": "+12015551234",
"freeCall": {
"maxDurationSeconds": 120
}
}{
"error": "Invalid request",
"code": "VALIDATION_ERROR",
"issues": [
{
"path": "to",
"message": "Required"
}
]
}{
"error": "Unauthorized",
"code": "UNAUTHORIZED"
}{
"error": "Insufficient credit balance for this call. Calls cost $0.10/min. Add credits or turn on auto top-up.",
"code": "INSUFFICIENT_CREDITS"
}{
"error": "Calls to +53 (Cuba) are not allowed: the destination is under sanctions.",
"code": "DESTINATION_NOT_ALLOWED"
}{
"error": "string",
"code": "string",
"retryable": true,
"docs_url": "http://example.com",
"hint": "string",
"issues": [
{
"path": "string",
"message": "string"
}
]
}{
"error": "A call from this workspace to this number is already being placed. Wait for it to finish before you try again.",
"code": "CALL_ALREADY_DIALING"
}{
"error": "no_capable_provider",
"code": "NO_CAPABLE_PROVIDER",
"param": "tts"
}{
"error": "This workspace started 60 outbound calls in the last minute, the most it may start per minute. No call was placed. Retry in 12 seconds, or contact support to raise the limit.",
"code": "OUTBOUND_RATE_LIMITED",
"scope": "per_minute",
"limit": 60,
"retryAfterSeconds": 12
}{
"error": "LiveKit SIP outbound dial failed",
"code": "LIVEKIT_SIP_DIAL_FAILED"
}{
"error": "Phone number provisioning is temporarily unavailable.",
"code": "PHONE_NUMBER_PROVISIONING_PENDING"
}