Identity Lifecycle - Paxos Documentation

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

{
  "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.

"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.
`DOCUMENT_VERIFICATION`	Institution	Business document review. See 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.
`KYC_REFRESH`	Both	Periodic re-verification of identity information. See Periodic 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

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

{
  "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:

"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 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 if you believe a control was applied in error.
Your application (SET_BY_CLIENT) — applied programmatically via the Identity Controls API, 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.
`CLOSED`	Paxos or Client	Identity closed. No further activity permitted.

status_details.active_controls lists all controls currently in effect:

"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.
`reason`	Human-readable explanation of why the control was applied.

An empty active_controls array means no controls are in effect.

Sub-statuses

These fields are deprecated. Use status_details.requirements instead — it provides the same information in a structured, actionable format. See Migrating from Deprecated Fields.

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 webhook fires when an identity’s status changes and includes status_details.requirements in the Event API response.

This webhook fires on status changes only — not on every individual requirement change within a stable status. Call 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.

​Summary Status

​Requirements

​Requirement Status

​Requirement Types

​Who Needs to Act

​Surfacing Requirements to Users

​Error Codes

​The MEMBERS Requirement

​Active Controls

​Sub-statuses

​Sanctions Verification (sanctions_verification_status)

​Additional Screening (additional_screening_status)

​ID Verification (id_verification_status, persons only)

​Staying Current with Webhooks

​Migrating from Deprecated Fields

Summary Status

Requirements

Requirement Status

Requirement Types

Who Needs to Act

Surfacing Requirements to Users

Error Codes

The MEMBERS Requirement

Active Controls

Sub-statuses

Sanctions Verification (`sanctions_verification_status`)

Additional Screening (`additional_screening_status`)

ID Verification (`id_verification_status`, persons only)

Staying Current with Webhooks

Migrating from Deprecated Fields