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",
    "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.

Reading the response

The endpoint returns 202 Accepted for any well-formed, authenticated request. The real result is in the JSON body.

Status	Meaning	What to do
processed	The event was applied.	Mark the sync as successful.
skipped	Duplicate `eventId`. Already applied earlier.	Treat as success.
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.

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" }
  }
}

Deduplication order: externalId first, then phoneNumber within the same workspace. Sending null, undefined or empty strings does not overwrite existing values — omit a field to leave it untouched.

{
  "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"
  }
}

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" }
}

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.

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

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

Ringee normalizes what it can, but +14155550123 always wins over (415) 555-0123. A number Ringee cannot normalize may fail dedup against an existing contact.

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

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.

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.ownerExternalId

string

External owner id (sales rep).

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. Surface it in your sync logs.

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",
    "ownerEmail": "rep@example.com",
    "customFields": {
      "tier": "vip"
    }
  }
}
'

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

Get Started

CRM to Ringee

Ringee to CRM

Guides

Reading the response

Event examples

Sending events well

Next steps

Click-to-call

Outbound webhooks

Authorizations

Body

Response

​Reading the response

​Event examples

​Sending events well

​Next steps

Click-to-call

Outbound webhooks

Authorizations

Body

Response

Reading the response

Event examples

Sending events well

Next steps