Build on Reception AI

Integration API

A small, read-only REST API for piping Reception AI call history and metrics into your CRM, data warehouse, or internal tools. Authenticate with a scoped API key, hit three endpoints, done.

Create an API key Jump to quickstart

Scoped to one organization
Read-only by design
JSON, no SDK required

Overview

The Integration API is the boundary between Reception AI and the rest of your stack. Use it to sync calls into a CRM, warehouse calls for reporting, or trigger workflows when a new lead is captured. It is deliberately narrow: you cannot change the assistant, buy numbers, or manage users through it.

Base URL

https://voiceapi.klarnow.ai/api/integrations/v1

Auth

X-Api-Key: krai_…

Quickstart

An organization admin opens Settings → Connect apps and creates a new key. The secret is shown once—store it in your backend.
Include the key on every request using the X-Api-Key header.
Make a GET request to one of the endpoints below and parse the JSON response.

curl -sS "https://voiceapi.klarnow.ai/api/integrations/v1/calls" \
  -H "X-Api-Key: krai_your_secret_here"

Treat the key like a password

Never embed an integration key in a browser, mobile app, or public repo. Rotate keys in Settings → Connect apps if one is exposed.

Security

Authentication

Every request must include your API key in one of two headers. Both are accepted and behave the same; pick whichever fits your HTTP client best.

X-Api-Key: krai_your_secret_here

Key format

Keys always start with krai_and are opaque random strings. Don't depend on their length or shape.

Scope

Each key is bound to a single organization. It cannot read data from other organizations, even if their ids are known.

Endpoints

Three JSON endpoints. All are GET only. Paths are relative to the base URL above.

List calls

GET/integrations/v1/calls

All calls for the organization, newest first.

Returns an array of call objects. Use this to sync call history on a schedule or on demand.

Response

[
  {
    "id": "call_01HW3Z…",
    "organizationId": "org_01HW3Y…",
    "callerNumber": "+441234567890",
    "callerName": "Ada Lovelace",
    "callType": "new_enquiry",
    "outcome": "lead_captured",
    "duration": 142,
    "summary": "Caller asked about same-day delivery and left contact details.",
    "transcript": "Assistant: Hello…",
    "recordingUrl": "https://…/recordings/call_01HW3Z.mp3",
    "leadData": {
      "name": "Ada Lovelace",
      "email": "[email protected]",
      "note": "Wants a quote for 50 units"
    },
    "createdAt": "2026-04-22T10:14:07.000Z"
  }
]

Retrieve stats

GET/integrations/v1/calls/stats

Aggregated call metrics for the organization.

Returns a single stats object. Ideal for dashboards and BI tools.

Response

{
  "totalCalls": 42,
  "averageDuration": 95.5,
  "callsByType": {
    "new_enquiry": 10,
    "existing_client": 5,
    "staff": 1,
    "referral": 0,
    "unknown": 0
  },
  "callsByOutcome": {
    "lead_captured": 8,
    "transferred": 2,
    "callback_scheduled": 4,
    "message_taken": 6,
    "resolved": 22
  },
  "leadsCaptured": 8
}

Retrieve a call

GET/integrations/v1/calls/:id

A single call by its id.

Returns one call object. Responds with 404 when the id is unknown or belongs to another organization.

cURL

curl -sS "https://voiceapi.klarnow.ai/api/integrations/v1/calls/call_01HW3Z" \
  -H "X-Api-Key: krai_your_secret_here"

Schema

The call object

Every call is returned as a JSON object with the fields below. Additional fields may appear over time—treat the schema as additive.

idstring
Unique identifier for the call.
organizationIdstring
The organization that owns the call. Always matches the key holder.
callerNumberstring
E.164-formatted number of the caller, e.g. +441234567890.
callerNamestring | null
Name captured during the call, if the assistant collected one.
callTypeenum
One of new_enquiry, existing_client, staff, referral, or unknown.
outcomeenum
One of lead_captured, transferred, callback_scheduled, message_taken, resolved.
durationinteger
Length of the call, in seconds.
summarystring
Short human-readable summary of what happened.
transcriptstring | null
Full transcript, if recording and transcription are enabled.
recordingUrlstring | null
Signed URL to the audio recording, if available.
leadDataobject | null
Structured fields the assistant collected (name, email, notes, etc.).
createdAtstring
ISO-8601 timestamp when the call ended.

Example call

{
  "id": "call_01HW3Z…",
  "organizationId": "org_01HW3Y…",
  "callerNumber": "+441234567890",
  "callerName": "Ada Lovelace",
  "callType": "new_enquiry",
  "outcome": "lead_captured",
  "duration": 142,
  "summary": "Caller asked about same-day delivery and left contact details.",
  "transcript": "Assistant: Hello…",
  "recordingUrl": "https://…/recordings/call_01HW3Z.mp3",
  "leadData": {
    "name": "Ada Lovelace",
    "email": "[email protected]",
    "note": "Wants a quote for 50 units"
  },
  "createdAt": "2026-04-22T10:14:07.000Z"
}

Schema

The stats object

A rollup of the organization's calls. Great for summary widgets without needing to page through every call.

totalCallsinteger
Total number of calls in the period.
averageDurationnumber
Mean call length in seconds across the period.
callsByTypeobject
Count of calls bucketed by callType.
callsByOutcomeobject
Count of calls bucketed by outcome.
leadsCapturedinteger
Number of calls whose outcome was lead_captured.

Errors

The API uses standard HTTP status codes. Error responses are JSON and include a human-readable message.

Code	Meaning
200	Request succeeded.
401	Missing, malformed, or revoked API key.
404	Resource not found or not owned by the key's organization.
5xx	Transient server error. Retry with exponential backoff.

Out of scope

Not available on this API

Integration keys cannot buy phone numbers, change the assistant, upload documents, or manage users. Those flows live in the Reception AI dashboard and the signed-in account APIs—not this key.

If you need programmatic control over account settings, contact us and we'll talk through the right approach for your use case. API base for those authenticated routes is https://voiceapi.klarnow.ai/api.

Ready to connect your stack?

Create a key in minutes—no approval step, no external tooling.

Create an API key