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