Skip to main content
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": "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"
}
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

FieldAPI fieldNotes
First nameindividual.firstNameRequired for any customer record
Last nameindividual.lastNameRequired for any customer record
Date of birthindividual.dateOfBirthObject: { "day": "15", "month": "01", "year": "1990" } (lenient formatting accepted)
Full SSNindividual.fullSsnRequired for identity verification
Addressindividual.address.*US addresses only (initial release)
Purpose of accountindividual.purposeOfAccountRequired for compliance review
Source of fundsindividual.sourceOfFundsRequired for compliance review
Employment statusindividual.employmentStatusRequired for trading capabilities
Occupationindividual.occupationRequired for trading capabilities
Expected volumeindividual.expectedVolumeRequired for trading capabilities
Citizenshipindividual.citizenshipUS only (initial release)
EmailemailCustomer-level field
PhonephoneE.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.