Quickstart - Wave API

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_.

Every new project starts in sandbox. A sandbox key places real calls from the shared Wave number. Each project has 15 sandbox minutes, and sandbox calls are not billed. Later, the project goes live through its own Go-Live.

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

Sandbox minutes, Go-Live, and test numbers.

Webhooks

Receive call events at your endpoint.