> ## 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.

# Identity Lifecycle

> Understand identity statuses, requirements, and controls, and how to respond to them in your integration.

The `status` field on an identity is the single source of truth for what it can do. The `status_details` object — available on [Get Identity](/api-reference/endpoints/identity/get-identity) and [List Identities](/api-reference/endpoints/identity/list-identities) responses — gives a structured breakdown of why an identity is in a given state and what, if anything, needs to happen next. Use it to drive onboarding flows, surface actionable messaging to your users, and respond to lifecycle events.

## Summary Status

An identity has five possible states:

| Status     | Meaning                                                                               |
| ---------- | ------------------------------------------------------------------------------------- |
| `PENDING`  | Under review. No onboarding decision has been made yet. The identity cannot transact. |
| `APPROVED` | Passed all verifications. The identity has full access to your integration.           |
| `DENIED`   | Failed review. The identity cannot be used with integrations.                         |
| `DISABLED` | Previously approved but off-boarded. Restricted access only.                          |
| `ERROR`    | Frozen for compliance reasons. Entirely disabled.                                     |

The onboarding decision — `APPROVED` or `DENIED` — is made asynchronously after you submit the identity. The decision is based on the identity's risk rating and the outcome of its verification checks. Use webhooks to be notified when the decision is made rather than polling.

```json theme={null}
{
  "id": "f190b163-208f-4d73-8deb-4fb8b24add00",
  "status": "PENDING",
  "status_details": { ... }
}
```

Use `status` to gate access to your integration — only identities in `APPROVED` status can transact.

This status determines what the identity can do:

| Status     | Hold Assets | Create Buy Orders | Create Sell Orders | Execute Open Orders | Create Crypto Deposit Address | Create Crypto Withdrawal | Receive Crypto Deposits |
| ---------- | :---------: | :---------------: | :----------------: | :-----------------: | :---------------------------: | :----------------------: | :---------------------: |
| `PENDING`  |      ❌      |         ❌         |          ❌         |          ❌          |               ❌               |             ❌            |            ❌            |
| `DENIED`   |      ❌      |         ❌         |          ❌         |          ❌          |               ❌               |             ❌            |            ❌            |
| `APPROVED` |      ✅      |         ✅         |          ✅         |          ✅          |               ✅               |             ✅            |            ✅            |
| `DISABLED` |      ✅      |         ❌         |          ✅         |          ✅          |               ❌               |             ❌            |           ❌\*           |
| `ERROR`    |      ✅      |         ❌         |          ❌         |          ✅          |               ❌               |             ❌            |           ❌\*           |

*\*Crypto deposits received by identities in `DISABLED` or `ERROR` status are held for review.*

> `summary_status` returns the same values and is deprecated. Use `status` going forward.

## Requirements

`status_details.requirements` lists all outstanding requirements affecting an identity. Use it to understand what is blocking or pending, drive onboarding flows, and determine whether your application needs to take action.

```json theme={null}
"requirements": [
  {
    "type": "KYC_REFRESH",
    "status": "FAILED",
    "awaiting_action_from": "CLIENT",
    "errors": [
      {
        "code": "KYC_REFRESH_OVERDUE",
        "description": "KYC refresh has expired."
      }
    ]
  },
  {
    "type": "SCREENING_CHECK",
    "status": "PENDING",
    "awaiting_action_from": "PAXOS",
    "errors": [
      {
        "code": "SCREENING_IN_PROGRESS",
        "description": "Screening check is in progress."
      }
    ]
  }
]
```

Each entry has the following fields:

| Field                  | Description                                                                                       |
| ---------------------- | ------------------------------------------------------------------------------------------------- |
| `type`                 | The requirement type — see types below.                                                           |
| `status`               | The state of the requirement — see below.                                                         |
| `awaiting_action_from` | Who must act to resolve it: `PAXOS` or `CLIENT`. Not present for `MEMBERS` type.                  |
| `errors`               | Structured detail for developer use. Do not expose `code` or `description` directly to end users. |

### Requirement Status

| `status`  | Meaning                                                                                                                                  |
| --------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
| `PENDING` | Not yet resolved. Could be under review (`awaiting_action_from: PAXOS`) or waiting on your application (`awaiting_action_from: CLIENT`). |
| `FAILED`  | A verification did not pass. May or may not require action from your side — always check `awaiting_action_from`.                         |

### Requirement Types

| Type                       | Applies to  | Description                                                                                                               |
| -------------------------- | ----------- | ------------------------------------------------------------------------------------------------------------------------- |
| `ID_VERIFICATION`          | Person      | Government-issued ID verification. See [Required Details](/guides/identity/required-details).                             |
| `DOCUMENT_VERIFICATION`    | Institution | Business document review. See [Required Details](/guides/identity/required-details).                                      |
| `SCREENING_CHECK`          | Both        | Background screening. Typically no client action required.                                                                |
| `COMPLIANCE_CHECK`         | Both        | Internal compliance review. No client action required.                                                                    |
| `ENHANCED_DUE_DILIGENCE`   | Both        | Required for higher-risk identities. Submit additional documentation. See [Enhanced Due Diligence](/guides/identity/edd). |
| `KYC_REFRESH`              | Both        | Periodic re-verification of identity information. See [Periodic KYC Refresh](/guides/identity/kyc-refresh).               |
| `TAX_DETAILS_VERIFICATION` | Both        | Tax identification number verification.                                                                                   |
| `MEMBERS`                  | Institution | One or more institution members have outstanding requirements. Check `institution_members` in the response.               |

### Who Needs to Act

Use `awaiting_action_from` to decide whether to wait or take action:

| `awaiting_action_from` | What to do                                                                                                   |
| ---------------------- | ------------------------------------------------------------------------------------------------------------ |
| `CLIENT`               | Your application needs to act — for example, initiate a KYC refresh flow or submit additional documentation. |
| `PAXOS`                | Paxos is processing. No action needed from your side.                                                        |
| Not present            | Applies to `MEMBERS` type only — check `institution_members` for member-level detail.                        |

### Surfacing Requirements to Users

You are responsible for crafting user-facing copy. Use the combination of `type`, `awaiting_action_from`, and `status` to determine what to show. The messages below are illustrative examples only — tailor them to your product's tone and your users' context:

| `type`                     | `awaiting_action_from` | `status`  | Example user-facing message                                  |
| -------------------------- | ---------------------- | --------- | ------------------------------------------------------------ |
| Any                        | `PAXOS`                | `PENDING` | "Your account is under review."                              |
| `ID_VERIFICATION`          | `CLIENT`               | `PENDING` | "Please complete identity verification."                     |
| `DOCUMENT_VERIFICATION`    | `CLIENT`               | `FAILED`  | "Document verification was not successful. Please resubmit." |
| `KYC_REFRESH`              | `CLIENT`               | `FAILED`  | "Your information needs to be updated."                      |
| `ENHANCED_DUE_DILIGENCE`   | `CLIENT`               | `PENDING` | "Additional documentation is required to continue."          |
| `TAX_DETAILS_VERIFICATION` | `CLIENT`               | `FAILED`  | "Please verify your tax details."                            |
| `MEMBERS`                  | —                      | `FAILED`  | "One or more account members require attention."             |

### Error Codes

The `errors[].code` field is a machine-readable enum for logging and routing logic. Do not expose `code` or `description` directly to end users — both are intended for developer use only.

* `IDENTITY_VERIFICATION_REQUIRED`
* `IDENTITY_VERIFICATION_FAILED`
* `DOCUMENT_UPLOAD_REQUIRED`
* `DOCUMENT_VERIFICATION_FAILED`
* `SCREENING_IN_PROGRESS`
* `SCREENING_FAILED`
* `COMPLIANCE_REVIEW_REQUIRED`
* `COMPLIANCE_REVIEW_FAILED`
* `EDD_DOCUMENTATION_REQUIRED`
* `MEMBER_VERIFICATION_PENDING`
* `MEMBER_VERIFICATION_FAILED`
* `TIN_NOT_FOUND`
* `KYC_REFRESH_REQUIRED`
* `KYC_REFRESH_OVERDUE`

<Warning>
  Additional error codes may be added in the future. Build your integration to handle unknown codes gracefully.
</Warning>

```json theme={null}
{
  "type": "KYC_REFRESH",
  "status": "FAILED",
  "awaiting_action_from": "CLIENT",
  "errors": [
    {
      "code": "KYC_REFRESH_OVERDUE",
      "description": "KYC refresh has expired."
    }
  ]
}
```

### The MEMBERS Requirement

When `type` is `MEMBERS`, check the top-level `institution_members` array in the response to identify which members are failing or pending:

```json theme={null}
"institution_members": [
  {
    "id": "m1",
    "identity_id": "b8e1f234-0011-4abc-9900-aabbccddeeff",
    "name": "John Doe",
    "roles": ["BENEFICIAL_OWNER"],
    "summary_status": "DENIED"
  },
  {
    "id": "m2",
    "identity_id": "c9f2a345-1122-5bcd-aa11-bbccddeeff00",
    "name": "Jane Doe",
    "roles": ["CONTROL_PERSON"],
    "summary_status": "APPROVED"
  }
]
```

Call [Get Identity](/api-reference/endpoints/identity/get-identity) on each member's `identity_id` to retrieve their individual `status_details` and requirements.

## Active Controls

Controls allow Paxos or your application to restrict what an identity can do — independently of its compliance status. An identity that has passed all requirements can still have a control applied to limit its activity. `status` reflects the outcome of the compliance review; `active_controls` reflects operational restrictions layered on top.

Controls are applied by two parties:

* **Paxos** (`SET_BY_PAXOS`) — applied for compliance or risk reasons. Contact [Support](https://support.paxos.com) if you believe a control was applied in error.
* **Your application** (`SET_BY_CLIENT`) — applied programmatically via the [Identity Controls API](/api-reference/endpoints/identity-controls/overview), for example to mark an inactive account as dormant.

| Control type | Applied by      | Use case                                                                                                           |
| ------------ | --------------- | ------------------------------------------------------------------------------------------------------------------ |
| `SELL_ONLY`  | Paxos or Client | Identity can only sell or liquidate assets. No new purchases or deposits.                                          |
| `FROZEN`     | Paxos           | All transactions blocked. Identity holds assets but cannot move them.                                              |
| `DORMANT`    | Client          | Identity marked inactive by your application to reduce costs. See [Dormancy Lifecycle](/guides/identity/dormancy). |
| `CLOSED`     | Paxos or Client | Identity closed. No further activity permitted.                                                                    |

`status_details.active_controls` lists all controls currently in effect:

```json theme={null}
"active_controls": [
  {
    "id": "ctrl-001",
    "type": "SELL_ONLY",
    "set_by": "SET_BY_PAXOS",
    "is_overridable": false,
    "reason_code": "COMPLIANCE_KYC",
    "reason": "Prohibited risk rating",
    "created_at": "2026-04-10T08:00:00Z"
  }
]
```

| Field            | Description                                                                                                                            |
| ---------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
| `type`           | The restriction applied — see types above.                                                                                             |
| `set_by`         | `SET_BY_PAXOS` — contact Support to resolve. `SET_BY_CLIENT` — your application applied it.                                            |
| `is_overridable` | Whether your application can remove this control via the [Identity Controls API](/api-reference/endpoints/identity-controls/overview). |
| `reason`         | Human-readable explanation of why the control was applied.                                                                             |

An empty `active_controls` array means no controls are in effect.

## Sub-statuses

<Warning>
  These fields are deprecated. Use `status_details.requirements` instead — it provides the same information in a structured, actionable format. See [Migrating from Deprecated Fields](#migrating-from-deprecated-fields).
</Warning>

The following fields may still appear in identity responses and reflect the outcome of individual verification checks.

### Sanctions Verification (`sanctions_verification_status`)

* `PENDING` — Sanctions check in progress.
* `APPROVED` — No sanctions hit found.
* `DENIED` — Sanctions hit found. Cannot proceed.
* `ERROR` — Possible sanctions hit, held for manual review.

### Additional Screening (`additional_screening_status`)

* `PENDING` — Screening checks in progress.
* `APPROVED` — Passed all screening checks.
* `DENIED` — Failed screening checks.
* `ERROR` — Possible screening hit, held for manual review.

> Additional screening covers negative news and politically exposed person checks. Sanctions checks are reported separately in `sanctions_verification_status`.

### ID Verification (`id_verification_status`, persons only)

* `PENDING` — Verification in progress.
* `APPROVED` — Identity confirmed.
* `DENIED` — Unable to verify the person's identity.

> When using Passthrough IDV, `id_verification_status` reflects the `passthrough_verification_status` provided at identity creation. Note that `passthrough_verification_status` can only be set to a terminal status — `APPROVED` or `DENIED`.

## Staying Current with Webhooks

The [`identity_summary_status_change`](/api-reference/events/identity-summary-status-change-object) webhook fires when an identity's `status` changes and includes `status_details.requirements` in the [Event API](/api-reference/endpoints/events/get-event) response.

> This webhook fires on status changes only — not on every individual requirement change within a stable status. Call [Get Identity](/api-reference/endpoints/identity/get-identity) to retrieve the latest requirements at any point.

## Migrating from Deprecated Fields

The following fields are deprecated and will be removed in a future release. Migrate to `status` and `status_details` instead.

| Deprecated field                  | Replacement                      |
| --------------------------------- | -------------------------------- |
| `summary_status`                  | `status`                         |
| `user_disabled`                   | `status_details.active_controls` |
| `admin_disabled`                  | `status_details.active_controls` |
| `id_verification_status`          | `status_details.requirements`    |
| `sanctions_verification_status`   | `status_details.requirements`    |
| `additional_screening_status`     | `status_details.requirements`    |
| `document_verification_status`    | `status_details.requirements`    |
| `summary_tin_verification_status` | `status_details.requirements`    |

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