Skip to main content
The Xobito Public API lets you manage contacts, chats, templates, canned responses, and organization settings, and send WhatsApp messages — all the same operations available from the dashboard, callable from your own backend.

Base URL

All request/response examples in this documentation use https://api.xobito.com — swap in your own environment’s host if you’re pointed at a different one.

Authentication

Every request carries your API key in a header — there’s no OAuth flow, no bearer token exchange:
See API Authentication with API Keys for how to create and rotate keys.

Making a request

GET routes take query/path parameters only. Every list/write route in this API takes a JSON body on POST/PUT, even list — there’s no GET with query-string filters:
cURL

Response format

Every response — success or error — shares one envelope:
200
422 error
boolean
true on every 2xx, false otherwise.
string
An internal code, e.g. "HC-1" for a generic success, "HC-10" for a generic 422. Not consistent across routes for the same conceptual error — a “not found” is C-1/data_not_found on some routes and CT-1/validation.not_found or ORG-20/a resource-specific *_not_found on others, documented per-route throughout this API. Don’t match on code alone across different endpoints; see API Error Codes and Responses.
integer
Present on error responses, mirrors the actual HTTP status.
string
Machine-readable outcome name, e.g. "success_200", "error_422", or a route-specific "validation.xxx_not_found".
string
Human-readable summary.
object
The actual payload on success — shape documented per-endpoint throughout this API. Absent on error responses.
array
Present only on 422 — one string per failing field.
See API Error Codes and Responses for the fuller error-code reference.

Status codes observed across this API

integer
Success.
integer
Malformed request body (not valid JSON).
integer
payment_required — the organization has no active subscription. Documented on most write/list routes; not independently reproduced live on every single one.
integer
Resource not found. code/name vary by route — see the note on code above.
integer
Request body is valid JSON but fails schema validation — error lists every failing field.
integer
A missing, invalid, revoked, or expired x-api-key. See Authentication.
integer
A problem on Xobito’s side. Try again, and contact support if it keeps happening.

Sending messages is asynchronous

The three send calls (template, service message and canned response) don’t wait for the message to be sent. They check the channel (and the template or canned response), queue the message, and return message_id with status: "queued" straight away. A 200 means “accepted”, not “sent”. Track what happens next with message webhooks. See Sending is asynchronous for the details, including the cases where a queued message is dropped without an error.

Scopes

Every route requires a scope in the resource:read/resource:write shape (e.g. contact:read, chat:write) — inferred by convention from the resource each route operates on, and noted on every endpoint page, but not independently confirmed against a key with mismatched scopes for every single route. See API Permissions and Scopes for the full list.

Next steps

API Authentication with API Keys

Create, rotate, and scope an API key.

API Permissions and Scopes

Every scope this API checks, and what it gates.

API Error Codes and Responses

The full error envelope and code reference.

List and Search Channels

A good first real call — no write scope needed.