Build on Reception AI

Integration API

A small, read-only REST API for piping your Reception AI profile, call history, and metrics into your CRM, data warehouse, or internal tools. Authenticate with a scoped API key, hit a handful of 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

A small set of JSON endpoints. All are GET only. Paths are relative to the base URL above.

Retrieve profile

GET/integrations/v1/profile

Profile of the organization that owns the API key.

Returns a single profile object with business details, the assigned phone number, contacts, booking settings, plan, and the account owner. Handy for pre-filling CRM records or verifying which organization a key belongs to.

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

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 profile object

Describes the organization linked to the API key, including the phone number assigned to its AI receptionist and the owner's contact details.

organizationIdstring
Unique identifier for your organization. Matches the key holder.
businessNamestring
Display name of the business as configured in Reception AI.
assistantNamestring | null
Custom assistant display name. Null when using the default.
phoneNumberstring | null
E.164-formatted phone number assigned to the AI receptionist, e.g. +441234567890.
planstring
Billing plan identifier (e.g. trial, starter, professional).
activeboolean
Whether the receptionist is currently live.
onboardingCompleteboolean
True once the organization has finished onboarding and provisioned a number.
trialEndsAtstring | null
ISO-8601 timestamp when the trial ends, if on a trial plan.
receptionistModeenum
One of bookings, enquiries, existing_customers, or multi.
coverageAreastring
Free-text service area the business covers.
servicesstring[]
List of services the business offers.
specialismsstring[]
Optional specialisms or focus areas for the business.
operatingHoursobject
Object with open, close (HH:mm), and IANA timezone.
bookingobject
Object with method (callback | calendar_link | direct_transfer), link, and transferNumber.
contactsobject
Object with escalation and notification contact arrays (name, email, phone).
ownerobject
Primary account owner — object with name and email.
createdAtstring
ISO-8601 timestamp the organization was created.
updatedAtstring
ISO-8601 timestamp of the last update.

Example profile

{
  "organizationId": "org_01HW3Y…",
  "businessName": "Treasure Trove Home Care",
  "assistantName": "Treasure Trove Receptionist",
  "phoneNumber": "+441234567890",
  "plan": "trial",
  "active": true,
  "onboardingComplete": true,
  "trialEndsAt": "2026-05-01T00:00:00.000Z",
  "receptionistMode": "multi",
  "coverageArea": "Greater London",
  "services": ["Home care", "Respite care"],
  "specialisms": ["Dementia support"],
  "operatingHours": {
    "open": "09:00",
    "close": "17:00",
    "timezone": "Europe/London"
  },
  "booking": {
    "method": "callback",
    "link": null,
    "transferNumber": "+441234567000"
  },
  "contacts": {
    "escalation": [
      { "name": "Jane Doe", "phone": "+441234567001", "email": "[email protected]" }
    ],
    "notification": [
      { "name": "Ops Inbox", "email": "[email protected]" }
    ]
  },
  "owner": {
    "name": "Jane Doe",
    "email": "[email protected]"
  },
  "createdAt": "2026-01-12T10:14:07.000Z",
  "updatedAt": "2026-04-20T09:02:31.000Z"
}

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