Dormancy Lifecycle

Manage dormant identities with automated lifecycle controls.

Overview

The Identity Dormancy Lifecycle feature enables you to manage identities that become inactive over time. Use Identity Controls to mark identities as dormant and the enhanced Identity API to monitor their status.

Key capabilities:

• Query identities with detailed status information including pending requirements, failed requirements, and active controls
• Set and remove dormant controls on identities
• Filter identities by active control type and reason code
• Track control lifecycle with creation and deletion timestamps

Use Cases

• Compliance: Automatically flag accounts inactive for regulatory periods (e.g., 90, 180, or 365 days)
• Risk management: Reduce exposure by restricting dormant account activity
• Resource optimization: Identify and manage inactive identities
• Reactivation workflows: Track and restore dormant accounts when users return

Understanding Dormancy Controls

A dormancy control marks an identity as inactive, changing its status to DISABLED. This prevents the identity from performing operations while maintaining a complete audit trail of the control lifecycle.

Control Types

Type	Description	Set By
DORMANT	Identity is dormant due to inactivity	Client or Paxos
CLOSED	Identity is permanently closed	Client or Paxos

Reason Codes

Code	Description	Typical Use
DORMANT	Identity inactive for specified period	Automated dormancy workflows
END_USER_REQUESTED	User requested the control	Manual account closure
COMPLIANCE	Regulatory or compliance requirement	Paxos-initiated controls
OTHER	Miscellaneous reason	Custom scenarios

Identity Status Impact

When a dormant control is active, the identity status changes to DISABLED. The status_details field shows the active control:

{
  "id": "f190b163-208f-4d73-8deb-4fb8b24add00",
  "status": "DISABLED",
  "status_details": {
    "active_controls": [
      {
        "id": "59b8e3c5-2b6e-4fa6-afcf-8c685598241d",
        "type": "DORMANT",
        "controlled_by": "CLIENT",
        "reason_code": "DORMANT",
        "reason": "No activity for 180 days",
        "created_at": "2006-01-02T15:04:05Z"
      }
    ]
  }
}

Workflow

➊ Set Dormant Control

Mark an identity as dormant using the Create Identity Control endpoint.

curl -X POST "https://api.paxos.com/v2/identity/controls" \
  -H "Authorization: Bearer {access_token}" \
  -H "Content-Type: application/json" \
  -d '{
    "identity_id": "f190b163-208f-4d73-8deb-4fb8b24add00",
    "type": "DORMANT",
    "reason_code": "DORMANT",
    "reason": "No activity for 180 days"
  }'

The identity’s status immediately changes to DISABLED and operations are blocked.

�② List Dormant Identities

Query all identities with dormant controls using the enhanced List Identities endpoint.

Filter by dormant control type:

curl -X GET "https://api.paxos.com/identity/identities?control_type=DORMANT" \
  -H "Authorization: Bearer {access_token}"

Filter by reason code:

curl -X GET "https://api.paxos.com/identity/identities?control_reason_code=DORMANT" \
  -H "Authorization: Bearer {access_token}"

Filter by status:

curl -X GET "https://api.paxos.com/identity/identities?status=DISABLED" \
  -H "Authorization: Bearer {access_token}"

➌ Check Identity Details

Retrieve a specific identity to view its complete status including active controls, pending requirements, and failed requirements.

curl -X GET "https://api.paxos.com/identity/identities/{identity_id}" \
  -H "Authorization: Bearer {access_token}"

➍ View Control History

List all controls (active and deleted) for an identity to maintain a complete audit trail.

curl -X GET "https://api.paxos.com/v2/identity/controls?identity_id={identity_id}&include_deleted=true" \
  -H "Authorization: Bearer {access_token}"

Response:

{
  "items": [
    {
      "id": "ae54b3b4-cce6-4707-b34b-c9c4f0537798",
      "type": "DORMANT",
      "controlled_by": "CLIENT",
      "reason_code": "DORMANT",
      "reason": "No activity for 180 days",
      "created_at": "2006-01-02T15:04:05Z"
    }
  ],
  "next_page_cursor": ""
}

➎ Remove Dormant Control

Reactivate a dormant identity by deleting the control.

curl -X DELETE "https://api.paxos.com/v2/identity/controls" \
  -H "Authorization: Bearer {access_token}" \
  -H "Content-Type: application/json" \
  -d '{
    "identity_id": "f190b163-208f-4d73-8deb-4fb8b24add00",
    "id": "ae54b3b4-cce6-4707-b34b-c9c4f0537798",
    "reason": "User returned and requested reactivation"
  }'

The identity’s status returns to its previous state (typically APPROVED if no other controls or requirements apply).

Status Details Structure

The status_details field provides comprehensive information about an identity’s current state:

Active Controls - Controls currently applied to the identity

{
  "active_controls": [
    {
      "id": "control-id",
      "type": "DORMANT",
      "controlled_by": "CLIENT",
      "reason_code": "DORMANT",
      "reason": "Descriptive reason",
      "created_at": "2006-01-02T15:04:05Z"
    }
  ]
}

Pending Requirements - Requirements that must be satisfied before the identity can be approved

{
  "pending_requirements": [
    {
      "type": "SANCTIONS_SCREENING",
      "message": "Pending Sanctions Screening"
    }
  ]
}

Failed Requirements - Requirements that failed and prevent identity approval

{
  "failed_requirements": [
    {
      "type": "RISK_RATING",
      "message": "Jurisdiction not supported by Paxos"
    }
  ]
}

Best Practices

Automated Dormancy Detection

Implement a scheduled job to detect and flag dormant identities:

1. Query identities last active before your threshold (e.g., 180 days ago)
2. Filter out identities that already have a dormant control
3. Create dormant controls for qualifying identities
4. Log all dormancy actions for audit trails

Reactivation Workflow

When a dormant user returns:

1. Verify user identity through your authentication flow
2. List the identity’s controls to find the dormant control ID
3. Delete the dormant control with a descriptive reason
4. Check the identity status to confirm it’s no longer DISABLED
5. Allow user to resume normal operations

Pagination

When querying large identity sets, use pagination:

# Initial request
curl -X GET "https://api.paxos.com/identity/identities?limit=100" \
  -H "Authorization: Bearer {access_token}"

# Subsequent pages
curl -X GET "https://api.paxos.com/identity/identities?limit=100&page_cursor={next_page_cursor}" \
  -H "Authorization: Bearer {access_token}"

Control History

Keep include_deleted=true when listing controls to maintain a complete audit trail of an identity’s lifecycle.

Identity Status States

Status	Description
PENDING	Identity verification in progress
APPROVED	Identity approved and active
DENIED	Identity denied due to failed requirements
DISABLED	Identity disabled (e.g., by dormant or closed control)
ERROR	Error during identity processing

API Reference

Identity Queries

• List Identities - Query identities with filtering
• Get Identity - Retrieve detailed identity status

Identity Controls

• List Identity Controls - View all controls for an identity
• Create Identity Control - Set a new control
• Delete Identity Control - Remove an existing control

Support

Questions? Contact Support.