> ## 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 overview

> What a Sakawave customer is, which fields it holds, and how it moves through its lifecycle.

A **customer** is a person or business your business serves. Sakawave holds the identity record; you hold the relationship. Nothing about a customer moves money on its own — a customer becomes financially useful once you open a [wallet account](/services/customers/use-cases#1-onboard-a-customer-and-give-them-a-wallet) for them.

Only business clients can manage customers. A non-business client receives `409 client_not_a_business` on every operation here.

## The object

| Field group | Fields | Notes |
| - | - | - |
| Identity | `id`, `type`, `jurisdiction` | Fixed at creation. `type` is `individual` or `business` and decides which fields below apply. |
| Your reference | `externalReference` | Yours to choose. Unique among your customers that are not archived. |
| Names | `displayName`, `name`, `firstName`, `middleName`, `lastName` | `displayName` is always safe to render. For an individual it is the personal names joined; for a business it is `name`. |
| Contact | `email`, `phoneNumber`, `address` | `email` is stored lowercased; `address.country` and `jurisdiction` uppercased. |
| Personal | `dateOfBirth`, `gender` | Individual customers only. |
| Verification | `tier`, `hasBvn`, `hasNin`, `hasPassport`, `hasDriversLicence`, `hasTaxId`, `hasRegistrationNumber` | Identity numbers go in and never come back out. See [identity and verification](/services/customers/identity-and-verification). |
| Timestamps | `createdAt`, `updatedAt` | ISO 8601, UTC. |

`type` and `jurisdiction` cannot be changed after creation. Everything else in the table is mutable through `PATCH`, subject to the type rules.

## Lifecycle

A customer has three states, and only two transitions.

```mermaid theme={null}
stateDiagram-v2
    [*] --> active: POST /v1/customers
    active --> active: PATCH /v1/customers/{customerId}
    active --> archived: DELETE /v1/customers/{customerId}
    note right of active
        Archiving is refused while the
        customer holds an open wallet
        or a live card.
    end note
    note right of archived
        Terminal. There is no unarchive.
    end note
```

**Active.** Visible to reads, countable in lists, eligible to hold accounts and cards.

**Archived.** Hidden, not deleted. The record disappears from `GET` and `LIST` — both answer `404` — while ledger history and completed transfers keep their references to it. Archiving also releases the customer's `externalReference` and identity numbers, so those values can be reused by a new customer.

<Warning>
  Archiving is terminal. A customer archived by mistake must be created again, which mints a new `id`, and the old `id` stays referenced by history.
</Warning>

## What this service does not do

* **It does not verify anyone.** Storing a BVN records that you hold one; it does not check it. Every customer sits at tier 1.
* **It does not hold money.** Balances live on accounts, not customers.
* **It does not deduplicate people.** Two customers with the same name and address are two customers. Uniqueness is enforced on `externalReference` and identity numbers, nothing else.
* **It does not delete.** `DELETE` archives.

## Events

| Event | When |
| - | - |
| `customer.created` | A customer was created. Carries the full customer object. |
| `customer.updated` | A `PATCH` succeeded. Carries the full customer object as it now stands. |
| `customer.kyc.approved`, `customer.kyc.rejected`, `customer.kyc.suspended` | The customer's verification changed. Sent whenever it does, not only for the first verdict. Carries the customer object plus `kyc`. |

Archiving emits nothing. If you mirror customers locally, reconcile archives by listing customers and treating an absent record as archived.

## Next

<CardGroup cols={2}>
  <Card title="Introduction" icon="book-open" href="/services/customers/introduction">
    What the service is for, and when to reach for it.
  </Card>

  <Card title="Get started" icon="play" href="/services/customers/get-started">
    One successful call in under ten minutes.
  </Card>

  <Card title="Setup and configuration" icon="sliders" href="/services/customers/setup-and-configuration">
    Keys, environments, limits, and webhook wiring.
  </Card>

  <Card title="Use cases" icon="list-checks" href="/services/customers/use-cases">
    Complete flows, with the error branches that actually happen.
  </Card>
</CardGroup>


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