Sessions

A session is a time-bound pairing between two real phone numbers, exposed via a single masked number.

Lifecycle

stateDiagram-v2
    [*] --> Open: POST /v1/sessions
    Open --> Active: party dials masked
    Active --> Open: call ends (session still alive)
    Open --> Completed: TTL expires
    Open --> Completed: tenant closes
    Active --> Completed: TTL expires mid-call
    Completed --> [*]: masked number returned to pool

Choosing a TTL

You decide how long a session is valid via the ttl_minutes field. Common patterns:

If you omit ttl_minutes, we apply your tenant's default. Hard cap is whatever your account is provisioned for (typically 240 minutes / 4 hours per session) — let us know if you need something longer.

Routing while open

While a session is open, the masked number routes calls between the two parties:

• Inbound — either party dials the masked number; we bridge to the other
• Outbound — your platform calls POST /v1/calls/originate and we ring both legs

The same physical masked number can be reused across non-overlapping sessions over time. Within an active session, the number is exclusive to that pairing — there is no number reuse for as long as the session is live.

Closing a session early

Use POST /v1/sessions/{ref}/complete to release the masked number before TTL expiry — useful when an order is cancelled or fulfilled early, or when you want the number freed for the next pairing.

Concurrency

You can have many sessions open at the same time. Each one uses a different masked number from your tenant's pool, so concurrent calls don't collide. Active-session routing keeps inbound calls correctly directed even if the same masked number was used for a different pairing yesterday.

Inspecting a session

curl https://api.cloudtalknet.com/v1/sessions/ses_2YqkX... \
  -H "X-API-Key: $CLOUDTALK_API_KEY"

The response includes the session's state, masked number, both leg identifiers, and timestamps. See the API reference for the full schema.