Inbound events

POST

api

integrations

custom

webhook

curl --request POST \
  --url https://api.ringee.io/api/integrations/custom/webhook \
  --header 'Content-Type: application/json' \
  --header 'X-Ringee-Api-Key: <api-key>' \
  --data '
{
  "event": "contact.upserted",
  "eventId": "crm_01HX5Z7K8MZP1Q4V0G9YJ2RH3T",
  "occurredAt": "2026-05-23T14:30:00.000Z",
  "data": {
    "externalId": "ext_contact_42",
    "phoneNumber": "+14155550123",
    "firstName": "Ada",
    "lastName": "Lovelace",
    "email": "ada@example.com",
    "companyExternalId": "ext_company_7",
    "jobTitle": "Founder",
    "campaignId": "3f8a1c54-9d2b-4e7a-b1c6-5a0d9e8f7c21",
    "ownerEmail": "rep@example.com",
    "customFields": {
      "tier": "vip"
    }
  }
}
'

{
  "status": "processed",
  "eventId": "crm_9f1c2a7e"
}

Send everything your CRM knows about a contact or company to a single Ringee endpoint. Ringee upserts the record, links it to your externalId, and makes it callable. Pick the event you are sending in the request body above — each one has its own data shape.

The envelope

Every request uses the same four top-level fields:

Field	Type	Required	Description
`event`	string	Yes	One of the four inbound event names below
`eventId`	string	Yes	Stable unique id for this logical event
`occurredAt`	string	Yes	ISO-8601 timestamp from your system
`data`	object	Yes	Event-specific payload

Reading the response

The endpoint returns 202 Accepted for any authenticated request with a complete envelope. The real result is in the JSON body.

Status	Meaning	What to do
processed	The event was applied.	Mark the sync as successful.
skipped	Ringee already recorded this `eventId`.	Do not process it again. Preserve the original result; retry a corrected failure with a new id.
failed	The event was accepted but could not be applied.	Show `message`, mark as a sync failure, fix and resend with a new `eventId`.

A 202 status code only means the transport was accepted. Do not treat it as a successful sync without checking status in the body.

Warnings

A processed response can also carry a warnings array. The event applied, but something you sent had no effect:

{
  "status": "processed",
  "eventId": "crm_9f1c2a7e",
  "warnings": [
    "Unknown contact.upserted fields were ignored: campagnId. Check them for typos.",
    "data.ownerEmail \"rep@example.com\" does not match a member of this workspace; the contact was left unassigned."
  ]
}

Warnings are how you find the bugs that do not fail: a misspelled field name, a number without a country code, an owner nobody in Ringee matches. Log them while you build and surface them on your settings screen — a field Ringee dropped silently is the most expensive kind of sync bug to find later.

What the endpoint guarantees

An event applies completely or not at all

Ringee validates the whole payload — field shapes, the phone number, the campaign you named — before it writes anything. A failed response means nothing was created or updated, so you can correct the payload and send it again knowing Ringee holds no half-synced record.

One request tells you everything that is wrong

Problems are reported together, not one per round trip. A missing externalId and a missing phoneNumber come back in the same message:

{
  "status": "failed",
  "eventId": "crm_9f1c2a7e",
  "message": "data.externalId is required; data.phoneNumber is required"
}

The same eventId is never applied twice

eventId is the idempotency key, scoped to your integration. A transport retry is free: the second delivery returns skipped and changes nothing. That also means a corrected payload needs a new id — the old one is already recorded.

Omitting a field never clears it

Ringee patches, it does not replace. Send only what changed: null, undefined and empty strings leave the stored value alone. To blank a field, clear it in Ringee.

Event examples

contact.upserted
company.upserted
contact.deleted
company.deleted

Create or update a contact from your CRM’s current state.

{
  "event": "contact.upserted",
  "eventId": "crm_01HX5Z7K8MZP1Q4V0G9YJ2RH3T",
  "occurredAt": "2026-05-23T14:30:00.000Z",
  "data": {
    "externalId": "ext_contact_42",
    "phoneNumber": "+14155550123",
    "firstName": "Ada",
    "lastName": "Lovelace",
    "email": "ada@example.com",
    "companyExternalId": "ext_company_7",
    "jobTitle": "Founder",
    "ownerEmail": "rep@example.com",
    "customFields": { "tier": "vip" }
  }
}

string

required

Stable contact id in your system. The primary deduplication key.

string

required

Dialable number. Required because the point of a synced contact is that somebody can call it — see Phone numbers.

string

Display name.

string

Given name.

string

Family name.

string

Pre-composed full name.

string

Primary email.

string

External company id to link. Ringee creates the company when no link exists yet and companyName is present.

string

Fallback company name when a linked company is unavailable.

string

Contact position or title.

string (UUID)

Ringee campaign to add this contact to as a lead — see Adding a contact to a campaign.

string

Resolves a Ringee member in an organization workspace. An email nobody matches leaves the contact unassigned and returns a warning.

string

Accepted and kept in the stored snapshot, but not currently used for owner resolution.

string

Lead source label.

object

Arbitrary contact fields.

object

Provider-specific metadata.

Deduplication order: externalId first, then the normalized phoneNumber within the same workspace.

In a personal workspace the integration owner owns every synced contact, and ownerEmail is not used.

{
  "event": "company.upserted",
  "eventId": "crm_01HX5Z8FYBKD7QY5W3JN9NF2EA",
  "occurredAt": "2026-05-23T14:30:05.000Z",
  "data": {
    "externalId": "ext_company_7",
    "name": "Babbage Engines Ltd.",
    "domain": "babbage.example.com",
    "industry": "Hardware",
    "size": "11-50"
  }
}

string

required

Stable company id in your system.

string

required

Display name.

string

Registered legal name.

string

Primary domain, used as a secondary deduplication signal.

string

Industry label.

string

Headcount band, such as 11-50.

string

Main phone.

string

Homepage URL.

string

Source label.

object

Arbitrary company fields.

object

Provider-specific metadata.

Deduplication order: externalId, then domain within the same workspace.

Marks the contact as archived in Ringee.

{
  "event": "contact.deleted",
  "eventId": "crm_01HX5Z9MQ7G3T2DR0NXJW1B8VC",
  "occurredAt": "2026-05-23T14:35:00.000Z",
  "data": { "externalId": "ext_contact_42" }
}

string

required

External contact id previously sent in contact.upserted.

Ringee never deletes the underlying contact. Call history, notes, callbacks and meetings are preserved — only the integration’s link is archived. Re-sending contact.upserted with the same externalId un-archives it. If no link exists, the delete is a successful no-op.

{
  "event": "company.deleted",
  "eventId": "crm_01HX5ZA1H4T6N2DR9CB7YP6F0K",
  "occurredAt": "2026-05-23T14:35:30.000Z",
  "data": { "externalId": "ext_company_7" }
}

string

required

External company id previously sent in company.upserted.

This archives only the link created by this integration. Historical company relationships remain available in Ringee. If no link exists, the delete is a successful no-op.

Phone numbers

Ringee normalizes data.phoneNumber to E.164 against real numbering plans. That normalized value is what agents dial and what deduplication matches on.

You send	Ringee stores	Response
`+14155550123`	`+14155550123`	Clean.
`+34 911 23 45 67`	`+34911234567`	Clean — punctuation is not a problem.
`(415) 555-0123`	`+14155550123`	A warning: no country code was sent.
`n/a`	nothing	`failed` — `not a dialable number`.

A number with no leading + is read with United States as the assumed country, and the response tells you so. That assumption is wrong for most of the world, so send E.164.

Deduplication matches on the normalized number, so a contact stored under a differently normalized value will not match and a second contact is created. Your externalId link is immune to this: it resolves the same contact regardless of phone formatting.

Adding a contact to a campaign

Include data.campaignId on contact.upserted and the contact joins that outbound campaign as a lead, in the same request that syncs it.

{
  "event": "contact.upserted",
  "eventId": "crm_01HX6B2P4WQF8ND3ZR7KT5YVMA",
  "occurredAt": "2026-05-23T14:31:00.000Z",
  "data": {
    "externalId": "ext_contact_42",
    "phoneNumber": "+14155550123",
    "firstName": "Ada",
    "campaignId": "3f8a1c54-9d2b-4e7a-b1c6-5a0d9e8f7c21"
  }
}

The campaign id is the last segment of the campaign URL in the dashboard, under Campaigns. What it does:

The contact is added as a pending lead. If the campaign is already running, the lead is queued for dialing immediately.
A contact that is already a lead of that campaign is left untouched. Its attempts, status and disposition history survive every re-sync, so a CRM that replays contact.upserted on each edit never resets a lead’s progress.
Membership is only ever added. Dropping campaignId from a later event does not remove the lead — remove it in Ringee.

Campaigns exist only in organization workspaces, and the campaign must belong to the same workspace as your integration. A campaignId that is not a UUID, matches no campaign, or belongs to another workspace fails the event — and because validation runs before any write, the contact is not synced either. Correct it and resend with a new eventId.

Sending events well

Do not send on every render or save

Sync only when a field Ringee cares about actually changes: name, phone, email, company, job title, owner. Sending an event on every UI update wastes quota and makes your logs unreadable.

Use E.164 phone numbers

+14155550123 always wins over (415) 555-0123. See Phone numbers for what Ringee does with the difference.

Treat warnings as bugs

An ignored field and an unmatched owner are invisible in production and obvious in the response. Fail your integration tests on any unexpected warnings entry.

Never re-send what Ringee wrote

If your CRM record was created or updated by a Ringee webhook, do not send it back. Store a sync_origin marker on those rows and skip them. See Build an integration.

Queue before you send

Write the event to a local outbox table first, then attempt delivery. A contact save in your CRM should never fail because Ringee is momentarily unreachable.

Next steps

Click-to-call

Open a secure dialer for a synced contact

Outbound webhooks

Receive call activity back in your CRM

Logs and errors

Every inbound error message and how to fix it

Build an integration

The full two-way sync, end to end

Authorizations

X-Ringee-Api-Key

string

header

required

The cik_live_ secret key of a Custom Integration. Shown once at creation. Server-side only.

Body

application/json

contact.upserted
company.upserted
contact.deleted
company.deleted

Create or update a contact from your CRM's current state.

event

string

required

The event type.

Allowed value: "contact.upserted"

eventId

string

required

Unique, stable id for this event. Ringee deduplicates on it.

Example:

"crm_01HX5Z7K8MZP1Q4V0G9YJ2RH3T"

occurredAt

string<date-time>

required

When the change happened in your system.

Example:

"2026-05-23T14:30:00.000Z"

data

object

required

Omit a field to leave it untouched. Sending null, undefined or an empty string does not overwrite an existing value. The whole payload is validated before anything is written, so a rejected event leaves no partial contact behind.

Hide child attributes

data.externalId

string

required

Stable id of the contact in your system. This is the join key for every later event.

Example:

"ext_contact_42"

data.phoneNumber

string

required

Phone in any format; normalized to E.164 when possible. Required because Ringee must be able to dial the contact.

Example:

"+14155550123"

data.firstName

string

Given name.

Example:

"Ada"

data.lastName

string

Family name.

Example:

"Lovelace"

data.fullName

string

Pre-composed full name.

data.name

string

Display name.

data.email

string

Primary email.

Example:

"ada@example.com"

data.companyExternalId

string

External company id to link this contact to.

Example:

"ext_company_7"

data.companyName

string

Fallback company name when no companyExternalId is provided.

data.jobTitle

string

Position or title.

Example:

"Founder"

data.campaignId

string<uuid>

Ringee campaign to add this contact to as a lead. The contact joins as a pending lead, and is queued immediately when the campaign is already running; a contact that is already a lead of that campaign is left untouched. Campaigns exist only in organization workspaces, and the campaign must belong to the same workspace as the integration.

Example:

"3f8a1c54-9d2b-4e7a-b1c6-5a0d9e8f7c21"

data.ownerExternalId

string

External owner id accepted in the stored snapshot. It is not currently used for Ringee owner resolution; use ownerEmail.

data.ownerEmail

string

Owner email — resolves to a Ringee user when the integration is organization-scoped.

Example:

"rep@example.com"

data.source

string

Lead source label.

data.customFields

object

Arbitrary key/value pairs stored on the contact.

data.crmMetadata

object

Provider-specific metadata stored on the contact.

Response

Accepted. Check status in the body to know whether the event was applied.

status

enum<string>

required

processed — applied. skipped — duplicate eventId, already applied earlier; treat as success. failed — accepted but could not be applied; fix and resend with a new eventId.

Available options:

processed,

skipped,

failed

eventId

string

required

Echoes the eventId you sent.

message

string

Present on skipped and failed. On failed it lists every problem found, separated by ; , so one request is enough to learn what to fix.

warnings

string[]

Non-fatal remarks about a payload that was applied anyway: an unknown or mistyped field that was ignored, a phone number read with an assumed country, an ownerEmail matching nobody in the workspace. Absent when there is nothing to report.

curl --request POST \
  --url https://api.ringee.io/api/integrations/custom/webhook \
  --header 'Content-Type: application/json' \
  --header 'X-Ringee-Api-Key: <api-key>' \
  --data '
{
  "event": "contact.upserted",
  "eventId": "crm_01HX5Z7K8MZP1Q4V0G9YJ2RH3T",
  "occurredAt": "2026-05-23T14:30:00.000Z",
  "data": {
    "externalId": "ext_contact_42",
    "phoneNumber": "+14155550123",
    "firstName": "Ada",
    "lastName": "Lovelace",
    "email": "ada@example.com",
    "companyExternalId": "ext_company_7",
    "jobTitle": "Founder",
    "campaignId": "3f8a1c54-9d2b-4e7a-b1c6-5a0d9e8f7c21",
    "ownerEmail": "rep@example.com",
    "customFields": {
      "tier": "vip"
    }
  }
}
'

{
  "status": "processed",
  "eventId": "crm_9f1c2a7e"
}

Get Started

CRM to Ringee

Ringee to CRM

Guides

The envelope

Reading the response

Warnings

What the endpoint guarantees

Event examples

Phone numbers

Adding a contact to a campaign

Sending events well

Next steps

Click-to-call

Outbound webhooks

Logs and errors

Build an integration

Authorizations

Body

Response

​The envelope

​Reading the response

​Warnings

​What the endpoint guarantees

​Event examples

​Phone numbers

​Adding a contact to a campaign

​Sending events well

​Next steps

Click-to-call

Outbound webhooks

Logs and errors

Build an integration

Authorizations

Body

Response

The envelope

Reading the response

Warnings

What the endpoint guarantees

Event examples

Phone numbers

Adding a contact to a campaign

Sending events well

Next steps