API v1 · Production

Build on the Voxiomni voice platform.

Create and publish voice agents, purchase and manage phone numbers, retrieve calls and recordings, inspect quality audits, and receive signed events when processing finishes.

Get started Download OpenAPI specification

Base URLhttps://api.voxiomni.com/api/v1

Core concepts

Authentication

Create an API key in Settings → Development. Send it as a Bearer token on every request. A key belongs to one workspace and is shown only once when it is created.

Granular scopes

Grant only the permissions an integration needs. Scope checks are performed independently for every operation.

agents:readRead agents
agents:writeCreate and update agent drafts
agents:publishPublish agent drafts
phone_numbers:readRead phone numbers
phone_numbers:writeSearch, purchase, and release numbers
calls:readRead calls, transcripts, and analysis
recordings:readDownload recordings
quality:readRead quality audits

cURL

curl https://api.voxiomni.com/api/v1/agents \
  -H "Authorization: Bearer $VOXIOMNI_API_KEY" \
  -H "Accept: application/json"

Keep keys server-side.

Never expose an API key in browser code, mobile applications, public repositories, logs, or support screenshots. Revoke a key immediately if it is disclosed.

Core concepts

Responses and errors

JSON properties use camelCase. Enum values returned by the API use lower camel case. Send Content-Type: application/json whenever a request has a JSON body.

Error response

{
  "code": "validation_error",
  "message": "Complete the required agent fields."
}

200Request succeeded

201Resource created

204Succeeded with no body

400Invalid input or query

401Missing, invalid, or revoked key

403Required scope is missing

404Resource not found

409State or ownership conflict

500Unexpected server error

Error codes

code	HTTP status	Meaning
`validation_error`	400	The request body, path, date range, or query is invalid.
`unauthorized`	401	The Bearer token is missing, malformed, invalid, or revoked.
`forbidden`	403	The key does not contain the required scope.
`not_found`	404	The resource does not exist in the key's workspace.
`conflict`	409	The state change cannot be completed, for example because a number is assigned.
`internal_error`	500	An unexpected error occurred.

API reference

Agents

Agent changes are saved as a draft. Creating or updating an agent does not make the draft live; call the publish operation after the draft is ready. Phone number associations are controlled by phoneNumberIds.

GET/agentsagents:read

List agents

Returns every agent in the authenticated workspace. No query parameters are accepted.

200 OKAgent[] — an array that may be empty.

Request

curl https://api.voxiomni.com/api/v1/agents \
  -H "Authorization: Bearer $VOXIOMNI_API_KEY"

Response example

[
  {
    "id": "agent_8d41f3d4f6324af2b77b3b183f923f4c",
    "name": "Collections assistant",
    "purpose": "Negotiate overdue invoices",
    "status": "active",
    "language": "Português (Brasil)",
    "voice": "Clara",
    "model": "advanced",
    "greeting": "Hello, may I speak with {{name}}?",
    "instructions": "Confirm identity before discussing an invoice.",
    "transferNumber": "+551130000000",
    "phoneNumberIds": ["pn_38a04ad5"],
    "phoneNumbers": ["+55 11 3000-0000"],
    "knowledgeSources": [],
    "toolIds": [],
    "structuredDataSources": [],
    "recording": { "enabled": true, "retentionDays": 30 },
    "advanced": { "responseStyle": "Balanced", "voiceExpressiveness": "Moderate", "inactivityTimeoutSeconds": 60, "interruptionSensitivity": "Medium" },
    "quality": { "enabled": false, "auditPercentage": 10, "criteria": [] },
    "published": true,
    "updatedAt": "2026-10-11T18:32:14Z"
  }
]

GET/agents/{agentId}agents:read

Retrieve an agent

Returns one agent from the authenticated workspace.

Path parameter	Type	Required	Description
`agentId`	string	Yes	The agent ID, such as `agent_8d41...`.

200 OKAgent response object.

Request

curl https://api.voxiomni.com/api/v1/agents/agent_8d41f3d4f6324af2b77b3b183f923f4c \
  -H "Authorization: Bearer $VOXIOMNI_API_KEY"

Errors: 401, 403, 404.

POST/agentsagents:write

Create an agent draft

Creates a new agent and stores its first draft. The request body is the complete Agent write object.

201 CreatedThe created Agent response object.

Request JSON

{
  "name": "Collections assistant",
  "purpose": "Negotiate overdue invoices",
  "status": "active",
  "language": "Português (Brasil)",
  "voice": "Clara",
  "greeting": "Hello, may I speak with {{name}}?",
  "instructions": "Confirm identity before discussing an invoice.",
  "transferNumber": "+551130000000",
  "phoneNumberIds": [],
  "model": "advanced",
  "knowledgeSources": [],
  "toolIds": [],
  "structuredDataSources": [],
  "recording": { "enabled": true, "retentionDays": 30 },
  "advanced": {
    "responseStyle": "Balanced",
    "voiceExpressiveness": "Moderate",
    "inactivityTimeoutSeconds": 60,
    "interruptionSensitivity": "Medium"
  },
  "quality": { "enabled": false, "auditPercentage": 10, "criteria": [] },
  "testCallerNumber": null
}

cURL

curl -X POST \
  https://api.voxiomni.com/api/v1/agents \
  -H "Authorization: Bearer $VOXIOMNI_API_KEY" \
  -H "Content-Type: application/json" \
  --data @agent.json

Draft only

After a successful create, call POST /agents/{agentId}/publish before expecting production calls to use this configuration.

Errors: 400 for missing required fields, invalid quality settings, or foreign workspace IDs; 409 if a selected number belongs to another agent.

PUT/agents/{agentId}agents:write

Replace an agent draft

Replaces the draft configuration. This is a full update, not a patch: send every required field and every association that must remain. Omitting an optional collection clears it.

Input	Required	Description
`agentId` path parameter	Yes	ID of the agent to update.
JSON body	Yes	Complete Agent write object, using the same shape as `POST /agents`.

200 OKThe updated Agent response object. Production keeps using the previous published version until you publish again.

Request

curl -X PUT \
  https://api.voxiomni.com/api/v1/agents/agent_8d41f3d4f6324af2b77b3b183f923f4c \
  -H "Authorization: Bearer $VOXIOMNI_API_KEY" \
  -H "Content-Type: application/json" \
  --data @agent.json

Errors: 400, 404, 409.

POST/agents/{agentId}/publishagents:publish

Publish an agent draft

Promotes the current draft to production and applies its phone number routing. This request has no body.

200 OKThe published Agent response object, with published: true.

Request

curl -X POST \
  https://api.voxiomni.com/api/v1/agents/agent_8d41f3d4f6324af2b77b3b183f923f4c/publish \
  -H "Authorization: Bearer $VOXIOMNI_API_KEY"

Errors: 404 if the agent does not exist; 409 if a selected number is no longer available.

API reference

Phone numbers

Search and purchase Voxiomni numbers, inspect workspace numbers, and release numbers that are no longer assigned. Custom routing configuration is not exposed in API v1.

GET/phone-numbersphone_numbers:read

List owned phone numbers

Returns all phone numbers owned by the workspace, sorted by number.

200 OKPhoneNumber[] — an array that may be empty.

Request

curl https://api.voxiomni.com/api/v1/phone-numbers \
  -H "Authorization: Bearer $VOXIOMNI_API_KEY"

Response example

[
  {
    "id": "pn_38a04ad5",
    "number": "+551130000000",
    "formatted": "+55 11 3000-0000",
    "locality": "São Paulo",
    "region": "SP",
    "country": "BR",
    "currency": "BRL",
    "monthlyPrice": 47.90,
    "status": "active",
    "agentId": "agent_8d41f3d4f6324af2b77b3b183f923f4c",
    "connectionType": "voxiomniNumber",
    "purchasedAt": "2026-10-11T18:32:14Z"
  }
]

GET/phone-numbers/availablephone_numbers:write

Search available phone numbers

Searches provider inventory. Use the returned id as providerNumberId when purchasing.

Query parameter	Type	Required	Description
`contains`	string	No	Digits or area code that should appear in the number.

200 OKPhoneNumber[] with status: "available".

Request

curl "https://api.voxiomni.com/api/v1/phone-numbers/available?contains=11" \
  -H "Authorization: Bearer $VOXIOMNI_API_KEY"

POST/phone-numbersphone_numbers:write

Purchase a phone number

Purchases a number from current provider inventory and creates a recurring charge. Assign it to an active agent immediately or leave it reserved.

Body property	Type	Required	Description
`providerNumberId`	string	Yes	The `id` returned by `GET /phone-numbers/available`.
`agentId`	string \| null	No	An active agent in the same workspace. Use `null` to keep the number reserved.

201 CreatedThe purchased PhoneNumber object.

Request JSON

{
  "providerNumberId": "PN8f2d07b3a7",
  "agentId": "agent_8d41f3d4f6324af2b77b3b183f923f4c"
}

Response JSON

{
  "id": "pn_38a04ad5",
  "number": "+551130000000",
  "formatted": "+55 11 3000-0000",
  "locality": "São Paulo",
  "region": "SP",
  "country": "BR",
  "currency": "BRL",
  "monthlyPrice": 47.90,
  "status": "active",
  "agentId": "agent_8d41f3d4f6324af2b77b3b183f923f4c",
  "connectionType": "voxiomniNumber",
  "purchasedAt": "2026-10-11T18:32:14Z"
}

Errors: 400 for a missing ID, foreign workspace agent, or inactive agent; 404 if the billing wallet is unavailable; 409 for insufficient balance or changed inventory.

GET/phone-numbers/{phoneNumberId}phone_numbers:read

Retrieve a phone number

Returns one number owned by the authenticated workspace.

Path parameter	Type	Required	Description
`phoneNumberId`	string	Yes	The Voxiomni phone number ID, not the E.164 number.

200 OKA PhoneNumber object, using the fields in the purchase example.

Request

curl https://api.voxiomni.com/api/v1/phone-numbers/pn_38a04ad5 \
  -H "Authorization: Bearer $VOXIOMNI_API_KEY"

Errors: 404 if the number is not owned by the workspace.

DELETE/phone-numbers/{phoneNumberId}phone_numbers:write

Release a phone number

Permanently releases the number at the provider. Remove it from its agent, save the agent, and publish that agent before releasing the number.

204 No ContentNo response body.

Request

curl -X DELETE \
  https://api.voxiomni.com/api/v1/phone-numbers/pn_38a04ad5 \
  -H "Authorization: Bearer $VOXIOMNI_API_KEY"

Errors: 404 if it does not exist; 409 if still assigned.

API reference

Calls

Read calls and post-processing results. Calls are retained for 90 days. A request may cover at most 90 days; when dates are omitted, the API returns the latest 30-day window.

GET/callscalls:read

List calls

Query parameter	Type	Required	Default	Description
`from`	date-time	No	30 days before `to`	Inclusive beginning, ISO 8601.
`to`	date-time	No	Current UTC time	Exclusive end, ISO 8601.
`customerPhone`	string	No	—	Filter by caller/customer number.
`agent`	string	No	—	Filter by agent name or identifier.
`outcome`	enum	No	—	`unresolved`, `resolved`, or `transferred`.
`page`	integer	No	1	1-based page number.
`pageSize`	integer	No	50	Clamped to 1–50.

200 OKA CallPage with items, total, page, pageSize, and totalPages.

Request

curl "https://api.voxiomni.com/api/v1/calls?from=2026-10-01T00:00:00Z&to=2026-11-01T00:00:00Z&outcome=resolved&page=1&pageSize=50" \
  -H "Authorization: Bearer $VOXIOMNI_API_KEY"

Response example

{
  "items": [{
    "id": "call_748cfe8c",
    "caller": "+5511999999999",
    "calledNumber": "+551130000000",
    "agentId": "agent_8d41f3d4f6324af2b77b3b183f923f4c",
    "agentName": "Collections assistant",
    "startedAt": "2026-10-11T18:30:00Z",
    "endedAt": "2026-10-11T18:32:14Z",
    "durationSeconds": 134,
    "status": "completed",
    "outcome": "resolved",
    "summary": "Customer accepted the payment plan.",
    "recording": { "available": true, "status": "available", "contentType": "audio/mpeg", "durationSeconds": 134, "expiresAt": "2026-11-10T18:32:14Z" },
    "transcription": { "status": "completed", "completedAt": "2026-10-11T18:33:01Z", "error": null },
    "analysis": { "status": "completed", "summary": "Customer accepted the payment plan.", "primaryReason": "Debt negotiation", "result": "Payment plan accepted", "sentiment": "neutral", "resolutionStatus": "resolved", "topics": ["invoice", "payment plan"], "nextSteps": [], "completedAt": "2026-10-11T18:33:10Z", "error": null },
    "transcript": [],
    "quality": { "selected": true, "status": "completed", "score": 96, "completedAt": "2026-10-11T18:34:00Z" },
    "processedAt": "2026-10-11T18:34:01Z"
  }],
  "total": 1,
  "page": 1,
  "pageSize": 50,
  "totalPages": 1
}

Errors: 400 if from >= to or the interval exceeds 90 days.

GET/calls/{callId}calls:read

Retrieve a call

Returns one call including recording state, transcription state, transcript, analysis, and quality state.

Path parameter	Type	Required	Description
`callId`	string	Yes	The Voxiomni call ID.

200 OKA complete Call object.

Request

curl https://api.voxiomni.com/api/v1/calls/call_748cfe8c \
  -H "Authorization: Bearer $VOXIOMNI_API_KEY"

Errors: 404 when the call does not exist or passed retention.

GET/calls/{callId}/recordingrecordings:read

Download a call recording

Streams recording bytes. The response is not JSON. Use the response Content-Type to determine the format. HTTP range requests are supported.

200 OKBinary response body with the stored recording's media type.

Request

curl https://api.voxiomni.com/api/v1/calls/call_748cfe8c/recording \
  -H "Authorization: Bearer $VOXIOMNI_API_KEY" \
  --output recording.bin

Errors: 404 when the call or recording is absent, disabled, pending, or expired.

API reference

Quality audits

Read audits selected by each agent's quality sampling configuration. The API is read-only; reviewers complete or correct reviews in the Voxiomni app.

GET/quality-auditsquality:read

List quality audits

Query parameter	Type	Required	Default	Description
`from`	date-time	No	30 days before `to`	Inclusive beginning, ISO 8601.
`to`	date-time	No	Current UTC time	Exclusive end, ISO 8601.
`agentId`	string	No	—	Return audits for one agent.
`reviewStatus`	enum	No	—	`pending` or `reviewed`.
`page`	integer	No	1	1-based page number.
`pageSize`	integer	No	25	Clamped to 1–50.

200 OKA QualityAuditPage with items, page, pageSize, total, and totalPages.

Request

curl "https://api.voxiomni.com/api/v1/quality-audits?reviewStatus=pending&page=1&pageSize=25" \
  -H "Authorization: Bearer $VOXIOMNI_API_KEY"

GET/quality-audits/{callId}quality:read

Retrieve a quality audit

Looks up an audit by call ID and returns the audit, associated transcript, and recording availability.

Path parameter	Type	Required	Description
`callId`	string	Yes	The call ID, not the audit's own `id`.

200 OKAn object with audit, transcript, and recordingAvailable.

Response JSON

{
  "audit": {
    "id": "audit_2c7076aa",
    "callId": "call_748cfe8c",
    "agentId": "agent_8d41f3d4f6324af2b77b3b183f923f4c",
    "agentName": "Collections assistant",
    "caller": "+5511999999999",
    "callStartedAt": "2026-10-11T18:30:00Z",
    "callDurationSeconds": 134,
    "status": "completed",
    "score": 96,
    "summary": "The required identity check was completed.",
    "improvementSuggestion": "Repeat the due date before closing.",
    "findings": [{
      "criterionId": "criterion_identity",
      "criterionName": "Confirm identity",
      "severity": "critical",
      "verdict": "passed",
      "explanation": "The customer confirmed their identity.",
      "confidence": 0.98,
      "evidence": [{ "timestamp": "00:00:03", "speaker": "customer", "quote": "Yes, this is Carlos." }],
      "review": null
    }],
    "error": null,
    "completedAt": "2026-10-11T18:34:00Z",
    "reviewStatus": "pending",
    "reviewedAt": null
  },
  "transcript": [
    { "id": "msg_1", "role": "agent", "speaker": "Agent", "text": "May I speak with Carlos?", "timestamp": "00:00:00" },
    { "id": "msg_2", "role": "customer", "speaker": "Customer", "text": "Yes, this is Carlos.", "timestamp": "00:00:03" }
  ],
  "recordingAvailable": true
}

Errors: 404 when no audit exists for the call.

Data models

Agent models

Agent write object

This complete object is required by both POST /agents and PUT /agents/{agentId}. Optional fields use the documented defaults.

Property	Type	Required	Accepted values / behavior
`name`	string	Yes	Display name. Outer whitespace is removed.
`purpose`	string	Yes	Business objective.
`status`	enum	Yes	`inactive` or `active`.
`language`	enum	Yes	Exact label from Supported languages.
`voice`	enum	Yes	Exact, case-sensitive voice name compatible with `model`. See Models and voices.
`greeting`	string	Yes	First message spoken by the agent.
`instructions`	string	Yes	System instructions and operational rules.
`transferNumber`	string \| null	No	E.164 human transfer destination; blank becomes `null`.
`phoneNumberIds`	string[]	No	Owned number IDs. Every number must be unassigned or already assigned to this agent. Default `[]`.
`model`	enum	Yes	`standard`, `advanced`, or `premium`. See Models and voices.
`knowledgeSources`	object[]	No	Required `knowledgeBaseId` and `usageInstructions` per item. Default `[]`.
`toolIds`	string[]	No	Existing REST tool IDs in the workspace. Default `[]`.
`structuredDataSources`	object[]	No	Required `schemaId` and `usageInstructions` per item. Default `[]`.
`recording.enabled`	boolean	No	Default `false`.
`recording.retentionDays`	integer	No	`7`, `30`, `60`, or `90`; otherwise normalized to `30`.
`advanced.responseStyle`	string	No	Case-sensitive: `Precise`, `Balanced`, or `Creative`. Default `Balanced`.
`advanced.voiceExpressiveness`	string	No	Case-sensitive: `Low`, `Moderate`, or `High`. Default `Moderate`.
`advanced.inactivityTimeoutSeconds`	integer	No	`30`, `60`, or `90`. Default `60`.
`advanced.interruptionSensitivity`	string	No	Case-sensitive: `Low`, `Medium`, or `High`. Default `Medium`.
`quality.enabled`	boolean	No	Enables quality sampling. Default `false`.
`quality.auditPercentage`	integer	No	0–100; must be greater than zero when enabled. Default `10`.
`quality.criteria`	object[]	No	Up to 50. Each has optional `id`, required `name` (max 120) and `rule` (max 2,000), `severity` (`low`, `medium`, `high`, `critical`), and `enabled`.
`testCallerNumber`	string \| null	No	Caller number allowed to test the current draft when supported.

Agent response object

Property	Type	Description
`id`	string	Stable agent ID.
`name`, `purpose`, `status`, `language`, `voice`, `model`, `greeting`, `instructions`, `transferNumber`	mixed	The saved draft configuration.
`phoneNumberIds`	string[]	Associated number IDs.
`phoneNumbers`	string[]	Formatted associated numbers.
`knowledgeSources`, `toolIds`, `structuredDataSources`	arrays	Saved workspace resource associations.
`recording`, `advanced`, `quality`	objects	Normalized versions of the corresponding write objects.
`published`	boolean	Whether a production version exists; it does not mean the latest draft is published.
`updatedAt`	date-time	Last draft or publish update.

Data models

Enums and supported values

Send enum values exactly as shown. JSON enums use lower camel case unless a field is explicitly marked as case-sensitive.

Agent models and compatible voices

The public API exposes Voxiomni's commercial tiers only. Send and receive one of the three model values below; internal implementation identifiers are not part of the public contract.

Tier	`model` value	Compatible `voice` values
Economy	`standard`	`Marin`, `Cedar`, `Coral`, `Sage`, `Verse`, `Alloy`, `Ash`, `Ballad`, `Echo`, `Shimmer`
Advanced	`advanced`	`Clara`, `Rafael`
Premium	`premium`	`Fernanda`, `Joana`, `Roberta`, `Cassia`, `Carla`, `Karen`, `Ana`, `Wil`, `Diego`, `Ale`, `Mario`, `Matheus`, `Jon`, `Adam`

Model and voice must match.

Voice names are case-sensitive. Select a voice from the same row as the requested model; changing tiers normally requires changing the voice as well.

Supported languages

The following exact labels are supported by the agent editor and public API:

English (US)Português (Brasil)EspañolFrançaisDeutschItalianoNederlandsPolskiРусскийУкраїнськаالعربيةעבריתहिन्दीاردوفارسی中文日本語한국어Bahasa IndonesiaBahasa MelayuไทยTiếng ViệtTürkçeSvenskaNorskDanskSuomiČeštinaSlovenčinaMagyarRomânăБългарскиΕλληνικάCatalàHrvatskiSrpskiSlovenščinaEestiLatviešuLietuviųÍslenskaМакедонскиBosanskiՀայերենAzərbaycan diliБеларускаяҚазақ тіліKiswahiliTagalogதமிழ்ಕನ್ನಡमराठीनेपालीGalegoCymraegMāoriAfrikaans

Enum reference

Context / property	Accepted or returned values
Agent `status`	`inactive`, `active`
`recording.retentionDays`	`7`, `30`, `60`, `90`
`advanced.responseStyle` (case-sensitive)	`Precise`, `Balanced`, `Creative`
`advanced.voiceExpressiveness` (case-sensitive)	`Low`, `Moderate`, `High`
`advanced.inactivityTimeoutSeconds`	`30`, `60`, `90`
`advanced.interruptionSensitivity` (case-sensitive)	`Low`, `Medium`, `High`
Quality criterion `severity`	`low`, `medium`, `high`, `critical`
Phone number `status`	`available`, `reserved`, `active`
Phone number `connectionType`	`voxiomniNumber`, `callForwarding`, `sipTrunk`
Call `status`	`inProgress`, `completed`, `transferred`, `missed`, `failed`
Call `outcome`	`unresolved`, `resolved`, `transferred`
Recording `status`	`disabled`, `pending`, `recording`, `available`, `absent`, `failed`, `expired`
Transcription / analysis `status`	`pending`, `processing`, `completed`, `failed`
Analysis `sentiment`	`positive`, `neutral`, `negative`, `mixed`, `unknown`
Analysis `resolutionStatus`	`resolved`, `partiallyResolved`, `unresolved`, `unknown`
Next step `owner`	`customer`, `company`, `agent`, `unknown`
Quality audit `status`	`pending`, `completed`, `failed`
Quality `reviewStatus`	`pending`, `reviewed`
Quality finding `verdict`	`passed`, `failed`, `notApplicable`
Quality review `decision`	`confirmed`, `falsePositive`, `incorrect`
Webhook `type`	`call.ended`, `call.processed`, `call.failed`, `quality.completed`, `quality.failed`, `quality.reviewed`

Data models

Call models

Call object

Property	Type	Description
`id`	string	Stable ID used by call, recording, audit, and webhook operations.
`caller`, `calledNumber`	string	Customer and destination numbers.
`agentId`, `agentName`	string	Agent identity captured for the call.
`startedAt`	date-time	Call start time.
`endedAt`	date-time \| null	Null while in progress.
`durationSeconds`	integer	Total duration.
`status`	enum	`inProgress`, `completed`, `transferred`, `missed`, or `failed`.
`outcome`	enum	`unresolved`, `resolved`, or `transferred`.
`summary`	string	May be empty until processing completes.
`recording`	object	`available`, `status` (`disabled`, `pending`, `recording`, `available`, `absent`, `failed`, `expired`), `contentType`, `durationSeconds`, and `expiresAt`.
`transcription`	object	`status` (`pending`, `processing`, `completed`, `failed`), `completedAt`, and `error`.
`analysis`	object	`status`, `summary`, `primaryReason`, `result`, `sentiment`, `resolutionStatus`, `topics`, `nextSteps`, `completedAt`, and `error`.
`analysis.sentiment`	enum	`positive`, `neutral`, `negative`, `mixed`, or `unknown`.
`analysis.resolutionStatus`	enum	`resolved`, `partiallyResolved`, `unresolved`, or `unknown`.
`analysis.nextSteps[]`	object[]	`owner` (`customer`, `company`, `agent`, `unknown`), `action`, and nullable `dueDate`.
`transcript[]`	object[]	`id`, `role`, `speaker`, `text`, and `timestamp`.
`quality`	object	`selected`, `status`, nullable `score`, and nullable `completedAt`.
`processedAt`	date-time \| null	When all post-call processing finished.

Data models

Quality models

Property	Type	Description
`id`, `callId`, `agentId`, `agentName`, `caller`	string	Audit, call, agent, and caller identity.
`callStartedAt`	date-time	Start time.
`callDurationSeconds`	integer	Duration.
`status`	enum	`pending`, `completed`, or `failed`.
`score`	integer \| null	Overall score from 0 to 100 when completed.
`summary`	string	Overall audit explanation.
`improvementSuggestion`	string \| null	Suggested coaching action.
`findings[]`	object[]	One result per criterion.
`findings[].severity`	enum	`low`, `medium`, `high`, or `critical`.
`findings[].verdict`	enum	`passed`, `failed`, or `notApplicable`.
`findings[].confidence`	decimal	Normally 0–1.
`findings[].evidence[]`	object[]	`timestamp`, `speaker`, and `quote`.
`findings[].review`	object \| null	`decision` (`confirmed`, `falsePositive`, `incorrect`), `note`, reviewer identity, and `reviewedAt`.
`error`	string \| null	Failure detail.
`completedAt`	date-time \| null	Automatic audit completion time.
`reviewStatus`	enum	`pending` or `reviewed`.
`reviewedAt`	date-time \| null	Human review completion time.

Webhooks

One endpoint, multiple event types

Create an HTTPS endpoint in Settings → Development and select its events. Voxiomni sends an HTTP POST with Content-Type: application/json. Route by type and deduplicate by id.

Event envelope

{
  "id": "evt_7df2d10f",
  "type": "call.processed",
  "apiVersion": "2026-10-01",
  "createdAt": "2026-10-11T18:34:01Z",
  "tenantId": "tenant_43a6f21c",
  "data": {
    "id": "call_748cfe8c",
    "status": "completed",
    "summary": "Customer accepted the payment plan."
  }
}

Property	Type	Description
`id`	string	Unique event ID for idempotency.
`type`	enum	The event type below.
`apiVersion`	string	Current contract version: `2026-10-01`.
`createdAt`	date-time	Event creation time.
`tenantId`	string	Workspace that owns the event.
`data`	object	A Call object or Quality audit object.

Acknowledge first.

Verify the signature, persist the event, return a 2xx response quickly, and run heavier work asynchronously.

Webhooks

Verify webhook signatures

Read the exact raw body before JSON parsing. Compute HMAC-SHA256 over {timestamp}.{rawBody} with the endpoint signing secret, then compare the lowercase hexadecimal digest with the value after v1=.

Voxiomni-Event-IdEvent ID for deduplication.

Voxiomni-TimestampUnix timestamp for this attempt.

Voxiomni-Signaturev1=<64-character SHA-256 hex>

User-AgentVoxiomni-Webhooks/1.0

Node.js verification

import crypto from 'node:crypto'

export function verifyVoxiomniWebhook(rawBody, headers, secret) {
  const timestamp = headers['voxiomni-timestamp']
  const header = headers['voxiomni-signature'] ?? ''
  const receivedHex = header.startsWith('v1=') ? header.slice(3) : ''

  if (!timestamp || !/^[a-f0-9]{64}$/.test(receivedHex)) return false

  const expected = crypto
    .createHmac('sha256', secret)
    .update(`${timestamp}.${rawBody}`)
    .digest()
  const received = Buffer.from(receivedHex, 'hex')
  return received.length === expected.length &&
    crypto.timingSafeEqual(received, expected)
}

Replay protection

Reject timestamps outside your tolerance and ignore event IDs already processed.

Webhooks

Event types

call.ended

The call ended. data is a Call object, but post-processing may still be pending.

call.processed

All post-call processing finished. data is the final Call object.

call.failed

The call ended in a failed state. data is a Call object and may be partial.

quality.completed

The automatic audit completed. data is a Quality audit object.

quality.failed

The audit failed. data has status: "failed" and an error.

quality.reviewed

A human completed the review. data contains the updated audit and decisions.

Webhooks

Delivery and retries

Delivery is at least once. The same event can arrive more than once, so consumers must be idempotent. Any 2xx response marks success.

Immediate+1 minute+5 minutes+30 minutes+2 hours+12 hours

Voxiomni retries network failures and HTTP 408, 409, 425, 429, and 5xx. Other non-2xx responses fail without an automatic retry. Delivery records are retained in the app for 30 days and can be retried manually.

Endpoint requirements

The URL must use HTTPS, resolve only to public IP addresses, and contain no embedded credentials or fragment.