REST API v1

Every request is authenticated with your API key from the portal's Webhook & Send API page. The same key opens the REST API, the Send API, and webhooks. Send it as any one of three headers; X-SumGenius-Api-Key is preferred.

The API is server-to-server. CORS is intentionally disabled, so call it from your backend and keep the key out of browsers.

• 401 unauthorized

  No API key sent.

• 401 invalid_api_key

  Key not recognized.

• 403 addon_inactive

  Key is valid but the add-on is not active.

The HTTP status carries success or failure. A single resource arrives as {"data": {...}}; a list adds has_more and next_cursor. Errors carry a stable code to branch on; message is human-facing and may change.

Lists are newest-first and cursor-paginated: pass limit (1 to 100, default 25) and feed next_cursor back as starting_after until has_more is false. Tags and team return their whole set in one page.

Each account may make up to 200 authenticated REST requests per minute, with short bursts of up to 20 requests per second. All active API keys for the account share the same quota, so creating another key does not increase it.

The per-minute quota is measured over a rolling 60-second window rather than a fixed clock minute, so capacity returns gradually as individual requests age out instead of all at once on a boundary.

A separate system-wide safety ceiling protects API availability during aggregate traffic spikes. When either ceiling is reached, the API returns 429 rate_limited. Wait for Retry-After before retrying; use exponential backoff rather than an immediate retry loop.

Every authenticated REST response includes RateLimit-Limit, RateLimit-Remaining, and RateLimit-Reset. Reset is a Unix timestamp. The equivalent X-RateLimit-* headers are also sent for compatibility.

This quota controls requests accepted by /api/v1. Message platforms enforce their own separate, account-specific delivery limits; temporary platform throttles continue through the existing queue and retry behavior.

• timestampsUTC ISO-8601

  Everywhere, e.g. 2026-07-25T04:35:23+00:00. The updated_since filters accept the same format.

• channelenum

  facebook · instagram · sms · telegram · whatsapp

• stageenum

  new · contacted · qualified · customer · lost

• statusenum

  active · resolved · pending · archived · escalated (conversations)

• custom_fieldsobject

  Your own per-contact data, as {field_key: value}. Only fields that are set and active appear; unset fields are omitted, never null. Define fields with POST /custom-fields, write values through PATCH /contacts/{id}.

Your account identity, plan, and configured webhook endpoints. A good first call to verify a key works.

List contacts, newest first. Filters combine with AND. An invalid filter value returns 400 invalid_param.

Query parameters

• channelenumoptional
• stageenumoptional
• tagstringoptional

  Exact tag name; contacts carrying that tag.

• emailstringoptional

  Exact match.

• phonestringoptional

  Exact match.

• namestringoptional

  Substring match on the display name.

• updated_sincetimestampoptional

  Contacts updated at or after this time.

• limit · starting_afterpaginationoptional

One contact by id, in the same shape as the list. A non-numeric, unknown, or unowned id returns 404.

Create or update a contact by its natural identity. A new identity returns 201; an existing one is updated and returns 200. Updates are partial: omitted fields are untouched and existing tags are kept (tags adds, it does not replace).

Body

• channelenumrequired
• platform_user_idstringrequired

  The person's id on that channel, 1 to 255 characters. For SMS this is the phone number.

• namestringoptional

  Up to 255 characters.

• emailstringoptional

  Valid email address.

• phonestringoptional

  Digits and + ( ) . - # x, 3 to 50 characters.

• stageenumoptional
• notesstringoptional

  Up to 5,000 characters.

• tagsstring[]optional

  Tag names; missing tags are created automatically.

• custom_fieldsobjectoptional

  Merged into the contact's fields, applied atomically with the rest of the upsert. Same semantics as PATCH. Fields must already be defined.

Partial update by id. Only fields present in the body change. Send "" to clear a field. Idempotent by nature, so no idempotency key is needed. An empty body returns 400 listing the updatable fields.

Body · all optional

• stageenum
• namestring

  Up to 255 characters, or "" to clear.

• emailstring

  Valid email, or "" to clear.

• phonestring

  3 to 50 characters, or "" to clear.

• notesstring

  Up to 5,000 characters, or "" to clear.

• custom_fieldsobject

  Merge semantics: only the keys you send change, null as a value clears that field, other fields are untouched. Values are validated against each field's type (400 names the offending key). Every actual change fires a contact.field_changed webhook event.

Attach a tag by name. A tag that does not exist yet is created, then attached. Re-attaching is a no-op 200. Returns the updated contact.

Body

• namestringrequired

  1 to 50 characters. Created if missing, with the default color.

Detach a tag from a contact. {tag} is a tag id or a URL-encoded name; a name that is all digits or contains / must go by id. Detaching a tag the contact does not have is an idempotent 200; a tag that does not exist at all is 404. Only the attachment is removed; the tag itself survives.

Permanently erases a person: the contact and every conversation, message, and appointment they have. Built for right-to-erasure requests.

Tag definitions and send-history audit records survive. Repeating the call is a safe 404.

Your field definitions, in creation order. Active fields only by default.

Query parameters

• include_archivedbooleanoptional

  Also return archived definitions (with archived true) so their ids stay discoverable for unarchiving.

Define a field. Returns 201 on create, 200 if an equivalent field already exists (same key and type), 409 if the key exists with a different type or archived, and 400 at the 15-active-field limit.

Body

• field_keystringrequired

  1 to 50 characters of a-z 0-9 _. Permanent after create — it is the JSON key in every payload.

• labelstringrequired

  Display name, 1 to 100 characters. Renameable later.

• typeenumoptional

  text (default, up to 500 chars) · number · date (YYYY-MM-DD) · boolean. Permanent after create.

Rename a field's label, or archive / unarchive it. field_key and type are immutable — sending either returns 400. There is no delete: archiving hides a field from every surface without touching any contact data, and unarchiving restores it (subject to the 15-active limit).

Body

• labelstringoptional
• archivedbooleanoptional

  true hides the field everywhere; false restores it, values intact. Writes to an archived field's values return 400.

List conversations, newest first. contact_id links each thread to its person.

Query parameters

• channelenumoptional
• statusenumoptional
• assigned_tointegeroptional

  A team member id from team.

• updated_sincetimestampoptional
• limit · starting_afterpaginationoptional

Assign or unassign a conversation, exactly like the inbox does it: a pending or escalated thread becomes active, history is recorded, and a system line is added to the transcript. Returns the updated conversation.

Body

• assigned_tointeger | nullrequired

  A team member id from team, or null to unassign. An unknown id is 400.

Permanently deletes one conversation: the full transcript, in-chat appointments, tag labels, and assignment records.

The response counts what was removed. Analytics rows are kept but stripped of message text and unlinked; send-history audit survives. A repeat delete is a safe 404.

The transcript of one conversation, newest first (default limit 50). Copilot drafts are excluded; this is the conversation as the customer saw it.

• directionderived

  user is inbound; bot, agent, followup are outbound; the rest is system.

• typeenum

  text · image · video · audio · file · quick_reply · button · postback · comment_trigger

• body_purgedboolean

  When a body was purged for compliance, text is null and this is true; the message is still listed.

Send on any channel. Same engine as the Send API with full parity; recommended for new integrations. Route by conversation_id, by platform + platform_user_id, or by to_phone for SMS and WhatsApp.

Body

• idempotency_keystringrequired

  Your unique key per send. A replay returns the original result without resending. Also accepted as an Idempotency-Key header.

• actionenumoptional

  send_message (default) · react · unreact · typing_on. Support varies by channel.

• conversation_idinteger

  Route by an existing thread.

• platform + platform_user_idstring

  Route by the person's channel id.

• to_phonestring

  Route by phone (SMS, WhatsApp).

• message_textstringrequired

  Not required for typing_on or WhatsApp template sends (template_name, template_language, template_components).

Cold outbound

SMS, WhatsApp, and Telegram may send to a recipient with no existing conversation; the thread is created automatically. Facebook and Instagram require the customer to message first.

Send errors

All tag definitions, ordered by name, in one page. name is what the contacts ?tag= filter matches.

Create a tag definition. Idempotent on name: new returns 201, existing returns 200 with its color unchanged.

Body

• namestringrequired

  1 to 50 characters, unique per account.

• colorstringoptional

  6-digit hex like #FF0000; anything else is 400.

Deletes a tag definition account-wide and removes it from every contact and conversation carrying it. By numeric id only.

List bookings, newest first.

Query parameters

• statusstringoptional

  Exact match, e.g. confirmed or cancelled. Free text: an unknown value returns an empty list, not 400.

• conversation_idintegeroptional
• limit · starting_afterpaginationoptional

One appointment by id, same shape as the list. Unknown or unowned id returns 404.

Your team members, ordered by name, in one page. A member's id is what assigned_to references and what assign accepts. Credentials and permission data are never exposed.

• roleenum

  agent · manager

• statusenum

  online · away · busy · offline