Skip to main content
POST
Use this endpoint when your audio file is stored locally. Call this API first to receive a pre-signed upload URL, then upload your file directly to it. Transcription processing starts automatically once the upload completes.

​
Step 1 — Request upload URL

The upload_url expires in 5 minutes. Proceed to Step 2 immediately after receiving it.
participant_id and evaluator_id are optional. If provided, they must exist and belong to your account.
The name field is sanitized to ASCII — accented or non-Latin characters are automatically stripped.
period_date is optional — it sets when the recording was made and overwrites the transcription’s created_at. If omitted, created_at is the upload timestamp. See Recording date below for accepted formats.

​
Step 2 — Upload the file

Send a PUT request to the upload_url from the Step 1 response. You must include the metadata fields as headers — they are embedded in the upload URL signature and the request will fail if they are missing or don’t match.
A 200 OK with an empty body confirms the upload succeeded. Processing starts automatically in the background.
If you sent period_date in Step 1, replay the normalized value echoed in the Step 1 response (data.period_date) as the x-amz-meta-period_date header — not your original input. Like the other metadata headers, it is embedded in the upload URL signature.
Use the transcription_id from Step 1 to check results once processing completes, or configure a webhook to receive a notification automatically.
For supported formats, file size limits, and duration limits, see Rate Limits & Quotas.

​
Recording date (period_date)

Customers often upload calls in batches, after the fact — a batch recorded in April might be uploaded in June. Without period_date, every transcription is stamped with the upload time, so all of April’s calls would land in June and monthly or quarterly reporting would be impossible. period_date states when the recording actually happened. Because it overwrites created_at, setting it correctly at upload time automatically fixes every time-based analytic at once: the timeline, the month-over-month comparison, per-criterion evolution, the evaluator heatmap, and the start_date/end_date analytics filters — all are derived from created_at. It behaves identically here and on Submit from public URL: same format, same validation, same errors.

​
Accepted formats

The date is required; the time is optional. Everything is resolved to a UTC instant and stored in created_at.
Two defaults callers tend to assume wrongly: no time means 00:00:00 UTC (not “some time that day”), and no timezone means UTC (not your local time). A client that means local time must send the offset — and note an offset can move the instant to the previous day, and therefore into the previous reporting month (2026-04-01T00:30:00+02:00 resolves to March 31st).
Omitted, null, or empty-string values are treated as “not provided” — no error, created_at falls back to the upload timestamp. Anything else malformed returns 400: month-only values ("2026-04"), a space instead of the T separator, non-ISO formats ("15/04/2026"), impossible dates, or non-string types.
If you know the recording’s time of day, send it. The evaluator dashboard’s charts.heatmap is a weekday × hour grid built from created_at — date-only uploads all pile into the midnight column, flattening the hour axis. Everything else (month, timeline, evolution, comparison, date filters, weekday) is correct either way.
There is no endpoint to correct the date afterwards — Update Transcription Group does not accept period_date. If a recording was submitted with the wrong date, delete it and submit the audio again with the correct period_date.

Authorizations

​
x-api-key
string
header
required

Body

application/json
​
configuration_id
string<uuid>
required

The unique identifier of the configuration to use for this transcription.

​
name
string

Optional label or filename for the transcription. Only ASCII characters are kept — non-ASCII characters are automatically stripped.

​
participant_id
string<uuid>

Optional. Link this transcription to a participant. Must exist and belong to your account.

​
evaluator_id
string<uuid>

Optional. Link this transcription to an evaluator. Must exist and belong to your account.

​
period_date
string

Optional. When the recording was made — a date (YYYY-MM-DD) or an ISO 8601 datetime; the time is optional. Overwrites the transcription's created_at, which drives all time-based analytics. Without a time the date is taken at 00:00:00 UTC; without a timezone the value is interpreted as UTC. Month-only values (2026-04) and non-ISO formats are rejected with 400. If omitted, created_at is the upload timestamp.

Pattern: ^\d{4}-\d{2}-\d{2}(T\d{2}:\d{2}(:\d{2}(\.\d+)?)?(Z|[+-]\d{2}:?\d{2})?)?$
Example:

"2026-04-15T14:30:00Z"

Response

200 - application/json

Pre-signed URL generated successfully. PUT the audio file to upload_url with the correct Content-Type header.

​
data
object