Skip to Content
Call IngestionOverview

Call Ingestion

You can forward calls from your PBX or contact center system to ThinkVoice for analysis. The endpoints in this section work from your system to ThinkVoice; to have ThinkVoice notify you when the analysis completes, see the Webhook section.

Endpoints

EndpointPurpose
POST /api/v1/webhooks/callsSends the details of a call. Send Call
POST /api/v1/webhooks/calls/{callId}/audioUploads the recording of a previously sent call as a file. Upload Recording
POST /api/v1/webhooks/hipcall/callsAccepts the call_hangup notification from the Hipcall PBX. Hipcall Integration

Authentication

These endpoints do not use a Bearer token. During the integration, our team provides you with two values:

ValueDescription
API keyIdentifies your integration (PBX/provider).
API secretDetermines which company (tenant) the data is written to.

Send these values as headers with every request:

X-Api-Key: <API_KEY> X-Api-Secret: <API_SECRET>

The values are in GUID format. If a missing, invalid or disabled value is sent, the request is rejected with 401. Store these values on the server side only.

For PBXs such as Hipcall that do not support custom headers, the values are passed in the URL query string instead of headers. See the Hipcall Integration page for details.

Response Format

All successful and failed responses share the same simple structure:

{ "success": true, "message": "019e925a-5f79-7778-b0be-a45a146cf828 successfully processed" }
FieldTypeNullableDescription
successboolNoWhether the operation succeeded.
messagestringNoDescription of the result. For a successful call submission, it starts with the call ID generated by ThinkVoice.

Rate Limit

The limit for these endpoints is 600 requests per 60 seconds. When exceeded, 429 is returned and the Retry-After header indicates how long to wait, in seconds. If you are doing a bulk transfer, spread your requests so they stay below this limit.

Common Error Codes

HTTPDescription
400The request body is invalid (missing required field, wrong date format, etc.). The reason is given in the message field.
401X-Api-Key / X-Api-Secret is missing, invalid or disabled.
404The call for which a recording is being uploaded was not found.
415The recording file type is not supported.
429Rate limit exceeded.
500Unexpected error. Try again after a while; if it persists, contact our team.
Last updated: