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

url = "https://api.heify.com/request-upload-url"

payload = {
    "configuration_id": "a1b2c3d4-e5f6-7890-1234-567890abcdef",
    "evaluator_id": "2abb5563-dd64-47bb-bb17-94252e168b06",
    "name": "sales-call-2026-03-21.mp3"
}
headers = {
    "x-api-key": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)
const options = {
  method: 'POST',
  headers: {'x-api-key': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    configuration_id: 'a1b2c3d4-e5f6-7890-1234-567890abcdef',
    evaluator_id: '2abb5563-dd64-47bb-bb17-94252e168b06',
    name: 'sales-call-2026-03-21.mp3'
  })
};

fetch('https://api.heify.com/request-upload-url', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));
<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.heify.com/request-upload-url",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'configuration_id' => 'a1b2c3d4-e5f6-7890-1234-567890abcdef',
    'evaluator_id' => '2abb5563-dd64-47bb-bb17-94252e168b06',
    'name' => 'sales-call-2026-03-21.mp3'
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "x-api-key: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}
package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.heify.com/request-upload-url"

	payload := strings.NewReader("{\n  \"configuration_id\": \"a1b2c3d4-e5f6-7890-1234-567890abcdef\",\n  \"evaluator_id\": \"2abb5563-dd64-47bb-bb17-94252e168b06\",\n  \"name\": \"sales-call-2026-03-21.mp3\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("x-api-key", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}
HttpResponse<String> response = Unirest.post("https://api.heify.com/request-upload-url")
  .header("x-api-key", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"configuration_id\": \"a1b2c3d4-e5f6-7890-1234-567890abcdef\",\n  \"evaluator_id\": \"2abb5563-dd64-47bb-bb17-94252e168b06\",\n  \"name\": \"sales-call-2026-03-21.mp3\"\n}")
  .asString();
require 'uri'
require 'net/http'

url = URI("https://api.heify.com/request-upload-url")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["x-api-key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"configuration_id\": \"a1b2c3d4-e5f6-7890-1234-567890abcdef\",\n  \"evaluator_id\": \"2abb5563-dd64-47bb-bb17-94252e168b06\",\n  \"name\": \"sales-call-2026-03-21.mp3\"\n}"

response = http.request(request)
puts response.read_body
{
  "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"
  }'

import requests

response = requests.post(
    "https://api.heify.com/request-upload-url",
    headers={"x-api-key": "YOUR_API_KEY"},
    json={
        "configuration_id": "a1b2c3d4-e5f6-7890-1234-567890abcdef",
        "evaluator_id": "2abb5563-dd64-47bb-bb17-94252e168b06",
        "name": "sales-call-2026-03-21.mp3"
    }
)

data = response.json()["data"]
upload_url = data["upload_url"]
transcription_id = data["transcription_id"]
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"

data = response.json()["data"]  # Step 1 response

# Build metadata headers from Step 1 response
meta_headers = {
    "Content-Type": "audio/mpeg",
    "x-amz-meta-configuration_id": data["configuration_id"],
}
if data.get("participant_id"):
    meta_headers["x-amz-meta-participant_id"] = data["participant_id"]
if data.get("evaluator_id"):
    meta_headers["x-amz-meta-evaluator_id"] = data["evaluator_id"]
if data.get("name"):
    meta_headers["x-amz-meta-name"] = data["name"]

with open("recording.mp3", "rb") as f:
    upload_response = requests.put(data["upload_url"], data=f, headers=meta_headers)

if upload_response.status_code == 200:
    print(f"Upload successful. Transcription ID: {data['transcription_id']}")
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