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

# Customers

> A customer is your end-user, onboarded through our Coinbase KYC program. By KYC'ing your customers, you can enable them to use crypto payments, trading, and custody under your own brand.

A **customer** is one of your end-users, onboarded to Coinbase's KYC (Know Your Customer) and compliance program so they can access crypto payments, trading, and custody through your product. You collect their information and drive the experience; Coinbase verifies it, runs screening, and tracks what they're authorized to do.

Each customer record holds the identity information you submit, the [capabilities](/customers-kyc/capabilities) they've requested (and whether each is active), and any outstanding [requirements](/customers-kyc/requirements) still blocking activation.

## What you get back

When you retrieve a customer, the response ties together identity, capabilities, and requirements in one place. There is no top-level customer `status`; read the `capabilities` and `requirements` maps together to understand where someone is in onboarding.

```json theme={null}
{
  "customerId": "customer_af2937b0-9846-4fe7-bfe9-ccc22d935114",
  "type": "individual",
  "individual": {
    "firstName": "Jane",
    "lastName": "Doe",
    "email": "jane.doe@example.com"
  },
  "capabilities": {
    "custodyCrypto": { "requested": true, "status": "active" },
    "custodyFiat": { "requested": false, "status": "unrequested" },
    "custodyStablecoin": { "requested": false, "status": "unrequested" },
    "tradeCrypto": { "requested": true, "status": "pending" },
    "tradeStablecoin": { "requested": false, "status": "unrequested" },
    "transferCrypto": { "requested": true, "status": "active" },
    "transferFiat": { "requested": false, "status": "unrequested" },
    "transferStablecoin": { "requested": false, "status": "unrequested" }
  },
  "requirements": {
    "fullSsn": { "status": "rejected", "impact": ["tradeCrypto"] },
    "sourceOfFunds": { "status": "due" },
    "taxAttestation": {
      "status": "due",
      "impact": ["tradeCrypto"],
      "taxForms": ["us_w9"]
    }
  },
  "createdAt": "2026-01-10T14:25:00Z",
  "updatedAt": "2026-01-10T14:30:00Z"
}
```

See [Capabilities](/customers-kyc/capabilities) for what each capability means and [Requirements](/customers-kyc/requirements) for how to resolve outstanding items.

### Write surface vs. read surface

The fields you submit are not all echoed back. On create and update you can submit the full set of [identity fields](#identity-information-you-collect), but a customer **read** response only returns contact-identity fields on `individual`:

| Returned on read (`individual`)  | Ingestion-only (write, never returned)                                                                                                                                 |
| -------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `firstName`, `lastName`, `email` | `address`, `dateOfBirth`, `ssnLast4`, `fullSsn`, `citizenship`, `phoneNumber`, `purposeOfAccount`, `sourceOfFunds`, `employmentStatus`, `occupation`, `expectedVolume` |

Sensitive identity information (SSN, date of birth, address, and the due-diligence fields) is accepted for verification but never returned by the API.

Some fields you submit are write-only at the top level too. Terms of Service acceptances, tax attestations, and the end-user IP address are accepted on create and update but are not echoed back on the customer object. Terms of Service progress is instead reflected through the `tos` requirement (it disappears once the required versions are accepted); see [Terms of Service](#terms-of-service).

## Working with customers

Typical integration flow:

1. **Create** a customer when someone starts onboarding. Set `type` to `individual`, request the capabilities they need, and submit whatever identity information you already have.
2. **Update** the customer as they complete steps: additional identity fields, Terms of Service acceptances, tax attestations, or newly requested capabilities.
3. **Retrieve** the customer (or listen for [webhooks](/customers-kyc/webhooks)) to check capability status and outstanding requirements before initiating an operation.
4. **List** customers when you need an admin or support view across your user base.
5. **Delete** a customer when the relationship ends.

Use the [Customers API](/api-reference/v2/rest-api/customers/customers) for request and response shapes, field names, and error codes:

| Goal                                           | API reference                                                               |
| ---------------------------------------------- | --------------------------------------------------------------------------- |
| Register a new customer                        | [Create a customer](/api-reference/v2/rest-api/customers/create-a-customer) |
| Look up one customer                           | [Get a customer](/api-reference/v2/rest-api/customers/get-a-customer)       |
| Page through your customers                    | [List customers](/api-reference/v2/rest-api/customers/list-customers)       |
| Submit new information or request capabilities | [Update a customer](/api-reference/v2/rest-api/customers/update-a-customer) |
| Remove a customer                              | [Delete a customer](/api-reference/v2/rest-api/customers/delete-a-customer) |

<Note>
  Create, update, and delete support an optional `Idempotency-Key` header so a retried request is applied at most once. Updates use `PUT` with partial bodies; omit a field to leave it unchanged.
</Note>

<Warning>
  Sending empty arrays for `tosAcceptances` or `taxAttestations` is rejected. Omit those fields entirely when you are not changing them.
</Warning>

Newly requested capabilities start as `pending` with their outstanding requirements listed under `requirements`. Verification is asynchronous, so a capability can stay `pending` briefly after all requirements are submitted.

## Identity information you collect

Submit identity fields under `individual` on create or update. Not every field is required for every customer; which fields matter depends on the [capabilities](/customers-kyc/capabilities) you request. Submit only what the live `requirements` map (and your integration needs) call for.

| Information          | Notes                                                             |
| -------------------- | ----------------------------------------------------------------- |
| First and last name  | Given and family name                                             |
| Date of birth        | Day, month, and year as separate values                           |
| SSN (last 4 or full) | US only; full SSN format `123-45-6789`                            |
| Address              | US addresses only today                                           |
| Citizenship          | ISO country code; US only today                                   |
| Email                | Contact email                                                     |
| Phone number         | E.164 format, e.g. `+15551234567`                                 |
| Purpose of account   | Why the customer is opening the account (e.g. investing, trading) |
| Source of funds      | Where funds originate (e.g. salary, investments)                  |
| Employment status    | e.g. employed full-time, self-employed, retired                   |
| Occupation           | Industry (e.g. technology, finance)                               |
| Expected volume      | Expected dollar range of activity                                 |

<Note>
  Address `countryCode` and `citizenship` must be `US`. See the [Overview](/customers-kyc/overview) for current product scope.
</Note>

Exact field paths, accepted enum values, and validation rules live in the [Create a customer](/api-reference/v2/rest-api/customers/create-a-customer) API reference. Due-diligence fields (purpose, source of funds, employment, occupation, expected volume) are required for higher-assurance capabilities such as `tradeCrypto`.

## End-user IP address

Include your **end-user's** IP address (not your server's) on create and update requests via `compliance.requesterIpAddress`. Coinbase uses it as a per-request compliance signal. This value is write-only and is never returned in responses.

## Terms of Service

Before capabilities can activate, your customer must agree to Coinbase's Terms of Service. This is a legal agreement step: you link to the document in your product, the customer reads and accepts it, and you tell Coinbase that acceptance occurred.

When acceptance is still needed, the customer object includes a **Terms of Service** requirement. That requirement tells you which document versions the customer has not yet accepted and gives you links you can embed or open in your UI (including translated versions where available).

Typical flow:

1. **Check requirements.** If Terms of Service is outstanding, see which versions still need acceptance and which URLs to show.
2. **Present and capture.** Display each required document to your customer and record that they agreed (including when and in which language).
3. **Submit acceptance.** Send those records to Coinbase on update. Once every required version is covered, the requirement clears and capabilities that depended on it can move forward through verification.

Coinbase may publish updated Terms of Service over time. When that happens, only the **new** versions show up as outstanding. You do not need to re-collect acceptance for versions the customer already agreed to.

<Warning>
  You must present the actual Terms of Service to the customer. Do not record acceptance on their behalf without displaying the document.
</Warning>

See [Requirements](/customers-kyc/requirements#terms-of-service) for the resolution flow and [Update a customer](/api-reference/v2/rest-api/customers/update-a-customer) for how to submit acceptances.

## Tax attestations

Some capabilities require the customer to certify tax information before they activate, for example IRS Form **W-9** for US individuals. Coinbase uses these attestations for tax reporting and withholding compliance. When a `taxAttestation` requirement is outstanding, the customer's `requirements.taxAttestation.taxForms[]` lists each form the customer must complete (for example, `us_w9` for W-9).

1. Read `requirements.taxAttestation.taxForms[]` and collect the certification for each form from your customer.
2. Submit one attestation entry per required form on update.

The fields accepted per entry depend on the form. Like Terms of Service acceptances, tax attestations are ingestion-only and never returned on read.

<Warning>
  You must present the actual tax form to the customer and capture their certification. Do not record an attestation on their behalf without displaying the form.
</Warning>

See the [Requirements](/customers-kyc/requirements) page for the full resolution flow and [Update a customer](/api-reference/v2/rest-api/customers/update-a-customer) for request fields.

## Customer lifecycle

There is no top-level customer `status`. A customer is a container of **capabilities**, and each capability moves through its own lifecycle independently, driven by the **requirements** it depends on. To understand a customer's state, read the `capabilities` and `requirements` maps together.

### Capability status

Each entry in the `capabilities` map has a `status`:

| Status        | Meaning                                                                                           |
| ------------- | ------------------------------------------------------------------------------------------------- |
| `unrequested` | You have not requested this capability. It does nothing until requested.                          |
| `pending`     | Requested and under evaluation. One or more requirements are still outstanding or being verified. |
| `active`      | Granted. The customer is authorized to use this capability.                                       |
| `inactive`    | Blocked by a terminal compliance decision. Cannot be recovered through the API.                   |

### Requirement status

While a capability is `pending`, the requirements gating it appear in the `requirements` map, each with its own `status`:

| Status     | Meaning                                                                 |
| ---------- | ----------------------------------------------------------------------- |
| `due`      | Coinbase needs this value. Submit it on update.                         |
| `pending`  | Submitted and under verification. No action needed.                     |
| `rejected` | The submitted value failed verification. Collect it again and resubmit. |

When a requirement is satisfied it **disappears** from the map. A capability becomes `active` once all of its requirements are gone.

### How they move together

A requested capability starts `pending` with its requirements listed. From there, verification produces one of three outcomes:

| Outcome                                             | Capability becomes | Its requirements       | Recoverable?                                              |
| --------------------------------------------------- | ------------------ | ---------------------- | --------------------------------------------------------- |
| **Approved** (all requirements verified)            | `active`           | Disappear from the map | n/a                                                       |
| **Recoverable decline** (a submitted value failed)  | stays `pending`    | Become `rejected`      | Yes. Resubmit corrected info, which restarts verification |
| **Terminal block** (for example, a sanctions match) | `inactive`         | Disappear from the map | No                                                        |

```
unrequested ──[request capability]──► pending ──[all requirements satisfied]──► active
                                          │
                                          ├─[value rejected]──► pending  (requirement → rejected; resubmit to retry)
                                          │
                                          └─[terminal compliance block]──► inactive  (requirements cleared; cannot resubmit)
```

A capability in `inactive` is blocked by a compliance decision and cannot be recovered through the API. No requirement resubmission will clear it. Do not surface compliance-specific reasons to your end-users; Coinbase makes and manages those determinations on your behalf. See [Requirements](/customers-kyc/requirements) for what you can and cannot resolve, and [Testing in sandbox](/customers-kyc/requirements#testing-in-sandbox) to exercise each outcome with magic values.

## Next steps

<CardGroup cols={2}>
  <Card title="Capabilities" icon="circle-check" href="/customers-kyc/capabilities">
    All capabilities, statuses, and how to check them before an operation
  </Card>

  <Card title="Requirements" icon="list-check" href="/customers-kyc/requirements">
    Resolve outstanding requirements, Terms of Service, and tax attestations
  </Card>
</CardGroup>