calls

Create or update a call

Syncs one call from your call-tracking vendor into Ritten's CRM.

This endpoint is idempotent: a call is identified by its provider and externalId, and resubmitting the same pair replaces the stored call in full with the payload you send. Send the complete record every time — retries and corrected re-sends are always safe, and there is no separate update endpoint. Both create and replace return 200 with the stored record.

Two consequences of full-record replace to be aware of:

  • Omitting an optional field (campaign, note) clears any value stored by an earlier send.
  • Staff-made changes in Ritten (linking the call to a case) are never touched by this endpoint.
post/calls

Request

  • Base URL: https://api.ritten.io/v1
  • URL: https://api.ritten.io/v1/calls
  • Auth: none declared

Request body

providerstring required

Lowercase slug identifying your call-tracking vendor (e.g. ringcentral, talkroute). Pick it once and never change it: the slug is part of the call's permanent identity, so calls re-sent under a renamed slug create duplicates instead of updating the originals. The value ctm is reserved for Ritten's built-in CTM integration and is rejected.

externalIdstring required

The call's unique id in your vendor's system. Identifies the call together with provider.

calledAtstring date-time required

When the call started, as an RFC 3339 timestamp.

callerNamestring required

Name of the caller. Unstructured free text; may contain PHI.

direction'inbound' | 'outbound' required

Whether the call was received or placed by the clinic.

phoneNumberstring required

The caller's phone number, in any format your vendor provides.

durationSecondsinteger required

Call duration in seconds.

campaignstring

Marketing campaign attributed to the call. Optional — but because sends are full-record replaces, omitting this field clears any previously stored value.

notestring

Free-text call note or summary. May contain PHI. Optional — but because sends are full-record replaces, omitting this field clears any previously stored value.

Example request

{
  "provider": "ringcentral",
  "externalId": "rec-8842613",
  "calledAt": "2024-01-15T14:32:00Z",
  "callerName": "Jane Doe",
  "direction": "inbound",
  "phoneNumber": "+15551234567",
  "durationSeconds": 142,
  "campaign": "Google Ads",
  "note": "Caller asked about admission availability."
}

Response

Call created or replaced successfully. The stored record is returned in both cases.

idstring uuid

Ritten's id for the call.

providerstring
externalIdstring
callerNamestring
direction'inbound' | 'outbound'
phoneNumberstring
durationSecondsinteger
calledAtstring date-time
campaignstring
notestring
createdAtstring date-time

When the call was first synced into Ritten.

Example response

{
  "id": "182c2e54-3494-4b85-aba5-038cf539d5bf",
  "provider": "ringcentral",
  "externalId": "rec-8842613",
  "callerName": "Jane Doe",
  "phoneNumber": "+15551234567",
  "durationSeconds": 142,
  "calledAt": "2024-01-15T14:32:00Z",
  "campaign": "Google Ads",
  "note": "Caller asked about admission availability.",
  "createdAt": "2024-01-15T14:35:00Z"
}

Changes

No recorded changes to this operation across all 1 revision of this API.