Quickstart

1. Get a sandbox API key

Sign up at wave.sa and complete Nafath identity verification.
Log in to the dashboard and open API Keys.
Copy your sandbox key — it starts with sk_sandbox_.

Treat your key like a password. It’s shown once on creation; if you lose it, use Revoke & Regenerate in the dashboard.

2. Place a callback

Send a destination number to POST /v1/callback:

curl -X POST https://api.wave.sa/v1/callback \
  -H "Authorization: Bearer sk_sandbox_xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{ "to": "+966500000000" }'

const res = await fetch("https://api.wave.sa/v1/callback", {
  method: "POST",
  headers: {
    Authorization: "Bearer sk_sandbox_xxxxxxxxxxxx",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ to: "+966500000000" }),
});
const data = await res.json();
console.log(data);

import requests

res = requests.post(
    "https://api.wave.sa/v1/callback",
    headers={"Authorization": "Bearer sk_sandbox_xxxxxxxxxxxx"},
    json={"to": "+966500000000"},
)
print(res.json())

3. Read the response

A successful request returns 202 Accepted:

{
  "call_id": "call_abc123",
  "status": "initiated",
  "sandbox": true,
  "vitalpbx_channel_id": "…",
  "created_at": "2026-06-17T10:00:00.000Z"
}

status is initiated — Wave has placed the call. Terminal statuses (answered/ended) are not emitted yet. See Call lifecycle.

Next steps

Sandbox mode

Trial window, destination lock, and test numbers.

Webhooks

Receive call events at your endpoint.

Introduction Authentication

Get Started

Web Callback

Reference

1. Get a sandbox API key

2. Place a callback

3. Read the response

Next steps

Sandbox mode

Webhooks

​1. Get a sandbox API key

​2. Place a callback

​3. Read the response

​Next steps

Sandbox mode

Webhooks

1. Get a sandbox API key

2. Place a callback

3. Read the response

Next steps