Customers

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 they’ve requested (and whether each is active), and any outstanding 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.

{
  "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 for what each capability means and 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, 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.

Working with customers

Typical integration flow:

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

Use the Customers API for request and response shapes, field names, and error codes:

Goal	API reference
Register a new customer	Create a customer
Look up one customer	Get a customer
Page through your customers	List customers
Submit new information or request capabilities	Update a customer
Remove a customer	Delete a customer

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.

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

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

Address countryCode and citizenship must be US. See the Overview for current product scope.

Exact field paths, accepted enum values, and validation rules live in the 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:

Check requirements. If Terms of Service is outstanding, see which versions still need acceptance and which URLs to show.
Present and capture. Display each required document to your customer and record that they agreed (including when and in which language).
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.

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

See Requirements for the resolution flow and 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).

Read requirements.taxAttestation.taxForms[] and collect the certification for each form from your customer.
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.

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.

See the Requirements page for the full resolution flow and 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 for what you can and cannot resolve, and Testing in sandbox to exercise each outcome with magic values.

GET STARTED

WALLETS

PAYMENTS

STABLECOINS

TRADING

ONCHAIN TOOLS

WEBHOOKS

CONSUMER APIS

BUSINESS APIS

INSTITUTIONAL APIS

Customers

What you get back

Write surface vs. read surface

Working with customers

Identity information you collect

End-user IP address

Terms of Service

Tax attestations

Customer lifecycle

Capability status

Requirement status

How they move together

Next steps

Capabilities

Requirements

​What you get back

​Write surface vs. read surface

​Working with customers

​Identity information you collect

​End-user IP address

​Terms of Service

​Tax attestations

​Customer lifecycle

​Capability status

​Requirement status

​How they move together

​Next steps

Capabilities

Requirements

What you get back

Write surface vs. read surface

Working with customers

Identity information you collect

End-user IP address

Terms of Service

Tax attestations

Customer lifecycle

Capability status

Requirement status

How they move together

Next steps