The Voyp API

Start an AI phone call with one HTTP request, then read back the transcript and summary when it ends. Calls made through the API use your Voyp account, its settings and its credits.

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.

  1. Log in at app.voyp.app.
  2. Open API keys in the sidebar, or go straight to app.voyp.app/keys.
  3. Click New key. The key appears in the list.
  4. 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

ParameterTypeDescription
number REQUIREDstringThe phone number to call. Use the international format with the country code, such as +14155550123.
context REQUIREDstringWhat 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.
languagestringThe language of the call as a locale code, such as en-US or pt-PT. Defaults to your account’s language.
startbooleanIf true, the assistant speaks first as soon as the call connects. Otherwise it waits for the other side to speak. Defaults to false.
recordbooleanRecord the call audio. Recording costs 1 extra credit per minute. Defaults to your account’s setting.
advancedbooleanUse Advanced mode, the real-time voice models. The per-minute rate is different from a standard call. Defaults to false.
transferbooleanLet 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 with Context 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

ParameterTypeDescription
limitintegerThe most calls to return. Defaults to 50.
beforeintegerOnly return calls that started before this moment, given as a Unix timestamp in milliseconds. Defaults to now.
afterintegerOnly 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.

FieldTypeDescription
callSidstringThe id of the call.
numberstringThe number that was called, in international format.
statusstringHow the call ended: completed, no-answer, busy, canceled or failed.
timestringWhen the call started, as an ISO 8601 date in UTC.
durationintegerHow long the call lasted, in seconds.
creditsintegerThe credits the call spent.
directionstringoutbound for calls Voyp placed.
sourcestringWhere the call was started. Calls made with this API have api.
languagestringThe language of the call, if you set one.
contextstringThe context you gave for the call.
summarystringA one-sentence summary of what happened, when Voyp generated one.
recordingstringA link to the audio, if the call was recorded.
messagesarrayThe 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.