Requests and responses

JSON in, JSON out, with a consistent status envelope. The handful of exceptions are listed here.

Format

Request and response bodies are JSON (Content-Type: application/json). Two exceptions:

• Add a file to a knowledge base takes multipart/form-data with a file part.
• Preview a voice returns MP3 audio (audio/mpeg), not JSON.

The envelope

Every JSON response carries a status field.

{ "status": "success", "contact": { "…": "…" } }

{ "status": "error", "error": "Contact 3f1c… not found in this sub-account" }

The payload sits next to status under a key named after the resource (contact, contacts, pipeline, invoice, …). Error responses never include stack traces or internal details; the error string is safe to show to users.

IDs and tenancy

Resource ids are UUIDs unless an endpoint says otherwise. An id that belongs to another sub-account returns 404, exactly like an id that doesn’t exist, so you can’t probe for other tenants’ data.

Unknown fields

Body fields an endpoint doesn’t declare are silently dropped, not rejected. If a field you sent has no effect, check the endpoint’s parameter table for its exact name.

Dates and phone numbers

• Timestamps are ISO 8601 in UTC, e.g. 2026-10-01T10:00:00.000Z.
• Phone numbers are E.164 (+14155550123). Values that aren’t valid E.164 are dropped on write.

Loop prevention

If you both write to Centerfy and subscribe to its outbound webhooks, send X-Webhook-Source on your requests so your own changes aren’t echoed back. Details: X-Webhook-Source header.