> ## 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 a Person

> Create a person identity and handle the onboarding decision on the Paxos Platform.

This guide walks through creating a [Person Identity](/api-reference/endpoints/identity/create-identity) and responding to the onboarding decision. This should take around 15 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 the Identity

To create a person identity, provide:

* The person's required details — see [Required Details](/guides/identity/required-details#required-person-details)
* Identity verification (IDV) details from your IDV provider — see [Identity Verification](/guides/identity#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`.

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

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

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

## ➌ 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`](/api-reference/webhooks/identity-approved) — the identity passed review
* [`identity.denied`](/api-reference/webhooks/identity-denied) — the identity failed review

See [Webhooks Quickstart](/guides/webhooks/quickstart) to set up a consumer.

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/{identity_id}" \
--request "GET" \
--header "Authorization: Bearer {access_token}"
```

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

<Info>
  An identity may remain `PENDING` if Enhanced Due Diligence is required. See [Enhanced Due Diligence](/guides/identity/edd) to handle this case.
</Info>

If the identity is stuck in `PENDING`, use [status\_details](/guides/identity/identity-lifecycle#requirements) 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:

<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 user accounts and move money on their behalf
  </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)

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