Skip to main content

​
Batch Audio Upload

Upload multiple audio files and their metadata simultaneously through a 3-step process using S3 presigned URLs.
Presigned URLs are valid for 1 hour only. Complete all three steps within that window.

​
Overview

​
Step 1: Get Presigned URLs

​
Request

POST /api/v1/calls/upload
Authorization: Bearer YOUR_TOKEN
Content-Type: application/json

​
Body

{
  "metadata_filename": "metadata.csv",
  "audios_filename": "audios.zip"
}
Both fields are required for batch upload.

​
Response 200

{
  "status": "success",
  "data": {
    "metadata_upload_url": "https://s3.amazonaws.com/.../metadata.csv?...",
    "metadata_key": "country/firm/user-uuid/metadata.csv",
    "audio_upload_url": "https://s3.amazonaws.com/.../audios.zip?...",
    "audio_key": "country/firm/user-uuid/audios.zip",
    "expires_in": 3600
  }
}
Save these values from the response — you need them for Steps 2 and 3:
  • metadata_upload_url — for uploading CSV
  • audio_upload_url — for uploading ZIP
  • metadata_key and audio_key — for Step 3

​
Step 2: Upload Files to S3

​
2a. Upload metadata.csv

PUT <metadata_upload_url from Step 1>
Content-Type: text/csv
Body: (binary CSV file contents)

​
2b. Upload audios.zip

PUT <audio_upload_url from Step 1>
Content-Type: application/zip
Body: (binary ZIP file contents)
Do NOT include the Authorization header in Step 2 requests. The presigned URL already contains authentication.

​
Step 3: Trigger Processing

​
Request

POST /api/v1/calls/process-upload
Authorization: Bearer YOUR_TOKEN
Content-Type: application/json

​
Body

{
  "metadata_key": "country/firm/user-uuid/metadata.csv",
  "audios_key": "country/firm/user-uuid/audios.zip"
}
Use the metadata_key and audio_key values from Step 1.

​
Response 200

{
  "status": "success",
  "data": {
    "message": "Files validated and queued for processing"
  }
}

​
CSV Format (metadata.csv)

​
Required Columns

ColumnDescriptionExample
audio_file_nameFile name in the ZIP archivecall_001.wav
client_phone_numberCustomer phone number+77012345678
operator_nameOperator nameJohn Smith
start_timeCall start time (ISO 8601)2026-01-13T10:30:00
segment_typeSegment typesales
right_channelRight channel role: operator or clientoperator
left_channelLeft channel role: operator or clientclient

​
Optional Columns

ColumnDescription
partner_call_idExternal call ID
directioninbound or outbound
operator_group_nameOperator group name
disconnect_reasonCall end reason

​
Example CSV

audio_file_name,client_phone_number,operator_name,start_time,segment_type,right_channel,left_channel,direction,partner_call_id
call_001.wav,+77012345678,John Smith,2026-01-13T10:30:00,sales,operator,client,inbound,CALL-001
call_002.mp3,+77012345679,Jane Doe,2026-01-13T11:00:00,support,operator,client,inbound,CALL-002

​
ZIP Archive Format

audios.zip
├── call_001.wav
├── call_002.mp3
├── call_003.flac
└── ...
Requirements:
  • All files must be in the root of the archive (no nested folders)
  • File names must exactly match the audio_file_name values in the CSV
  • Supported formats: .wav, .mp3, .flac, .ogg, .aiff, .au

​
Monitoring Processing

After triggering processing, check the status of your calls using the Get Calls endpoint with the status filter.