Create a customer - Coinbase Developer Documentation

Authorizations

Authorization

string

header

required

A JWT signed using your CDP API Key Secret, encoded in base64. Refer to the Generate Bearer Token section of our Authentication docs for information on how to generate your Bearer Token.

Headers

X-Idempotency-Key

string

An optional string request header for making requests safely retryable. When included, duplicate requests with the same key will return identical responses. Refer to our Idempotency docs for more information on using idempotency keys.

Required string length: 1 - 128

Body

application/json

Fields accepted on customer create and update requests. Shared by CreateCustomerRequest and UpdateCustomerRequest; excludes the server-managed response-only fields that appear on Customer.

type

enum<string>

required

The type of the customer. Required on create; accepted but ignored on update.

Available options:

individual

Example:

"individual"

capabilities

object

Capabilities to request for the customer.

Show child attributes

Example:

{
  "custodyCrypto": { "requested": true },
  "transferCrypto": { "requested": true }
}

individual

object

Information about an Individual customer. Not all fields are required for all customers; the requirements depend on which capabilities are requested. Submit only fields that are required by the capabilities that have been requested.

Show child attributes

Example:

{
  "firstName": "Jane",
  "lastName": "Doe",
  "address": {
    "line1": "500 Main St",
    "city": "Boston",
    "state": "MA",
    "postCode": "02108",
    "countryCode": "US"
  },
  "ssnLast4": "6789",
  "dateOfBirth": {
    "day": "15",
    "month": "08",
    "year": "1990"
  },
  "email": "jane.doe@example.com",
  "phoneNumber": "+15551234567"
}

projectIds

string<uuid>[]

The project IDs that this customer is associated with.

The ID of the Project, a UUID v4.

Pattern: ^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$

Example:

[]

tosAcceptances

object[]

Terms of Service acceptances to record on the customer. Submit one entry per required version surfaced inline on requirements.tos.tosVersions[] (returned by Get Customer, Create Customer, and Update Customer whenever a tos requirement is unsatisfied). The server rejects each acceptance whose language is not listed under languages on the matching required version with errorType: "unsupported_tos_language".

When new required Terms of Service versions are published, only the new versionIds appear in requirements.tos.tosVersions[]; submit acceptances for only those new version(s).

Omit tosAcceptances on a partial update to leave previously recorded acceptances unchanged. Sending tosAcceptances: [] is invalid (errorType: "invalid_request") because it would clear all acceptances without replacing them; omit the field entirely when you are not updating Terms of Service acceptances.

Show child attributes

Example:

[
  {
    "versionId": "us_individual_2026-05-29",
    "language": "en",
    "acceptedAt": "2026-04-10T12:00:00Z"
  }
]

taxAttestations

IRS Form W-9 · object[]

write-only

Tax attestations to record on the customer. Submit one entry per required form surfaced inline on requirements.taxAttestation.taxForms[] (returned by Get Customer, Create Customer, and Update Customer whenever a taxAttestation requirement is unsatisfied). The required fields per entry depend on form; see TaxAttestation. This field is ingestion-only and is never returned on read.

Omit taxAttestations on a partial update to leave previously recorded attestations unchanged. Sending taxAttestations: [] is invalid (errorType: "invalid_request") because it would clear all attestations without replacing them; omit the field entirely when you are not updating tax attestations.

Show child attributes

Example:

[
  {
    "form": "us_w9",
    "isExemptBackupWithholding": true,
    "edeliveryConsent": true,
    "acceptedAt": "2026-04-17T20:00:00Z"
  }
]

compliance

object

write-only

Compliance context for a request. Carries per-request compliance signals, such as the IP address of the individual (i.e., end-customer) that initiated the request.

This object is request-only — it is never echoed back in responses. Inner fields are write-only.

Show child attributes

Example:

{ "requesterIpAddress": "203.0.113.42" }

Response

Customer created successfully.

A customer record returned on read (Get / Create / Update Customer).

customerId

string

required

The ID of the Customer, which is a UUID prefixed by customer_.

Pattern: ^customer_[a-f0-9\-]{36}$

Example:

"customer_af2937b0-9846-4fe7-bfe9-ccc22d935114"

type

enum<string>

required

The type of the Customer.

Available options:

individual

Example:

"individual"

capabilities

object

required

Current state of each capability for this customer. Each capability shows whether it has been requested and its current status.

Show child attributes

Example:

{
  "custodyCrypto": { "requested": true, "status": "active" },
  "custodyFiat": {
    "requested": false,
    "status": "unrequested"
  },
  "custodyStablecoin": {
    "requested": false,
    "status": "unrequested"
  },
  "tradeCrypto": {
    "requested": false,
    "status": "unrequested"
  },
  "tradeStablecoin": {
    "requested": false,
    "status": "unrequested"
  },
  "transferCrypto": { "requested": true, "status": "active" },
  "transferFiat": {
    "requested": false,
    "status": "unrequested"
  },
  "transferStablecoin": {
    "requested": false,
    "status": "unrequested"
  }
}

requirements

object

required

Map of requirements to be submitted. Each key is the field name, with values to describe its state. Requirements are only shown for requested capabilities. When a requirement is fulfilled, it disappears from this map.

Show child attributes

Example:

{
  "firstName": {
    "status": "due",
    "impact": ["custodyCrypto", "transferCrypto"]
  },
  "fullSsn": {
    "status": "rejected",
    "impact": ["custodyCrypto"]
  },
  "ssnLast4": {
    "status": "pending",
    "impact": ["custodyCrypto"]
  },
  "sourceOfFunds": { "status": "due" },
  "citizenship": { "status": "due" },
  "tos": {
    "status": "due",
    "impact": ["transferFiat"],
    "tosVersions": [
      {
        "versionId": "us_individual_2026-05-29",
        "languages": ["en"],
        "url": "https://docs.cdp.coinbase.com/legal/terms/us_individual_2026-05-29"
      }
    ]
  },
  "taxAttestation": {
    "status": "due",
    "impact": ["transferFiat"],
    "taxForms": ["us_w9"]
  }
}

createdAt

string<date-time>

read-only

Timestamp when the customer was created.

Example:

"2026-01-10T14:25:00Z"

updatedAt

string<date-time>

read-only

Timestamp when the customer was last updated.

Example:

"2026-01-10T14:30:00Z"

individual

object

Individual customer data returned on read — the individual object on Get / Create / Update Customer responses. Only contact-identity fields are echoed back; every other field accepted on the IndividualInput object (address, ssnLast4, dateOfBirth, fullSsn, citizenship, phoneNumber, and the CDD fields) is ingestion-only and never returned.

Show child attributes

Example:

{
  "firstName": "Jane",
  "lastName": "Doe",
  "email": "jane.doe@example.com"
}

projectIds

string<uuid>[]

The project IDs that this customer is associated with.

The ID of the Project, a UUID v4.

Pattern: ^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$

Example:

[]

tosAcceptances

object[]

Show child attributes

Example:

[
  {
    "versionId": "us_individual_2026-05-29",
    "language": "en",
    "acceptedAt": "2026-04-10T12:00:00Z"
  }
]