Accounts5

Customers6

Deposit Destinations3

Disbursements3

End User Account Management9

End User Accounts26

EVM Accounts15

EVM Smart Accounts12

EVM Swaps2

EVM Token Balances1

Faucets2

Mandates12

Onchain Data2

Onramp7

Payment Methods2

Payment Sessions21

Policy Engine5

Solana Accounts11

Solana Token Balances1

SQL API3

Transfers5

Webhooks6

x402 Facilitator10

Webhooks

Customers2

Disbursements3

Health5

Mandates8

Onchain Data3

Onramp8

Payment Sessions14

Transfers7

Wallet Webhooks12

Customers

Create a customer

Changed on Oct 6, 2026

Create a new customer record. You can optionally request capabilities and submit verification requirements in the same request.

This endpoint supports creating a customer with:

Minimal data (customer type only)
Capability requests
KYC data submission
Combined request for capability and required info for verification

post/v2/customers

Request

Base URL: https://api.cdp.coinbase.com/platform
URL: https://api.cdp.coinbase.com/platform/v2/customers
Auth: HTTP bearer

Headers

X-Idempotency-Keystring

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.

Request body

type'individual' required

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

projectIdsProjectId[]

The project IDs that this customer is associated with.

Example request

{
  "type": "individual",
  "capabilities": {
    "custodyCrypto": {
      "requested": true
    },
    "transferCrypto": {
      "requested": true
    }
  },
  "individual": {
    "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": [],
  "tosAcceptances": [
    {
      "versionId": "us_individual_2026-05-29",
      "language": "en",
      "acceptedAt": "2026-04-10T12:00:00Z"
    }
  ],
  "taxAttestations": [
    {
      "form": "us_w9",
      "isExemptBackupWithholding": true,
      "edeliveryConsent": true,
      "acceptedAt": "2026-04-17T20:00:00Z"
    }
  ],
  "compliance": {
    "requesterIpAddress": "203.0.113.42"
  }
}

Response

Customer created successfully.

customerIdstring required

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

type'individual' required

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

requirementsRequirementsMap required

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

For the tos key, each entry in tosVersions[] has its own optional deadline. The requirement-level deadline is an aggregate of those rows: the earliest set deadline among unaccepted versions, not a separate clock. A version with no deadline requires immediate acceptance but keeps the aggregate status due. A future deadline is also due and represents non-blocking grace. The aggregate status is past_due only when at least one unaccepted version has a deadline set in the past. Do not infer status or blocking behavior from omission of the aggregate deadline.

createdAtstring date-time

Timestamp when the customer was created.

updatedAtstring date-time

Timestamp when the customer was last updated.

projectIdsProjectId[]

The project IDs that this customer is associated with.

Example response

{
  "customerId": "customer_af2937b0-9846-4fe7-bfe9-ccc22d935114",
  "type": "individual",
  "capabilities": {
    "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": {
    "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://www.coinbase.com/legal/user-agreements-third-party-provider"
        }
      ]
    },
    "taxAttestation": {
      "status": "due",
      "impact": [
        "transferFiat"
      ],
      "taxForms": [
        "us_w9"
      ]
    }
  },
  "createdAt": "2026-01-10T14:25:00Z",
  "updatedAt": "2026-01-10T14:30:00Z",
  "individual": {
    "firstName": "Jane",
    "lastName": "Doe",
    "email": "jane.doe@example.com"
  },
  "projectIds": [],
  "tosAcceptances": [
    {
      "versionId": "us_individual_2026-05-29",
      "language": "en",
      "acceptedAt": "2026-04-10T12:00:00Z"
    }
  ]
}

Changes

Oct 6, 2026156440e9f8df Revision changes
- warning
  added the new incompatible_event_types enum value to the response property for the response status
- warning
  added the new incompatible_event_types enum value to the response property for the response status
- warning
  added the new incompatible_event_types enum value to the response property for the response status
- warning
  added the new incompatible_event_types enum value to the response property for the response status
- warning
  added the new incompatible_event_types enum value to the response property for the response status
- warning
  added the new incompatible_event_types enum value to the response property for the response status
- warning
  added the new invalid_webhook_headers enum value to the response property for the response status
- warning
  added the new invalid_webhook_headers enum value to the response property for the response status
- warning
  added the new invalid_webhook_headers enum value to the response property for the response status
- warning
  added the new invalid_webhook_headers enum value to the response property for the response status
- warning
  added the new invalid_webhook_headers enum value to the response property for the response status
- warning
  added the new invalid_webhook_headers enum value to the response property for the response status
- warning
  added the new invalid_webhook_url enum value to the response property for the response status
- warning
  added the new invalid_webhook_url enum value to the response property for the response status
- warning
  added the new invalid_webhook_url enum value to the response property for the response status
- warning
  added the new invalid_webhook_url enum value to the response property for the response status
- warning
  added the new invalid_webhook_url enum value to the response property for the response status
- warning
  added the new invalid_webhook_url enum value to the response property for the response status
- warning
  added the new mandate_action_pending enum value to the response property for the response status
- warning
  added the new mandate_action_pending enum value to the response property for the response status
- warning
  added the new mandate_action_pending enum value to the response property for the response status
- warning
  added the new mandate_action_pending enum value to the response property for the response status
- warning
  added the new mandate_action_pending enum value to the response property for the response status
- warning
  added the new mandate_action_pending enum value to the response property for the response status
- warning
  added the new mandate_canceled enum value to the response property for the response status
- warning
  added the new mandate_canceled enum value to the response property for the response status
- warning
  added the new mandate_canceled enum value to the response property for the response status
- warning
  added the new mandate_canceled enum value to the response property for the response status
- warning
  added the new mandate_canceled enum value to the response property for the response status
- warning
  added the new mandate_canceled enum value to the response property for the response status
- warning
  added the new mandate_expired enum value to the response property for the response status
- warning
  added the new mandate_expired enum value to the response property for the response status
- warning
  added the new mandate_expired enum value to the response property for the response status
- warning
  added the new mandate_expired enum value to the response property for the response status
- warning
  added the new mandate_expired enum value to the response property for the response status
- warning
  added the new mandate_expired enum value to the response property for the response status
- warning
  added the new mandate_invalid_status enum value to the response property for the response status
- warning
  added the new mandate_invalid_status enum value to the response property for the response status
- warning
  added the new mandate_invalid_status enum value to the response property for the response status
- warning
  added the new mandate_invalid_status enum value to the response property for the response status
- warning
  added the new mandate_invalid_status enum value to the response property for the response status
- warning
  added the new mandate_invalid_status enum value to the response property for the response status
- warning
  added the new mandate_policy_violation enum value to the response property for the response status
- warning
  added the new mandate_policy_violation enum value to the response property for the response status
- warning
  added the new mandate_policy_violation enum value to the response property for the response status
- warning
  added the new mandate_policy_violation enum value to the response property for the response status
- warning
  added the new mandate_policy_violation enum value to the response property for the response status
- warning
  added the new mandate_policy_violation enum value to the response property for the response status
- warning
  added the new mandate_revoked enum value to the response property for the response status
- warning
  added the new mandate_revoked enum value to the response property for the response status
- warning
  added the new mandate_revoked enum value to the response property for the response status
- warning
  added the new mandate_revoked enum value to the response property for the response status
- warning
  added the new mandate_revoked enum value to the response property for the response status
- warning
  added the new mandate_revoked enum value to the response property for the response status
- warning
  added the new subscription_limit_exceeded enum value to the response property for the response status
- warning
  added the new subscription_limit_exceeded enum value to the response property for the response status
- warning
  added the new subscription_limit_exceeded enum value to the response property for the response status
- warning
  added the new subscription_limit_exceeded enum value to the response property for the response status
- warning
  added the new subscription_limit_exceeded enum value to the response property for the response status
- warning
  added the new subscription_limit_exceeded enum value to the response property for the response status
Sep 25, 2026229ed860a74b Revision changes
- warning
  added the new mfa_challenge_not_found enum value to the response property for the response status
- warning
  added the new mfa_challenge_not_found enum value to the response property for the response status
- warning
  added the new mfa_challenge_not_found enum value to the response property for the response status
- warning
  added the new mfa_challenge_not_found enum value to the response property for the response status
- warning
  added the new mfa_challenge_not_found enum value to the response property for the response status
- warning
  added the new mfa_challenge_not_found enum value to the response property for the response status
- warning
  added the new operation_in_progress enum value to the response property for the response status
- warning
  added the new operation_in_progress enum value to the response property for the response status
- warning
  added the new operation_in_progress enum value to the response property for the response status
- warning
  added the new operation_in_progress enum value to the response property for the response status
- warning
  added the new operation_in_progress enum value to the response property for the response status
- warning
  added the new operation_in_progress enum value to the response property for the response status

Operation history (4 revisions)