Speko Docs
API Reference

Create phone session

POST /v1/sessions/phone — place an outbound PSTN call backed by a Speko voice session.

POST
/v1/sessions/phone

Authorization

bearerAuth
AuthorizationBearer <token>

In: header

Header Parameters

Idempotency-Key?string

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.

Length1 <= length <= 256

Request 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"
}