Submit your first transcription

This guide authenticates, submits a recording, and retrieves its completed transcript and analytics.

1. Create an access token

curl --request POST "https://api.example.com/api/v1/auth/token" \
  --header "Content-Type: application/json" \
  --data '{
    "username": "your-username",
    "password": "your-password"
  }'

{
  "token": "eyJ...",
  "expires": "2026-10-01T14:00:00Z",
  "eventId": "1234"
}

Send the token as Authorization: Bearer <token> on every following request. If the user has two-factor authentication turned on, you receive a challenge instead; see Authentication.

2. Submit audio

POST /api/v1/speech/process accepts either:

• url: a link Speechlytics downloads the recording from. Direct media links and YouTube links are supported.
• dataBase64: the recording encoded as base64.

URL submission avoids inflating the request by a third and is preferable for large files. The request body limit is about 290 MB.

Submit a media URL

curl --request POST "https://api.example.com/api/v1/speech/process" \
  --header "Authorization: Bearer $SPEECHLYTICS_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
    "url": "https://media.example.com/calls/recording.mp3",
    "filename": "recording.mp3",
    "language": 0,
    "hasPriority": false,
    "checkFilenameExistence": true,
    "metadata": "{\"username\":\"agent@example.com\",\"local\":\"1001\",\"remote\":\"+15551234567\",\"externalId\":\"crm-call-42\"}"
  }'

Submit base64 audio

curl --request POST "https://api.example.com/api/v1/speech/process" \
  --header "Authorization: Bearer $SPEECHLYTICS_TOKEN" \
  --header "Content-Type: application/json" \
  --data "{
    \"dataBase64\": \"$(base64 -w 0 recording.wav)\",
    \"filename\": \"recording.wav\",
    \"language\": 0,
    \"hasPriority\": false,
    \"checkFilenameExistence\": true
  }"

Request fields

Field	Type	Meaning
url	string	Media URL to download. Use this or dataBase64.
dataBase64	string	Base64 recording. Use this or url.
filename	string	The call's name. Used for duplicate detection.
language	integer	0 (Auto) uses the account's default language if one is set, otherwise automatic detection. Any other value pins the language. See the Language enum in the API reference.
metadata	string	A JSON object serialized as a string. See below.
hasPriority	boolean	Queue the call ahead of normal-priority work.
checkFilenameExistence	boolean	Reject the submission with 302 if the account already has a call with this filename.

Metadata

metadata attributes the call to an agent and customer and links it to your own systems:

Key	Meaning
username	Agent identity, typically an email. Used to group calls in Intelligence.
local	Agent-side number or extension.
remote	Customer-side number.
externalId	Your id for the call. Returned on results.
type	Call type, for example inbound or outbound.
agent, customer	Which stereo channel each party is on: 0 Both, 1 Left, 2 Right.

When username or local is present, Speechlytics creates the agent automatically if it does not exist.

What happens next

Speechlytics validates and prepares the audio, checks the account's remaining minutes, stores the recording and queues it. The immediate response is:

{
  "id": 12345,
  "status": 0
}

Save id; it identifies the call in every result operation. The initial status is 0 (Queued), 3 (Failed: the format is unsupported or the audio is shorter than the account minimum) or 4 (QuotaLimit: not enough minutes).

3. Retrieve the result

Poll the status endpoint until the call reaches a terminal state:

curl "https://api.example.com/api/v1/calls/12345/status" \
  --header "Authorization: Bearer $SPEECHLYTICS_TOKEN"

Value	State	Meaning
0	Queued	Accepted and waiting for a worker.
1	InProgress	Processing is active.
2	Processed	Transcription and all enabled post-processing are complete. Terminal.
3	Failed	Processing failed; inspect error. Terminal.
4	QuotaLimit	The account did not have enough remaining minutes. Terminal.
5	NotFound	No call with this id is visible to your account.
8	Live	A live session is running.

The CallStatus enum also defines values 6, 7 and 9–19. They mark pipeline stages such as masking (13, 14), polishing (15–19) and analytics in the call's internal status history, and are not returned in status.

When processed, the response can contain transcript channels, translations, keyword matches, topics, sentiments, a summary, structured analysis, custom-question results, scores, speaker metrics and word frequencies. Sections appear only when they are enabled for the account and supported by the audio.

Poll gently

Poll every few seconds at most, and back off for long recordings. Status responses can be cached for up to 30 seconds. For high volumes use push delivery instead.

Push delivery instead of polling

• Account webhook: Speechlytics posts call updates to the endpoint configured for your account.
• Call-events WebSocket: connect to /api/v1/calls/events?token=<token> and receive the same updates.

See Webhooks and call events for payloads, delivery behavior and encryption.

Common responses

Response	Cause
302 Found	checkFilenameExistence is true and the filename already exists for the account.
400 Bad Request	The base64 input is invalid or the request cannot be processed.
401 Unauthorized	The JWT is missing, expired or invalid.
429 Too Many Requests	You exceeded the rate limit. Back off and retry.
503 Service Unavailable	Audio storage or queue publication failed; retry with backoff.

For every request field and response schema, see the API reference.