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