Di API
No private endpoint dey. No even for the interface.
Plenty products get two APIs: the documented one wey dem offer you, and the interesting one wey dem own screens dey use. The second one always better, and dem no ever allow you near am. Here na only one dey, and the interface na client of am like anything else — na constraint for us, and na the reason why everything wey you wan build dey possible.
Wetin that rule really cost
E mean say screen go sometimes wait make the API correct, instead of to go around am take one convenient field. The day wey screen need something wey public API no fit give am, na that day the API wrong, and the fix na the API.
The gain be say three different-different clients no cost anything extra. The MCP server na client. Dash-b tile na client. Your own script na client. None of dem be second-class citizen wey dey work around surface wey dem design for another person, because no other surface dey to be second to.
Documented, and tested
OpenAPI dey generated at /docs and every route get test wey be the example inside the documentation. Documentation wey dem write separate from the code dey drift within one month; documentation wey dey fail the build when e wrong no dey drift.
How yu dey sign in
Your castomo account, through the authorization code flow with PKCE — the same account wey you dey use for dash-b and the rest of the family. Page wey no get server of e own fit run that flow well well; na wetin dem design the flow for. For machine-to-machine work, project-scoped API key.
- 1Pipul
/v1/contacts·/lists·/segments·/tags·/imports - 2Content
/v1/creatives, wit validation, preview and render per target - 3Automation
/v1/funnels·/funnels/:id/versions·/runs·/simulate - 4Broadcast
/v1/campaigns, with audience, materialise, schedule and send as separate steps - 5Event dem wey dey come in
/v1/events— your own application events, as triggers - 6Delivery
/sender-identities·/domains·/apps·/webhooks - 7Nomba dem
/v1/reports/*, and/track/*for di tracking host
OpenAPI dey /docs/mcp for di same process
How we dey do am
Di same shape like every oda castomo service
Which one matter pass as e sound. If you already dey call one of dem, you already know how this one dey answer, fail and paginate.
One error envelope
Every failure get the same shape, stable code and message wey target person. No route dey invent e own way to dey unhappy.
Cursor pagination
No be offset. List wey dey change while you dey waka through am no go quietly skip or repeat rows, wey offset pagination dey do quietly and all the time.
Idempotency keys
For every route wey dey change things. Retry request wey you no sure say land, and you go get the same answer instead of second contact, second campaign or second send.
Scoped to one project
One token dey point to one tenant and one project, the two of dem. Row-level security dey enforced inside the database itself, no be by remembering to add clause.
Webhooks wey dey go out
Signed, retried with backoff, and delivered at least once — so your endpoint suppose dey idempotent too. The events na the same vocabulary wey the reports dey use.
Comot data and export am
Person fit export or erase contact through the API, and erasure go reach every sibling service wey hold copy through the family own internal lane.
Everything wey the interface fit do, na so POST fit do am.
Events na the interesting part
Everything else for this page na plumbing wey you go expect. POST /v1/events na the route wey dey change wetin the product dey for.
Your application already know things wey no marketing tool fit see: who finish onboarding, who invite colleague, who hit limit, who export their data on Sunday afternoon. Post dem as events with your own token, and each one go become trigger, condition and segment.
The rest follow from the contact model. Dem dey append events, dem no dey edit am; na the log wey the whole product hang on. Funnel wey trigger on event wey you define no be integration — na the same mechanism wey message_opened dey use, with different name inside.
- 1You post am
POST /v1/events— name, contact, payload, idempotency key. - 2E landDem append am to the contact log. Nothing else need to know say e exist.
- 3Funnel startAny funnel wey im entry name that event, for any contact wey qualify under im entry spec.
- 4Other funnels branch on am"Dis event don happen for the last 14 days?" na ordinary segment predicate.
- iAnd e end runsGoal node wey name the same event go stop sequence the moment the person do the thing.
Yu own vocabularyYu own token
Boundaries wey good to know before you build
ClickSomo store three identifiers about you — tenant, project and user, as opaque ids — and nothing else. No password, no profile, no card, no invoice. Plan limits dey come as numbers: how many contacts, how many sends, how many generations. Payment vocabulary no cross that line for either direction.
Your contacts na yours. You be the data controller; we be the processor. No route dey wey another product for the family fit read or write your contact list, and no ingest lane dey for one to use.
If you dey evaluate dis one seriously: read /docs before you read any other part of dis website. The API na the honest description of wetin the product dey do, and every claim for dis pages map to route or node kind wey you fit find there. When the schema change, dis pages go change too.