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

# Customers

A customer represents one of your end-users, onboarded to Coinbase's compliance program so they can access crypto payments, trading, and custody through your product. The customer object holds their identity information, tracks verification state per capability, and shows which actions they're authorized to take.

## Customer object

```json theme={null}
{
  "customerId": "customer_af2937b0-9846-4fe7-bfe9-ccc22d935114",
  "email": "jane.smith@example.com",
  "phone": "+14155550100",
  "individual": {
    "firstName": "Jane",
    "lastName": "Smith",
    "dateOfBirth": { "day": "15", "month": "01", "year": "1990" },
    "address": {
      "line1": "123 Main St",
      "city": "San Francisco",
      "state": "CA",
      "postCode": "94105",
      "countryCode": "US"
    },
    "purposeOfAccount": "investing",
    "sourceOfFunds": "employment"
  },
  "capabilities": {
    "custodyFiat":        { "requested": true,  "status": "active" },
    "custodyStablecoin":  { "requested": true,  "status": "active" },
    "transferFiat":       { "requested": true,  "status": "active" },
    "transferCrypto":     { "requested": true,  "status": "pending" },
    "custodyCrypto":      { "requested": false, "status": "unrequested" },
    "transferStablecoin": { "requested": false, "status": "unrequested" },
    "tradeStablecoin":    { "requested": false, "status": "unrequested" },
    "tradeCrypto":        { "requested": false, "status": "unrequested" }
  },
  "requirements": {},
  "tosAcceptances": [
    {
      "versionId": "us_individual_2026-05-29",
      "language": "en",
      "acceptedAt": "2026-05-01T10:01:00Z"
    }
  ],
  "createdAt": "2026-05-01T10:00:00Z",
  "updatedAt": "2026-05-01T10:02:00Z"
}
```

<Note>
  There is no top-level `status` field on the customer object. Status is tracked per-capability; see the `capabilities` map above.
</Note>

## Operations

### Create a customer

`POST /v2/customers`

Submit identity information and explicitly request the capabilities you want to enable. The capabilities block tells Coinbase which compliance requirements to evaluate.

### Get a customer

`GET /v2/customers/{customerId}`

Returns the current customer object, including all capabilities and outstanding requirements.

### Update a customer

`POST /v2/customers/{customerId}`

Submit additional identity information needed to unlock a capability, or correct an existing field.

### List customers

`GET /v2/customers`

Returns all customers for your entity, with pagination support.

## Identity fields

| Field              | API field                     | Notes                                                                                  |
| ------------------ | ----------------------------- | -------------------------------------------------------------------------------------- |
| First name         | `individual.firstName`        | Required for any customer record                                                       |
| Last name          | `individual.lastName`         | Required for any customer record                                                       |
| Date of birth      | `individual.dateOfBirth`      | Object: `{ "day": "15", "month": "01", "year": "1990" }` (lenient formatting accepted) |
| Full SSN           | `individual.fullSsn`          | Required for identity verification                                                     |
| Address            | `individual.address.*`        | US addresses only (initial release)                                                    |
| Purpose of account | `individual.purposeOfAccount` | Required for compliance review                                                         |
| Source of funds    | `individual.sourceOfFunds`    | Required for compliance review                                                         |
| Employment status  | `individual.employmentStatus` | Required for trading capabilities                                                      |
| Occupation         | `individual.occupation`       | Required for trading capabilities                                                      |
| Expected volume    | `individual.expectedVolume`   | Required for trading capabilities                                                      |
| Citizenship        | `individual.citizenship`      | US only (initial release)                                                              |
| Email              | `email`                       | Customer-level field                                                                   |
| Phone              | `phone`                       | E.164 format                                                                           |

See the [Capabilities](/customers-kyc/capabilities) page for which fields each capability requires.

## End-user context

Include `compliance.requesterIpAddress` on every create or update request. This is the IP address of the end-user (not your server) and is required for T3 onboarding:

```json theme={null}
{
  "individual": { ... },
  "capabilities": { ... },
  "compliance": {
    "requesterIpAddress": "203.0.113.42"
  }
}
```

This field is write-only and never returned in responses.

## Terms of Service

Certain capabilities require the customer to accept Coinbase's Terms of Service before they become active. When a `tos` requirement is present on the customer object, the requirement includes a `url` field with the current Terms of Service link.

1. Read the `url` from the `tos` requirement on the customer object and render it to the customer.
2. Record the customer's acceptance and submit it:

```json theme={null}
POST /v2/customers/{customerId}
{
  "tosAcceptances": [
    {
      "versionId": "us_individual_2026-05-29",
      "language": "en",
      "acceptedAt": "2026-05-01T10:01:00Z"
    }
  ]
}
```

<Warning>
  You must present the actual Terms of Service text to the customer. Do not accept on their behalf without display.
</Warning>

## Customer lifecycle

There is no top-level status field on the customer. Each capability has its own independent state:

```
Capability: unrequested → [request it] → pending → active
                                                  → inactive (compliance block)
                                    rejected → resubmit → pending
```

Compliance-driven `inactive` states cannot be resolved through the API. Do not expose compliance-specific reasons to your end-users; Coinbase manages these compliance decisions on your behalf. See the [Requirements](/customers-kyc/requirements) page for what you can and cannot resolve.