# ScoreCall API

**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](./openapi.yaml) · [Quickstart](#quickstart) · [Signed webhooks](#signed-webhooks) · [Integration checklist](#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

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:

```bash
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"
done
```

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

```bash
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.

```json
{
  "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:

```bash
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

`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

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.

```json
{
  "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:

```js
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

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

| 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

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