Integration guide
Turn call recordings into scores your software can act on.
ScoreCall is an API-first AI service for call quality. Send a recording, choose a scoring campaign, and receive a score out of 100. Use the result in a CRM, a quality review queue, or an AI agent. Retrieve transcripts and recordings separately when the workflow needs them.
OpenAPI 3.1 specification · Quickstart · Signed webhooks · Integration checklist
Availability. This guide describes the durable scoring API. Use the base URL supplied for an environment running this version. The public API hostname and rollout are pending. Signed webhooks require campaign setup.
Quickstart
Section titled “Quickstart”Get your API key from Account → API key in ScoreCall. Use it server-side in the X-Api-Key header. Store the key in your secret manager.
Set SCORECALL_API_URL to your environment’s base URL, without a trailing slash. Load SCORECALL_API_KEY from your secret manager. List the campaigns, agents, and teams available to your account:
BASE="${SCORECALL_API_URL:?Set the ScoreCall base URL}"
for collection in campaigns agents teams; do curl --silent --show-error --fail-with-body \ --header "X-Api-Key: ${SCORECALL_API_KEY:?Set the ScoreCall API key}" \ "$BASE/api/v1/$collection"doneChoose an enabled campaign and agent from those responses. Use an opaque reference for the recording so you can save the result against the right record. This example assumes campaign 42 and agent 7 exist in your account.
curl --silent --show-error --fail-with-body \ --header "X-Api-Key: $SCORECALL_API_KEY" \ --header "Idempotency-Key: crm-recording-rec_01JEXAMPLE" \ --form 'file=@recording.wav' \ --form 'campaignId=42' \ --form 'agentId=7' \ --form 'label=rec_01JEXAMPLE' \ --form 'callDate=2026-11-01T10:30:00Z' \ "$BASE/api/v1/analyze"ScoreCall persists the job before returning HTTP 202 Accepted for a submission with an idempotency key. Save the returned scoreId with your recording. A retry with the same key and input returns the same ID and the current job state.
{ "success": true, "scoreId": 1234, "status": "queued", "label": "rec_01JEXAMPLE", "eventId": "5e7d6035-ba85-4f03-a695-20fc7e82af53", "callScoreOn100": null, "errorCode": null, "completedAt": null}Check progress using the returned ID:
curl --silent --show-error --fail-with-body \ --header "X-Api-Key: $SCORECALL_API_KEY" \ "$BASE/api/v1/scorings/1234"| Job state | How to handle it |
|---|---|
queued |
Save the job ID and check again later. |
processing |
Wait for a webhook or poll with backoff. |
succeeded |
Save callScoreOn100. A score of 0 is valid. |
failed |
Save the failure and surface it for review. errorCode is scoring_failed. |
The success field confirms that the API request succeeded. Read status for the scoring outcome. completedAt is set when a job reaches a terminal state. It represents UTC, including when the API omits the zone suffix.
Submission reference
Section titled “Submission reference”POST /api/v1/analyze accepts multipart/form-data.
| Field | Required | Description |
|---|---|---|
file |
Yes | Audio file up to 150 MiB. ScoreCall checks the file header. Start with WAV or MP3. |
campaignId |
Yes | Enabled campaign in the API key’s account. It selects the scoring criteria. |
agentId |
Yes | Enabled agent in the same account. |
teamId |
Optional | Enabled team in the same account. Omit it or send 0 for an unassigned team. |
label |
Optional | Your recording reference, up to 256 characters. Defaults to the filename without its extension. |
callDate |
Optional | Recording time as an ISO 8601 timestamp. Defaults to the time ScoreCall first accepts the job. |
For new integrations, send Idempotency-Key on every upload and keep it stable across retries. Use 1–128 ASCII letters, digits, dots, hyphens, underscores, or colons. Keep the audio bytes, file extension, and metadata identical on retry. Keys are scoped to the account. Reusing a key for different input returns 409 Conflict.
A submission that omits the key uses the compatibility response, HTTP 200 with success, scoreId, and message. A subsequent retrieval uses the job-status endpoint on deployments running this API version.
Signed webhooks
Section titled “Signed webhooks”Ask ScoreCall to configure an HTTPS callback URL and a shared signing secret for your campaign. Then submit jobs with both Idempotency-Key and X-Scorecall-Webhook-Format: compact-v1. The callback destination comes from the campaign’s integration configuration. ScoreCall sends one event when the job succeeds or fails.
{ "schemaVersion": "compact-v1", "id": "5e7d6035-ba85-4f03-a695-20fc7e82af53", "eventId": "5e7d6035-ba85-4f03-a695-20fc7e82af53", "eventType": "scoring.success", "createdAt": "2026-11-01T10:32:18Z", "scoringSucces": true, "errorCode": null, "data": { "object": { "id": 1234, "label": "rec_01JEXAMPLE", "callScoreOn100": 86.5 } }}For scoring.failed, scoringSucces is false, errorCode is scoring_failed, and the score is null. The spelling of scoringSucces is part of the wire format. Use eventType to branch and eventId to deduplicate deliveries.
Verify the HMAC-SHA256 signature in X-Scorecall-Signature against the exact request bytes, before parsing JSON. This Node.js helper expects a Buffer or Uint8Array containing the raw body:
import { createHmac, timingSafeEqual } from 'node:crypto'
export function verifyScoreCallSignature(rawBody, signature, secret) { if (!secret || !/^sha256=[a-f0-9]{64}$/i.test(signature ?? '')) return false const received = Buffer.from(signature.slice(7), 'hex') const expected = createHmac('sha256', secret).update(rawBody).digest() return timingSafeEqual(received, expected)}Check that the label and score ID match the recording. In one database transaction, persist the terminal result and a receipt with a unique event ID. Return any HTTP 2xx within 20 seconds, including for a delivery you already processed. ScoreCall backs off and retries network failures, timeouts, HTTP 408, 429, and 5xx, up to ten delivery attempts. The event ID and request body stay stable on retry.
The job status response exposes the same eventId as the webhook. Apply a terminal result from either source through the same deduplication logic. Compact callbacks carry the terminal state and score. Use the file endpoints for recordings and transcripts.
Download results and recordings
Section titled “Download results and recordings”Each endpoint requires your API key. Use a scoreId from your account.
| Endpoint | Response |
|---|---|
GET /api/v1/files/{scoreId}/audio |
302 to a temporary URL for the recording |
GET /api/v1/files/{scoreId}/transcript |
302 to a temporary URL for transcript JSON |
GET /api/v1/files/{scoreId}/pdf |
200 with the transcript PDF |
GET /api/v1/files/{scoreId}/txt |
200 with the transcript as plain text |
For redirects, fetch the Location in a separate request with no API key attached. A temporary URL grants access until it expires, so keep it out of logs and shared messages. Fetch a fresh URL when needed.
Errors and retries
Section titled “Errors and retries”| HTTP status | What to do |
|---|---|
400 |
Check the fields, headers, and credit balance before retrying. |
401 / 403 |
Check the server-side key and account access. |
404 |
Check the account, selected IDs, and artifact availability. |
409 |
Compare the input with the original submission for that key. |
413 / 415 |
Check the file size or encoding. |
503 with signed-callback configuration error |
Configure the campaign callback before resubmitting. |
Network timeout, 408, 429, or other 5xx |
Back off and retry with the original key and input. |
Error bodies vary between API validation and gateway failures. Handle HTTP status first and parse a JSON body when present.
Integration checklist
Section titled “Integration checklist”- Keep the upload fast. Store the audio privately. Save its record and queue the ScoreCall submission in the same database transaction. Have a background worker read the audio and submit it.
- Correlate by recording. Use the local audio record ID as
label. Derive a stable idempotency key from it. Keep separate jobs for multiple recordings on the same sale or case. - Persist your submission. Save the returned
scoreId, the recording ID, and the state. If an upload times out before you receive a response, retry with the original key. - Verify and reconcile. Verify signature bytes, match the event to the recording, and update the score and receipt together. Poll the status endpoint with backoff when a callback is delayed.
- Test before enabling. Verify duplicate submission, missed and repeated callbacks, zero scores, terminal failures, and disabled campaign routing with synthetic recordings.
In a sales portal, use one score and audit trail per uploaded recording. Attach each result to its original sale so reviewers can see which conversation was scored.