Virtual numbers

A virtual number is a Saudi DID assigned to one of your end-users. When someone dials it, Wave answers and plays that user’s standing instructions — a gate code, delivery notes, a greeting — or forwards the call to their real number without revealing it. Your user never has to publish their personal number.

Virtual numbers use a production API key (sk_live_) and the virtual_numbers:write / virtual_numbers:read scopes. Ask your Wave contact to enable the feature for your account.

Allocate a number to a user

POST /v1/virtual-numbers. Identify the end-user with your own id (external_user_id) — the call is idempotent on it, so a retry returns the same number rather than allocating a second one.

curl -X POST https://api.wave.sa/v1/virtual-numbers \
  -H "Authorization: Bearer sk_live_xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "external_user_id": "user_8842",
    "display_name": "Layla",
    "instructions": {
      "text": "Please leave the parcel at the door. Gate code 4471.",
      "language": "ar",
      "forward_to": "+966541704013"
    }
  }'

const res = await fetch("https://api.wave.sa/v1/virtual-numbers", {
  method: "POST",
  headers: {
    Authorization: "Bearer sk_live_xxxxxxxxxxxx",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    external_user_id: "user_8842",
    display_name: "Layla",
    instructions: {
      text: "Please leave the parcel at the door. Gate code 4471.",
      language: "ar",
      forward_to: "+966541704013",
    },
  }),
});
const { data } = await res.json();

Request

Field	Type	Required	Notes
`external_user_id`	string	yes	Your id for the user (≤128 chars). The idempotency key.
`display_name`	string	no	≤120 chars.
`type`	string	no	`mobile`, `landline`, `tollfree`, `unified`, `shortcode`.
`prefix`	string	no	Preferred numeric prefix.
`instructions.text`	string	no	Spoken to the caller (≤1000 chars).
`instructions.audio_url`	string (URL)	no	Played instead of `text` when set.
`instructions.language`	string	no	`ar` or `en`.
`instructions.forward_to`	string	no	KSA number to bridge to, with the caller’s id presented.

Response — `201 Created` (or `200 OK` on an idempotent retry)

{
  "data": {
    "id": "8f2c…",
    "e164": "+966590007001",
    "status": "assigned",
    "external_user_id": "user_8842",
    "display_name": "Layla",
    "contact_id": "1a9b…",
    "instructions": {
      "text": "Please leave the parcel at the door. Gate code 4471.",
      "audio_url": null,
      "language": "ar",
      "forward_to": "+966541704013"
    },
    "assigned_at": "2026-08-19T10:00:00.000Z"
  }
}

A recorded audio_url plays instantly; text goes through text-to-speech. Set both and the audio wins — so you can start with text today and upgrade to a recording later with no code change.

Update a user’s instructions

PUT /v1/virtual-numbers/:id/instructions — edited in place, no re-allocation.

cURL

curl -X PUT https://api.wave.sa/v1/virtual-numbers/8f2c…/instructions \
  -H "Authorization: Bearer sk_live_xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{ "text": "I have moved. Please call when you arrive.", "language": "en" }'

List & look up

GET /v1/virtual-numbers — filter by external_user_id, page with limit (≤100) and offset. GET /v1/virtual-numbers/:id returns one.

{
  "data": [ { "id": "8f2c…", "e164": "+966590007001", "external_user_id": "user_8842", "…": "…" } ],
  "meta": { "limit": 50, "offset": 0 }
}

Release a number

DELETE /v1/virtual-numbers/:id returns the DID to the pool and frees the user to be assigned a different one later.

{ "id": "8f2c…", "status": "released" }

Instructions are your end-users’ personal data — a gate code, an address, a real phone number. Wave never logs their content. Treat the numbers and instructions you store with the same care.

Get Started

Voice

Web Callback

Reference

Allocate a number to a user

Request

Response — `201 Created` (or `200 OK` on an idempotent retry)

Update a user’s instructions

List & look up

Release a number

Next steps

How voice works

Webhooks

​Allocate a number to a user

​Request

​Response — 201 Created (or 200 OK on an idempotent retry)

​Update a user’s instructions

​List & look up

​Release a number

​Next steps

How voice works

Webhooks

Allocate a number to a user

Request

Response — `201 Created` (or `200 OK` on an idempotent retry)

Update a user’s instructions

List & look up

Release a number

Next steps