---
title: "Goomzo for AI agents"
description: "What an AI coding agent needs to know to connect a business's systems to Goomzo."
url: "https://docs.goomzo.africa/docs/developers/agents"
docs_index: /llms.txt
lastUpdated: 2026-11-12
section: "AI agents"
related:
  - /docs/developers/agents/customers
---

> For an index of all documentation, see [/llms.txt](https://docs.goomzo.africa/llms.txt). Any page is also available as Markdown by adding .md to its URL.

# Goomzo for AI agents

> What an AI coding agent needs to know to connect a business's systems to Goomzo.

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`](https://docs.goomzo.africa/llms.txt?utm_source=llms&utm_medium=ai) lists every page, and [`/llms-full.txt`](https://docs.goomzo.africa/llms-full.txt?utm_source=llms&utm_medium=ai) has
them all in one file.

## What Goomzo is

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.

| Concept                   | What it is                                                                        | Example                              |
| ------------------------- | --------------------------------------------------------------------------------- | ------------------------------------ |
| **Customer**              | A person the business knows, found by phone or email                              | Amina, `+255712345678`               |
| **Detail** (`attributes`) | Something true about a customer now, one value per name; replaced when it changes | `plan: "gold"`, `city: "Arusha"`     |
| **Activity**              | Something a customer did, at a time; only ever added                              | `purchased: "Shoes"`, `spent: 45000` |
| **Segment**               | A named group of customers, picked by hand or filled automatically by rules       | **VIP**, **Bought twice this month** |
| **Message / broadcast**   | An SMS, email or WhatsApp message to one person, or one message to many           | Covered in the messaging guide       |

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

## Rules every integration follows

- **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](https://docs.goomzo.africa/docs/developers/authentication?utm_source=llms&utm_medium=ai) 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](https://docs.goomzo.africa/docs/developers/idempotency?utm_source=llms&utm_medium=ai).
- **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](https://docs.goomzo.africa/docs/developers/errors?utm_source=llms&utm_medium=ai).

## Use the SDK when the system is JavaScript or TypeScript

```bash
npm install @goomzo/sdk
```

```ts
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 next

<Cards>
  <Card
    title="Track customers"
    href="/docs/developers/agents/customers"
    description="Customers, details, activity and segments: how to map a system onto them."
  />
  <Card title="API overview" href="/docs/developers" description="Every route, with examples." />
  <Card title="Webhooks" href="/docs/developers/webhooks" description="Hear about new customers and deliveries." />
</Cards>

---

For an index of all available documentation, see [/llms.txt](https://docs.goomzo.africa/llms.txt)