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

End User Account Management

Look up end users by identity

Changed on Oct 6, 2026

Looks up end users. Exactly one lookup type must be provided per request:

email: searches across all email-based authentication methods (email, Google, Apple, GitHub). May return multiple end users if the same email address appears across different auth methods.
oauthProvider + oauthSubject: looks up a user by their OAuth provider and subject (the sub claim from the provider's ID token). Both params must be provided together.
phoneNumber: looks up a user by their SMS-verified phone number.
siweAddress: looks up a user by the Ethereum address they authenticated with via Sign In With Ethereum (EIP-4361).

Returns all matching end users. If no end users match, an empty array is returned.

This API is intended to be used by the developer's own backend, and is authenticated using the developer's CDP API key.

get/v2/end-users/lookup

Request

Base URL: https://api.cdp.coinbase.com/platform
URL: https://api.cdp.coinbase.com/platform/v2/end-users/lookup
Auth: HTTP bearer

Query parameters

emailstring email

An email address. Maximum length 254 characters per RFC 5321.

Example:user@example.com

The email address to search for across all email-based authentication methods.

oauthProvider'google' | 'apple' | 'x' | 'telegram' | 'github'

The type of OAuth2 provider.

Example:google

The OAuth provider to search by. Must be provided together with oauthSubject.

oauthSubjectstring

The OAuth subject (the sub claim from the provider's ID token). Must be provided together with oauthProvider.

phoneNumberstring

A phone number in E.164 format.

Example:+12055555555

The E.164-formatted phone number to search for. Must be URL-encoded when passed as a query parameter (e.g. +14155552671 → %2B14155552671).

siweAddressstring

A blockchain address. Format varies by network (e.g., 0x-prefixed for EVM, base58 for Solana).

Example:0x742d35Cc6634C0532925a3b844Bc454e4438f44e

The ERC-55 checksummed Ethereum address to search for. Looks up a user by the address they authenticated with via Sign In With Ethereum (EIP-4361).

Response

Successfully looked up end users.

Example response

{
  "endUsers": [
    {
      "userId": "e051beeb-7163-4527-a5b6-35e301529ff2",
      "authenticationMethods": [
        {
          "type": "email",
          "email": "user@example.com"
        },
        {
          "type": "sms",
          "phoneNumber": "+12055555555"
        },
        {
          "type": "jwt",
          "sub": "e051beeb-7163-4527-a5b6-35e301529ff2",
          "kid": "NjVBRjY5MDlCMUIwNzU4RTA2QzZFMDQ4QzQ2MDAyQjVDNjk1RTM2Qg"
        },
        {
          "type": "google",
          "sub": "115346410074741490243",
          "email": "test.user@gmail.com"
        },
        {
          "type": "telegram",
          "id": 1223456,
          "firstName": "Satoshi",
          "lastName": "Nakamoto",
          "photoUrl": "https://image.url/profile.jpg",
          "authDate": 1770681412,
          "username": "satoshinakamoto"
        },
        {
          "type": "siwe",
          "address": "0x742d35Cc6634C0532925a3b844Bc454e4438f44e"
        }
      ],
      "mfaMethods": {
        "enrollmentPromptedAt": "2025-01-15T10:30:00Z",
        "totp": {
          "enrolledAt": "2025-01-15T10:30:00Z"
        },
        "sms": {
          "enrolledAt": "2025-01-15T10:30:00Z"
        }
      },
      "evmAccounts": [
        "0x742d35Cc6634C0532925a3b844Bc454e4438f44e"
      ],
      "evmAccountObjects": [
        {
          "address": "0x742d35Cc6634C0532925a3b844Bc454e4438f44e",
          "createdAt": "2025-01-15T10:30:00Z"
        },
        {
          "address": "0x1234567890abcdef1234567890abcdef12345678",
          "createdAt": "2025-01-15T11:00:00Z"
        }
      ],
      "evmSmartAccounts": [
        "0x742d35Cc6634C0532925a3b844Bc454e4438f44e"
      ],
      "evmSmartAccountObjects": [
        {
          "address": "0x742d35Cc6634C0532925a3b844Bc454e4438f44e",
          "ownerAddresses": [
            "0x1234567890abcdef1234567890abcdef12345678",
            "0xabcdefabcdefabcdefabcdefabcdefabcdefabcd"
          ],
          "createdAt": "2025-01-15T12:00:00Z"
        }
      ],
      "solanaAccounts": [
        "HpabPRRCFbBKSuJr5PdkVvQc85FyxyTWkFM2obBRSvHT"
      ],
      "solanaAccountObjects": [
        {
          "address": "HpabPRRCFbBKSuJr5PdkVvQc85FyxyTWkFM2obBRSvHT",
          "createdAt": "2025-01-15T10:30:00Z"
        },
        {
          "address": "9xQeWvG816bUx9EPjHmaT23yvVM2ZWbrrpZb9PusVFin",
          "createdAt": "2025-01-15T11:30:00Z"
        }
      ],
      "createdAt": "2025-01-15T10:30: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 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 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_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_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 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 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 (6 revisions)