Create an API key
You create API keys in the Voyp web app. You need a Voyp account; the one you use in the mobile apps works.
- Log in at app.voyp.app.
- Open API keys in the sidebar, or go straight to app.voyp.app/keys.
- Click New key. The key appears in the list.
- Click the copy button next to the key and store it somewhere safe, such as an environment variable.
A key starts with sk_ and gives full access to your account’s calls and credits, so treat it like a password. Keep it on your server: don’t put it in a web page, a mobile app or a public repository. You can create several keys, one per integration, and delete a key from the same page when you no longer need it.
Authentication
Send your key as a Bearer token in the Authorization header of every request:
Authorization: Bearer sk_your_api_key
The examples on this page read the key from an environment variable named VOYP_API_KEY:
export VOYP_API_KEY="sk_your_api_key"
A request without a key gets the HTTP status 401.
Requests and errors
The base URL is https://api.voyp.app. Requests and responses are JSON. Send Content-Type: application/json with every request that has a body.
When a request can’t be completed, the response is a JSON object with a single error field. The HTTP status of an error response can still be 200, so always check the body for error before you use it:
{ "error": "Not enough credits" }
Make a call
POSThttps://api.voyp.app/api/calls/create
Starts an outbound phone call. Voyp dials the number, and the assistant handles the conversation by following your context. As on every Voyp call, the assistant introduces itself as an AI.
Body parameters
| Parameter | Type | Description |
|---|---|---|
| number REQUIRED | string | The phone number to call. Use the international format with the country code, such as +14155550123. |
| context REQUIRED | string | What the call is for and everything the assistant needs to know: who it’s calling for, what to ask, and the details the other side will want. Up to 2,048 characters. |
| language | string | The language of the call as a locale code, such as en-US or pt-PT. Defaults to your account’s language. |
| start | boolean | If true, the assistant speaks first as soon as the call connects. Otherwise it waits for the other side to speak. Defaults to false. |
| record | boolean | Record the call audio. Recording costs 1 extra credit per minute. Defaults to your account’s setting. |
| advanced | boolean | Use Advanced mode, the real-time voice models. The per-minute rate is different from a standard call. Defaults to false. |
| transfer | boolean | Let the assistant offer to transfer the call to you. Defaults to true if your account has a transfer number, otherwise false. |
Example request
curl -X POST https://api.voyp.app/api/calls/create \
-H "Authorization: Bearer $VOYP_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"number": "+14155550123",
"context": "Call Luigi’s Trattoria and book a table for five tonight at 8pm, under the name Ana Silva. If 8pm is taken, any time between 7pm and 9pm works.",
"language": "en-US"
}'
import os
import requests
response = requests.post(
"https://api.voyp.app/api/calls/create",
headers={"Authorization": f"Bearer {os.environ['VOYP_API_KEY']}"},
json={
"number": "+14155550123",
"context": (
"Call Luigi's Trattoria and book a table for five tonight at 8pm, "
"under the name Ana Silva. If 8pm is taken, any time between "
"7pm and 9pm works."
),
"language": "en-US",
},
)
data = response.json()
if "error" in data:
raise RuntimeError(data["error"])
call_id = data["call"]
print("Call started:", call_id)
const response = await fetch("https://api.voyp.app/api/calls/create", { method: "POST", headers: { Authorization: `Bearer ${process.env.VOYP_API_KEY}`, "Content-Type": "application/json", }, body: JSON.stringify({ number: "+14155550123", context: "Call Luigi's Trattoria and book a table for five tonight at 8pm, " + "under the name Ana Silva. If 8pm is taken, any time between " + "7pm and 9pm works.", language: "en-US", }), }); const data = await response.json(); if (data.error) throw new Error(data.error); const callId = data.call; console.log("Call started:", callId);
Response
The response carries the id of the call. Keep it: you need it to retrieve the call later.
{ "call": "CA3f1c9b2e7d5a4c8e9b0a1d2c3e4f5a6b" }
Limits and common errors
- The call spends credits from your account for each minute, at the rate for the number you call. If your balance doesn’t cover the first minute, the request fails with
Not enough credits. - A call lasts 15 minutes at most, or less if your credits run out sooner.
- You can have one call in progress at a time. A second request fails with
User already has a call in progress. Voyp Business accounts can run calls at the same time. - A number that can’t be dialed fails with
Invalid phone number. - A missing context fails with
Please provide a valid context for the call, and one over the limit withContext is too long, please provide a shorter context. - Voyp checks every context before it dials. One that breaks the terms fails with
Call context violates policy.
Retrieve a call
GEThttps://api.voyp.app/api/calls/{call_id}
Returns one of your calls, with its status, duration, transcript and summary. Replace {call_id} with the id you got when you started the call.
A call becomes available here once it has ended. While it is still ringing or in conversation, the response is { "error": "call not found" }. To wait for a result, ask again every few seconds until the call comes back, as the Python and JavaScript examples do. The transcript and the summary are added a few seconds after the call ends.
Example request
curl https://api.voyp.app/api/calls/CA3f1c9b2e7d5a4c8e9b0a1d2c3e4f5a6b \ -H "Authorization: Bearer $VOYP_API_KEY"
import os import time import requests API = "https://api.voyp.app" HEADERS = {"Authorization": f"Bearer {os.environ['VOYP_API_KEY']}"} def get_call(call_id): # Returns the call, or None while it is still in progress data = requests.get(f"{API}/api/calls/{call_id}", headers=HEADERS).json() return data.get("call") def wait_for_call(call_id, timeout=20 * 60): # Ask every 5 seconds until the call has ended and its transcript is in deadline = time.time() + timeout while time.time() < deadline: call = get_call(call_id) if call and ("messages" in call or call["status"] != "completed"): return call time.sleep(5) raise TimeoutError("The call did not finish in time") call = wait_for_call("CA3f1c9b2e7d5a4c8e9b0a1d2c3e4f5a6b") print(call["status"], call.get("summary")) for message in call.get("messages") or []: speaker = "Voyp" if message.get("sent") else "Them" print(f"{speaker}: {message['text']}")
const API = "https://api.voyp.app"; const headers = { Authorization: `Bearer ${process.env.VOYP_API_KEY}` }; // Returns the call, or undefined while it is still in progress async function getCall(callId) { const response = await fetch(`${API}/api/calls/${callId}`, { headers }); const data = await response.json(); return data.call; } // Ask every 5 seconds until the call has ended and its transcript is in async function waitForCall(callId, timeoutMs = 20 * 60 * 1000) { const deadline = Date.now() + timeoutMs; while (Date.now() < deadline) { const call = await getCall(callId); if (call && (call.messages || call.status !== "completed")) return call; await new Promise((resolve) => setTimeout(resolve, 5000)); } throw new Error("The call did not finish in time"); } const call = await waitForCall("CA3f1c9b2e7d5a4c8e9b0a1d2c3e4f5a6b"); console.log(call.status, call.summary); for (const message of call.messages ?? []) { console.log(`${message.sent ? "Voyp" : "Them"}: ${message.text}`); }
Response
The call comes back under call. See the call object for every field.
{
"call": {
"callSid": "CA3f1c9b2e7d5a4c8e9b0a1d2c3e4f5a6b",
"number": "+14155550123",
"direction": "outbound",
"source": "api",
"status": "completed",
"time": "2026-11-21T19:02:11.000Z",
"duration": 74,
"credits": 10,
"language": "en-US",
"context": "Call Luigi’s Trattoria and book a table for five tonight at 8pm…",
"summary": "Table for five booked for tonight at 8:00 PM under Ana Silva.",
"messages": [
{ "text": "Luigi’s Trattoria, good evening.", "sent": false, "time": 1795287735000 },
{ "text": "Hi, I’m an AI assistant calling for Ana Silva. I’d like to book a table for five tonight at 8pm.", "sent": true, "time": 1795287738000 },
{ "text": "Sure, five at eight. You’re all set.", "sent": false, "time": 1795287749000 }
]
}
}
List calls
GEThttps://api.voyp.app/api/calls
Returns the calls on your account that have ended, newest first. It includes calls started from the apps as well as from the API.
Query parameters
| Parameter | Type | Description |
|---|---|---|
| limit | integer | The most calls to return. Defaults to 50. |
| before | integer | Only return calls that started before this moment, given as a Unix timestamp in milliseconds. Defaults to now. |
| after | integer | Only return calls that started after this moment, given as a Unix timestamp in milliseconds. If you send after, before is ignored. |
To page back through older calls, take the time of the last call you received, convert it to milliseconds and send it as before. Stop when a page comes back with fewer calls than your limit.
Example request
curl "https://api.voyp.app/api/calls?limit=20" \ -H "Authorization: Bearer $VOYP_API_KEY"
import os from datetime import datetime import requests API = "https://api.voyp.app" HEADERS = {"Authorization": f"Bearer {os.environ['VOYP_API_KEY']}"} def list_calls(limit=20, before=None): params = {"limit": limit} if before: params["before"] = before data = requests.get(f"{API}/api/calls", headers=HEADERS, params=params).json() if "error" in data: raise RuntimeError(data["error"]) return data["calls"] calls = list_calls() for call in calls: print(call["time"], call["number"], call["status"], call.get("summary")) # Next page: everything older than the last call received if calls: last = datetime.fromisoformat(calls[-1]["time"].replace("Z", "+00:00")) older = list_calls(before=int(last.timestamp() * 1000))
const API = "https://api.voyp.app"; const headers = { Authorization: `Bearer ${process.env.VOYP_API_KEY}` }; async function listCalls({ limit = 20, before } = {}) { const params = new URLSearchParams({ limit }); if (before) params.set("before", before); const response = await fetch(`${API}/api/calls?${params}`, { headers }); const data = await response.json(); if (data.error) throw new Error(data.error); return data.calls; } const calls = await listCalls(); for (const call of calls) { console.log(call.time, call.number, call.status, call.summary); } // Next page: everything older than the last call received if (calls.length > 0) { const last = new Date(calls.at(-1).time).getTime(); const older = await listCalls({ before: last }); }
Response
The calls come back under calls, each one a call object.
{
"calls": [
{
"callSid": "CA3f1c9b2e7d5a4c8e9b0a1d2c3e4f5a6b",
"number": "+14155550123",
"status": "completed",
"time": "2026-11-21T19:02:11.000Z",
"duration": 74,
"credits": 10,
"summary": "Table for five booked for tonight at 8:00 PM under Ana Silva.",
"messages": [ … ]
},
{
"callSid": "CA9d8c7b6a5f4e3d2c1b0a9f8e7d6c5b4a",
"number": "+14155550188",
"status": "no-answer",
"time": "2026-11-20T10:15:42.000Z",
"duration": 0,
"credits": 0
}
]
}
The call object
Both Retrieve a call and List calls return calls in this shape. Fields that don’t apply to a call are left out or null, and a call may carry other fields not listed here.
| Field | Type | Description |
|---|---|---|
| callSid | string | The id of the call. |
| number | string | The number that was called, in international format. |
| status | string | How the call ended: completed, no-answer, busy, canceled or failed. |
| time | string | When the call started, as an ISO 8601 date in UTC. |
| duration | integer | How long the call lasted, in seconds. |
| credits | integer | The credits the call spent. |
| direction | string | outbound for calls Voyp placed. |
| source | string | Where the call was started. Calls made with this API have api. |
| language | string | The language of the call, if you set one. |
| context | string | The context you gave for the call. |
| summary | string | A one-sentence summary of what happened, when Voyp generated one. |
| recording | string | A link to the audio, if the call was recorded. |
| messages | array | The transcript, in order. Each message has text, sent (true when the Voyp assistant spoke, false for the other side) and time (a Unix timestamp in milliseconds). |
Help
If something doesn’t behave the way this page says, write to support@voyp.app with the id of the call. To let an AI agent place calls instead of your own code, use the Voyp MCP server, which works with the same API key. To place calls for your own customers through your SIP trunk, with webhooks and scoped keys, see Voyp Enterprise.
Build something that calls.
Create an API key in the web app and start your first call in a few lines of code.