> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sakawave.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Customers introduction

> The problem the Customers service solves, when to use it, and what it deliberately leaves to you.

Most Sakawave integrations are built by a business serving its own users. The Customers service is where those users are recorded, so that accounts, cards, and transfers can be attributed to somebody rather than floating on your books.

## The problem it solves

Without customers, everything your business does is one undifferentiated pool. You could open accounts and move money, but you could not answer "whose balance is this?" without keeping a mapping somewhere else and hoping it stays in step.

A customer record gives you three things:

1. **An owner for accounts.** Passing `customerId` when you open an account makes it that customer's wallet rather than your own operational money.
2. **A place for identity.** Names, contact details, address, and identity numbers live in one record with one lifecycle, rather than being scattered across the objects that happen to need them.
3. **A stable join key.** `externalReference` is yours. Set it to whatever your own system calls this person, and the two systems stay joined without a lookup table.

## When to create a customer

Create one when a real person or business will hold value, receive money, or carry a card at Sakawave.

Do **not** create one for:

* **Your own operational accounts.** Omit `customerId` when opening an account and it belongs to your business directly.
* **Transfer recipients.** Somebody you pay is a [transfer recipient](/guides/transfer-corridors-and-recipients), not a customer. Recipients are payout destinations; customers hold balances.
* **Your staff or internal actors.** Dashboard users are a different concept entirely.

The distinction that matters: a customer is somebody Sakawave holds money *for*. A recipient is somebody money goes *to*.

## What it leaves to you

The service is deliberately thin, and three responsibilities stay on your side.

**Consent and lawful basis.** You send us personal data; you are the one who collected it. Sakawave stores what you send and does not ask whether you were entitled to send it.

**Deduplication.** Two customers with identical details are two customers. Uniqueness is enforced only on `externalReference` and identity numbers. If you need "one record per human", give every human a stable `externalReference` and let the `409` tell you when you have seen them before.

**Verification.** Recording a BVN is not checking a BVN. See [identity and verification](/services/customers/identity-and-verification) for what tier 1 actually means and what it does not promise.

## The shape of the API

Five operations, and they behave the way the HTTP verbs suggest.

| Operation | Notes |
| - | - |
| [`POST /v1/customers`](/api-reference/customers/create-a-customer) | Creates. `type` chooses which fields apply. |
| [`GET /v1/customers`](/api-reference/customers/list-customers) | Lists, newest first, archived excluded. Filterable and sortable. |
| [`GET /v1/customers/{customerId}`](/api-reference/customers/get-a-customer) | Reads one. |
| [`PATCH /v1/customers/{customerId}`](/api-reference/customers/update-a-customer) | Updates. Absent means "leave alone"; `null` means "clear". |
| [`DELETE /v1/customers/{customerId}`](/api-reference/customers/archive-a-customer) | Archives. Returns `204`. |

There is no bulk endpoint and no upsert. Creating a thousand customers is a thousand calls, paced against the [rate limits](/services/customers/setup-and-configuration#rate-limits).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.