Onboard a Person

This guide walks through creating a Person Identity and responding to the onboarding decision. This should take around 15 minutes.

Prerequisites

Sign up to the Paxos Dashboard in Sandbox
Contact Support to request access to the Identity API — write scopes are gated and must be provisioned before you can create identities

➊ Authenticate

Create an API Key on the Sandbox Paxos Dashboard with the following scopes:

identity:read_identity
identity:write_identity

The identity:write_identity scope is gated. Contact Support to have it enabled before creating API keys with this scope.

Run the following to get an access_token:

curl --location 'https://oauth.sandbox.paxos.com/oauth2/token' \
--form grant_type=client_credentials \
--form client_id={paxos_client_id} \
--form client_secret={paxos_secret} \
--form scope='identity:read_identity identity:write_identity'

Confirm the response includes the required scopes and save the access_token:

{
  "access_token": "{access_token}",
  "expires_in": 3599,
  "scope": "identity:read_identity identity:write_identity",
  "token_type": "bearer"
}

Include -H "Authorization: Bearer {access_token}" on all subsequent requests.

➋ Create the Identity

To create a person identity, provide:

The person’s required details — see Required Details
Identity verification (IDV) details from your IDV provider — see Identity Verification

Set verifier_type to PASSTHROUGH and provide the following details about how and when IDV was performed.

Set ref_id to your internal user ID. It is stored alongside the identity so you can correlate identity records with your own user records. It must be unique per identity.

Field	Description
`passthrough_verifier_type`	The IDV provider used (e.g., `JUMIO`, `PERSONA`)
`passthrough_verified_at`	When IDV was completed
`passthrough_verification_id`	The IDV record ID in the provider’s system
`passthrough_verification_status`	Set to `APPROVED` if the user was successfully verified
`passthrough_verification_fields`	The fields verified during IDV

All passthrough fields are required when verifier_type is set to PASSTHROUGH.

curl --location "https://api.sandbox.paxos.com/v2/identity/identities" \
--request "POST" \
--header "Authorization: Bearer {access_token}" \
--data '{
    "ref_id": "{your_end_user_ref_id}",
    "person_details": {
        "verifier_type": "PASSTHROUGH",
        "passthrough_verifier_type": "JUMIO",
        "passthrough_verified_at": "2021-06-16T09:28:14Z",
        "passthrough_verification_id": "775300ef-4edb-47b9-8ec4-f45fe3cbf41f",
        "passthrough_verification_status": "APPROVED",
        "passthrough_verification_fields": ["FULL_LEGAL_NAME", "DATE_OF_BIRTH"],
        "first_name": "Billy",
        "last_name": "Duncan",
        "date_of_birth": "1960-01-01",
        "address": {
            "address1": "123 Main St",
            "city": "New York",
            "province": "NY",
            "country": "USA",
            "zip_code": "10001"
        },
        "nationality": "USA",
        "cip_id": "073-05-1120",
        "cip_id_type": "SSN",
        "cip_id_country": "USA",
        "phone_number": "+1 555 678 1234",
        "email": "example@somemail.org"
    },
    "customer_due_diligence": {
        "estimated_yearly_income": "INCOME_50K_TO_100K",
        "expected_transfer_value": "TRANSFER_VALUE_25K_TO_50K",
        "source_of_wealth": "EMPLOYMENT_INCOME",
        "employment_status": "FULL_TIME",
        "employment_industry_sector": "ARTS_ENTERTAINMENT_RECREATION"
    }
}'

The response includes the identity_id. The identity enters PENDING status immediately:

{
    "id": "{identity_id}",
    "status": "PENDING",
    "created_at": "2021-06-16T09:28:14Z",
    "updated_at": "2021-06-16T09:28:14Z",
    "ref_id": "{your_end_user_ref_id}",
    "person_details": { ... }
}

The cip_id must be unique across all identities. If a 409 duplicate cip_id error occurs, either decline services for that user or — if confirmed to be the same person — create a new account linked to the existing identity instead.

➌ Wait for the Onboarding Decision

The submission is reviewed asynchronously. The identity transitions from PENDING to either APPROVED or DENIED. The recommended approach is to listen for webhook events:

identity.approved — the identity passed review
identity.denied — the identity failed review

See Webhooks Quickstart to set up a consumer. To check status directly, call Get Identity:

curl --location "https://api.sandbox.paxos.com/v2/identity/identities/{identity_id}" \
--request "GET" \
--header "Authorization: Bearer {access_token}"

In Sandbox, the example details above will result in auto-approval. Call Get Identity immediately after creating the identity to confirm status is APPROVED.

An identity may remain PENDING if Enhanced Due Diligence is required. See Enhanced Due Diligence to handle this case.

If the identity is stuck in PENDING, use status_details to understand what is blocking it and whether action is required from your side.

Next Steps

Once the identity is APPROVED, connect it to the product your integration supports:

Crypto Brokerage

Create an Account and Profile, then start booking orders

Fiat Transfers

Fund user accounts and move money on their behalf

API Reference

Questions? Contact Support.

Get Started

Identity

Travel Rule

Stablecoin Orchestration

Fiat Transfers

Address Verification

Stablecoin Payments

Crypto Brokerage

Webhooks

Additional Guides

Versioning

Prerequisites

➊ Authenticate

➋ Create the Identity

➌ Wait for the Onboarding Decision

Next Steps

Crypto Brokerage

Fiat Transfers

API Reference

​Prerequisites

​➊ Authenticate

​➋ Create the Identity

​➌ Wait for the Onboarding Decision

​Next Steps

Crypto Brokerage

Fiat Transfers

​API Reference

Prerequisites

➊ Authenticate

➋ Create the Identity

➌ Wait for the Onboarding Decision

Next Steps

API Reference