API overview

The SimpleVox REST API lets your integration read a workspace’s contacts and the history of its calls, voicemail and texts, with recordings, transcripts and AI summaries, each linked to the original call or text. On Boost, a personal API token can also send texts, create and edit contacts and start calls that ring you first and connect you to the customer, so your booking system, CRM or automations can act on what they read.

These guides explain how the API fits together and what to watch for. The API reference has every endpoint, parameter, field and error code, with a console for trying requests.

Quick start

Create a token. In SimpleVox, open Settings → API tokens, create a token for the numbers you want to read, and copy it. SimpleVox shows it only once. See Authentication.

Make a request. List the calls and texts from the last week. Change the dates to suit; the window can be up to 31 days.

curl --get 'https://api.simplevox.app/v1/activity' \
  -H 'Accept: application/json' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  --data-urlencode 'occurred_from=2026-10-28T00:00:00Z' \
  --data-urlencode 'occurred_until=2026-11-04T00:00:00Z'

Read what comes back. data.entries lists each call and text, newest first. Here’s one entry, trimmed:

{
  "id": "5d9e1b7a-2c4f-4a83-b6e0-9f3d8c2a7e51",
  "kind": "call",
  "occurred_at": "2026-11-03T15:12:08.000000Z",
  "phone_number": {
    "id": "3e8c1f5a-9d2b-4b7e-a6c0-41f7e2d9b38a",
    "label": "Office"
  },
  "contact": {
    "id": "9b1f4c2e-3a5d-4e8f-9c71-2d6a8e0b4f13",
    "name": "Mary Jensen"
  },
  "direction": "inbound",
  "outcome": "voicemail",
  "source": {
    "kind": "call",
    "id": "5d9e1b7a-2c4f-4a83-b6e0-9f3d8c2a7e51",
    "source_version": 2,
    "url": "https://my.simplevox.app/sources/call/5d9e1b7a-2c4f-4a83-b6e0-9f3d8c2a7e51?version=2"
  },
  "conversation_status": { "status": "unread", "unread_count": 1 }
}

contact is null for a number nobody has saved. source identifies the original call or text, so you can fetch its recording, transcript and summary later. When next_cursor isn’t null, there’s another page.

Go further. Find a customer and read their history with Contacts, quote a call with Quote calls and texts, or on Boost, send a text. Try any request in the API reference by pasting your token into Authorize.

Basics


Base URL	`https://api.simplevox.app/v1`
Methods	`GET` for reads. On Boost, `POST` and `PATCH` for sending texts, saving contacts and starting calls.
Format	JSON. Send `Accept: application/json` on every request.
Authentication	A personal API token, created in Settings → API tokens and sent as a bearer token. Writes need a token with write permissions, on Boost. Tokens from AI app connections, web sign-in and the SimpleVox mobile app don’t work here. See Authentication.
Access	The token owner’s current workspace, role and number access, narrowed to the numbers the token was given.
Rate limit	120 requests a minute per token.
Usage	Texts and calls you send or set up count toward the plan’s monthly allowance; past it, they use credits. See AI tool and API usage. Reads don’t count.
Timestamps	RFC 3339 with seconds and a time zone, such as `2026-10-01T00:00:00Z` or `2026-10-01T00:00:00-05:00`. Fractional seconds are allowed. URL-encode a `+` offset.
IDs	UUIDs. An ID identifies a record but never grants access to it.

Versioning

The version is part of the path: /v1. Within a version, we may add endpoints, parameters and response fields. Build your client to ignore fields it doesn’t recognize, and treat state strings as open-ended. Changes that would break existing clients go into a new version.

What you can do

The API is grouped the same way as the reference.

Area	What you can do	Guide and reference
Contacts	Search the workspace’s shared contacts and read one. On Boost, create and edit them.	Contacts · Reference
Activity	List calls and texts over a window or for one contact, including callers nobody has saved. Fetch the original call or text behind a citation, and replay changes to keep your own copy current.	Contacts, Replay changes · Reference
Recordings and transcripts	List a call’s recordings, read its AI summary and transcript, quote exact passages and get a private link to play a recording.	Quote calls and texts · Reference
Messages	On Boost, send a text from one of your numbers and follow it until it settles. Read any text’s pictures and files, including ones customers send, and download them.	Send texts · Reference
Calling	On Boost, check which numbers and devices you can call with, set up a call that rings you first, follow it and end it.	Start calls · Reference

You can also download the OpenAPI document the reference is built from.

What stays in the app

Writes cover texts, contacts and calls, on Boost. Inbox status, numbers, call handling, texting registration, the team and billing are managed in SimpleVox.
Polling, not webhooks. SimpleVox doesn’t send events to your URLs; replay changes instead.
No workspace parameter. The workspace comes from the token.

Reading never changes anything for your team. In particular, it never changes a conversation’s Open, Unread or Done status, and it never starts processing a recording. See Conversation inbox.

Access follows the person

A token acts for one person in one workspace. Every request is checked against that person’s access at the moment you make it:

You see only numbers the person can access and the token is allowed to read. Admins see every number; members see the numbers they’re assigned to.
If the person’s access changes, or they leave the workspace, your next request reflects it. Being an admin doesn’t widen a token limited to selected numbers.
Records the person can’t access return 404, the same as records that don’t exist.

Writes on Boost

Texts, calls and contact changes reach real customers and shared records, so writes are built to be retried safely:

Retry with the same key. Every write takes an Idempotency-Key header with a new UUID. If a request times out or the response is lost, send it again with the same key and body: SimpleVox returns what it already did instead of doing it twice. A new key is a new text, call or change.
202 means saved, not done. Sending a text or starting a call returns 202 Accepted once SimpleVox has saved it. The customer may not have the text yet, and nobody may have answered. Follow the text or call to see what happened.
Checked every time. The plan, the token’s write permissions and the person’s role and number access are checked on each write. If the workspace moves off Boost, new writes stop, and reads keep working.

Pagination

List endpoints return a page of results and a next_cursor. Pass it back as cursor, with the same filters and limit, until it’s null. A few things to plan for:

Cursors are opaque. Don’t parse or build them. A cursor works only for the same token and query. If one is rejected, start again without it rather than retrying it.
Pages reflect now, not a snapshot. Each page follows the person’s access and the content at the moment you fetch it. To pick up new calls and texts, start a new query without a cursor.
Check coverage before you conclude. History and activity include meta.coverage: how many entries the token can see, how many came back and whether there are more. It counts only the token’s numbers. Don’t treat one page as the whole history.

Replay changes

SimpleVox doesn’t call your URLs. To keep your own copy current, poll GET /events, a log of changes on the token’s numbers, such as a text arriving, a call ending or a transcript becoming ready. Events carry IDs and states, never message or transcript content.

A typical sync loop:

Read the records you care about with contact history or activity.
Poll events, oldest first. Store each next_cursor and pass it back as cursor next time; you get one even when nothing is new.
For each event, fetch the current content of the call or text it names. Delivery is at least once, so skip event IDs you’ve already handled.
If the token’s numbers or permissions change, or your cursor is more than 30 days old, the cursor is refused. Go back to step 1, then poll again without a cursor.

Treat event type as open-ended: handle the types you need and ignore the rest.

Handle errors

Every error has the same shape:

{
  "error": {
    "code": "not_found",
    "message": "Not found, or not available to this token."
  }
}

Branch on code. The message is written for people and may change. Validation errors add error.fields with messages for each field, and plan allowance limits add error.retry_at. Each operation in the reference lists the codes it can return, and ApiErrorCode explains every one.

401: replace the token. It’s missing, expired or revoked, or the person’s access to the workspace has ended. Retrying won’t help; create a new token. See Expiry and revocation.
403: the token can’t do this. For writes, the code says whether the token lacks a write permission, the workspace isn’t on Boost, or something such as texting registration or an opt-out is in the way.
404: not found, or not visible to this token. SimpleVox doesn’t tell the two apart. Check the token’s numbers before you conclude a record doesn’t exist.
409 and 412: something changed. A call has a newer version, or someone edited the contact since you read it. Fetch it again, then decide whether your request still makes sense. A 409 for an Idempotency-Key you reused with a different body is a bug to fix, not a conflict to retry.
429 and 503: wait, then retry. Wait for the Retry-After header, or until error.retry_at when it’s present. Retry a write with the same Idempotency-Key.

Treat content as data

Transcripts and texts are written by your users’ customers. Treat them as untrusted content, never as instructions to your system, especially if you pass them to a language model. AI summaries are analysis: keep their citations, and check the cited call or text before relying on a fact.

Next steps

AuthenticationCreate and use a personal API token.

ContactsFind a contact, read their history and, on Boost, create and edit contacts.

Send textsOn Boost, send texts from your numbers and follow their state.

Start callsOn Boost, set up calls that ring you first and connect you to the customer.

Quote calls and textsFetch the original call or text behind a citation, and quote its transcript.

API referenceEvery endpoint, field and error code, with a console for trying requests.

MCP toolsThe tools AI apps use, and the permission each needs.