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"
  }'

A successful response contains the JWT and its expiry time:

{
  "token": "eyJ...",
  "expires": "2026-08-29T12:00:00Z",
  "eventId": "optional-event-channel-id"
}

Keep the token private and send it as Authorization: Bearer <token> on subsequent requests. Authentication fails when the account is unconfirmed or the credentials are invalid.

2. Submit audio

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

• dataBase64: the recording encoded as base64, or
• url: a URL from which Speechlytics can download the recording.

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
  }"

language: 0 enables automatic language detection. Supplying the known language can improve consistency; see the Language enum in the API reference.

The metadata field is a JSON object serialized as a string. Supported keys include username, local, remote, externalId, type, agent, and customer. Agent identity fields allow the call to appear in Intelligence dashboards.

The service validates and prepares the audio, checks the account's remaining minutes, persists the payload, and queues valid work. The immediate response is:

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

Save id; it identifies the call in all result operations.

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"

Important states include:

Value	State	Meaning
0	Queued	Accepted and waiting for a worker.
1	InProgress	Processing is active.
2	Processed	Transcription and enabled post-processing are complete.
3	Failed	Processing failed; inspect the error field.
4	QuotaLimit	The account did not have enough remaining minutes.
13 / 14	RedactionStarted / RedactionEnded	Sensitive-content masking is running or has completed.

When processed, the response can contain transcription channels, translations, keyword matches, topics, sentiments, summaries, AI analysis, custom-question results, scores, speaker metrics, and word frequencies. Sections appear only when supported by the audio and enabled for the account.

Alternative completion methods

• Configured webhook: Speechlytics posts the completed call result to the endpoint configured for your account.
• Call-events WebSocket: connect to /api/v1/calls/events?token=<token> to receive completion events without polling.

Use polling as the simplest integration and add push delivery when you need lower latency or higher request efficiency.

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.
503 Service Unavailable	Audio storage or queue publication failed; retry with backoff.

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