Skip to main content
POST
/
request-upload-url
Submit from local file (1/2)
curl --request POST \
  --url https://api.heify.com/request-upload-url \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "configuration_id": "a1b2c3d4-e5f6-7890-1234-567890abcdef",
  "evaluator_id": "2abb5563-dd64-47bb-bb17-94252e168b06",
  "name": "sales-call-2026-03-21.mp3"
}
'
{
  "data": {
    "transcription_id": "b147ee2b-41f8-43ac-8838-29b17229abf4",
    "upload_url": "https://storage.heify.com/upload/client-id/b147ee2b-41f8-43ac-8838-29b17229abf4?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Expires=300&...",
    "configuration_id": "a1b2c3d4-e5f6-7890-1234-567890abcdef",
    "participant_id": null,
    "evaluator_id": "2abb5563-dd64-47bb-bb17-94252e168b06",
    "name": "sales-call-2026-03-21.mp3"
  }
}
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

curl -X POST https://api.heify.com/request-upload-url \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{
    "configuration_id": "a1b2c3d4-e5f6-7890-1234-567890abcdef",
    "evaluator_id": "2abb5563-dd64-47bb-bb17-94252e168b06",
    "name": "sales-call-2026-03-21.mp3"
  }'
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.

​
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. 
curl -X PUT \
  -H "Content-Type: audio/mpeg" \
  -H "x-amz-meta-configuration_id: CONFIGURATION_ID_FROM_STEP_1" \
  -H "x-amz-meta-evaluator_id: EVALUATOR_ID_FROM_STEP_1" \
  --data-binary @recording.mp3 \
  "UPLOAD_URL_FROM_STEP_1"
A 200 OK with an empty body confirms the upload succeeded. Processing starts automatically in the background.
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.

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.

Response

200 - application/json

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

​
data
object