Call Metadata API

📞 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. 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.

Per-file metadata on POST /api/files/

The file upload endpoint accepts optional call metadata alongside the regular fields (see Transcription API 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
`direction`	string	`inbound` or `outbound`
`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 os
import 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

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_source": "api",
    "direction": "inbound",
    "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}/

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 six 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.

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`)
`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/

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, direction, caller_number, campaign are optional.

filename,call_datetime,agent_id,agent_name,direction,caller_number,campaign
call_001.mp3,2026-06-15 09:12:00,A-06,Ana Diaz,inbound,+34600111222,Retention
call_002.mp3,2026-06-15 09:41:00,A-10,Luis Gomez,outbound,+34600333444,Winback

Accepted 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 exists
unmatched — rows kept for files that have not been uploaded yet
errors — 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

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.