Getting started
Sandbox
Base URL and keys
https://api.voximate.no/sandbox/v1The sandbox needs no sign-up. Any key that starts with vox_test_ followed by 4 to 64 letters, digits,_ or - works, for example vox_test_acme_dev. Each key opens its own sandbox workspace, so pick one your team will not share by accident; anyone who uses the same key sees the same workspace.
curl https://api.voximate.no/sandbox/v1/me \
-H "Authorization: Bearer vox_test_acme_dev"| Sandbox | Production | |
|---|---|---|
| Base URL | https://api.voximate.no/sandbox/v1 | https://api.voximate.no/public/v1 |
| Key | vox_test_… | vox_live_… from Settings → API keys |
| Data | Example data, one workspace per test key | Your workspace |
| Outbound calls | Never dialled; they play out on the clock | Ring real phones |
| Webhooks | Stored, never sent | Sent and signed |
| Scopes | Every scope | The scopes the key was given |
Never send a live key to the sandbox
vox_live_ keys without looking them up. Keep live keys on your server, out of test fixtures and screenshots.Try it in the browser
What a new workspace holds
A new sandbox workspace starts with the objects used in every example in these docs, under the same ids. The code samples therefore run as they are: change only the base URL and the key.
| Object | Id | What it is |
|---|---|---|
| Agent | 7c3f1e90-5a44-4b21-9c07-2ed5b8f41a66 | "Reception - Nordvik Dental", published, answers +4721000000 |
| Agent | 5e8d2c4a-7b1f-4e3a-9c6d-0a1b2c3d4e5f | "After-hours line", a draft in English |
| Phone number | b8f2a1c4-3d5e-4f60-8a71-92b3c4d5e6f7 | +4721000000, assigned to the published agent |
| Phone number | c4d5e6f7-1a2b-4c3d-8e9f-0a1b2c3d4e5f | +4721000001, not assigned |
| Call | 3c27f11c-8a1e-4d55-9b0e-1f4c2a7d9e10 | Outbound, completed, with transcript and analysis |
| Call | e7f8a9b0-c1d2-4e3f-8a4b-5c6d7e8f9a0b | Inbound, completed, with transcript and analysis |
| Webhook endpoint | d1e2f3a4-b5c6-4d7e-8f90-a1b2c3d4e5f6 | https://example.com/voximate/webhooks, with two deliveries in its log |
Create, change, publish and delete freely: the workspace is yours alone and is reset after a day without use (see Limits and resets).
Calls play out on the clock
POST /calls runs every check the live API runs — a published agent, a number to call from, the call limits, the Idempotency-Key — and answers 202 with a queued call. Nothing is dialled. Read the call again and it has moved on, the way a real one would:
| Time after the request | status |
|---|---|
| 0 to 2 seconds | queued |
| 2 to 6 seconds | ringing |
| 6 to 20 seconds | in_progress |
| After 20 seconds | completed, 14 seconds long, with a transcript and an analysis |
The transcript opens with the call's first_message, or the agent's own when you sent none. Usage (GET /usage) counts sandbox calls like real ones.
Test numbers
Call these numbers to see how your code handles a call that does not connect:
| to | Ends as | After |
|---|---|---|
+4700000001 | no_answer | 10 seconds |
+4700000002 | busy | 5 seconds |
+4700000003 | failed, end_reason not_connected | 3 seconds |
Webhooks
- Webhook endpoints are created, listed, changed and deleted as in production, and a secret is issued on create and on rotate.
- The sandbox never sends a request to your endpoint.
POST /webhooks/{webhook_id}/testanswersdelivered: falsewith a note saying so, and the attempt appears in the delivery log. - To receive real, signed events, use a live key: see Webhooks.
Limits and resets
- 120 requests a minute from one IP address; above that,
429 rate_limitedwithRetry-After. - The live outbound-call limits apply: at most 10 calls started a minute per workspace.
- A workspace keeps at most 100 agents, 300 calls and 20 webhook endpoints, and about 256 KB in all; past that,
409until you delete something. Request bodies can be at most 16 KB (400 body_too_large), so a longsystem_promptthat works live may be too big here. - A workspace is reset to the example data after 24 hours without a request, and may be reset when Voximate deploys. For a fresh start at any time, use a new test key.
- Every answer carries the header
X-Voximate-Sandbox: true.
Going live
Read the base URL and the key from configuration, and nothing else in your code has to change: point production at https://api.voximate.no/public/v1 with a vox_live_ key from Settings → API keys.
// The same code for both: only the base URL and the key change.
const BASE = process.env.VOXIMATE_API_BASE ?? 'https://api.voximate.no/sandbox/v1';
const KEY = process.env.VOXIMATE_API_KEY; // vox_test_… in development, vox_live_… in production
const res = await fetch(`${BASE}/agents`, { headers: { Authorization: `Bearer ${KEY}` } });What changes when you go live