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

API key from RubricHQ Settings → API Keys. Send it as: Authorization: Bearer <YOUR_API_KEY>.

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_idintegerOptional

Optional. RubricHQ client (workspace) ID. Defaults to the workspace your API key belongs to.

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"`).

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. e.g. 978-987-9876

duration_secondsintegerOptional

Optional. Total call duration in seconds.

call_timestampdatetimeOptional

Optional. When the call occurred (ISO 8601) in your system. Defaults to the time the call was added in our system 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. Every metric that runs consumes credits from your workspace balance.

metadatamap from strings to anyOptional

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

Response

Call accepted for analysis

idintegerOptional

Internal RubricHQ call ID.

call_identifierstringOptional

Your provided call identifier.

analysis_statusenumOptional

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

linksobjectOptional

Convenience URLs for polling this call's status.

Errors

404

Not Found Error

409

Conflict Error

422

Unprocessable Entity Error