Calls

Launch AI outbound calls, list call history, and retrieve call details including transcripts and recordings.

Create a call

POST /v1/calls

Enqueue an outbound AI call. The call is queued and processed asynchronously.

Required scope: calls:write

Request body

Field	Type	Required	Description
agentId	string	Yes	ID of the AI agent to use for the call
toNumber	string	Yes	Destination phone number in E.164 format
fromNumber	string	Yes	Caller ID phone number (must belong to your org)
voiceId	string	No	Override the agent's default voice
language	string	No	Override the agent's default language
customerName	string	No	Name of the person being called
dynamicVariables	object	No	Key-value pairs injected into the agent's prompt
metadata	object	No	Custom metadata attached to the call
scheduledAt	string	No	ISO 8601 timestamp to schedule the call
disableKnowledgeBases	boolean	No	Disable knowledge bases for this call (default: false)

Example

curl -X POST https://api.replicer.ai/v1/calls \
  -H "Authorization: Bearer rpl_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "agentId": "clx1234567890",
    "toNumber": "+1234567890",
    "fromNumber": "+0987654321",
    "customerName": "John Doe",
    "dynamicVariables": {
      "company": "Acme Corp",
      "purpose": "Follow-up on quote"
    },
    "metadata": {
      "campaign_id": "summer_2026"
    }
  }'

Response 201 Created

{
  "data": {
    "id": "call-uuid-here",
    "status": "queued",
    "taskId": "task-xyz-123"
  },
  "requestId": "req-abc123"
}

Errors

Code	Cause
validation_error	Missing agentId, toNumber, or fromNumber
not_found	Agent doesn't exist or doesn't belong to your org
forbidden	fromNumber doesn't belong to your org

---

List calls

GET /v1/calls

Retrieve a paginated list of calls for your organization.

Required scope: calls:read

Query parameters

Parameter	Type	Description
page	integer	Page number (default: 1)
limit	integer	Results per page (default: 20, max: 100)
status	string	Filter by call status
direction	string	Filter by direction: INBOUND or OUTBOUND
dateFrom	string	ISO 8601 — only calls after this date
dateTo	string	ISO 8601 — only calls before this date

Example

curl "https://api.replicer.ai/v1/calls?status=completed&limit=10" \
  -H "Authorization: Bearer rpl_live_your_key"

Response 200 OK

{
  "data": [
    {
      "id": "clx-call-001",
      "customerName": "John Doe",
      "customerPhone": "+1234567890",
      "duration": 240,
      "status": "completed",
      "direction": "OUTBOUND",
      "disconnectionReason": "agent_hangup",
      "sentiment": "positive",
      "summary": "Discussed pricing for enterprise plan...",
      "transcript": "Agent: Hello, this is...",
      "recording": "https://storage.example.com/recordings/...",
      "callSuccessful": true,
      "tokenCost": 12.50,
      "agentId": "clx-agent-001",
      "campaignId": "clx-campaign-001",
      "startedAt": "2026-04-05T14:00:00Z",
      "endedAt": "2026-04-05T14:04:00Z",
      "createdAt": "2026-04-05T13:59:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 10,
    "total": 150,
    "totalPages": 15
  },
  "requestId": "req-def456"
}

---

Get a call

GET /v1/calls/{id}

Retrieve details of a specific call.

Required scope: calls:read

Path parameters

Parameter	Description
id	The call ID

Example

curl https://api.replicer.ai/v1/calls/clx-call-001 \
  -H "Authorization: Bearer rpl_live_your_key"

Response 200 OK

{
  "data": {
    "id": "clx-call-001",
    "customerName": "John Doe",
    "customerPhone": "+1234567890",
    "duration": 240,
    "status": "completed",
    "direction": "OUTBOUND",
    "disconnectionReason": "agent_hangup",
    "sentiment": "positive",
    "summary": "Discussed pricing...",
    "transcript": "Full transcript here...",
    "recording": "https://storage.example.com/...",
    "callSuccessful": true,
    "tokenCost": 12.50,
    "agentId": "clx-agent-001",
    "campaignId": null,
    "startedAt": "2026-04-05T14:00:00Z",
    "endedAt": "2026-04-05T14:04:00Z",
    "createdAt": "2026-04-05T13:59:00Z"
  },
  "requestId": "req-ghi789"
}

Call status values

Status	Description
queued	Call is queued for processing
in_progress	Call is currently active
completed	Call finished normally
failed	Call failed to connect
cancelled	Call was cancelled before connecting