Quickstart

Open your first masked session in five minutes.

1. Get an API key

Ask your CloudTalk Networks contact for an X-API-Key scoped to your tenant. Keep it server-side only — never ship it to a browser, mobile app, or public client.

2. Create a session

Tell us the two real phone numbers and how long the session should live.

curl -X POST https://api.cloudtalknet.com/v1/sessions \
  -H "Content-Type: application/json" \
  -H "X-API-Key: $CLOUDTALK_API_KEY" \
  -d '{
    "order_id": "ord_001",
    "driver_phone": "+2348011112222",
    "customer_phone": "+2349033334444",
    "ttl_minutes": 60
  }'

You'll get back something like:

{
  "session_id": "ses_2YqkX...",
  "masked_e164": "+2347000111222",
  "expires_at": "2026-05-08T09:10:00Z"
}

Hand masked_e164 to either party. When they dial it, we route the call to the other side.

3. (Optional) originate the call from your platform

If you want to initiate the call from your side instead of waiting for one of the parties to dial:

curl -X POST https://api.cloudtalknet.com/v1/calls/originate \
  -H "Content-Type: application/json" \
  -H "X-API-Key: $CLOUDTALK_API_KEY" \
  -d '{
    "session_id": "ses_2YqkX...",
    "callee_id": "+2349033334444"
  }'

4. Close the session when done

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

You can also just let the TTL expire — we'll release the masked number automatically.

What just happened

sequenceDiagram
    participant You as Your Backend
    participant CTN as CloudTalk Networks
    You->>CTN: POST /v1/sessions
    CTN-->>You: masked_e164, session_id, expires_at
    Note over You: Show masked_e164 to Customer & Driver
    You->>CTN: POST /v1/sessions/{ref}/complete (or wait for TTL)
    CTN-->>You: 200 OK