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

{
  "customerId": "customer_af2937b0-9846-4fe7-bfe9-ccc22d935114",
  "email": "[e-mail]",
  "phone": "[phone]",
  "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"
}

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

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

{
  "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:

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

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

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 page for what you can and cannot resolve.