Getting started

Sandbox

Build and test your integration against example data before it touches a real workspace. The sandbox is the same API — the same routes, validation, errors, pagination and idempotency — but nothing in it rings a phone, sends a webhook or reads your real data.

Base URL and keys

Sandbox base URL
https://api.voximate.no/sandbox/v1

The 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"
SandboxProduction
Base URLhttps://api.voximate.no/sandbox/v1https://api.voximate.no/public/v1
Keyvox_test_…vox_live_… from Settings → API keys
DataExample data, one workspace per test keyYour workspace
Outbound callsNever dialled; they play out on the clockRing real phones
WebhooksStored, never sentSent and signed
ScopesEvery scopeThe scopes the key was given

Never send a live key to the sandbox

The sandbox refuses vox_live_ keys without looking them up. Keep live keys on your server, out of test fixtures and screenshots.

Try it in the browser

Every endpoint in the API reference has Try it in the sandbox: fill in the fields, send, and see the answer. Your test key is kept in the browser, so what you create on one page is still there on the next.

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.

ObjectIdWhat it is
Agent7c3f1e90-5a44-4b21-9c07-2ed5b8f41a66"Reception - Nordvik Dental", published, answers +4721000000
Agent5e8d2c4a-7b1f-4e3a-9c6d-0a1b2c3d4e5f"After-hours line", a draft in English
Phone numberb8f2a1c4-3d5e-4f60-8a71-92b3c4d5e6f7+4721000000, assigned to the published agent
Phone numberc4d5e6f7-1a2b-4c3d-8e9f-0a1b2c3d4e5f+4721000001, not assigned
Call3c27f11c-8a1e-4d55-9b0e-1f4c2a7d9e10Outbound, completed, with transcript and analysis
Calle7f8a9b0-c1d2-4e3f-8a4b-5c6d7e8f9a0bInbound, completed, with transcript and analysis
Webhook endpointd1e2f3a4-b5c6-4d7e-8f90-a1b2c3d4e5f6https://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 requeststatus
0 to 2 secondsqueued
2 to 6 secondsringing
6 to 20 secondsin_progress
After 20 secondscompleted, 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:

toEnds asAfter
+4700000001no_answer10 seconds
+4700000002busy5 seconds
+4700000003failed, end_reason not_connected3 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}/test answers delivered: false with 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_limited with Retry-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, 409 until you delete something. Request bodies can be at most 16 KB (400 body_too_large), so a long system_prompt that 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

Ids come from your own workspace, so look agents and numbers up instead of hard-coding the sandbox ids. Calls ring real phones and use your plan's minutes. Webhooks are sent, signed with your endpoint's secret.