Add Calls | RubricHQ Docs

curl -X POST https://api.rubrichq.io/api/public/v1/calls \
     -H "Authorization: Bearer <token>" \
     -H "Content-Type: application/json" \
     -d '{
  "call_identifier": "call-full-001",
  "agent_id": 42,
  "client_id": 7,
  "recording_url": "https://your-storage.com/recordings/call-full-001.wav",
  "transcript": [
    {
      "role": "AI Assistant",
      "content": "Hello, thanks for calling support. How can I help you today?",
      "start_time": 0.5,
      "end_time": 3.2
    },
    {
      "role": "User",
      "content": "I'\''d like to pay my invoice, number 88210.",
      "start_time": 3.8,
      "end_time": 6.4
    },
    {
      "role": "Function Call",
      "content": "",
      "start_time": 6.5,
      "end_time": 6.5,
      "data": {
        "id": "call_a1b2c3",
        "name": "lookupInvoice",
        "arguments": "{\"invoice_number\":\"88210\"}"
      }
    },
    {
      "role": "Function Call Result",
      "content": "",
      "start_time": 7.2,
      "end_time": 7.2,
      "data": {
        "id": "call_a1b2c3",
        "name": "lookupInvoice",
        "result": "{\"status\":\"unpaid\",\"amount_due\":\"49.00\",\"currency\":\"USD\"}"
      }
    },
    {
      "role": "AI Assistant",
      "content": "I found invoice 88210 — the balance due is $49.00. Would you like to pay it now?",
      "start_time": 7.6,
      "end_time": 11.3
    }
  ],
  "call_direction": "inbound",
  "call_end_reason": "completed",
  "customer_number": "+15550001234",
  "duration_seconds": 92,
  "call_timestamp": "2026-03-09T10:00:00Z",
  "label": "Billing query — full example",
  "metric_ids": [
    101,
    102,
    103
  ],
  "metadata": {
    "campaign_id": "q1-billing",
    "region": "us-east"
  }
}'

{
  "id": 1024,
  "call_identifier": "call-abc-123",
  "analysis_status": "pending",
  "links": {
    "detail": "/api/public/v1/calls/1024",
    "by_identifier": "/api/public/v1/calls/call-abc-123"
  }
}

Submit a call recording and/or transcript for analysis. At least one of recording_url or transcript is required.

The response returns immediately with analysis_status: "pending". Poll GET /calls/{id} to check when analysis is complete.

Authentication

AuthorizationBearer

JWT token from RubricHQ Settings → API Keys

Request

This endpoint expects an object.

call_identifierstringRequired

Required. Your unique ID for this call. Used for deduplication and retrieval.

agent_idintegerRequired

Required. RubricHQ agent ID to associate with this call.

client_idintegerRequired

Required. RubricHQ client (workspace) ID.

recording_urlstringOptionalformat: "uri"

Publicly accessible URL to the audio recording (WAV, MP3, or M4A). Required if no transcript is provided. RubricHQ will download and store this securely. Needed for audio-based metrics (latency, interruptions, silence, WPM). Omit it for text-only calls — audio analysis simply won’t run.

transcriptlist of objectsOptional

The conversation as an ordered list of turns. Required if no recording_url is provided. Each turn is an object:

Field	Type	Description
`role`	string	One of `"AI Assistant"`, `"User"`, `"Function Call"`, or `"Function Call Result"`.
`content`	string	What was said in this turn. Empty for tool-call turns.
`start_time`	number	Seconds from the start of the call when the turn began.
`end_time`	number	Seconds from the start of the call when the turn ended.
`data`	object	Only on tool-call turns. Carries `id`, `name`, and `arguments` (on `"Function Call"`) or `result` (on `"Function Call Result"`).

If provided alongside a recording_url, transcript-based metrics run immediately while audio metrics run asynchronously.

call_directionenumOptionalDefaults to inbound

Optional (defaults to inbound). Whether the call was initiated by the agent (outbound) or the customer (inbound).

call_end_reasonstringOptional

Optional. How the call ended (e.g. completed, dropped, transferred).

customer_numberstringOptional

Optional. Customer phone number.

duration_secondsintegerOptional

Optional. Total call duration in seconds.

call_timestampdatetimeOptional

Optional. When the call occurred (ISO 8601). Defaults to ingestion time if omitted.

labelstringOptional

Optional. Free-text label for this call (visible in the dashboard).

metric_idslist of integersOptional

Optional. IDs of specific metrics to compute. Defaults to all enabled metrics for the agent.

metadatamap from strings to anyOptional

Optional. Arbitrary key-value pairs stored with the call (visible in the dashboard).

Response

Call accepted for analysis

idinteger

Internal RubricHQ call ID.

call_identifierstring

Your provided call identifier.

analysis_statusenum

pending — analysis queued or in progress
computed — all metrics computed successfully
failed — analysis encountered an error

linksobject

Convenience URLs for polling this call's status.

Errors

404

Not Found Error

409

Conflict Error

422

Unprocessable Entity Error