This guide is for Paxos partners who are building products for their own end users using Paxos infrastructure. You are responsible for managing your users’ onboarding experience — including collecting information, presenting the right flows at the right time, and handling lifecycle events on their behalf. Paxos does not interact with your end users directly.
The status_details object on GetIdentity and ListIdentities responses gives you 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 and lifecycle management flows, surface actionable messaging to your users, and respond to lifecycle events.
➊ Check the Identity Status
The top-level status field tells you the overall state of the identity. Use this to gate access to your integration.
{
"id": "f190b163-208f-4d73-8deb-4fb8b24add00",
"status": "PENDING",
...
}
| Status | Meaning |
|---|
PENDING | Under review. The identity cannot transact yet. |
APPROVED | Passed all verifications. Full access to integrations. |
DENIED | Failed review. Cannot be used with integrations. |
DISABLED | Previously approved but off-boarded. Restricted or entirely disabled access to integrations. |
ERROR | Frozen for compliance reasons. Entirely disabled access to integrations. |
summary_status returns the same values as status and is deprecated. Use status going forward.
status_details.active_controls lists any restrictions currently applied to the identity. An identity can satisfy all requirements and still have controls limiting what it can do.
"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: SELL_ONLY, FROZEN, DORMANT, or CLOSED. |
set_by | SET_BY_PAXOS — set by Paxos, contact Support to resolve. SET_BY_CLIENT — set by your application. |
is_overridable | Whether your application can remove this control via the Identity Controls API. |
reason | Human-readable explanation of why the control was applied. |
active_controls array means no controls are in effect.
➌ Read Requirements
status_details.requirements lists all outstanding requirements — both pending and failed — that are affecting the identity’s status.
"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."
}
]
}
]
Determine who needs to act
Use awaiting_action_from to decide whether your application needs to do something or simply wait:
awaiting_action_from | What to do |
|---|
CLIENT | Your application needs to take action — for example, initiating a KYC refresh flow or submitting additional documentation. |
PAXOS | Paxos is processing. No action is needed from your side. |
| Not present | Applies to MEMBERS type only — check institution_members in the response for member-level detail. |
Understand the requirement status
status | Meaning |
|---|
PENDING | Not yet resolved. Could be under Paxos 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 — check awaiting_action_from. |
Use errors for debugging — not user messaging
The errors array is intended for developer use. The code field is a machine-readable enum useful for logging and routing logic. Do not expose code or description directly to end users.
Additional error codes may be added in the future. Build your integration to handle unknown codes gracefully.
Available error codes
identity_verification_requiredidentity_verification_faileddocument_upload_requireddocument_verification_failedscreening_in_progressscreening_failedcompliance_review_requiredcompliance_review_failededd_documentation_requiredmember_verification_pendingmember_verification_failedtin_not_foundkyc_refresh_requiredkyc_refresh_overdue
{
"type": "KYC_REFRESH",
"status": "FAILED",
"awaiting_action_from": "CLIENT",
"errors": [
{
"code": "kyc_refresh_overdue",
"description": "KYC refresh has expired."
}
]
}
type, awaiting_action_from, and status to determine what to show. See some examples below:
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.” |
Requirement types
| Type | Applies to | Description |
|---|
ID_VERIFICATION | Person | Government-issued ID verification. Required to confirm the identity of the person. See Required Details. |
DOCUMENT_VERIFICATION | Institution | Business document review. Required to verify the legal entity. See Required Details. |
SCREENING_CHECK | Both | Background screening check. Paxos screens identities as part of the onboarding process. No action is typically required from the client. |
COMPLIANCE_CHECK | Both | Internal compliance review. Paxos is reviewing the identity and no action is required from the client. |
ENHANCED_DUE_DILIGENCE | Both | Enhanced due diligence review. Required for higher-risk identities. Your application must submit additional documentation to proceed. See Enhanced Due Diligence. |
KYC_REFRESH | Both | Periodic re-verification of identity information. Required when an identity’s information has expired. See Periodic KYC Refresh. |
TAX_DETAILS_VERIFICATION | Both | Tax identification number verification. Required to validate the identity’s tax details on file. |
MEMBERS | Institution | One or more institution members have outstanding requirements. Check institution_members in the response for details on which members are failing or pending. |
Handling the MEMBERS requirement
When type is MEMBERS, check the top-level institution_members array in the response to see 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"
}
]
identity_id to retrieve their individual status_details and requirements.
Staying up to date with webhooks
The identity_summary_status_change webhook fires when an identity’s overall status changes and includes status_details.requirements in the Event API response.
Note: this webhook fires on status changes only — not every time an individual requirement changes within a stable status. Call Get Identity to retrieve the latest requirements at any point.
Migration from Deprecated Fields
The following fields are deprecated and will be removed in a future release. Migrate to status and status_details.requirements 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 |
document_verification_status | status_details.requirements |
summary_tin_verification_status | status_details.requirements |
Questions? Contact Support.
