API reference

API reference

Every endpoint in the Voximate API, generated from the OpenAPI spec. Base URL https://api.voximate.no/public/v1, authenticated with Authorization: Bearer vox_live_….

Account

The API key in use and what it may do.

Retrieve the current API key

get/me
Needs no scope — any valid key.

Returns the key that made the request: its id, workspace and scopes. Needs no scope, so it is the quickest way to check that a key works.

Returns · 200

The API key.

Show response fields
  • objectstringrequired

    Always "api_key"

  • idstring (uuid)required

    The key id (never the secret).

  • workspace_idstring (uuid)required

    Your workspace.

  • workspace_namestring | nullrequired

    The workspace name shown in the dashboard; null if it could not be read just now.

  • scopesarray of stringrequired

    What the key may do, for example calls:write.

Errors

  • 401No API key, or the key is invalid, expired or revoked.

Every error has the same shape — see Errors.

curl "https://api.voximate.no/public/v1/me" \
  -H "Authorization: Bearer $VOXIMATE_API_KEY"
Response · 200
{
  "object": "api_key",
  "id": "0b6f3c2e-1a4d-4e5f-9a8b-7c6d5e4f3a2b",
  "workspace_id": "4f1a2b3c-5d6e-4f70-8a9b-0c1d2e3f4a5b",
  "scopes": [
    "agents:read",
    "calls:read",
    "calls:write"
  ]
}

Agents

AI voice agents: their instructions, greeting, voice and language.

List agents

get/agents
Requiresagents:read

Returns the agents in your workspace, newest first.

Query parameters

  • limitinteger

    How many items to return, 1 to 100.

    Default 20

  • cursorstring

    The next_cursor from the previous page.

Returns · 200

A page of agents.

Show response fields
  • objectstringrequired

    Always "list"

  • dataarray of Agentrequired
    Show child attributes
    • objectstringrequired

      Always "agent"

    • idstring (uuid)required
    • namestringrequired
    • descriptionstring | nullrequired
    • statusstringrequired

      Only a published agent answers phone calls and can place outbound calls.

      One ofdraftpublishedunpublishedarchived

    • languagestring | nullrequired

      BCP 47 tag, for example nb-NO or en-US.

    • system_promptstring | nullrequired

      The instructions the agent follows on every call.

    • first_messagestring | nullrequired

      What the agent says when it picks up.

    • outbound_first_messagestring | nullrequired

      What the agent says first on calls it makes. When null, those calls open with first_message. A call can set its own with first_message on POST /calls.

    • voiceobjectrequired
      Show child attributes
      • providerstring | nullrequired
      • voice_idstring | nullrequired
    • llmobjectrequired
      Show child attributes
      • providerstring | nullrequired
      • modelstring | nullrequired
    • created_atstring (date-time)required
    • updated_atstring (date-time)required
  • has_morebooleanrequired

    True when another page follows this one.

  • next_cursorstring | nullrequired

    Pass as cursor to fetch the next page. null on the last page.

Errors

  • 400The request is malformed: a missing field, a wrong type, an unknown parameter or an id that is not a UUID.
  • 401No API key, or the key is invalid, expired or revoked.
  • 403The key is valid but lacks the scope this operation needs (`missing_scope`), or — for adding, changing, testing or removing a webhook endpoint — was not made by a workspace owner or admin (`role_required`).

Every error has the same shape — see Errors.

curl "https://api.voximate.no/public/v1/agents?limit=20" \
  -H "Authorization: Bearer $VOXIMATE_API_KEY"
Response · 200
{
  "object": "list",
  "data": [
    {
      "object": "agent",
      "id": "7c3f1e90-5a44-4b21-9c07-2ed5b8f41a66",
      "name": "Reception - Nordvik Dental",
      "description": "Answers the main line and books check-ups.",
      "status": "published",
      "language": "nb-NO",
      "system_prompt": "You are Sara, the receptionist at Nordvik Dental. Keep answers short.",
      "first_message": "Hei, du har kommet til Nordvik Tannklinikk. Hva kan jeg hjelpe deg med?",
      "outbound_first_message": "Hei, dette er Nordvik Tannklinikk.",
      "voice": {
        "provider": "elevenlabs",
        "voice_id": "aya-norwegian"
      },
      "llm": {
        "provider": "openai",
        "model": "gpt-4o"
      },
      "created_at": "2026-10-01T09:12:44.000Z",
      "updated_at": "2026-10-12T18:03:10.000Z"
    }
  ],
  "has_more": false,
  "next_cursor": null
}

Create an agent

post/agents
Requiresagents:write

Creates an agent as a draft. A draft answers in the dashboard test panel but takes no phone calls until it is published.

Headers

  • Idempotency-Keystring

    Any unique string (a UUID is ideal). Retrying a request with the same key within 24 hours returns the first answer instead of doing the work again.

Request body · application/json

  • namestringrequired

    max 200 characters

  • descriptionstring

    max 1000 characters

  • languagestring

    BCP 47 tag. Default nb-NO.

    max 20 characters

  • system_promptstring

    max 50000 characters

  • first_messagestring

    max 500 characters

  • outbound_first_messagestring

    What it says first on calls it makes.

    max 500 characters

  • voice_idstring

    A voice id from the dashboard voice picker.

    max 200 characters

Returns · 201

The new agent.

Show response fields
  • objectstringrequired

    Always "agent"

  • idstring (uuid)required
  • namestringrequired
  • descriptionstring | nullrequired
  • statusstringrequired

    Only a published agent answers phone calls and can place outbound calls.

    One ofdraftpublishedunpublishedarchived

  • languagestring | nullrequired

    BCP 47 tag, for example nb-NO or en-US.

  • system_promptstring | nullrequired

    The instructions the agent follows on every call.

  • first_messagestring | nullrequired

    What the agent says when it picks up.

  • outbound_first_messagestring | nullrequired

    What the agent says first on calls it makes. When null, those calls open with first_message. A call can set its own with first_message on POST /calls.

  • voiceobjectrequired
    Show child attributes
    • providerstring | nullrequired
    • voice_idstring | nullrequired
  • llmobjectrequired
    Show child attributes
    • providerstring | nullrequired
    • modelstring | nullrequired
  • created_atstring (date-time)required
  • updated_atstring (date-time)required

Errors

  • 400The request is malformed: a missing field, a wrong type, an unknown parameter or an id that is not a UUID.
  • 401No API key, or the key is invalid, expired or revoked.
  • 403The key is valid but lacks the scope this operation needs (`missing_scope`), or — for adding, changing, testing or removing a webhook endpoint — was not made by a workspace owner or admin (`role_required`).
  • 409The Idempotency-Key was already used with a different request, or that request is still running.
  • 422The request is well-formed but cannot be carried out in the current state.

Every error has the same shape — see Errors.

curl -X POST "https://api.voximate.no/public/v1/agents" \
  -H "Authorization: Bearer $VOXIMATE_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
  "name": "After-hours line",
  "language": "nb-NO",
  "system_prompt": "You take messages after opening hours. Ask for name, number and reason.",
  "first_message": "Hei! Vi har stengt nå, men jeg kan ta imot en beskjed."
}'
Response · 201
{
  "object": "agent",
  "id": "7c3f1e90-5a44-4b21-9c07-2ed5b8f41a66",
  "name": "After-hours line",
  "description": "Answers the main line and books check-ups.",
  "status": "draft",
  "language": "nb-NO",
  "system_prompt": "You are Sara, the receptionist at Nordvik Dental. Keep answers short.",
  "first_message": "Hei, du har kommet til Nordvik Tannklinikk. Hva kan jeg hjelpe deg med?",
  "outbound_first_message": "Hei, dette er Nordvik Tannklinikk.",
  "voice": {
    "provider": "elevenlabs",
    "voice_id": "aya-norwegian"
  },
  "llm": {
    "provider": "openai",
    "model": "gpt-4o"
  },
  "created_at": "2026-10-01T09:12:44.000Z",
  "updated_at": "2026-10-12T18:03:10.000Z"
}

Retrieve an agent

get/agents/{agent_id}
Requiresagents:read

Path parameters

  • agent_idstring (uuid)required

    The agent id.

Returns · 200

The agent.

Show response fields
  • objectstringrequired

    Always "agent"

  • idstring (uuid)required
  • namestringrequired
  • descriptionstring | nullrequired
  • statusstringrequired

    Only a published agent answers phone calls and can place outbound calls.

    One ofdraftpublishedunpublishedarchived

  • languagestring | nullrequired

    BCP 47 tag, for example nb-NO or en-US.

  • system_promptstring | nullrequired

    The instructions the agent follows on every call.

  • first_messagestring | nullrequired

    What the agent says when it picks up.

  • outbound_first_messagestring | nullrequired

    What the agent says first on calls it makes. When null, those calls open with first_message. A call can set its own with first_message on POST /calls.

  • voiceobjectrequired
    Show child attributes
    • providerstring | nullrequired
    • voice_idstring | nullrequired
  • llmobjectrequired
    Show child attributes
    • providerstring | nullrequired
    • modelstring | nullrequired
  • created_atstring (date-time)required
  • updated_atstring (date-time)required

Errors

  • 400The request is malformed: a missing field, a wrong type, an unknown parameter or an id that is not a UUID.
  • 401No API key, or the key is invalid, expired or revoked.
  • 403The key is valid but lacks the scope this operation needs (`missing_scope`), or — for adding, changing, testing or removing a webhook endpoint — was not made by a workspace owner or admin (`role_required`).
  • 404Nothing with that id exists in your workspace.

Every error has the same shape — see Errors.

curl "https://api.voximate.no/public/v1/agents/7c3f1e90-5a44-4b21-9c07-2ed5b8f41a66" \
  -H "Authorization: Bearer $VOXIMATE_API_KEY"
Response · 200
{
  "object": "agent",
  "id": "7c3f1e90-5a44-4b21-9c07-2ed5b8f41a66",
  "name": "Reception - Nordvik Dental",
  "description": "Answers the main line and books check-ups.",
  "status": "published",
  "language": "nb-NO",
  "system_prompt": "You are Sara, the receptionist at Nordvik Dental. Keep answers short.",
  "first_message": "Hei, du har kommet til Nordvik Tannklinikk. Hva kan jeg hjelpe deg med?",
  "outbound_first_message": "Hei, dette er Nordvik Tannklinikk.",
  "voice": {
    "provider": "elevenlabs",
    "voice_id": "aya-norwegian"
  },
  "llm": {
    "provider": "openai",
    "model": "gpt-4o"
  },
  "created_at": "2026-10-01T09:12:44.000Z",
  "updated_at": "2026-10-12T18:03:10.000Z"
}

Update an agent

patch/agents/{agent_id}
Requiresagents:write

Changes only the fields you send. A published agent stays published, and the change applies from its next call.

Path parameters

  • agent_idstring (uuid)required

    The agent id.

Request body · application/json

  • namestring

    max 200 characters

  • descriptionstring | null

    max 1000 characters

  • languagestring

    max 20 characters

  • system_promptstring

    max 50000 characters

  • first_messagestring | null

    max 500 characters

  • outbound_first_messagestring | null

    null removes it.

    max 500 characters

  • voice_idstring

    max 200 characters

Returns · 200

The updated agent.

Show response fields
  • objectstringrequired

    Always "agent"

  • idstring (uuid)required
  • namestringrequired
  • descriptionstring | nullrequired
  • statusstringrequired

    Only a published agent answers phone calls and can place outbound calls.

    One ofdraftpublishedunpublishedarchived

  • languagestring | nullrequired

    BCP 47 tag, for example nb-NO or en-US.

  • system_promptstring | nullrequired

    The instructions the agent follows on every call.

  • first_messagestring | nullrequired

    What the agent says when it picks up.

  • outbound_first_messagestring | nullrequired

    What the agent says first on calls it makes. When null, those calls open with first_message. A call can set its own with first_message on POST /calls.

  • voiceobjectrequired
    Show child attributes
    • providerstring | nullrequired
    • voice_idstring | nullrequired
  • llmobjectrequired
    Show child attributes
    • providerstring | nullrequired
    • modelstring | nullrequired
  • created_atstring (date-time)required
  • updated_atstring (date-time)required

Errors

  • 400The request is malformed: a missing field, a wrong type, an unknown parameter or an id that is not a UUID.
  • 401No API key, or the key is invalid, expired or revoked.
  • 403The key is valid but lacks the scope this operation needs (`missing_scope`), or — for adding, changing, testing or removing a webhook endpoint — was not made by a workspace owner or admin (`role_required`).
  • 404Nothing with that id exists in your workspace.
  • 422The request is well-formed but cannot be carried out in the current state.

Every error has the same shape — see Errors.

curl -X PATCH "https://api.voximate.no/public/v1/agents/7c3f1e90-5a44-4b21-9c07-2ed5b8f41a66" \
  -H "Authorization: Bearer $VOXIMATE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "first_message": "Hei, du har kommet til Nordvik Tannklinikk. Hvordan kan jeg hjelpe?"
}'
Response · 200
{
  "object": "agent",
  "id": "7c3f1e90-5a44-4b21-9c07-2ed5b8f41a66",
  "name": "Reception - Nordvik Dental",
  "description": "Answers the main line and books check-ups.",
  "status": "published",
  "language": "nb-NO",
  "system_prompt": "You are Sara, the receptionist at Nordvik Dental. Keep answers short.",
  "first_message": "Hei, du har kommet til Nordvik Tannklinikk. Hva kan jeg hjelpe deg med?",
  "outbound_first_message": "Hei, dette er Nordvik Tannklinikk.",
  "voice": {
    "provider": "elevenlabs",
    "voice_id": "aya-norwegian"
  },
  "llm": {
    "provider": "openai",
    "model": "gpt-4o"
  },
  "created_at": "2026-10-01T09:12:44.000Z",
  "updated_at": "2026-10-12T18:03:10.000Z"
}

Delete an agent

delete/agents/{agent_id}
Requiresagents:write

Deletes the agent. Phone numbers it answered are left without an agent. Past calls and their transcripts are kept.

Path parameters

  • agent_idstring (uuid)required

    The agent id.

Returns · 200

The agent was deleted.

Show response fields
  • objectstringrequired
  • idstring (uuid)required
  • deletedbooleanrequired

    Always true

Errors

  • 400The request is malformed: a missing field, a wrong type, an unknown parameter or an id that is not a UUID.
  • 401No API key, or the key is invalid, expired or revoked.
  • 403The key is valid but lacks the scope this operation needs (`missing_scope`), or — for adding, changing, testing or removing a webhook endpoint — was not made by a workspace owner or admin (`role_required`).
  • 404Nothing with that id exists in your workspace.

Every error has the same shape — see Errors.

curl -X DELETE "https://api.voximate.no/public/v1/agents/7c3f1e90-5a44-4b21-9c07-2ed5b8f41a66" \
  -H "Authorization: Bearer $VOXIMATE_API_KEY"
Response · 200
{
  "object": "agent",
  "id": "7c3f1e90-5a44-4b21-9c07-2ed5b8f41a66",
  "deleted": true
}

Publish an agent

post/agents/{agent_id}/publish
Requiresagents:write

Makes the agent live: phone numbers assigned to it start reaching it, and it can place outbound calls.

Path parameters

  • agent_idstring (uuid)required

    The agent id.

Returns · 200

The published agent.

Show response fields
  • objectstringrequired

    Always "agent"

  • idstring (uuid)required
  • namestringrequired
  • descriptionstring | nullrequired
  • statusstringrequired

    Only a published agent answers phone calls and can place outbound calls.

    One ofdraftpublishedunpublishedarchived

  • languagestring | nullrequired

    BCP 47 tag, for example nb-NO or en-US.

  • system_promptstring | nullrequired

    The instructions the agent follows on every call.

  • first_messagestring | nullrequired

    What the agent says when it picks up.

  • outbound_first_messagestring | nullrequired

    What the agent says first on calls it makes. When null, those calls open with first_message. A call can set its own with first_message on POST /calls.

  • voiceobjectrequired
    Show child attributes
    • providerstring | nullrequired
    • voice_idstring | nullrequired
  • llmobjectrequired
    Show child attributes
    • providerstring | nullrequired
    • modelstring | nullrequired
  • created_atstring (date-time)required
  • updated_atstring (date-time)required

Errors

  • 400The request is malformed: a missing field, a wrong type, an unknown parameter or an id that is not a UUID.
  • 401No API key, or the key is invalid, expired or revoked.
  • 403The key is valid but lacks the scope this operation needs (`missing_scope`), or — for adding, changing, testing or removing a webhook endpoint — was not made by a workspace owner or admin (`role_required`).
  • 404Nothing with that id exists in your workspace.
  • 422The request is well-formed but cannot be carried out in the current state.

Every error has the same shape — see Errors.

curl -X POST "https://api.voximate.no/public/v1/agents/7c3f1e90-5a44-4b21-9c07-2ed5b8f41a66/publish" \
  -H "Authorization: Bearer $VOXIMATE_API_KEY"
Response · 200
{
  "object": "agent",
  "id": "7c3f1e90-5a44-4b21-9c07-2ed5b8f41a66",
  "name": "Reception - Nordvik Dental",
  "description": "Answers the main line and books check-ups.",
  "status": "published",
  "language": "nb-NO",
  "system_prompt": "You are Sara, the receptionist at Nordvik Dental. Keep answers short.",
  "first_message": "Hei, du har kommet til Nordvik Tannklinikk. Hva kan jeg hjelpe deg med?",
  "outbound_first_message": "Hei, dette er Nordvik Tannklinikk.",
  "voice": {
    "provider": "elevenlabs",
    "voice_id": "aya-norwegian"
  },
  "llm": {
    "provider": "openai",
    "model": "gpt-4o"
  },
  "created_at": "2026-10-01T09:12:44.000Z",
  "updated_at": "2026-10-12T18:03:10.000Z"
}

Unpublish an agent

post/agents/{agent_id}/unpublish
Requiresagents:write

Takes the agent off the phone. Its settings are kept and it can be published again.

Path parameters

  • agent_idstring (uuid)required

    The agent id.

Returns · 200

The unpublished agent.

Show response fields
  • objectstringrequired

    Always "agent"

  • idstring (uuid)required
  • namestringrequired
  • descriptionstring | nullrequired
  • statusstringrequired

    Only a published agent answers phone calls and can place outbound calls.

    One ofdraftpublishedunpublishedarchived

  • languagestring | nullrequired

    BCP 47 tag, for example nb-NO or en-US.

  • system_promptstring | nullrequired

    The instructions the agent follows on every call.

  • first_messagestring | nullrequired

    What the agent says when it picks up.

  • outbound_first_messagestring | nullrequired

    What the agent says first on calls it makes. When null, those calls open with first_message. A call can set its own with first_message on POST /calls.

  • voiceobjectrequired
    Show child attributes
    • providerstring | nullrequired
    • voice_idstring | nullrequired
  • llmobjectrequired
    Show child attributes
    • providerstring | nullrequired
    • modelstring | nullrequired
  • created_atstring (date-time)required
  • updated_atstring (date-time)required

Errors

  • 400The request is malformed: a missing field, a wrong type, an unknown parameter or an id that is not a UUID.
  • 401No API key, or the key is invalid, expired or revoked.
  • 403The key is valid but lacks the scope this operation needs (`missing_scope`), or — for adding, changing, testing or removing a webhook endpoint — was not made by a workspace owner or admin (`role_required`).
  • 404Nothing with that id exists in your workspace.

Every error has the same shape — see Errors.

curl -X POST "https://api.voximate.no/public/v1/agents/7c3f1e90-5a44-4b21-9c07-2ed5b8f41a66/unpublish" \
  -H "Authorization: Bearer $VOXIMATE_API_KEY"
Response · 200
{
  "object": "agent",
  "id": "7c3f1e90-5a44-4b21-9c07-2ed5b8f41a66",
  "name": "Reception - Nordvik Dental",
  "description": "Answers the main line and books check-ups.",
  "status": "unpublished",
  "language": "nb-NO",
  "system_prompt": "You are Sara, the receptionist at Nordvik Dental. Keep answers short.",
  "first_message": "Hei, du har kommet til Nordvik Tannklinikk. Hva kan jeg hjelpe deg med?",
  "outbound_first_message": "Hei, dette er Nordvik Tannklinikk.",
  "voice": {
    "provider": "elevenlabs",
    "voice_id": "aya-norwegian"
  },
  "llm": {
    "provider": "openai",
    "model": "gpt-4o"
  },
  "created_at": "2026-10-01T09:12:44.000Z",
  "updated_at": "2026-10-12T18:03:10.000Z"
}

Calls

Start outbound calls and read finished ones, with transcript and analysis.

List calls

get/calls
Requirescalls:read

Returns calls newest first. Filter by agent, direction and time.

Query parameters

  • limitinteger

    How many items to return, 1 to 100.

    Default 20

  • cursorstring

    The next_cursor from the previous page.

  • agent_idstring (uuid)

    Only calls handled by this agent.

  • directionstring

    Only inbound or only outbound calls.

    One of inbound, outbound

  • created_afterstring (date-time)

    Only calls that started at or after this time (ISO 8601).

  • created_beforestring (date-time)

    Only calls that started before this time (ISO 8601).

Returns · 200

A page of calls.

Show response fields
  • objectstringrequired

    Always "list"

  • dataarray of Callrequired
    Show child attributes
    • objectstringrequired

      Always "call"

    • idstring (uuid)required
    • agent_idstring (uuid) | nullrequired
    • directionstringrequired

      One ofinboundoutbound

    • channelstringrequired

      phone for calls over the phone network, web for browser and widget calls.

      One ofphoneweb

    • statusstringrequired

      One ofqueuedringingin_progresscompletedfailedno_answerbusycanceled

    • fromstring | nullrequired

      The calling number (E.164), when known.

    • tostring | nullrequired

      The called number (E.164), when known.

    • started_atstring (date-time)required
    • ended_atstring (date-time) | nullrequired
    • duration_secondsinteger | nullrequired
    • end_reasonstring | nullrequired

      Why the call ended, for example caller_hangup.

    • metadatamap of stringrequired

      The metadata you sent when you started the call.

    • has_recordingboolean | nullrequired

      Whether a recording exists. null in lists, where it is not looked up.

    • analysisCallAnalysis | nullrequired

      Filled in shortly after the call ends. Always null in lists.

      Show child attributes
      • summarystringrequired
      • outcomestring | nullrequired

        For example resolved, escalated, abandoned.

      • sentimentstring | nullrequired

        One ofpositiveneutralnegative

      • action_itemsarray of stringrequired
      • created_atstring (date-time) | nullrequired
  • has_morebooleanrequired

    True when another page follows this one.

  • next_cursorstring | nullrequired

    Pass as cursor to fetch the next page. null on the last page.

Errors

  • 400The request is malformed: a missing field, a wrong type, an unknown parameter or an id that is not a UUID.
  • 401No API key, or the key is invalid, expired or revoked.
  • 403The key is valid but lacks the scope this operation needs (`missing_scope`), or — for adding, changing, testing or removing a webhook endpoint — was not made by a workspace owner or admin (`role_required`).

Every error has the same shape — see Errors.

curl "https://api.voximate.no/public/v1/calls?limit=20" \
  -H "Authorization: Bearer $VOXIMATE_API_KEY"
Response · 200
{
  "object": "list",
  "data": [
    {
      "object": "call",
      "id": "3c27f11c-8a1e-4d55-9b0e-1f4c2a7d9e10",
      "agent_id": "7c3f1e90-5a44-4b21-9c07-2ed5b8f41a66",
      "direction": "outbound",
      "channel": "phone",
      "status": "completed",
      "from": "+4721000000",
      "to": "+4712345678",
      "started_at": "2026-10-12T10:04:12.000Z",
      "ended_at": "2026-10-12T10:07:33.000Z",
      "duration_seconds": 201,
      "end_reason": "caller_hangup",
      "metadata": {
        "crm_contact_id": "48213"
      },
      "has_recording": null,
      "analysis": null
    }
  ],
  "has_more": true,
  "next_cursor": "eyJvIjoyMH0"
}

Start an outbound call

post/calls
Requirescalls:write

Asks a published agent to call a phone number. Every check runs first (the agent is published, the number is yours, the number is not an emergency number, your plan has minutes); then the dial starts and this returns 202 with the call in status queued, without waiting for the phone to be answered.

How the call goes arrives as webhooks: call.started when it is answered, then call.completed with the analysis, or call.failed with reason no_answer, busy or not_connected. GET /calls/{call_id} shows the same.

The agent knows it placed the call: it says who it is and why it is calling, instead of answering as if it had been rung. It opens with first_message when you send one, else the agent's outbound_first_message, else its first_message.

Send an Idempotency-Key so a retried request can never ring the same person twice. If this answers 503 call_outcome_unknown, the call may already be ringing: look for it with GET /calls before trying again with a new key.

Headers

  • Idempotency-Keystring

    Any unique string (a UUID is ideal). Retrying a request with the same key within 24 hours returns the first answer instead of doing the work again.

Request body · application/json

  • agent_idstring (uuid)required

    A published agent.

  • tostringrequired

    The number to call, E.164.

    pattern ^\+[1-9]\d{6,14}$

  • fromstring

    One of your numbers, E.164. Optional when the agent has exactly one number assigned; required when it has several.

    pattern ^\+[1-9]\d{6,14}$

  • metadatamap of string

    Up to 20 string values, returned on the call and in its webhooks. Use it for your own ids.

    at most 20 keys

  • ring_timeout_secondsinteger

    How long to let it ring before the call counts as not answered. Default 30.

    10–120

  • first_messagestring

    What the agent says first on this call, instead of its own greeting. Send an empty string to have the agent wait for the person to speak first. Left out: the agent's outbound_first_message, or its first_message when it has none.

    max 500 characters

Returns · 202

The call passed every check and the dial has started.

Show response fields
  • objectstringrequired

    Always "call"

  • idstring (uuid)required
  • agent_idstring (uuid) | nullrequired
  • directionstringrequired

    One ofinboundoutbound

  • channelstringrequired

    phone for calls over the phone network, web for browser and widget calls.

    One ofphoneweb

  • statusstringrequired

    One ofqueuedringingin_progresscompletedfailedno_answerbusycanceled

  • fromstring | nullrequired

    The calling number (E.164), when known.

  • tostring | nullrequired

    The called number (E.164), when known.

  • started_atstring (date-time)required
  • ended_atstring (date-time) | nullrequired
  • duration_secondsinteger | nullrequired
  • end_reasonstring | nullrequired

    Why the call ended, for example caller_hangup.

  • metadatamap of stringrequired

    The metadata you sent when you started the call.

  • has_recordingboolean | nullrequired

    Whether a recording exists. null in lists, where it is not looked up.

  • analysisCallAnalysis | nullrequired

    Filled in shortly after the call ends. Always null in lists.

    Show child attributes
    • summarystringrequired
    • outcomestring | nullrequired

      For example resolved, escalated, abandoned.

    • sentimentstring | nullrequired

      One ofpositiveneutralnegative

    • action_itemsarray of stringrequired
    • created_atstring (date-time) | nullrequired

Errors

  • 400The request is malformed: a missing field, a wrong type, an unknown parameter or an id that is not a UUID.
  • 401No API key, or the key is invalid, expired or revoked.
  • 403The key is valid but lacks the scope this operation needs (`missing_scope`), or — for adding, changing, testing or removing a webhook endpoint — was not made by a workspace owner or admin (`role_required`).
  • 404Nothing with that id exists in your workspace.
  • 409The Idempotency-Key was already used with a different request, or that request is still running.
  • 422The request is well-formed but cannot be carried out in the current state.
  • 429Too many requests, or too many calls started in a short time. Wait the number of seconds in the Retry-After header.
  • 503A Voximate service did not answer (`upstream_unavailable`); retrying is safe. On `POST /calls` the code is `call_outcome_unknown` instead: the call may already be ringing, so look for it with `GET /calls` before trying again with a new Idempotency-Key.

Every error has the same shape — see Errors.

curl -X POST "https://api.voximate.no/public/v1/calls" \
  -H "Authorization: Bearer $VOXIMATE_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
  "agent_id": "7c3f1e90-5a44-4b21-9c07-2ed5b8f41a66",
  "to": "+4712345678",
  "first_message": "Hei, dette er Nordvik Tannklinikk. Jeg ringer om timen din i morgen.",
  "metadata": {
    "crm_contact_id": "48213"
  }
}'
Response · 202
{
  "object": "call",
  "id": "3c27f11c-8a1e-4d55-9b0e-1f4c2a7d9e10",
  "agent_id": "7c3f1e90-5a44-4b21-9c07-2ed5b8f41a66",
  "direction": "outbound",
  "channel": "phone",
  "status": "queued",
  "from": "+4721000000",
  "to": "+4712345678",
  "started_at": "2026-10-12T10:04:12.000Z",
  "ended_at": null,
  "duration_seconds": null,
  "end_reason": null,
  "metadata": {
    "crm_contact_id": "48213"
  },
  "has_recording": false,
  "analysis": null
}

Retrieve a call

get/calls/{call_id}
Requirescalls:read

Returns the call with its analysis (summary, outcome, sentiment) once the analysis is ready.

Path parameters

  • call_idstring (uuid)required

    The call id.

Returns · 200

The call.

Show response fields
  • objectstringrequired

    Always "call"

  • idstring (uuid)required
  • agent_idstring (uuid) | nullrequired
  • directionstringrequired

    One ofinboundoutbound

  • channelstringrequired

    phone for calls over the phone network, web for browser and widget calls.

    One ofphoneweb

  • statusstringrequired

    One ofqueuedringingin_progresscompletedfailedno_answerbusycanceled

  • fromstring | nullrequired

    The calling number (E.164), when known.

  • tostring | nullrequired

    The called number (E.164), when known.

  • started_atstring (date-time)required
  • ended_atstring (date-time) | nullrequired
  • duration_secondsinteger | nullrequired
  • end_reasonstring | nullrequired

    Why the call ended, for example caller_hangup.

  • metadatamap of stringrequired

    The metadata you sent when you started the call.

  • has_recordingboolean | nullrequired

    Whether a recording exists. null in lists, where it is not looked up.

  • analysisCallAnalysis | nullrequired

    Filled in shortly after the call ends. Always null in lists.

    Show child attributes
    • summarystringrequired
    • outcomestring | nullrequired

      For example resolved, escalated, abandoned.

    • sentimentstring | nullrequired

      One ofpositiveneutralnegative

    • action_itemsarray of stringrequired
    • created_atstring (date-time) | nullrequired

Errors

  • 400The request is malformed: a missing field, a wrong type, an unknown parameter or an id that is not a UUID.
  • 401No API key, or the key is invalid, expired or revoked.
  • 403The key is valid but lacks the scope this operation needs (`missing_scope`), or — for adding, changing, testing or removing a webhook endpoint — was not made by a workspace owner or admin (`role_required`).
  • 404Nothing with that id exists in your workspace.

Every error has the same shape — see Errors.

curl "https://api.voximate.no/public/v1/calls/3c27f11c-8a1e-4d55-9b0e-1f4c2a7d9e10" \
  -H "Authorization: Bearer $VOXIMATE_API_KEY"
Response · 200
{
  "object": "call",
  "id": "3c27f11c-8a1e-4d55-9b0e-1f4c2a7d9e10",
  "agent_id": "7c3f1e90-5a44-4b21-9c07-2ed5b8f41a66",
  "direction": "outbound",
  "channel": "phone",
  "status": "completed",
  "from": "+4721000000",
  "to": "+4712345678",
  "started_at": "2026-10-12T10:04:12.000Z",
  "ended_at": "2026-10-12T10:07:33.000Z",
  "duration_seconds": 201,
  "end_reason": "caller_hangup",
  "metadata": {
    "crm_contact_id": "48213"
  },
  "has_recording": true,
  "analysis": {
    "summary": "The caller booked a check-up on Tuesday 14 October at 12:00.",
    "outcome": "resolved",
    "sentiment": "positive",
    "action_items": [
      "Send booking confirmation by SMS"
    ],
    "created_at": "2026-10-12T10:07:51.000Z"
  }
}

Retrieve a call transcript

get/calls/{call_id}/transcript
Requirescalls:read

Every line spoken on the call, in order.

Path parameters

  • call_idstring (uuid)required

    The call id.

Returns · 200

The transcript.

Show response fields
  • objectstringrequired

    Always "transcript"

  • call_idstring (uuid)required
  • dataarray of TranscriptEntryrequired
    Show child attributes
    • indexintegerrequired
    • rolestringrequired

      One ofagentcaller

    • textstringrequired

Errors

  • 400The request is malformed: a missing field, a wrong type, an unknown parameter or an id that is not a UUID.
  • 401No API key, or the key is invalid, expired or revoked.
  • 403The key is valid but lacks the scope this operation needs (`missing_scope`), or — for adding, changing, testing or removing a webhook endpoint — was not made by a workspace owner or admin (`role_required`).
  • 404Nothing with that id exists in your workspace.

Every error has the same shape — see Errors.

curl "https://api.voximate.no/public/v1/calls/3c27f11c-8a1e-4d55-9b0e-1f4c2a7d9e10/transcript" \
  -H "Authorization: Bearer $VOXIMATE_API_KEY"
Response · 200
{
  "object": "transcript",
  "call_id": "3c27f11c-8a1e-4d55-9b0e-1f4c2a7d9e10",
  "data": [
    {
      "index": 0,
      "role": "agent",
      "text": "Hei, du har kommet til Nordvik Tannklinikk. Hva kan jeg hjelpe deg med?"
    },
    {
      "index": 1,
      "role": "caller",
      "text": "Jeg vil gjerne bestille en time til kontroll."
    }
  ]
}

Phone numbers

The numbers in your workspace and which agent answers each one.

List phone numbers

get/phone-numbers
Requiresnumbers:read

Query parameters

  • limitinteger

    How many items to return, 1 to 100.

    Default 20

  • cursorstring

    The next_cursor from the previous page.

Returns · 200

A page of phone numbers.

Show response fields
  • objectstringrequired

    Always "list"

  • dataarray of PhoneNumberrequired
    Show child attributes
    • objectstringrequired

      Always "phone_number"

    • idstring (uuid)required
    • numberstringrequired

      E.164.

    • labelstring | nullrequired
    • agent_idstring (uuid) | nullrequired

      The agent that answers it, or null.

    • statusstringrequired
    • capabilitiesarray of stringrequired
    • created_atstring (date-time)required
  • has_morebooleanrequired

    True when another page follows this one.

  • next_cursorstring | nullrequired

    Pass as cursor to fetch the next page. null on the last page.

Errors

  • 400The request is malformed: a missing field, a wrong type, an unknown parameter or an id that is not a UUID.
  • 401No API key, or the key is invalid, expired or revoked.
  • 403The key is valid but lacks the scope this operation needs (`missing_scope`), or — for adding, changing, testing or removing a webhook endpoint — was not made by a workspace owner or admin (`role_required`).

Every error has the same shape — see Errors.

curl "https://api.voximate.no/public/v1/phone-numbers?limit=20" \
  -H "Authorization: Bearer $VOXIMATE_API_KEY"
Response · 200
{
  "object": "list",
  "data": [
    {
      "object": "phone_number",
      "id": "b8f2a1c4-3d5e-4f60-8a71-92b3c4d5e6f7",
      "number": "+4721000000",
      "label": "Main line",
      "agent_id": "7c3f1e90-5a44-4b21-9c07-2ed5b8f41a66",
      "status": "active",
      "capabilities": [
        "voice"
      ],
      "created_at": "2026-09-02T08:00:00.000Z"
    }
  ],
  "has_more": false,
  "next_cursor": null
}

Retrieve a phone number

get/phone-numbers/{phone_number_id}
Requiresnumbers:read

Path parameters

  • phone_number_idstring (uuid)required

    The phone number id (not the number itself).

Returns · 200

The phone number.

Show response fields
  • objectstringrequired

    Always "phone_number"

  • idstring (uuid)required
  • numberstringrequired

    E.164.

  • labelstring | nullrequired
  • agent_idstring (uuid) | nullrequired

    The agent that answers it, or null.

  • statusstringrequired
  • capabilitiesarray of stringrequired
  • created_atstring (date-time)required

Errors

  • 400The request is malformed: a missing field, a wrong type, an unknown parameter or an id that is not a UUID.
  • 401No API key, or the key is invalid, expired or revoked.
  • 403The key is valid but lacks the scope this operation needs (`missing_scope`), or — for adding, changing, testing or removing a webhook endpoint — was not made by a workspace owner or admin (`role_required`).
  • 404Nothing with that id exists in your workspace.

Every error has the same shape — see Errors.

curl "https://api.voximate.no/public/v1/phone-numbers/b8f2a1c4-3d5e-4f60-8a71-92b3c4d5e6f7" \
  -H "Authorization: Bearer $VOXIMATE_API_KEY"
Response · 200
{
  "object": "phone_number",
  "id": "b8f2a1c4-3d5e-4f60-8a71-92b3c4d5e6f7",
  "number": "+4721000000",
  "label": "Main line",
  "agent_id": "7c3f1e90-5a44-4b21-9c07-2ed5b8f41a66",
  "status": "active",
  "capabilities": [
    "voice"
  ],
  "created_at": "2026-09-02T08:00:00.000Z"
}

Assign an agent to a phone number

patch/phone-numbers/{phone_number_id}
Requiresnumbers:write

Sets which agent answers calls to this number. Send null to leave the number without an agent.

Path parameters

  • phone_number_idstring (uuid)required

    The phone number id (not the number itself).

Request body · application/json

  • agent_idstring (uuid) | nullrequired

Returns · 200

The updated number.

Show response fields
  • objectstringrequired

    Always "phone_number"

  • idstring (uuid)required
  • numberstringrequired

    E.164.

  • labelstring | nullrequired
  • agent_idstring (uuid) | nullrequired

    The agent that answers it, or null.

  • statusstringrequired
  • capabilitiesarray of stringrequired
  • created_atstring (date-time)required

Errors

  • 400The request is malformed: a missing field, a wrong type, an unknown parameter or an id that is not a UUID.
  • 401No API key, or the key is invalid, expired or revoked.
  • 403The key is valid but lacks the scope this operation needs (`missing_scope`), or — for adding, changing, testing or removing a webhook endpoint — was not made by a workspace owner or admin (`role_required`).
  • 404Nothing with that id exists in your workspace.

Every error has the same shape — see Errors.

curl -X PATCH "https://api.voximate.no/public/v1/phone-numbers/b8f2a1c4-3d5e-4f60-8a71-92b3c4d5e6f7" \
  -H "Authorization: Bearer $VOXIMATE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "agent_id": "7c3f1e90-5a44-4b21-9c07-2ed5b8f41a66"
}'
Response · 200
{
  "object": "phone_number",
  "id": "b8f2a1c4-3d5e-4f60-8a71-92b3c4d5e6f7",
  "number": "+4721000000",
  "label": "Main line",
  "agent_id": "7c3f1e90-5a44-4b21-9c07-2ed5b8f41a66",
  "status": "active",
  "capabilities": [
    "voice"
  ],
  "created_at": "2026-09-02T08:00:00.000Z"
}

Webhooks

Endpoints that receive signed events from Voximate.

List webhook endpoints

get/webhooks
Requireswebhooks:read

Query parameters

  • limitinteger

    How many items to return, 1 to 100.

    Default 20

  • cursorstring

    The next_cursor from the previous page.

Returns · 200

A page of endpoints.

Show response fields
  • objectstringrequired

    Always "list"

  • dataarray of WebhookEndpointrequired
    Show child attributes
    • objectstringrequired

      Always "webhook_endpoint"

    • idstring (uuid)required
    • urlstring (uri)required
    • eventsarray of EventTyperequired

      One ofcall.startedcall.completedcall.failedcall.transferred

    • statusstringrequired

      One ofactivepauseddisabled

    • descriptionstring | nullrequired
    • secretstring | null

      The signing secret. Returned only when the endpoint is created and when the secret is rotated. An Idempotency-Key replay of the create answers null here: the secret is kept only in the vault, never with the stored answer. Rotate it if it was lost.

    • created_atstring (date-time)required
    • updated_atstring (date-time)required
  • has_morebooleanrequired

    True when another page follows this one.

  • next_cursorstring | nullrequired

    Pass as cursor to fetch the next page. null on the last page.

Errors

  • 400The request is malformed: a missing field, a wrong type, an unknown parameter or an id that is not a UUID.
  • 401No API key, or the key is invalid, expired or revoked.
  • 403The key is valid but lacks the scope this operation needs (`missing_scope`), or — for adding, changing, testing or removing a webhook endpoint — was not made by a workspace owner or admin (`role_required`).

Every error has the same shape — see Errors.

curl "https://api.voximate.no/public/v1/webhooks?limit=20" \
  -H "Authorization: Bearer $VOXIMATE_API_KEY"
Response · 200
{
  "object": "list",
  "data": [
    {
      "object": "webhook_endpoint",
      "id": "d1e2f3a4-b5c6-4d7e-8f90-a1b2c3d4e5f6",
      "url": "https://example.com/voximate/webhooks",
      "events": [
        "call.completed",
        "call.failed"
      ],
      "status": "active",
      "description": "CRM sync",
      "created_at": "2026-10-13T08:00:00.000Z",
      "updated_at": "2026-10-13T08:00:00.000Z"
    }
  ],
  "has_more": false,
  "next_cursor": null
}

Create a webhook endpoint

post/webhooks
Requireswebhooks:write

Registers a URL that receives the events you choose. The response carries the signing secret once — store it, you need it to verify each delivery. The URL must be public https.

Headers

  • Idempotency-Keystring

    Any unique string (a UUID is ideal). Retrying a request with the same key within 24 hours returns the first answer instead of doing the work again.

Request body · application/json

  • urlstring (uri)required

    A public https URL.

  • eventsarray of EventTyperequired

    One ofcall.startedcall.completedcall.failedcall.transferred

    at least 1 item · no duplicates

  • descriptionstring

    max 500 characters

Returns · 201

The new endpoint, with its signing secret.

Show response fields
  • objectstringrequired

    Always "webhook_endpoint"

  • idstring (uuid)required
  • urlstring (uri)required
  • eventsarray of EventTyperequired

    One ofcall.startedcall.completedcall.failedcall.transferred

  • statusstringrequired

    One ofactivepauseddisabled

  • descriptionstring | nullrequired
  • secretstring | null

    The signing secret. Returned only when the endpoint is created and when the secret is rotated. An Idempotency-Key replay of the create answers null here: the secret is kept only in the vault, never with the stored answer. Rotate it if it was lost.

  • created_atstring (date-time)required
  • updated_atstring (date-time)required

Errors

  • 400The request is malformed: a missing field, a wrong type, an unknown parameter or an id that is not a UUID.
  • 401No API key, or the key is invalid, expired or revoked.
  • 403The key is valid but lacks the scope this operation needs (`missing_scope`), or — for adding, changing, testing or removing a webhook endpoint — was not made by a workspace owner or admin (`role_required`).
  • 409The Idempotency-Key was already used with a different request, or that request is still running.
  • 422The request is well-formed but cannot be carried out in the current state.

Every error has the same shape — see Errors.

curl -X POST "https://api.voximate.no/public/v1/webhooks" \
  -H "Authorization: Bearer $VOXIMATE_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
  "url": "https://example.com/voximate/webhooks",
  "events": [
    "call.completed",
    "call.failed"
  ],
  "description": "CRM sync"
}'
Response · 201
{
  "object": "webhook_endpoint",
  "id": "d1e2f3a4-b5c6-4d7e-8f90-a1b2c3d4e5f6",
  "url": "https://example.com/voximate/webhooks",
  "events": [
    "call.completed",
    "call.failed"
  ],
  "status": "active",
  "description": "CRM sync",
  "created_at": "2026-10-13T08:00:00.000Z",
  "updated_at": "2026-10-13T08:00:00.000Z",
  "secret": "whsec_6b1d0f8e2a4c47b9a3e5d7f1c9b2a4e6"
}

Retrieve a webhook endpoint

get/webhooks/{webhook_id}
Requireswebhooks:read

Path parameters

  • webhook_idstring (uuid)required

    The webhook endpoint id.

Returns · 200

The endpoint.

Show response fields
  • objectstringrequired

    Always "webhook_endpoint"

  • idstring (uuid)required
  • urlstring (uri)required
  • eventsarray of EventTyperequired

    One ofcall.startedcall.completedcall.failedcall.transferred

  • statusstringrequired

    One ofactivepauseddisabled

  • descriptionstring | nullrequired
  • secretstring | null

    The signing secret. Returned only when the endpoint is created and when the secret is rotated. An Idempotency-Key replay of the create answers null here: the secret is kept only in the vault, never with the stored answer. Rotate it if it was lost.

  • created_atstring (date-time)required
  • updated_atstring (date-time)required

Errors

  • 400The request is malformed: a missing field, a wrong type, an unknown parameter or an id that is not a UUID.
  • 401No API key, or the key is invalid, expired or revoked.
  • 403The key is valid but lacks the scope this operation needs (`missing_scope`), or — for adding, changing, testing or removing a webhook endpoint — was not made by a workspace owner or admin (`role_required`).
  • 404Nothing with that id exists in your workspace.

Every error has the same shape — see Errors.

curl "https://api.voximate.no/public/v1/webhooks/d1e2f3a4-b5c6-4d7e-8f90-a1b2c3d4e5f6" \
  -H "Authorization: Bearer $VOXIMATE_API_KEY"
Response · 200
{
  "object": "webhook_endpoint",
  "id": "d1e2f3a4-b5c6-4d7e-8f90-a1b2c3d4e5f6",
  "url": "https://example.com/voximate/webhooks",
  "events": [
    "call.completed",
    "call.failed"
  ],
  "status": "active",
  "description": "CRM sync",
  "created_at": "2026-10-13T08:00:00.000Z",
  "updated_at": "2026-10-13T08:00:00.000Z"
}

Update a webhook endpoint

patch/webhooks/{webhook_id}
Requireswebhooks:write

Change the URL, the events, the description, or pause and resume deliveries.

Path parameters

  • webhook_idstring (uuid)required

    The webhook endpoint id.

Request body · application/json

  • urlstring (uri)
  • eventsarray of EventType

    One ofcall.startedcall.completedcall.failedcall.transferred

    at least 1 item · no duplicates

  • descriptionstring | null

    max 500 characters

  • statusstring

    One ofactivepaused

Returns · 200

The updated endpoint.

Show response fields
  • objectstringrequired

    Always "webhook_endpoint"

  • idstring (uuid)required
  • urlstring (uri)required
  • eventsarray of EventTyperequired

    One ofcall.startedcall.completedcall.failedcall.transferred

  • statusstringrequired

    One ofactivepauseddisabled

  • descriptionstring | nullrequired
  • secretstring | null

    The signing secret. Returned only when the endpoint is created and when the secret is rotated. An Idempotency-Key replay of the create answers null here: the secret is kept only in the vault, never with the stored answer. Rotate it if it was lost.

  • created_atstring (date-time)required
  • updated_atstring (date-time)required

Errors

  • 400The request is malformed: a missing field, a wrong type, an unknown parameter or an id that is not a UUID.
  • 401No API key, or the key is invalid, expired or revoked.
  • 403The key is valid but lacks the scope this operation needs (`missing_scope`), or — for adding, changing, testing or removing a webhook endpoint — was not made by a workspace owner or admin (`role_required`).
  • 404Nothing with that id exists in your workspace.
  • 422The request is well-formed but cannot be carried out in the current state.

Every error has the same shape — see Errors.

curl -X PATCH "https://api.voximate.no/public/v1/webhooks/d1e2f3a4-b5c6-4d7e-8f90-a1b2c3d4e5f6" \
  -H "Authorization: Bearer $VOXIMATE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "status": "paused"
}'
Response · 200
{
  "object": "webhook_endpoint",
  "id": "d1e2f3a4-b5c6-4d7e-8f90-a1b2c3d4e5f6",
  "url": "https://example.com/voximate/webhooks",
  "events": [
    "call.completed",
    "call.failed"
  ],
  "status": "paused",
  "description": "CRM sync",
  "created_at": "2026-10-13T08:00:00.000Z",
  "updated_at": "2026-10-13T08:00:00.000Z"
}

Delete a webhook endpoint

delete/webhooks/{webhook_id}
Requireswebhooks:write

Stops all deliveries to the endpoint and deletes its signing secret.

Path parameters

  • webhook_idstring (uuid)required

    The webhook endpoint id.

Returns · 200

The endpoint was deleted.

Show response fields
  • objectstringrequired
  • idstring (uuid)required
  • deletedbooleanrequired

    Always true

Errors

  • 400The request is malformed: a missing field, a wrong type, an unknown parameter or an id that is not a UUID.
  • 401No API key, or the key is invalid, expired or revoked.
  • 403The key is valid but lacks the scope this operation needs (`missing_scope`), or — for adding, changing, testing or removing a webhook endpoint — was not made by a workspace owner or admin (`role_required`).
  • 404Nothing with that id exists in your workspace.

Every error has the same shape — see Errors.

curl -X DELETE "https://api.voximate.no/public/v1/webhooks/d1e2f3a4-b5c6-4d7e-8f90-a1b2c3d4e5f6" \
  -H "Authorization: Bearer $VOXIMATE_API_KEY"
Response · 200
{
  "object": "webhook_endpoint",
  "id": "d1e2f3a4-b5c6-4d7e-8f90-a1b2c3d4e5f6",
  "deleted": true
}

Send a test event

post/webhooks/{webhook_id}/test
Requireswebhooks:write

Sends a signed webhook.test event to the endpoint right now and reports what your server answered. Use it to check your signature verification before real calls arrive.

Path parameters

  • webhook_idstring (uuid)required

    The webhook endpoint id.

Returns · 200

What your endpoint answered.

Show response fields
  • objectstringrequired

    Always "webhook_test"

  • deliveredbooleanrequired

    True when your endpoint answered 2xx.

  • response_statusinteger | nullrequired
  • errorstring | nullrequired
  • duration_msintegerrequired

Errors

  • 400The request is malformed: a missing field, a wrong type, an unknown parameter or an id that is not a UUID.
  • 401No API key, or the key is invalid, expired or revoked.
  • 403The key is valid but lacks the scope this operation needs (`missing_scope`), or — for adding, changing, testing or removing a webhook endpoint — was not made by a workspace owner or admin (`role_required`).
  • 404Nothing with that id exists in your workspace.

Every error has the same shape — see Errors.

curl -X POST "https://api.voximate.no/public/v1/webhooks/d1e2f3a4-b5c6-4d7e-8f90-a1b2c3d4e5f6/test" \
  -H "Authorization: Bearer $VOXIMATE_API_KEY"
Response · 200
{
  "object": "webhook_test",
  "delivered": true,
  "response_status": 200,
  "error": null,
  "duration_ms": 184
}

Rotate the signing secret

post/webhooks/{webhook_id}/rotate-secret
Requireswebhooks:write

Replaces the signing secret and returns the new one once. Deliveries are signed with the new secret from the next event.

Path parameters

  • webhook_idstring (uuid)required

    The webhook endpoint id.

Returns · 200

The endpoint with its new secret.

Show response fields
  • objectstringrequired

    Always "webhook_endpoint"

  • idstring (uuid)required
  • urlstring (uri)required
  • eventsarray of EventTyperequired

    One ofcall.startedcall.completedcall.failedcall.transferred

  • statusstringrequired

    One ofactivepauseddisabled

  • descriptionstring | nullrequired
  • secretstring | null

    The signing secret. Returned only when the endpoint is created and when the secret is rotated. An Idempotency-Key replay of the create answers null here: the secret is kept only in the vault, never with the stored answer. Rotate it if it was lost.

  • created_atstring (date-time)required
  • updated_atstring (date-time)required

Errors

  • 400The request is malformed: a missing field, a wrong type, an unknown parameter or an id that is not a UUID.
  • 401No API key, or the key is invalid, expired or revoked.
  • 403The key is valid but lacks the scope this operation needs (`missing_scope`), or — for adding, changing, testing or removing a webhook endpoint — was not made by a workspace owner or admin (`role_required`).
  • 404Nothing with that id exists in your workspace.

Every error has the same shape — see Errors.

curl -X POST "https://api.voximate.no/public/v1/webhooks/d1e2f3a4-b5c6-4d7e-8f90-a1b2c3d4e5f6/rotate-secret" \
  -H "Authorization: Bearer $VOXIMATE_API_KEY"
Response · 200
{
  "object": "webhook_endpoint",
  "id": "d1e2f3a4-b5c6-4d7e-8f90-a1b2c3d4e5f6",
  "url": "https://example.com/voximate/webhooks",
  "events": [
    "call.completed",
    "call.failed"
  ],
  "status": "active",
  "description": "CRM sync",
  "created_at": "2026-10-13T08:00:00.000Z",
  "updated_at": "2026-10-13T08:00:00.000Z",
  "secret": "whsec_0e9d8c7b6a5f4e3d2c1b0a9f8e7d6c5b"
}

List deliveries

get/webhooks/{webhook_id}/deliveries
Requireswebhooks:read

Recent delivery attempts to this endpoint, newest first, with the status code your server answered.

Path parameters

  • webhook_idstring (uuid)required

    The webhook endpoint id.

Query parameters

  • limitinteger

    How many items to return, 1 to 100.

    Default 20

  • cursorstring

    The next_cursor from the previous page.

Returns · 200

A page of deliveries.

Show response fields
  • objectstringrequired

    Always "list"

  • dataarray of WebhookDeliveryrequired
    Show child attributes
    • objectstringrequired

      Always "webhook_delivery"

    • idstring (uuid)required
    • event_typestringrequired
    • statusstringrequired

      One ofdeliveredfailedpending

    • response_statusinteger | nullrequired
    • attemptsintegerrequired
    • errorstring | nullrequired
    • created_atstring (date-time)required
    • delivered_atstring (date-time) | nullrequired
  • has_morebooleanrequired

    True when another page follows this one.

  • next_cursorstring | nullrequired

    Pass as cursor to fetch the next page. null on the last page.

Errors

  • 400The request is malformed: a missing field, a wrong type, an unknown parameter or an id that is not a UUID.
  • 401No API key, or the key is invalid, expired or revoked.
  • 403The key is valid but lacks the scope this operation needs (`missing_scope`), or — for adding, changing, testing or removing a webhook endpoint — was not made by a workspace owner or admin (`role_required`).
  • 404Nothing with that id exists in your workspace.

Every error has the same shape — see Errors.

curl "https://api.voximate.no/public/v1/webhooks/d1e2f3a4-b5c6-4d7e-8f90-a1b2c3d4e5f6/deliveries?limit=20" \
  -H "Authorization: Bearer $VOXIMATE_API_KEY"
Response · 200
{
  "object": "list",
  "data": [
    {
      "object": "webhook_delivery",
      "id": "a9b8c7d6-e5f4-4a3b-9c2d-1e0f9a8b7c6d",
      "event_type": "call.completed",
      "status": "delivered",
      "response_status": 200,
      "attempts": 1,
      "error": null,
      "created_at": "2026-10-12T10:07:52.000Z",
      "delivered_at": "2026-10-12T10:07:52.000Z"
    }
  ],
  "has_more": false,
  "next_cursor": null
}

Usage

Call counts and minutes for a period.

Retrieve usage

get/usage
Requiresanalytics:read

Calls and minutes for a period. Defaults to the last 30 days.

Query parameters

  • startstring (date-time)

    Start of the period (ISO 8601). Default: 30 days ago.

  • endstring (date-time)

    End of the period (ISO 8601). Default: now.

Returns · 200

Usage for the period.

Show response fields
  • objectstringrequired

    Always "usage"

  • periodobjectrequired
    Show child attributes
    • startstring (date-time)required
    • endstring (date-time)required
  • callsintegerrequired
  • minutesintegerrequired

    Call minutes in the period, rounded.

  • average_duration_secondsintegerrequired
  • outcomesmap of integerrequired

    Calls per outcome from each call’s AI analysis (resolved, escalated, abandoned, transferred, unknown). Calls without an analysis yet are not counted, so the total can be below calls.

Errors

  • 400The request is malformed: a missing field, a wrong type, an unknown parameter or an id that is not a UUID.
  • 401No API key, or the key is invalid, expired or revoked.
  • 403The key is valid but lacks the scope this operation needs (`missing_scope`), or — for adding, changing, testing or removing a webhook endpoint — was not made by a workspace owner or admin (`role_required`).

Every error has the same shape — see Errors.

curl "https://api.voximate.no/public/v1/usage" \
  -H "Authorization: Bearer $VOXIMATE_API_KEY"
Response · 200
{
  "object": "usage",
  "period": {
    "start": "2026-09-13T00:00:00.000Z",
    "end": "2026-10-13T00:00:00.000Z"
  },
  "calls": 281,
  "minutes": 577,
  "average_duration_seconds": 126,
  "outcomes": {
    "resolved": 190,
    "escalated": 12,
    "abandoned": 21,
    "transferred": 9,
    "unknown": 49
  }
}

Events

What Voximate posts to your webhook endpoints. Each delivery is signed — see Verifying signatures.

call.started

A call was answered and the agent is on the line.

call.started · payload
{
  "id": "evt_5f0c2b9a7d3e4c1f8a6b2d9e0c4f7a13",
  "object": "event",
  "type": "call.started",
  "api_version": "v1",
  "created_at": "2026-10-12T10:07:51.000Z",
  "data": {
    "object": {
      "object": "call",
      "id": "3c27f11c-8a1e-4d55-9b0e-1f4c2a7d9e10",
      "agent_id": "7c3f1e90-5a44-4b21-9c07-2ed5b8f41a66",
      "direction": "outbound",
      "channel": "phone",
      "status": "in_progress",
      "from": "+4721000000",
      "to": "+4712345678",
      "started_at": "2026-10-12T10:04:12.000Z",
      "ended_at": null,
      "duration_seconds": null,
      "end_reason": null,
      "metadata": {
        "crm_contact_id": "48213"
      },
      "has_recording": false,
      "analysis": null
    }
  }
}

call.completed

A call has ended and its analysis is ready. data.object is the call, with analysis filled in.

call.completed · payload
{
  "id": "evt_5f0c2b9a7d3e4c1f8a6b2d9e0c4f7a13",
  "object": "event",
  "type": "call.completed",
  "api_version": "v1",
  "created_at": "2026-10-12T10:07:51.000Z",
  "data": {
    "object": {
      "object": "call",
      "id": "3c27f11c-8a1e-4d55-9b0e-1f4c2a7d9e10",
      "agent_id": "7c3f1e90-5a44-4b21-9c07-2ed5b8f41a66",
      "direction": "outbound",
      "channel": "phone",
      "status": "completed",
      "from": "+4721000000",
      "to": "+4712345678",
      "started_at": "2026-10-12T10:04:12.000Z",
      "ended_at": "2026-10-12T10:07:33.000Z",
      "duration_seconds": 201,
      "end_reason": "caller_hangup",
      "metadata": {
        "crm_contact_id": "48213"
      },
      "has_recording": true,
      "analysis": {
        "summary": "The caller booked a check-up on Tuesday 14 October at 12:00.",
        "outcome": "resolved",
        "sentiment": "positive",
        "action_items": [
          "Send booking confirmation by SMS"
        ],
        "created_at": "2026-10-12T10:07:51.000Z"
      }
    }
  }
}

call.failed

A call out was never connected. data.reason says why: no_answer (it rang out or was declined), busy, or not_connected (the number or the network refused it). Sent once per call.

call.failed · payload
{
  "id": "evt_5f0c2b9a7d3e4c1f8a6b2d9e0c4f7a13",
  "object": "event",
  "type": "call.failed",
  "api_version": "v1",
  "created_at": "2026-10-12T10:07:51.000Z",
  "data": {
    "object": {
      "object": "call",
      "id": "3c27f11c-8a1e-4d55-9b0e-1f4c2a7d9e10",
      "agent_id": "7c3f1e90-5a44-4b21-9c07-2ed5b8f41a66",
      "direction": "outbound",
      "channel": "phone",
      "status": "failed",
      "from": "+4721000000",
      "to": "+4712345678",
      "started_at": "2026-10-12T10:04:12.000Z",
      "ended_at": "2026-10-12T10:07:33.000Z",
      "duration_seconds": 0,
      "end_reason": "caller_hangup",
      "metadata": {
        "crm_contact_id": "48213"
      },
      "has_recording": false,
      "analysis": null
    },
    "reason": "no_answer"
  }
}

call.transferred

The agent transferred the caller to a person or another number.

call.transferred · payload
{
  "id": "evt_5f0c2b9a7d3e4c1f8a6b2d9e0c4f7a13",
  "object": "event",
  "type": "call.transferred",
  "api_version": "v1",
  "created_at": "2026-10-12T10:07:51.000Z",
  "data": {
    "object": {
      "object": "call",
      "id": "3c27f11c-8a1e-4d55-9b0e-1f4c2a7d9e10",
      "agent_id": "7c3f1e90-5a44-4b21-9c07-2ed5b8f41a66",
      "direction": "outbound",
      "channel": "phone",
      "status": "in_progress",
      "from": "+4721000000",
      "to": "+4712345678",
      "started_at": "2026-10-12T10:04:12.000Z",
      "ended_at": "2026-10-12T10:07:33.000Z",
      "duration_seconds": 201,
      "end_reason": "caller_hangup",
      "metadata": {
        "crm_contact_id": "48213"
      },
      "has_recording": true,
      "analysis": null
    },
    "transferred_to": "+4712345670"
  }
}

webhook.test

Sent by "Send test event" in the dashboard and by POST /webhooks/{webhook_id}/test.

webhook.test · payload
{
  "id": "evt_0d1c2b3a4f5e6d7c8b9a0f1e2d3c4b5a",
  "object": "event",
  "type": "webhook.test",
  "api_version": "v1",
  "created_at": "2026-10-13T08:01:00.000Z",
  "data": {
    "message": "This is a test event from Voximate."
  }
}

Objects

The resources the API returns, field by field.

Agent

  • objectstringrequired

    Always "agent"

  • idstring (uuid)required
  • namestringrequired
  • descriptionstring | nullrequired
  • statusstringrequired

    Only a published agent answers phone calls and can place outbound calls.

    One ofdraftpublishedunpublishedarchived

  • languagestring | nullrequired

    BCP 47 tag, for example nb-NO or en-US.

  • system_promptstring | nullrequired

    The instructions the agent follows on every call.

  • first_messagestring | nullrequired

    What the agent says when it picks up.

  • outbound_first_messagestring | nullrequired

    What the agent says first on calls it makes. When null, those calls open with first_message. A call can set its own with first_message on POST /calls.

  • voiceobjectrequired
    Show child attributes
    • providerstring | nullrequired
    • voice_idstring | nullrequired
  • llmobjectrequired
    Show child attributes
    • providerstring | nullrequired
    • modelstring | nullrequired
  • created_atstring (date-time)required
  • updated_atstring (date-time)required

Call

  • objectstringrequired

    Always "call"

  • idstring (uuid)required
  • agent_idstring (uuid) | nullrequired
  • directionstringrequired

    One ofinboundoutbound

  • channelstringrequired

    phone for calls over the phone network, web for browser and widget calls.

    One ofphoneweb

  • statusstringrequired

    One ofqueuedringingin_progresscompletedfailedno_answerbusycanceled

  • fromstring | nullrequired

    The calling number (E.164), when known.

  • tostring | nullrequired

    The called number (E.164), when known.

  • started_atstring (date-time)required
  • ended_atstring (date-time) | nullrequired
  • duration_secondsinteger | nullrequired
  • end_reasonstring | nullrequired

    Why the call ended, for example caller_hangup.

  • metadatamap of stringrequired

    The metadata you sent when you started the call.

  • has_recordingboolean | nullrequired

    Whether a recording exists. null in lists, where it is not looked up.

  • analysisCallAnalysis | nullrequired

    Filled in shortly after the call ends. Always null in lists.

    Show child attributes
    • summarystringrequired
    • outcomestring | nullrequired

      For example resolved, escalated, abandoned.

    • sentimentstring | nullrequired

      One ofpositiveneutralnegative

    • action_itemsarray of stringrequired
    • created_atstring (date-time) | nullrequired

CallAnalysis

  • summarystringrequired
  • outcomestring | nullrequired

    For example resolved, escalated, abandoned.

  • sentimentstring | nullrequired

    One ofpositiveneutralnegative

  • action_itemsarray of stringrequired
  • created_atstring (date-time) | nullrequired

TranscriptEntry

  • indexintegerrequired
  • rolestringrequired

    One ofagentcaller

  • textstringrequired

PhoneNumber

  • objectstringrequired

    Always "phone_number"

  • idstring (uuid)required
  • numberstringrequired

    E.164.

  • labelstring | nullrequired
  • agent_idstring (uuid) | nullrequired

    The agent that answers it, or null.

  • statusstringrequired
  • capabilitiesarray of stringrequired
  • created_atstring (date-time)required

WebhookEndpoint

  • objectstringrequired

    Always "webhook_endpoint"

  • idstring (uuid)required
  • urlstring (uri)required
  • eventsarray of EventTyperequired

    One ofcall.startedcall.completedcall.failedcall.transferred

  • statusstringrequired

    One ofactivepauseddisabled

  • descriptionstring | nullrequired
  • secretstring | null

    The signing secret. Returned only when the endpoint is created and when the secret is rotated. An Idempotency-Key replay of the create answers null here: the secret is kept only in the vault, never with the stored answer. Rotate it if it was lost.

  • created_atstring (date-time)required
  • updated_atstring (date-time)required

WebhookDelivery

  • objectstringrequired

    Always "webhook_delivery"

  • idstring (uuid)required
  • event_typestringrequired
  • statusstringrequired

    One ofdeliveredfailedpending

  • response_statusinteger | nullrequired
  • attemptsintegerrequired
  • errorstring | nullrequired
  • created_atstring (date-time)required
  • delivered_atstring (date-time) | nullrequired

Usage

  • objectstringrequired

    Always "usage"

  • periodobjectrequired
    Show child attributes
    • startstring (date-time)required
    • endstring (date-time)required
  • callsintegerrequired
  • minutesintegerrequired

    Call minutes in the period, rounded.

  • average_duration_secondsintegerrequired
  • outcomesmap of integerrequired

    Calls per outcome from each call’s AI analysis (resolved, escalated, abandoned, transferred, unknown). Calls without an analysis yet are not counted, so the total can be below calls.

Event

  • idstringrequired

    Unique per event. The same event retried keeps its id: use it to drop duplicates.

  • objectstringrequired

    Always "event"

  • typestringrequired
  • api_versionstringrequired

    Always "v1"

  • created_atstring (date-time)required
  • dataobjectrequired

    For call events, data.object is the call.

Error

  • errorobjectrequired
    Show child attributes
    • typestringrequired

      The broad category. Branch on this.

      One ofinvalid_request_errorauthentication_errorpermission_errornot_found_erroridempotency_errorrate_limit_errorapi_error

    • codestringrequired

      A stable, specific code, for example missing_scope.

    • messagestringrequired

      A human-readable explanation. Wording may change.

    • paramstring | nullrequired

      The parameter the error is about, when there is one.

  • request_idstringrequired

    Same as the X-Request-Id header.