Masked numbers (DIDs)

A DID is a phone number from CloudTalk Networks' inventory that we expose to your end users in place of their real numbers. Tenants in the industry also call these "masked numbers" or "proxy numbers".

How the pool works

Each tenant has an inventory of DIDs allocated to them.

flowchart LR
    P[(Tenant DID pool)] -->|on session open| A[Assigned to session]
    A -->|session ends| P
    A -->|TTL expires| P

When you create a session, we pick a free DID from your pool. When the session ends — either you call complete or TTL expires — the DID returns to the pool, available for the next pairing.

Listing your assigned numbers

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

By default this returns only active DIDs — your current usable inventory.

If you want to see numbers that were previously assigned to you but have been returned to the pool (audit/billing history), pass an explicit filter:

# History only
curl 'https://api.cloudtalknet.com/v1/did/assignments?status=released' \
  -H "X-API-Key: $CLOUDTALK_API_KEY"

# Everything (active + released + suspended)
curl 'https://api.cloudtalknet.com/v1/did/assignments?status=all' \
  -H "X-API-Key: $CLOUDTALK_API_KEY"

A released assignment is not removed from history — we keep it so you can reconcile billing periods and prove which numbers belonged to you on any given date. It just won't appear in your day-to-day inventory view.

Picking a specific number for a session

By default we choose any free DID from your pool. If you want a particular number — for example, a known number for a regular driver or agent — pass masked_e164 to POST /v1/sessions:

{
  "driver_phone": "+2348011112222",
  "customer_phone": "+2349033334444",
  "ttl_minutes": 60,
  "masked_e164": "+2347000111222"
}

The request will succeed only if that number:

Exists in your tenant's pool, and
Has no other open session at that moment.

Otherwise we return 409 Conflict so you can either retry without the override (we'll auto-pick a free number) or surface the collision to your application.

Capacity planning

If your pool runs low, sessions can fail with 409 indicating no available DID. Reach out to provision more numbers — we typically allocate based on:

Peak concurrent sessions per hour
Average session length
Geographic coverage you need

A common rule of thumb: pool size ≈ 1.5 × peak concurrent sessions.