---
title: "Customers"
description: "Add and update customers from your own system, with their segments and activity."
url: "https://docs.goomzo.africa/docs/developers/customers"
docs_index: /llms.txt
lastUpdated: 2026-11-12
section: "Customers"
related:
  - /docs/developers/customers/activity
---

> 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.

# Customers

> Add and update customers from your own system, with their segments and activity.

A customer is someone your business knows, by phone, email or both. Your system adds them as they buy or sign up,
segments them, and records their activity, so the right people get the right messages.

## Requirements

- An API key with the `customers.write` permission. Segments also need `segments.write`, and activities
  `activity.write`.

## Requests

```text
POST /v1/customers
```

### Request syntax

```json
{
  "ifExists": "<IF_EXISTS>",
  "ifSegmentMissing": "<IF_SEGMENT_MISSING>",
  "customers": [
    {
      "name": "<NAME>",
      "phone": "<PHONE_NUMBER>",
      "email": "<EMAIL>",
      "attributes": { "<KEY>": "<VALUE>" },
      "segments": [{ "name": "<SEGMENT>" }],
      "activities": [{ "key": "<ACTIVITY>", "value": "<ACTIVITY_VALUE>" }]
    }
  ]
}
```

| Placeholder                      | Description                                                                                               | Sample value         |
| -------------------------------- | --------------------------------------------------------------------------------------------------------- | -------------------- |
| `<IF_EXISTS>`                    | _String. Optional._ `error`, the default, or `update`: a customer someone already has is updated instead. | `update`             |
| `<IF_SEGMENT_MISSING>`           | _String. Optional._ `error`, the default, or `create`: a segment named by `name` is added.                | `create`             |
| `<NAME>`                         | _String._ Their name.                                                                                     | `Amina Juma`         |
| `<PHONE_NUMBER>`                 | _String._ With the country code. Send a phone, an email, or both.                                         | `+255712345678`      |
| `<EMAIL>`                        | _String._ Their email address.                                                                            | `amina@example.com`  |
| `<KEY>`, `<VALUE>`               | _Object. Optional._ Their details, used as `{{attributes.x}}`. Sent with `update`, they replace theirs.   | `{ "plan": "gold" }` |
| `<SEGMENT>`                      | _String. Optional._ A segment by `name`, or by `id`. They're added to it, never taken out of others.      | `Shoppers`           |
| `<ACTIVITY>`, `<ACTIVITY_VALUE>` | _Optional._ Their activity. See [Activity](https://docs.goomzo.africa/docs/developers/customers/activity?utm_source=llms&utm_medium=ai).                          | `purchased`, `Shoes` |

### Example request

```bash
curl https://api.goomzo.africa/v1/customers \
  -H "Authorization: Bearer $GOOMZO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "ifExists": "update",
    "customers": [{
      "name": "Amina Juma",
      "phone": "+255712345678",
      "attributes": { "plan": "gold" },
      "segments": [{ "name": "Shoppers" }],
      "activities": [{ "key": "purchased", "value": "Shoes" }]
    }]
  }'
```

## Responses

The answer is `201` when any customer was added, otherwise `200`. It lists each customer with its `result`:
`created`, `updated` or `unchanged`.

## Notes

- **All or none:** up to 100 customers at once. A problem with any of them saves nobody, and the error names it,
  such as `customers[1].phone` or `customers[0].segments[2]`.
- **Finding someone:** an existing customer is found by phone first, then by email.
- **A checkout:** `"ifExists": "update"` suits a system that doesn't know whether the person is new.
- **Segment names:** match whatever their case, so `lead` finds **Lead** rather than adding another.
- **Other requests:** `GET /v1/customers` lists them, `PATCH /v1/customers/{id}` changes one, and
  `POST /v1/customers/import` takes a file.

## Next steps

- [Activity](https://docs.goomzo.africa/docs/developers/customers/activity?utm_source=llms&utm_medium=ai)
- [Segments](https://docs.goomzo.africa/docs/help/segments?utm_source=llms&utm_medium=ai)
- [Send messages](https://docs.goomzo.africa/docs/developers/messages/send?utm_source=llms&utm_medium=ai)

---

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