Goomzo for AI agents

This section is written for AI coding agents, and the people directing them, who connect an existing system (a shop, a point of sale, a booking app, a CRM) to Goomzo. Every page is also plain Markdown: add .md to its URL, or send Accept: text/markdown. /llms.txt lists every page, and /llms-full.txt has them all in one file.

What Goomzo isCopy Anchor Link

Goomzo is a customer engagement platform for businesses in Tanzania. A business keeps its customers in Goomzo, records their activity, segments them, and messages them by SMS, email or WhatsApp. Your job as an integration is usually the first three: keep Goomzo's picture of the business's customers current, so the business can see who they are and reach the right people.

Everything belongs to one business (an organization). An API key works in exactly one business.

Rules every integration followsCopy Anchor Link

• Base URL https://api.goomzo.africa. Requests and answers are JSON.
• Authenticate with an API key's secret: Authorization: Bearer gzk_…. Create keys in Settings → API keys. A key only reaches what its permissions allow; the Customer sync set has everything this guide uses. Never put a secret in browser or mobile code: call Goomzo from a server.
• Pin the version: send Goomzo-Version: 2026-11-08. The TypeScript SDK does this for you.
• Phones are mobile numbers in the business's own country (Tanzania today), written with the country code: +255712345678. Spaces and dashes are fine; a local 0712345678 is an error, and so is another country's number. Normalize to E.164 before sending, and compare phones in that form.
• Retry safely: send an Idempotency-Key with every POST (a UUID, or better, an id from your own system such as order-1042-paid). The same key within 24 hours is done once. See safe retries.
• All or none: a batch call saves everything or nothing. The error's fields names each problem by its place, such as customers[1].phone. Fix those and send the whole batch again.
• Rate limit: 600 requests a minute per key. On 429, wait Retry-After seconds. Batch instead of looping.
• Errors are { status, code, message, fields? } with an X-Request-Id header. Retry 429 and 5xx; never retry a 400 unchanged. See errors.

Use the SDK when the system is JavaScript or TypeScriptCopy Anchor Link

npm install @goomzo/sdk

import { Goomzo } from '@goomzo/sdk'

const goomzo = new Goomzo() // reads GOOMZO_API_KEY

It types every request from the API's own description, pins the version, adds an Idempotency-Key to every POST, retries what's safe to retry, pages lists for you, and checks webhook signatures. In other languages, call the HTTP API directly; the routes are the same.

Where to go nextCopy Anchor Link