> ## Documentation Index
> Fetch the complete documentation index at: https://docs.paxos.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Onboard an Institution

> Create an institution identity with required members and handle the onboarding decision on the Paxos Platform.

This guide walks through creating an [Institution Identity](/api-reference/endpoints/identity/create-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](/guides/dashboard/account) in Sandbox
* Contact [Support](https://support.paxos.com) 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](/guides/dashboard/admin/api) on the Sandbox [Paxos Dashboard](/guides/dashboard/account) with the following scopes:

* `identity:read_identity`
* `identity:write_identity`

> The `identity:write_identity` scope is gated. Contact [Support](https://support.paxos.com) to have it enabled before creating API keys with this scope.

Run the following to get an `access_token`:

```shell theme={null}
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`:

```json theme={null}
{
  "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](/guides/identity/institution-types#member-roles) for role definitions and [Required Details](/guides/identity/required-details#required-person-details) for the fields to collect.

Create a person identity for each required member:

```shell theme={null}
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.

```json theme={null}
{
    "id": "{person_identity_id}",
    "status": "PENDING",
    ...
}
```

> For IDV details and passthrough field descriptions, see [Onboard a Person](/guides/identity/onboard-person#-create-the-identity).

## ➌ 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](/guides/identity/required-details#required-institution-details) for the fields required by institution type. The example below creates a corporation:

```shell theme={null}
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:

```json theme={null}
{
    "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": { ... }
}
```

<Warning>
  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.
</Warning>

## ➍ 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](/guides/webhooks/quickstart) to receive these events:

* [`identity.approved`](/api-reference/webhooks/identity-approved) — the institution passed review
* [`identity.denied`](/api-reference/webhooks/identity-denied) — the institution failed review
* [`identity.documents_required`](/api-reference/webhooks/identity-documents-required) — additional documentation is required before a decision can be made

To check status directly, call [Get Identity](/api-reference/endpoints/identity/get-identity):

```shell theme={null}
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](/guides/identity/edd) for how to upload them.

If the identity is stuck in `PENDING` for another reason, use [status\_details](/guides/identity/identity-lifecycle#requirements) to understand what is blocking it.

> In Sandbox, institutions will remain `PENDING` by default. Contact [Support](https://support.paxos.com) to advance the identity to `APPROVED` for testing.

## Next Steps

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

<CardGroup cols={2}>
  <Card title="Crypto Brokerage" href="/guides/crypto-brokerage" icon="chart-line">
    Create an Account and Profile, then start booking orders
  </Card>

  <Card title="Fiat Transfers" href="/guides/developer/fiat-transfers/quickstart" icon="building-columns">
    Fund accounts and move money on behalf of the institution
  </Card>
</CardGroup>

## API Reference

* [Create Identity](/api-reference/endpoints/identity/create-identity)
* [Get Identity](/api-reference/endpoints/identity/get-identity)
* [Update Identity](/api-reference/endpoints/identity/update-identity)
* [List Identities](/api-reference/endpoints/identity/list-identities)
* [Document Upload](/api-reference/endpoints/identity-documents/document-upload)
* [List Identity Documents](/api-reference/endpoints/identity-documents/list-identity-documents)

> Questions? Contact [Support](https://support.paxos.com).