Identity Lifecycle

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

Tax-documentation requirements apply only to person and institution Identities in the Paxos Trust Company (PTC) population. Business-member Identities do not need to submit tax documentation. Beginning January 1, 2027, in-scope Identities without approved tax documentation will be blocked from taxable transactions.

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.
`TAX_DOCUMENTATION`	Paxos Trust Company (PTC) person or institution	The Identity has no accepted W-9, W-8BEN, or W-8BEN-E, or its current form requires action. Submit or resubmit the complete form through the Tax Documentation API when `awaiting_action_from` is `CLIENT`.
`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.”
`TAX_DOCUMENTATION`	`CLIENT`	`PENDING` or `FAILED`	”Please submit or update your tax documentation.”
`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. Tax-documentation error codes identify the lifecycle state of the Identity’s current W-form. Use the Tax Documentation API overview for the corresponding partner action and form-specific reason codes.

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
TAX_DOCUMENTATION_REQUIRED
TAX_DOCUMENTATION_VALIDATION_PENDING
TAX_DOCUMENTATION_RESUBMISSION_REQUIRED
TAX_DOCUMENTATION_EXPIRED
TAX_DOCUMENTATION_UNKNOWN_ISSUE

Tax-documentation requirements can also include specific reason codes. See Respond to tax-documentation requirements for the complete set and the required partner action.

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

Use the replacements below in new integrations and migrate existing integrations as you update them. Deprecated fields remain supported for compatibility, including in responses where they are currently returned. These deprecations do not change current API behavior.

Identity Status and Verification Fields

These response fields on Get Identity and List Identities are deprecated:

Deprecated field	Replacement
`summary_status`	`status`
`Identity.user_disabled`	`Identity.status_details.active_controls`
`Identity.admin_disabled`	`Identity.status_details.active_controls`
`Identity.summary_tin_verification_status`	`Identity.status_details.requirements`
`person_details.id_verification_status`	`status_details.requirements`
`person_details.sanctions_verification_status`	`status_details.requirements`
`person_details.additional_screening_status`	`status_details.requirements`
`institution_details.sanctions_verification_status`	`status_details.requirements`
`institution_details.document_verification_status`	`status_details.requirements`
`institution_details.additional_screening_status`	`status_details.requirements`

Read each requirement’s type, status, and awaiting_action_from together to determine the next action. Requirements describe outstanding work; do not expect a separate entry for every successful legacy verification check. For restrictions, inspect each active control’s type and set_by rather than treating the controls array as a boolean. InstitutionMember.summary_status in institution_members remains supported; use it to identify members needing attention, then call Get Identity with the member’s identity_id for their requirements.

Government ID Fields

When calling Create Identity or Update Identity, migrate the person identification fields as follows:

Deprecated field	Replacement
`person_details.govt_id`	`person_details.cip_id`
`person_details.govt_id_type`	`person_details.cip_id_type`

When supplying cip_id_type or cip_id_country, include both fields. Use an ISO 3166-1 alpha-3 country code such as USA. For a person whose cip_id_country is USA, cip_id_type must be SSN or ITIN. This rule is based on the CIP country. For other CIP countries, use the applicable identification type; do not use SSN or ITIN with a non-US CIP country. See Required Details. For compatibility, Paxos uses govt_id or govt_id_type when the corresponding CIP field is not supplied, and defaults a missing cip_id_country to USA for SSN or ITIN. Send the CIP fields explicitly when migrating instead of relying on these defaults. Deprecated identification fields continue to be returned where currently provided.

Pending Documents

For List Identity Documents responses, replace pending_documents with entries in documents whose status is NOT_STARTED, and read their document_types arrays to identify document types awaiting upload. Selected optional types can also appear with this status. The required flag applies to the entire entry and is true if any of its document types is required. If status is omitted, the upload state is unknown. Treat the entry as unresolved; do not assume that upload completed or that another upload is required. The deprecated pending_documents array is populated only when include_pending_docs is set. This deprecation applies to the response field; it does not deprecate the include_pending_docs query parameter. See Enhanced Due Diligence for document upload guidance.

Account Member Type

For account membership in Create Account and Add Account Members, replace AccountMember.type with the roles array. For example, replace "type": "AUTHORIZED_USER" on a member with "roles": ["AUTHORIZED_USER"]. If you previously sent multiple member entries for the same identity_id with different type values, combine them into one member entry with those values in roles. This deprecation applies to account members, which link identities to accounts. Institution members link person identities to institution identities and already use their own roles array. See Account Members for membership guidance.

Questions? Contact Support.

Get Started

Identity

Travel Rule

Stablecoin Orchestration

Fiat Transfers

Rewards Engine

Address Verification

Stablecoin Payments

Crypto Brokerage

Webhooks

Additional Guides

Versioning

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

Identity Status and Verification Fields

Government ID Fields

Pending Documents

Account Member Type

​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

​Identity Status and Verification Fields

​Government ID Fields

​Pending Documents

​Account Member Type

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

Identity Status and Verification Fields

Government ID Fields

Pending Documents

Account Member Type