Skip to main content
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: 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.
FieldDescription
passthrough_verifier_typeThe IDV provider used (e.g., JUMIO, PERSONA)
passthrough_verified_atWhen IDV was completed
passthrough_verification_idThe IDV record ID in the provider’s system
passthrough_verification_statusSet to APPROVED if the user was successfully verified
passthrough_verification_fieldsThe 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: 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.