Call Metadata API
Call center reporting needs facts that are not in the audio: when the call happened, which agent handled it, whether it was inbound or outbound, who hung up first. There are three ways to provide them:
- Per file at upload, as extra fields on
POST /api/files/— best when your system uploads recordings one by one - Per file afterwards, with
PATCH /api/files/{id}/— for corrections and for metadata that arrives after the recording - Per project, as a CSV manifest on
POST /api/projects/{id}/call-manifest/— best for bulk loads and for backfilling metadata after the fact
All three write to the same place, so you can mix them; the last write wins. Metadata sent through the API always takes precedence over the agent name the AI extracts from the conversation.
Whatever a call currently carries is readable on the file resource as call_metadata.
All endpoints require either a session cookie or an API key — see Authentication.
Agent metadata with automatic analysis
Section titled “Agent metadata with automatic analysis”In a call project with automatic analysis on, each call is analyzed soon after it arrives. If the call has no agent by then, the reports use the name the AI heard in the conversation, which can be wrong or split one agent into several. To avoid that, say who the agent is in one of these ways:
- In the upload, with
agent_id,agent_nameoragent_email - In a manifest sent first, with a row for that file that has an agent
- From an earlier upload of the same filename whose agent came from you
Otherwise the upload still succeeds and the call is processed as usual, but the 201 response includes a warnings list next to the usual file fields:
{ "id": 1042, "status": "transcribing", "warnings": [ { "code": "call_metadata_missing", "detail": "This project analyzes calls automatically, but this call has no agent metadata, ...", "docs_url": "https://docs.uspeech.io/api/call-metadata/" } ]}The warnings key only appears when there is a warning, and only on API-key uploads of recordings and SRT/VTT transcripts. In the web app, the Conversations page shows the warning instead.
If your metadata can only arrive after the recordings, send it as soon as you have it. The real name replaces the guessed one, and the reports update without analyzing the call again.
Per-file metadata on POST /api/files/
Section titled “Per-file metadata on POST /api/files/”The file upload endpoint accepts optional call metadata alongside the regular fields (see Uploading Recordings for the base request).
Content-Type: multipart/form-data
Additional form fields:
| Field | Type | Description |
|---|---|---|
call_datetime | datetime | When the call took place (ISO 8601, e.g. 2026-06-15T09:12:00Z) |
agent_id | string (≤64) | The agent’s identifier in your own systems |
agent_name | string (≤255) | The agent’s display name |
agent_email | The agent’s email. Lets an agent invited with this address see their own calls. An agent_id that is a valid email address is read as the agent’s email too | |
direction | string | inbound or outbound |
ended_by | string | Who hung up first, from your dialer: customer or agent. Excuses the rubric’s closing steps on calls the customer left before the agent’s goodbye |
caller_number | string (≤64) | Customer’s phone number |
campaign | string (≤255) | Campaign or queue name |
Fields left out are simply not set. Blank values are ignored here, so an empty field never shadows a manifest row that is already waiting for this file.
Example:
curl -X POST https://app.uspeech.io/api/files/ \ -H "Authorization: Api-Key $USPEECH_KEY" \ -F "project=312" \ -F "file_type=audio" \ -F "file=@./call_001.mp3" \ -F "call_datetime=2026-06-15T09:12:00Z" \ -F "agent_id=A-06" \ -F "agent_name=Ana Diaz" \ -F "direction=inbound" \ -F "caller_number=+34600111222" \ -F "campaign=Retention"import osimport requests
BASE_URL = "https://app.uspeech.io"HEADERS = {"Authorization": f"Api-Key {os.environ['USPEECH_KEY']}"}
with open("call_001.mp3", "rb") as fh: response = requests.post( f"{BASE_URL}/api/files/", headers=HEADERS, data={ "project": 312, "file_type": "audio", "call_datetime": "2026-06-15T09:12:00Z", "agent_id": "A-06", "agent_name": "Ana Diaz", "direction": "inbound", "caller_number": "+34600111222", "campaign": "Retention", }, files={"file": ("call_001.mp3", fh, "audio/mpeg")}, timeout=300, )response.raise_for_status()import { openAsBlob } from 'node:fs';
const BASE_URL = 'https://app.uspeech.io';const HEADERS = { Authorization: `Api-Key ${process.env.USPEECH_KEY}` };
const form = new FormData();form.set('project', '312');form.set('file_type', 'audio');form.set('call_datetime', '2026-06-15T09:12:00Z');form.set('agent_id', 'A-06');form.set('agent_name', 'Ana Diaz');form.set('direction', 'inbound');form.set('caller_number', '+34600111222');form.set('campaign', 'Retention');form.set('file', await openAsBlob('./call_001.mp3'), 'call_001.mp3');
const response = await fetch(`${BASE_URL}/api/files/`, { method: 'POST', headers: HEADERS, body: form,});if (!response.ok) throw new Error(await response.text());Reading metadata back
Section titled “Reading metadata back”Every file resource — from POST /api/files/, GET /api/files/{id}/ and GET /api/files/?project={id}/ — includes a call_metadata object. It is null for files that have no call record, which is every file in a project that is not a call project.
{ "id": 9871, "original_filename": "call_001.mp3", "status": "transcribed", "call_metadata": { "call_datetime": "2026-06-15T09:12:00Z", "call_datetime_source": "api", "agent_id": "A-06", "agent_name": "Ana Diaz", "agent_email": "ana.diaz@example.com", "agent_source": "api", "direction": "inbound", "ended_by": "customer", "caller_number": "+34600111222", "campaign": "Retention" }}The two _source fields tell you where the value came from, which is useful when reconciling with your own system:
| Field | Values | Meaning |
|---|---|---|
call_datetime_source | api, manifest, upload_time | upload_time means no real call time was ever provided — the file’s upload time is standing in |
agent_source | api, manifest, llm, "" | llm means the agent name was extracted from the conversation, not supplied by you; "" means no agent is linked |
PATCH /api/files/{id}/
Section titled “PATCH /api/files/{id}/”Update the call metadata of a file that is already uploaded. Only the fields you send are touched, so you can change one value without restating the rest.
Content-Type: application/json (or multipart/form-data)
Body fields: the same eight as the upload endpoint.
Clearing a value: send an empty string. {"campaign": ""} removes the campaign; sending agent_id and agent_name both empty unlinks the agent. This differs from the CSV manifest, where blank cells are skipped rather than treated as an instruction to clear.
Send agent_email together with agent_id. The agent fields you send decide which agent the call belongs to:
| Body | Result |
|---|---|
{"agent_id": "A-06", "agent_email": "ana.diaz@example.com"} | Sets the email on agent A-06, for all of that agent’s calls |
{"agent_id": "A-06", "agent_email": ""} | Leaves the agent’s email as it is |
{"agent_email": "ana.diaz@example.com"} | Moves this call to the agent with that email, creating a new agent if there is none |
{"agent_email": ""} | Unlinks the agent from this call, the same as clearing agent_id and agent_name |
call_datetime is the exception — it cannot be cleared, because a call always needs a time. Send a new value to change it, or omit it to leave it alone; null is rejected with 400. Clearing it in the product UI restores the file’s upload time.
Updating metadata does not re-run analysis. Scores, topics, sentiment and rubric results are left untouched.
Response (200 OK): the updated file resource, including the new call_metadata.
Errors:
| Status | When |
|---|---|
400 | The project is not a call project, the file is not a recording or transcript (only audio, srt and vtt carry call metadata), or a value is invalid (e.g. call_datetime: null, an unknown direction or ended_by, a malformed agent_email) |
404 | The file does not exist or is not visible to the caller |
Example — change the campaign and clear the direction:
curl -X PATCH https://app.uspeech.io/api/files/9871/ \ -H "Authorization: Api-Key $USPEECH_KEY" \ -H "Content-Type: application/json" \ -d '{"campaign": "Winback", "direction": ""}'response = requests.patch( f"{BASE_URL}/api/files/9871/", headers=HEADERS, json={"campaign": "Winback", "direction": ""}, timeout=30,)response.raise_for_status()print(response.json()["call_metadata"])const response = await fetch(`${BASE_URL}/api/files/9871/`, { method: 'PATCH', headers: { ...HEADERS, 'Content-Type': 'application/json' }, body: JSON.stringify({ campaign: 'Winback', direction: '' }),});if (!response.ok) throw new Error(await response.text());console.log((await response.json()).call_metadata);POST /api/projects/{id}/call-manifest/
Section titled “POST /api/projects/{id}/call-manifest/”Upload a CSV manifest with metadata for many calls at once. Rows are matched to the project’s files by filename, and rows that don’t match anything yet are stored on the project and applied to files uploaded later.
{id} is the project’s numeric ID — see Projects if you need to look it up.
Auth: API key or session.
Content-Type: multipart/form-data
Form fields:
| Field | Required | Description |
|---|---|---|
file | yes | The CSV manifest |
CSV columns (header row required): filename and call_datetime are required; agent_id, agent_name, agent_email, direction, ended_by, caller_number, campaign are optional. An agent_email that isn’t a valid address is dropped, and the rest of the row still applies. ended_by also accepts cliente, client and caller for the customer, and agente, asesor and asesora for the agent, in any capitalization; any other value is dropped.
filename,call_datetime,agent_id,agent_name,agent_email,direction,ended_by,caller_number,campaigncall_001.mp3,2026-06-15 09:12:00,A-06,Ana Diaz,ana.diaz@example.com,inbound,customer,+34600111222,Retentioncall_002.mp3,2026-06-15 09:41:00,A-10,Luis Gomez,luis.gomez@example.com,outbound,agent,+34600333444,WinbackAccepted date/time formats: ISO 8601, YYYY-MM-DD HH:MM[:SS], and DD/MM/YYYY HH:MM[:SS]. Values without a time zone are read in the server’s time zone.
Matching: exact filename first, then the name without its extension (case-insensitive), so call_001.wav in the manifest matches an uploaded call_001.mp3. Audio files and transcript uploads (SRT/VTT) are both matched.
Response (200 OK):
{ "matched": 118, "unmatched": ["call_119.mp3", "call_120.mp3"], "errors": ["Row 42 (call_041.mp3): invalid call_datetime '15-06-2026'"]}matched— rows applied to a file that already existsunmatched— rows kept for files that have not been uploaded yeterrors— rows that were skipped, with the reason
Errors:
| Status | When |
|---|---|
400 | The project is not a call project, no file was sent, or the CSV had no valid rows (the response includes errors) |
404 | The project does not exist or is not visible to the caller |
Example:
curl -X POST https://app.uspeech.io/api/projects/312/call-manifest/ \ -H "Authorization: Api-Key $USPEECH_KEY" \ -F "file=@./calls_june.csv"with open("calls_june.csv", "rb") as fh: response = requests.post( f"{BASE_URL}/api/projects/312/call-manifest/", headers=HEADERS, files={"file": ("calls_june.csv", fh, "text/csv")}, timeout=120, )response.raise_for_status()result = response.json()print(f"{result['matched']} matched, {len(result['unmatched'])} waiting")import { openAsBlob } from 'node:fs';
const form = new FormData();form.set('file', await openAsBlob('./calls_june.csv'), 'calls_june.csv');
const response = await fetch(`${BASE_URL}/api/projects/312/call-manifest/`, { method: 'POST', headers: HEADERS, body: form,});if (!response.ok) throw new Error(await response.text());const result = await response.json();console.log(`${result.matched} matched, ${result.unmatched.length} waiting`);Reading the results
Section titled “Reading the results”Once the calls have been analyzed, the metadata you attached here becomes the grouping and filtering dimensions of the report — by agent, direction, campaign and call date. See the Call Reports API for reading those results back.