TalkWiz API documentation

The API lets you send call transcripts for analysis and read the results. Create an API key in settings (admins only), and send it in the header Authorization: Bearer ....

Sending a call

POST /api/v1/calls. You can send one call, or up to 100 calls in the form { "calls": [...] }. The response returns right away, and the analysis runs in the background.

curl -X POST https://talkwiz.app/api/v1/calls \
  -H "Authorization: Bearer tw_live_xxxxxxxxxxxx_..." \
  -H "Content-Type: application/json" \
  -d '{
    "external_call_id": "12345",
    "started_at": "2026-01-31 14:30",
    "direction": "outbound",
    "agent_name": "Dana Cohen",
    "customer_phone": "052-1234567",
    "customer_name": "Yossi Levi",
    "campaign": "Winter promo",
    "transcript": "Agent: Hi Yossi, this is Dana...\nCustomer: Hi..."
  }'

Fields
Field	Description
`transcript`	Required. Text with "Agent:" / "Customer:" (or the Hebrew equivalents) at the start of lines, or an array of { speaker, text, start_sec, end_sec }.
`external_call_id`	The call ID in your system. Sending again with the same ID will not create a duplicate call.
`started_at`	Date and time. ISO 8601, or 31/01/2026 14:30 (in the organization's time zone).
`duration_sec`	Duration in seconds, or "05:23".
`direction`	inbound / outbound.
`agent_name, agent_external_id`	The agent. A new agent is created automatically.
`customer_phone, customer_name`	Customer details. Israeli numbers are converted to international format.
`campaign, call_outcome, metadata`	Extra fields as needed.

Sending a recording for transcription

Instead of a transcript you can send a recording. TalkWiz transcribes it, identifies the agent and the customer, and analyzes it like any call. It takes three steps, so large files upload directly to storage: register, upload the file to a signed address, and complete. Formats: mp3, m4a, mp4, wav, webm, ogg, flac, up to 25MB per file. The recording is deleted right after transcription.

# 1. Register the recording
curl -X POST https://talkwiz.app/api/v1/recordings \
  -H "Authorization: Bearer tw_live_xxxxxxxxxxxx_..." \
  -H "Content-Type: application/json" \
  -d '{ "file_name": "call-12345.mp3", "external_call_id": "12345", "agent_name": "Dana Cohen", "customer_phone": "052-1234567" }'

# 2. Upload the file to the returned upload_url (no Authorization)
curl -X PUT "<upload_url>" -H "Content-Type: audio/mpeg" --data-binary @call-12345.mp3

# 3. Complete: transcription starts in the background
curl -X POST https://talkwiz.app/api/v1/recordings/<id>/complete \
  -H "Authorization: Bearer tw_live_xxxxxxxxxxxx_..."

When registering you can send all the call fields in the table above, except transcript. Read the state with GET /api/v1/recordings/{id}: queued, transcribing, transcribed (with the call_id of the call that was created) or failed (with error).

Reading results

GET /api/v1/calls/{id} returns the call status, and GET /api/v1/calls/{id}/analysis returns the analysis results by template.

Limits and errors

Up to 60 requests a minute per key (error 429).
Request body up to 1MB (error 413), transcript up to 200,000 characters.
Errors return as { "error": { "code", "message", "message_he" } }.
Sensitive details (credit cards, ID numbers, bank accounts) are hidden automatically before storage.

Full OpenAPI specification: /api/v1/openapi.json