All guides

API reference

Every endpoint in the Ritmo API, rendered from the same document the server publishes.

Download the OpenAPI documentRead the API guide

Base URL

https://ritmo-api.uritm.com/api

Authentication

Issue a key in Settings → API. Send both halves as one bearer token separated by a colon: Authorization: Bearer rk_live_XXXX:YOUR_SECRET. The public half is safe to log; the secret half is shown once, at creation, and can never be displayed again. A key with no scopes has full access — narrow it by granting only the scopes it needs.

curl https://ritmo-api.uritm.com/api/v1/contacts \
  -H "Authorization: Bearer rk_live_XXXX:YOUR_SECRET"

Contacts

People in the workspace, and saved audience filters.

GET/v1/contactscontacts:read

List contacts

Paged, newest first. pageSize is capped at 200 regardless of what you ask for.

Parameters

searchstringMatches name, email or phone.
pageinteger
pageSizeinteger

Responses

200A page of contacts.
401The key is missing, malformed, revoked or expired. message is one of MISSING_API_KEY, MALFORMED_API_KEY, INVALID_API_KEY.
403The key is valid but lacks the scope this route needs. message is MISSING_SCOPE:<scope>.
429More than 120 requests in a minute for this key. The ceiling is per key, not per address.
POST/v1/contactscontacts:write

Create a contact

At least one of email or phone is required: a contact with neither cannot be matched to a conversation, an import row or a broadcast recipient, so it is a row nothing can ever reach.

Request body

{
  "name": "Mona Ahmed",
  "phone": "201000000001",
  "tags": [
    "vip"
  ],
  "attributes": {
    "city": "Cairo"
  }
}

Responses

201The created contact.
400Validation failed, or neither email nor phone was given (CONTACT_NEEDS_IDENTITY).
401The key is missing, malformed, revoked or expired. message is one of MISSING_API_KEY, MALFORMED_API_KEY, INVALID_API_KEY.
403The key is valid but lacks the scope this route needs. message is MISSING_SCOPE:<scope>.
429More than 120 requests in a minute for this key. The ceiling is per key, not per address.
GET/v1/segmentscontacts:read

List saved audiences

The filters a broadcast can target. cachedCount is for display only — a campaign re-runs the query when it starts, so a stale count never decides who gets messaged.

Responses

200Every segment in the workspace.
401The key is missing, malformed, revoked or expired. message is one of MISSING_API_KEY, MALFORMED_API_KEY, INVALID_API_KEY.
403The key is valid but lacks the scope this route needs. message is MISSING_SCOPE:<scope>.
429More than 120 requests in a minute for this key. The ceiling is per key, not per address.

Messages

Replying inside an existing conversation.

POST/v1/messagesmessages:write

Reply in a conversation

Sends into an existing conversation. There is no route to start one: on WhatsApp, Messenger and Instagram the customer has to write first, and a bulk first-contact belongs in a broadcast with an approved template. Outside a WhatsApp 24-hour window the message is stored as failed with code 131047 rather than being delivered.

Request body

{
  "conversationId": "clx…",
  "text": "Your order shipped today."
}

Responses

201The queued message.
400Validation failed, or the conversation does not exist.
401The key is missing, malformed, revoked or expired. message is one of MISSING_API_KEY, MALFORMED_API_KEY, INVALID_API_KEY.
402The monthly message allowance is spent or the workspace is suspended.
403The key is valid but lacks the scope this route needs. message is MISSING_SCOPE:<scope>.
429More than 120 requests in a minute for this key. The ceiling is per key, not per address.

OTP

One-time passcodes and transactional SMS through the tenant’s own provider account.

POST/v1/otp/sendotp:send

Send an SMS

Goes out on the workspace’s own SMS provider account, which must be verified with a test send first — an unverified provider is refused before any HTTP call, so a mistyped password cannot quietly burn your provider credit. Ritmo never stores the passcode.

Request body

{
  "mobile": "201000000001",
  "message": "Your code is 448120",
  "lang": "E"
}

Responses

201The gateway answered. Check sent — a rejected send is a 201 with sent: false, not an HTTP error, because the request itself was valid.
400Validation failed, or no verified provider is configured.
401The key is missing, malformed, revoked or expired. message is one of MISSING_API_KEY, MALFORMED_API_KEY, INVALID_API_KEY.
402More than 60 sends in a minute for this workspace (OTP_RATE_LIMITED), or the credit balance is too low (INSUFFICIENT_CREDITS).
403The key is valid but lacks the scope this route needs. message is MISSING_SCOPE:<scope>.
429More than 120 requests in a minute for this key. The ceiling is per key, not per address.

Templates

Approved WhatsApp message templates.

GET/v1/templatestemplates:read

List approved WhatsApp templates

Only templates Meta has approved, because only those can be sent. bodyVariableCount counts the distinct {{n}} placeholders in the body, which is exactly how many parameters a send must supply.

Responses

200Approved templates, by name.
401The key is missing, malformed, revoked or expired. message is one of MISSING_API_KEY, MALFORMED_API_KEY, INVALID_API_KEY.
403The key is valid but lacks the scope this route needs. message is MISSING_SCOPE:<scope>.
429More than 120 requests in a minute for this key. The ceiling is per key, not per address.

Broadcasts

Bulk campaigns on WhatsApp, Telegram and SMS.

GET/v1/broadcastsbroadcasts:read

List campaigns

The hundred most recent campaigns, newest first.

Responses

200Recent campaigns.
401The key is missing, malformed, revoked or expired. message is one of MISSING_API_KEY, MALFORMED_API_KEY, INVALID_API_KEY.
403The key is valid but lacks the scope this route needs. message is MISSING_SCOPE:<scope>.
429More than 120 requests in a minute for this key. The ceiling is per key, not per address.
POST/v1/broadcasts/{id}/startbroadcasts:write

Start or resume a campaign

A draft or scheduled campaign moves to QUEUED and its audience is materialised on the next worker tick. A paused one goes straight back to RUNNING and keeps the recipients it already has.

Parameters

idstring · in path · required

Responses

201The campaign, with its new status.
400The campaign is already running, completed or cancelled (BROADCAST_NOT_STARTABLE).
401The key is missing, malformed, revoked or expired. message is one of MISSING_API_KEY, MALFORMED_API_KEY, INVALID_API_KEY.
403The key is valid but lacks the scope this route needs. message is MISSING_SCOPE:<scope>.
404No campaign with that id in this workspace.
429More than 120 requests in a minute for this key. The ceiling is per key, not per address.

Usage

This calendar month, per channel.

GET/v1/usageusage:read

This month’s usage

The calendar month in UTC, not a rolling thirty days. A null limit means unlimited on this plan.

Responses

200Plan, limits and usage.
401The key is missing, malformed, revoked or expired. message is one of MISSING_API_KEY, MALFORMED_API_KEY, INVALID_API_KEY.
403The key is valid but lacks the scope this route needs. message is MISSING_SCOPE:<scope>.
429More than 120 requests in a minute for this key. The ceiling is per key, not per address.

API version 1.0.0