Onboard an Institution

This guide walks through creating an Institution Identity and responding to the onboarding decision. Institution identities require associated person identities for key member roles, so this guide covers both. This should take around 30 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 Person Identities for Members

Before creating an institution identity, create person identities for the individuals who hold roles within the institution — such as beneficial owners, authorized users, and management control persons. The required roles and the fields needed for each depend on the institution type. See Institution Types and Members for role definitions and Required Details for the fields to collect. Create a person identity for each required member:

curl --location "https://api.sandbox.paxos.com/v2/identity/identities" \
--request "POST" \
--header "Authorization: Bearer {access_token}" \
--data '{
    "ref_id": "{your_member_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": "1980-01-01",
        "address": {
            "address1": "123 Main St",
            "city": "New York",
            "province": "NY",
            "country": "USA",
            "zip_code": "10001"
        },
        "nationality": "USA",
        "cip_id": "073-05-1127",
        "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"
    }
}'

Save the id from each response — you will need these as identity_id values when creating the institution identity.

{
    "id": "{person_identity_id}",
    "status": "PENDING",
    ...
}

For IDV details and passthrough field descriptions, see Onboard a Person.

➌ Create the Institution Identity

Provide the institution’s required details and list the person identities created above as members with their respective roles.

Set ref_id to your internal identifier for this institution. It is stored alongside the identity so you can correlate identity records with your own records. It must be unique per identity.

See Required Details for the fields required by institution type. The example below creates a corporation:

curl --location "https://api.sandbox.paxos.com/v2/identity/identities" \
--request "POST" \
--header "Authorization: Bearer {access_token}" \
--data '{
    "ref_id": "{your_institution_ref_id}",
    "institution_members": [
        {
            "identity_id": "{person_identity_id}",
            "roles": ["BENEFICIAL_OWNER", "AUTHORIZED_USER", "MANAGEMENT_CONTROL_PERSON"]
        }
    ],
    "institution_details": {
        "name": "Foogle",
        "business_address": {
            "country": "United States",
            "address1": "1 Example St",
            "city": "New York",
            "province": "NY",
            "zip_code": "10001"
        },
        "email": "contact@foogle.com",
        "institution_type": "CORPORATION",
        "institution_sub_type": "HEDGE_FUND",
        "cip_id": "12-3456789",
        "cip_id_type": "EIN",
        "cip_id_country": "USA",
        "govt_registration_date": "2021-04-14T00:00:00Z",
        "incorporation_address": {
            "country": "United States",
            "address1": "1 Example St",
            "city": "New York",
            "province": "NY",
            "zip_code": "10001"
        },
        "regulation_status": "US_REGULATED",
        "trading_type": "PUBLIC",
        "listed_exchange": "NASDAQ",
        "ticker_symbol": "FOOG",
        "regulator_name": "SEC",
        "regulator_jurisdiction": "USA",
        "regulator_register_number": "12-3456789",
        "business_description": "Asset management firm"
    }
}'

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

{
    "id": "{institution_identity_id}",
    "status": "PENDING",
    "created_at": "2021-06-16T09:28:14Z",
    "updated_at": "2021-06-16T09:28:14Z",
    "ref_id": "{your_institution_ref_id}",
    "institution_details": { ... }
}

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

➍ Wait for the Onboarding Decision

Institution identities require document verification before an onboarding decision can be made. The identity will remain in PENDING status until the review completes, which may require uploading supporting documents. Set up a webhook consumer to receive these events:

identity.approved — the institution passed review
identity.denied — the institution failed review
identity.documents_required — additional documentation is required before a decision can be made

To check status directly, call Get Identity:

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

If documents are required, see Enhanced Due Diligence for how to upload them. If the identity is stuck in PENDING for another reason, use status_details to understand what is blocking it.

In Sandbox, institutions will remain PENDING by default. Contact Support to advance the identity to APPROVED for testing.

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 accounts and move money on behalf of the institution

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 Person Identities for Members

➌ Create the Institution Identity

➍ Wait for the Onboarding Decision

Next Steps

Crypto Brokerage

Fiat Transfers

API Reference

​Prerequisites

​➊ Authenticate

​➋ Create Person Identities for Members

​➌ Create the Institution Identity

​➍ Wait for the Onboarding Decision

​Next Steps

Crypto Brokerage

Fiat Transfers

​API Reference

Prerequisites

➊ Authenticate

➋ Create Person Identities for Members

➌ Create the Institution Identity

➍ Wait for the Onboarding Decision

Next Steps

API Reference