Public API overview

The Ringee Public API uses Custom Integrations to let an external system sync contacts and companies, receive call activity, open a secure dialer and run AI Voice Agents. CRM synchronization is bidirectional and event-based. AI Voice Agent execution uses resource-oriented endpoints that return call ids for asynchronous result polling.

Authentication

Create an integration and get your cik_live_ API key

AI Voice Agents

List agents, start calls and read structured results

Build an integration

End-to-end guide with idempotency, retries and loop prevention

What you can do

Capability	Direction	Endpoint
Create and update contacts and companies	CRM → Ringee	`POST /api/integrations/custom/webhook`
Archive deleted contacts and companies	CRM → Ringee	`POST /api/integrations/custom/webhook`
Open a secure dialer for a contact	CRM → Ringee	`POST /api/integrations/custom/click-to-call`
List configured AI Voice Agents	App → Ringee	`GET /api/v1/ai-voice-agents`
Start an autonomous AI voice call	App → Ringee	`POST /api/v1/ai-voice-agents/:id/calls`
Read AI voice call results	App → Ringee	`GET /api/v1/ai-voice-agents/calls/:callId`
Receive completed, missed and failed calls	Ringee → App	Your webhook URL
Receive outcomes, notes, callbacks, meetings	Ringee → App	Your webhook URL
Receive recordings and Do Not Call entries	Ringee → App	Your webhook URL

How it works

Inbound (CRM → Ringee): you send events to a single Ringee endpoint, authenticated with your secret API key. See Inbound events.
Outbound (Ringee → CRM): Ringee sends HMAC-signed events to the URL you configure, with automatic retries. See Outbound webhooks.
Click-to-call: you exchange a contact for a short-lived, signed dialer URL your agent opens in the browser. See Click-to-call.
AI Voice Agents: your server lists configured agents, starts calls and polls normalized results. See AI Voice Agents API.

The event envelope

Every event in both directions shares the same envelope:

{
  "event": "contact.upserted",
  "eventId": "crm_01HX5Z7K8MZP1Q4V0G9YJ2RH3T",
  "occurredAt": "2026-05-23T14:30:00.000Z",
  "data": {}
}

Outbound events (Ringee → your application) add two fields:

{
  "workspaceId": "org_2k7yX...",
  "integrationId": "ci_..."
}

They can also add shared source fields under data:

{
  "user": {
    "id": "usr_…",
    "email": "ada@babbage.example.com",
    "fullName": "Ada Lovelace"
  },
  "agent": { "id": "va_…", "name": "Sofia" },
  "externalId": "crm-contact-42"
}

data.user identifies the Ringee user the event belongs to. data.agent is present when an AI Voice Agent produced the event. If you start that call with metadata.external_id or metadata.externalId, Ringee copies it to data.externalId on every related outbound event.

eventId must identify one logical event and remain stable across transport retries. If Ringee returns status: "failed" while processing an inbound event, fix the payload and use a new eventId; the original id is already recorded.

Choosing the right integration surface

Ringee exposes several ways to build on top of it. They solve different problems and can be combined.

Public API

Server to server. Sync CRM records and receive call activity. Requires a backend.

Dialer SDK

Browser. Embed a real dialer in your own web app. No backend required.

MCP

AI agents. Let Claude or ChatGPT operate Ringee on the user’s behalf.

AI Voice Agents

Autonomous calls. Place server-originated conversations and read structured results.

A typical CRM integration uses both the Public API (to sync data and log activity) and either click-to-call or the Dialer SDK (to actually place calls from the CRM UI).

Every inbound, click-to-call and AI Voice Agent request uses the Custom Integration cik_live_… key. AI Voice Agent endpoints also accept that same key as a Bearer credential.

Base URL

Deployment	Base URL
Hosted	`https://api.ringee.io`
Self-hosted	Your `BACKEND_URL` (see Configuration reference)

All endpoints in this section are relative to that base URL and live under the global /api prefix.

Limits and expectations

Ringee considers an outbound delivery failed if your endpoint does not respond within 15 seconds or returns a non-2xx status.
Failed deliveries are retried up to 10 times with exponential backoff, capped at 5 minutes between attempts.
Outbound deliveries are independent and can arrive out of order. Use eventId for idempotency and data.callId for call-level correlation.
Event payloads can gain optional fields over time. Ignore unknown keys and validate the fields your integration actually needs.
Ringee currently emits terminal call events only. There are no call.started, call.ringing or call.answered events — do not build a real-time incoming-call screen on top of this API.

Get Started

CRM to Ringee

Ringee to CRM

Guides

Authentication

AI Voice Agents

Build an integration

What you can do

How it works

The event envelope

Choosing the right integration surface

Public API

Dialer SDK

MCP

AI Voice Agents

Base URL

Limits and expectations

Next steps

Create your API key

Event reference

Authentication

AI Voice Agents

Build an integration

​What you can do

​How it works

​The event envelope

​Choosing the right integration surface

Public API

Dialer SDK

MCP

AI Voice Agents

​Base URL

​Limits and expectations

​Next steps

Create your API key

Event reference

What you can do

How it works

The event envelope

Choosing the right integration surface

Base URL

Limits and expectations

Next steps