diff --git a/api-reference/preview/identity-dormancy-lifecycle.mdx b/api-reference/preview/identity-dormancy-lifecycle.mdx new file mode 100644 index 0000000..86b86bd --- /dev/null +++ b/api-reference/preview/identity-dormancy-lifecycle.mdx @@ -0,0 +1,273 @@ +--- +title: 'Dormancy Lifecycle' +description: 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: + +```json +{ + "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. + +```bash +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:** + +```bash +curl -X GET "https://api.paxos.com/identity/identities?control_type=DORMANT" \ + -H "Authorization: Bearer {access_token}" +``` + +**Filter by reason code:** + +```bash +curl -X GET "https://api.paxos.com/identity/identities?control_reason_code=DORMANT" \ + -H "Authorization: Bearer {access_token}" +``` + +**Filter by status:** + +```bash +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. + +```bash +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. + +```bash +curl -X GET "https://api.paxos.com/v2/identity/controls?identity_id={identity_id}&include_deleted=true" \ + -H "Authorization: Bearer {access_token}" +``` + +**Response:** + +```json +{ + "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. + +```bash +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 + +```json +{ + "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 + +```json +{ + "pending_requirements": [ + { + "type": "SANCTIONS_SCREENING", + "message": "Pending Sanctions Screening" + } + ] +} +``` + +**Failed Requirements** - Requirements that failed and prevent identity approval + +```json +{ + "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: + +```bash +# 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](/api-reference/preview/list-identities) - Query identities with filtering +- [Get Identity](/api-reference/preview/get-identity) - Retrieve detailed identity status + +### Identity Controls +- [List Identity Controls](/api-reference/preview/list-identity-controls) - View all controls for an identity +- [Create Identity Control](/api-reference/preview/create-identity-control) - Set a new control +- [Delete Identity Control](/api-reference/preview/delete-identity-control) - Remove an existing control + +## Support + +> Questions? Contact [Support](https://support.paxos.com). \ No newline at end of file diff --git a/api-reference/preview/identity-requirements-overview.mdx b/api-reference/preview/identity-requirements-overview.mdx new file mode 100644 index 0000000..0230f1e --- /dev/null +++ b/api-reference/preview/identity-requirements-overview.mdx @@ -0,0 +1,24 @@ +--- +title: 'Overview' +description: Understanding identity requirements and status details. +--- + +## Overview + +🚧 **Work in Progress** - This documentation is under active development. + +The Identity Requirements API provides detailed visibility into the requirements that govern identity approval and status changes. + +## Coming Soon + +- Comprehensive guide to identity requirements +- Requirement types and their meanings +- Status progression and state transitions +- Best practices for handling requirements +- Integration patterns and workflows + +## Available Now + +Explore the Identity Dormancy Lifecycle guide to get started with identity controls and status monitoring. + +> Questions? Contact [Support](https://support.paxos.com). diff --git a/api-reference/preview/identity-requirements/get-identity.mdx b/api-reference/preview/identity-requirements/get-identity.mdx new file mode 100644 index 0000000..b477b33 --- /dev/null +++ b/api-reference/preview/identity-requirements/get-identity.mdx @@ -0,0 +1,7 @@ +--- +openapi: get /identity/identities/{id} +--- + +```bash OAuth Scope +identity:read_identity +``` diff --git a/api-reference/preview/identity-requirements/list-identities.mdx b/api-reference/preview/identity-requirements/list-identities.mdx new file mode 100644 index 0000000..dedb1a8 --- /dev/null +++ b/api-reference/preview/identity-requirements/list-identities.mdx @@ -0,0 +1,7 @@ +--- +openapi: get /identity/identities +--- + +```bash OAuth Scope +identity:read_identity +``` diff --git a/api-reference/preview/paxos-v2-preview-identity-changes.openapi.json b/api-reference/preview/paxos-v2-preview-identity-changes.openapi.json new file mode 100644 index 0000000..86d29fd --- /dev/null +++ b/api-reference/preview/paxos-v2-preview-identity-changes.openapi.json @@ -0,0 +1,1578 @@ +{ + "openapi": "3.0.0", + "info": { + "title": "Paxos Identity API", + "version": "2025-09-22" + }, + "tags": [ + { + "name": "IdentityPublic" + } + ], + "paths": { + "/identity/identities": { + "get": { + "summary": "List Identities", + "description": "This endpoint enables you to fetch a list of Identities.\nYou can use query parameters to filter the results returned by `created_at`, `updated_at`, `status` and `identity_type`\n\nNote that this endpoint supports pagination and returns a cursor token for fetching next pages.", + "operationId": "ListIdentities", + "responses": { + "200": { + "description": "A successful response.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ListIdentitiesResponse" + } + } + } + } + }, + "parameters": [ + { + "name": "status", + "description": "Status of the Identity.", + "in": "query", + "required": false, + "schema": { + "type": "string", + "enum": [ + "PENDING", + "ERROR", + "APPROVED", + "DENIED", + "DISABLED" + ] + } + }, + { + "name": "created_at.lt", + "description": "Include timestamps strictly less than lt. RFC3339 format, like `2006-01-02T15:04:05Z`.", + "in": "query", + "required": false, + "schema": { + "type": "string", + "format": "date-time" + } + }, + { + "name": "created_at.lte", + "description": "Include timestamps less than or equal to lte. RFC3339 format, like `2006-01-02T15:04:05Z`.", + "in": "query", + "required": false, + "schema": { + "type": "string", + "format": "date-time" + } + }, + { + "name": "created_at.eq", + "description": "Include timestamps exactly equal to eq. RFC3339 format, like `2006-01-02T15:04:05Z`.", + "in": "query", + "required": false, + "schema": { + "type": "string", + "format": "date-time" + } + }, + { + "name": "created_at.gte", + "description": "Include timestamps greater than or equal to lte. RFC3339 format, like `2006-01-02T15:04:05Z`.", + "in": "query", + "required": false, + "schema": { + "type": "string", + "format": "date-time" + } + }, + { + "name": "created_at.gt", + "description": "Include timestamps strictly greater than gt. RFC3339 format, like `2006-01-02T15:04:05Z`.", + "in": "query", + "required": false, + "schema": { + "type": "string", + "format": "date-time" + } + }, + { + "name": "updated_at.lt", + "description": "Include timestamps strictly less than lt. RFC3339 format, like `2006-01-02T15:04:05Z`.", + "in": "query", + "required": false, + "schema": { + "type": "string", + "format": "date-time" + } + }, + { + "name": "updated_at.lte", + "description": "Include timestamps less than or equal to lte. RFC3339 format, like `2006-01-02T15:04:05Z`.", + "in": "query", + "required": false, + "schema": { + "type": "string", + "format": "date-time" + } + }, + { + "name": "updated_at.eq", + "description": "Include timestamps exactly equal to eq. RFC3339 format, like `2006-01-02T15:04:05Z`.", + "in": "query", + "required": false, + "schema": { + "type": "string", + "format": "date-time" + } + }, + { + "name": "updated_at.gte", + "description": "Include timestamps greater than or equal to lte. RFC3339 format, like `2006-01-02T15:04:05Z`.", + "in": "query", + "required": false, + "schema": { + "type": "string", + "format": "date-time" + } + }, + { + "name": "updated_at.gt", + "description": "Include timestamps strictly greater than gt. RFC3339 format, like `2006-01-02T15:04:05Z`.", + "in": "query", + "required": false, + "schema": { + "type": "string", + "format": "date-time" + } + }, + { + "name": "limit", + "description": "Number of results to return.", + "in": "query", + "required": false, + "schema": { + "type": "integer", + "format": "int32" + } + }, + { + "name": "order", + "description": "Return items in ascending (ASC) or descending (DESC) order. Defaults to DESC.", + "in": "query", + "required": false, + "schema": { + "type": "string", + "enum": [ + "DESC", + "ASC" + ] + } + }, + { + "name": "order_by", + "description": "The specific method by which the returned results will be ordered.", + "in": "query", + "required": false, + "schema": { + "type": "string", + "enum": [ + "CREATED_AT" + ] + } + }, + { + "name": "page_cursor", + "description": "Cursor token for fetching the next page.", + "in": "query", + "required": false, + "schema": { + "type": "string" + } + }, + { + "name": "identity_type", + "description": "Optionally filter by Identity type", + "in": "query", + "required": false, + "schema": { + "type": "string", + "enum": [ + "PERSON", + "INSTITUTION" + ] + } + }, + { + "name": "control_type", + "description": "Optionally filter by identity control type", + "in": "query", + "required": false, + "schema": { + "$ref": "#/components/schemas/IdentityControlType" + } + }, + { + "name": "control_reason_code", + "description": "Optionally filter by identity control reason code", + "in": "query", + "required": false, + "schema": { + "$ref": "#/components/schemas/IdentityControlReasonCode" + } + } + ], + "tags": [ + "Identity" + ], + "security": [ + { + "OAuth2": [ + "identity:read_identity" + ] + } + ] + } + }, + "/identity/identities/{id}": { + "get": { + "summary": "Get Identity", + "description": "Get an Identity by its (identity) id. You can only see identities created by you.\n\nYou can use the query parameter `include_details` to include identity details (`person_details` or `institution_details`) in\nthe response and the query parameter `include_institution_members` to include institution members in the response.", + "operationId": "GetIdentity", + "responses": { + "200": { + "description": "A successful response.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Identity" + }, + "examples": { + "pending": { + "summary": "PENDING - Awaiting Requirements", + "value": { + "id": "f190b163-208f-4d73-8deb-4fb8b24add00", + "status": "PENDING", + "status_details": { + "pending_requirements": [ + { + "type": "SANCTIONS_SCREENING", + "message": "Pending Sanctions Screening" + }, + { + "type": "ADDITIONAL_SCREENING", + "message": "Pending PEP/Adverse Media Screening" + }, + { + "type": "APPROVED_MEMBERS", + "message": "Pending members", + "metadata": { + "f190b163-208f-4d73-8deb-000000000001": "PENDING" + } + } + ] + } + } + }, + "disabled": { + "summary": "DISABLED - Active Controls", + "value": { + "id": "f190b163-208f-4d73-8deb-4fb8b24add00", + "status": "DISABLED", + "status_details": { + "active_controls": [ + { + "id": "59b8e3c5-2b6e-4fa6-afcf-8c685598241d", + "type": "CLOSED", + "controlled_by": "CLIENT", + "reason_code": "END_USER_REQUESTED", + "reason": "some client-set reason", + "created_at": "2006-01-02T15:04:05Z" + } + ] + } + } + }, + "denied": { + "summary": "DENIED - Failed Requirements", + "value": { + "id": "f190b163-208f-4d73-8deb-4fb8b24add00", + "status": "DENIED", + "status_details": { + "failed_requirements": [ + { + "type": "RISK_RATING", + "message": "Jurisdiction not supported by Paxos" + } + ] + } + } + } + } + } + } + } + }, + "parameters": [ + { + "name": "id", + "description": "id associated with the identity", + "in": "path", + "required": true, + "schema": { + "type": "string" + } + }, + { + "name": "include_details", + "description": "query param; details are encrypted, so we do not want to include them by default", + "in": "query", + "required": false, + "schema": { + "type": "boolean" + } + }, + { + "name": "include_institution_members", + "description": "query param; to include institution members for institution identity", + "in": "query", + "required": false, + "schema": { + "type": "boolean" + } + } + ], + "tags": [ + "Identity" + ], + "security": [ + { + "OAuth2": [ + "identity:read_identity" + ] + } + ] + } + }, + "/v2/identity/identities/{identity_id}/controls": { + "get": { + "summary": "List Identity Controls", + "description": "Get the current control settings for an identity.", + "operationId": "ListIdentityControls", + "responses": { + "200": { + "description": "A successful response.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/IdentityControls" + } + } + } + }, + "400": { + "$ref": "#/components/responses/BadRequest" + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + }, + "403": { + "$ref": "#/components/responses/Forbidden" + }, + "404": { + "$ref": "#/components/responses/NotFound" + } + }, + "parameters": [ + { + "name": "identity_id", + "description": "The Identity ID", + "in": "path", + "required": true, + "schema": { + "type": "string" + } + }, + { + "name": "include_deleted", + "description": "Include deleted controls in the response.", + "in": "query", + "required": false, + "schema": { + "type": "boolean" + } + } + ], + "tags": ["Identity Controls"], + "security": [ + { + "OAuth2": ["identity:read_identity"] + } + ] + }, + "post": { + "summary": "Create Identity Control", + "description": "Create a new control setting for an identity.", + "operationId": "CreateIdentityControl", + "responses": { + "200": { + "description": "A successful response.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/IdentityControls" + } + } + } + }, + "400": { + "$ref": "#/components/responses/BadRequest" + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + }, + "403": { + "$ref": "#/components/responses/Forbidden" + }, + "404": { + "$ref": "#/components/responses/NotFound" + } + }, + "parameters": [ + { + "name": "identity_id", + "description": "The Identity ID", + "in": "path", + "required": true, + "schema": { + "type": "string" + } + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/CreateIdentityControlRequest" + } + } + }, + "required": true + }, + "tags": ["Identity Controls"], + "security": [ + { + "OAuth2": ["identity:write_identity"] + } + ] + }, + "delete": { + "summary": "Delete Identity Control", + "description": "Delete a control setting for an identity.", + "operationId": "DeleteIdentityControl", + "responses": { + "200": { + "description": "A successful response.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/IdentityControls" + } + } + } + }, + "400": { + "$ref": "#/components/responses/BadRequest" + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + }, + "403": { + "$ref": "#/components/responses/Forbidden" + }, + "404": { + "$ref": "#/components/responses/NotFound" + } + }, + "parameters": [ + { + "name": "identity_id", + "description": "The Identity ID", + "in": "path", + "required": true, + "schema": { + "type": "string" + } + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/DeleteIdentityControlRequest" + } + } + }, + "required": true + }, + "tags": ["Identity Controls"], + "security": [ + { + "OAuth2": ["identity:write_identity"] + } + ] + } + } + }, + "components": { + "schemas": { + "CustomerDueDiligenceNetWorthRange": { + "type": "string", + "enum": [ + "NET_WORTH_0_TO_100K", + "NET_WORTH_100K_TO_500K", + "NET_WORTH_500K_TO_1M", + "NET_WORTH_1M_TO_2_5M", + "NET_WORTH_2_5M_TO_5M", + "NET_WORTH_5M_TO_7_5M", + "NET_WORTH_7_5M_TO_10M", + "NET_WORTH_10M_TO_25M", + "NET_WORTH_25M_TO_50M", + "NET_WORTH_OVER_50M" + ] + }, + "CustomerDueDiligenceTransferValueRange": { + "type": "string", + "enum": [ + "TRANSFER_VALUE_0_TO_25K", + "TRANSFER_VALUE_25K_TO_50K", + "TRANSFER_VALUE_50K_TO_100K", + "TRANSFER_VALUE_100K_TO_250K", + "TRANSFER_VALUE_250K_TO_500K", + "TRANSFER_VALUE_500K_TO_750K", + "TRANSFER_VALUE_750K_TO_1M", + "TRANSFER_VALUE_1M_TO_2_5M", + "TRANSFER_VALUE_2_5M_TO_5M", + "TRANSFER_VALUE_ABOVE_5M" + ] + }, + "CustomerDueDiligenceYearlyIncomeRange": { + "type": "string", + "enum": [ + "INCOME_0_TO_50K", + "INCOME_50K_TO_100K", + "INCOME_100K_TO_250K", + "INCOME_250K_TO_500K", + "INCOME_500K_TO_750K", + "INCOME_750K_TO_1M", + "INCOME_ABOVE_1M" + ] + }, + "MerchantFundingSourceFundingSource": { + "type": "string", + "enum": [ + "BUSINESS_LOANS_FINANCING", + "SALARY_SAVINGS", + "INVESTMENT_GAINS", + "INHERITANCE", + "REAL_ESTATE_INCOME", + "NON_PROFIT_SOURCES", + "OTHER_BUSINESS_INCOME" + ] + }, + "PassthroughVerificationField": { + "type": "string", + "enum": [ + "FULL_LEGAL_NAME", + "ADDRESS", + "DATE_OF_BIRTH", + "CIP_ID" + ] + }, + "PersonDetailsCIPIDType": { + "type": "string", + "enum": [ + "SSN", + "ID_CARD", + "ITIN", + "PASSPORT", + "DRIVING_LICENSE", + "VISA" + ], + "title": "" + }, + "identityprotoVerifierType": { + "type": "string", + "enum": [ + "JUMIO", + "PAXOS", + "PASSTHROUGH", + "MANUAL" + ] + }, + "AccountPurpose": { + "type": "string", + "enum": [ + "INVESTMENT_TRADING", + "SAVINGS", + "STABLECOIN_PURCHASE_REDEMPTION" + ] + }, + "CustomerDueDiligence": { + "type": "object", + "properties": { + "aliases": { + "type": "array", + "items": { + "type": "string" + }, + "description": "A list of alternate names or aliases associated with the Identity." + }, + "estimated_net_worth": { + "$ref": "#/components/schemas/CustomerDueDiligenceNetWorthRange" + }, + "estimated_yearly_income": { + "$ref": "#/components/schemas/CustomerDueDiligenceYearlyIncomeRange" + }, + "expected_transfer_value": { + "$ref": "#/components/schemas/CustomerDueDiligenceTransferValueRange" + }, + "source_of_wealth": { + "$ref": "#/components/schemas/WealthSource" + }, + "source_of_funds": { + "$ref": "#/components/schemas/FundsSource" + }, + "purpose_of_account": { + "$ref": "#/components/schemas/AccountPurpose" + }, + "employment_status": { + "$ref": "#/components/schemas/EmploymentStatus" + }, + "employment_industry_sector": { + "$ref": "#/components/schemas/InstitutionSubType" + }, + "industry_sector": { + "$ref": "#/components/schemas/InstitutionSubType" + }, + "has_underlying_trust_structure": { + "type": "boolean", + "description": "Whether or not the institution tied to the Identity has an underlying trust structure." + }, + "has_nominee_shareholders": { + "type": "boolean", + "description": "Whether or not the institution tied to the Identity has nominee shareholders." + }, + "created_at": { + "type": "string", + "format": "date-time", + "title": "When the customer due diligence was created" + }, + "is_publicly_traded": { + "type": "boolean", + "description": "`true` or `false` indicating whether or not the company is listed on a public stock exchange." + }, + "merchant_funding_source": { + "$ref": "#/components/schemas/MerchantFundingSourceFundingSource" + }, + "customer_regions": { + "type": "array", + "items": { + "$ref": "#/components/schemas/CustomerRegion" + }, + "description": "Regions where the customer base is located." + } + } + }, + "CustomerRegion": { + "type": "string", + "enum": [ + "US_CANADA", + "MEXICO_CENTRAL_AMERICA", + "SOUTH_AMERICA", + "EUROPE", + "ASIA", + "AFRICA", + "OCEANIA" + ] + }, + "EmploymentStatus": { + "type": "string", + "enum": [ + "CONTRACTUAL", + "FULL_TIME", + "PART_TIME", + "RETIRED", + "SELF_EMPLOYED", + "STUDENT", + "UNEMPLOYED" + ] + }, + "FundsSource": { + "type": "string", + "enum": [ + "SALARY_DISBURSEMENT", + "INHERITANCE_DISTRIBUTION", + "INVESTMENT_RETURNS", + "BUSINESS_DIVIDENDS_PROFITS", + "PROPERTY_SALE", + "LOAN_DISBURSEMENT", + "SAVINGS_ACCOUNT_WITHDRAWAL", + "GOVERNMENT_BENEFITS" + ] + }, + "Identity": { + "type": "object", + "properties": { + "id": { + "type": "string", + "title": "The id used for all other interactions with this account" + }, + "status": { + "$ref": "#/components/schemas/IdentityStatus" + }, + "status_details": { + "$ref": "#/components/schemas/IdentityStatusDetails" + }, + "type": { + "$ref": "#/components/schemas/IdentityType" + }, + "ref_id": { + "type": "string", + "description": "A user-facing ID to prevent duplicate account creation. Unique for all accounts created by the same API user." + }, + "metadata": { + "type": "object", + "additionalProperties": { + "type": "string" + }, + "title": "API User-facing metadata" + }, + "user_disabled": { + "type": "boolean", + "title": "true if the account has been disabled by the API user" + }, + "admin_disabled": { + "type": "boolean", + "title": "true if the account has been disabled by a Paxos admin" + }, + "person_details": { + "$ref": "#/components/schemas/PersonDetails" + }, + "institution_details": { + "$ref": "#/components/schemas/InstitutionDetails" + }, + "institution_members": { + "type": "array", + "items": { + "$ref": "#/components/schemas/InstitutionMember" + }, + "title": "members associated with institution identity type" + }, + "created_at": { + "type": "string", + "format": "date-time", + "description": "The time at which the identity is created at. RFC3339 format, like `YYYY-MM-DDTHH:MM:SS.sssZ`. ex: `2006-01-02T15:04:05Z`." + }, + "updated_at": { + "type": "string", + "format": "date-time", + "description": "The time at which the identity is updated at. RFC3339 format, like `YYYY-MM-DDTHH:MM:SS.sssZ`. ex: `2006-01-02T15:04:05Z`." + }, + "tax_details": { + "type": "array", + "items": { + "$ref": "#/components/schemas/TaxDetail" + }, + "title": "tax payer details" + }, + "tax_details_not_required": { + "type": "boolean", + "title": "whether or not tax_details are legally required" + }, + "summary_tin_verification_status": { + "$ref": "#/components/schemas/TINVerificationStatus" + }, + "customer_due_diligence": { + "$ref": "#/components/schemas/CustomerDueDiligence" + }, + "is_merchant": { + "type": "boolean", + "description": "True if the identity is a merchant." + }, + "last_kyc_refresh_date": { + "type": "string", + "format": "date-time", + "description": "The last timestamp the identity has undergone a periodic kyc refresh. RFC3339 format, like `YYYY-MM-DDTHH:MM:SS.sssZ`. ex: `2006-01-02T15:04:05Z`." + } + }, + "required": [ + "id" + ] + }, + "IdentityMailingAddress": { + "type": "object", + "properties": { + "country": { + "type": "string", + "maxLength": 35, + "pattern": "^[0-9A-Za-z /?:().,&'+-]+$" + }, + "address1": { + "type": "string", + "maxLength": 35, + "pattern": "^[0-9A-Za-z /?:().,&'+-]+$" + }, + "address2": { + "type": "string", + "description": "To clear address2 (i.e. when updating an identity), set address2 to an empty string (\"\").", + "maxLength": 35, + "pattern": "^[0-9A-Za-z /?:().,&'+-]+$" + }, + "city": { + "type": "string", + "maxLength": 35, + "pattern": "^[0-9A-Za-z /?:().,&'+-]+$" + }, + "province": { + "type": "string", + "maxLength": 35, + "pattern": "^[0-9A-Za-z /?:().,&'+-]+$" + }, + "zip_code": { + "type": "string", + "maxLength": 35, + "pattern": "^[0-9A-Za-z /?:().,&'+-]+$" + } + }, + "description": "A mailing address.", + "required": [ + "country", + "address1", + "city", + "province" + ] + }, + "IdentityStatus": { + "type": "string", + "enum": [ + "PENDING", + "ERROR", + "APPROVED", + "DENIED", + "DISABLED" + ], + "title": "" + }, + "IdentityType": { + "type": "string", + "enum": [ + "PERSON", + "INSTITUTION" + ] + }, + "InstitutionCIPIDType": { + "type": "string", + "enum": [ + "EIN", + "SSN", + "ITIN", + "REGISTRATION_NUMBER" + ], + "title": "" + }, + "InstitutionDetails": { + "type": "object", + "properties": { + "sanctions_verification_status": { + "$ref": "#/components/schemas/IdentityStatus" + }, + "name": { + "type": "string", + "title": "Allowed in create and update", + "maxLength": 200, + "pattern": "^[0-9A-Za-z /?:().,&'+-]+$" + }, + "business_address": { + "$ref": "#/components/schemas/IdentityMailingAddress" + }, + "phone_number": { + "type": "string", + "title": "Allowed in create and update" + }, + "email": { + "type": "string", + "title": "Allowed in create and update" + }, + "institution_type": { + "$ref": "#/components/schemas/InstitutionType" + }, + "institution_sub_type": { + "$ref": "#/components/schemas/InstitutionSubType" + }, + "cip_id": { + "type": "string", + "title": "Allowed in create and update\nSSN format: xxx-xx-xxxx\nITIN format: xxx-xx-xxxx\nEIN format: xx-xxxxxxx", + "maxLength": 200, + "pattern": "^[0-9A-Za-z /?:().,&'+-]+$" + }, + "cip_id_type": { + "$ref": "#/components/schemas/InstitutionCIPIDType" + }, + "cip_id_country": { + "type": "string", + "description": "Allowed in create and update. Must be an ISO 3166-1 alpha 3 code." + }, + "govt_registration_date": { + "type": "string", + "format": "date-time", + "title": "date at which the institution is registered with govt" + }, + "incorporation_address": { + "$ref": "#/components/schemas/IdentityMailingAddress" + }, + "regulation_status": { + "$ref": "#/components/schemas/RegulationStatus" + }, + "trading_type": { + "$ref": "#/components/schemas/TradingType" + }, + "listed_exchange": { + "type": "string", + "title": "exchange in which the institution is listed" + }, + "ticker_symbol": { + "type": "string", + "description": "Ticker symbol of the institution if publicly traded or ticker symbol of the parent institution." + }, + "parent_institution_name": { + "type": "string", + "title": "name of the parent institution if the institution is a subsidiary of parent institution" + }, + "regulator_name": { + "type": "string", + "title": "name of the financial regulator" + }, + "regulator_jurisdiction": { + "type": "string", + "title": "country or jurisdiction of financial regulator" + }, + "regulator_register_number": { + "type": "string", + "title": "registrar number of regulator" + }, + "document_verification_status": { + "$ref": "#/components/schemas/IdentityStatus" + }, + "additional_screening_status": { + "$ref": "#/components/schemas/IdentityStatus" + }, + "doing_business_as": { + "type": "string", + "title": "Allowed in create and update" + }, + "business_description": { + "type": "string", + "title": "free text description of business" + } + } + }, + "InstitutionMember": { + "type": "object", + "properties": { + "identity_id": { + "type": "string", + "title": "The ID of the member identity" + }, + "roles": { + "type": "array", + "items": { + "$ref": "#/components/schemas/InstitutionRoleType" + }, + "title": "The type of membership this identity has in the institution" + }, + "ownership": { + "type": "string", + "description": "Decimal number representing the percent ownership the identity has in the company-- e.g. 5 represents 5% ownership." + }, + "position": { + "type": "string", + "title": "The position the identity holds with the company" + }, + "name": { + "type": "string", + "title": "Member's full name. Not writable from API" + }, + "status": { + "$ref": "#/components/schemas/IdentityStatus" + }, + "id": { + "type": "string", + "description": "Institution member ID. Note: This field is auto-generated. Specifying an ID when creating an institution member is a client error." + } + } + }, + "InstitutionRoleType": { + "type": "string", + "enum": [ + "BENEFICIAL_OWNER", + "ACCOUNT_OPENER", + "TRUSTEE", + "AUTHORIZED_USER", + "GRANTOR", + "MANAGEMENT_CONTROL_PERSON", + "BENEFICIARY" + ], + "title": "" + }, + "InstitutionSubType": { + "type": "string", + "enum": [ + "INVESTMENT", + "HEDGE_FUND", + "MONEY_SERVICE_BUSINESS", + "STO_ISSUER", + "PRECIOUS_METALS", + "NON_PROFIT", + "REGISTERED_INVESTMENT_ADVISOR", + "AGRICULTURE_FORESTRY_FISHING_HUNTING", + "MINING", + "UTILITIES", + "CONSTRUCTION", + "MANUFACTURING", + "WHOLESALE_TRADE", + "RETAIL_TRADE", + "TRANSPORTATION_WAREHOUSING", + "INFORMATION", + "FINANCE_INSURANCE", + "REAL_ESTATE_RENTAL_LEASING", + "PROFESSIONAL_SCIENTIFIC_TECHNICAL_SERVICES", + "MANAGEMENT_OF_COMPANIES_ENTERPRISES", + "ADMINISTRATIVE_SUPPORT_WASTE_MANAGEMENT_REMEDIATION_SERVICES", + "EDUCATIONAL_SERVICES", + "HEALTH_CARE_SOCIAL_ASSISTANCE", + "ARTS_ENTERTAINMENT_RECREATION", + "ACCOMMODATION_FOOD_SERVICES", + "OTHER_SERVICES", + "PUBLIC_ADMINISTRATION", + "NOT_CLASSIFIED", + "ADULT_ENTERTAINMENT", + "AUCTIONS", + "AUTOMOBILES", + "BLOCKCHAIN", + "CRYPTO", + "DRUGS", + "EXPORT_IMPORT", + "E_COMMERCE", + "FINANCIAL_INSTITUTION", + "GAMBLING", + "INSURANCE", + "MARKET_MAKER", + "SHELL_BANK", + "TRAVEL_TRANSPORT", + "WEAPONS" + ], + "title": "" + }, + "InstitutionType": { + "type": "string", + "enum": [ + "TRUST", + "CORPORATION", + "LLC", + "PARTNERSHIP" + ], + "title": "" + }, + "ListIdentitiesResponse": { + "type": "object", + "properties": { + "next_page_cursor": { + "type": "string", + "description": "Cursor token required for fetching the next page." + }, + "items": { + "type": "array", + "items": { + "$ref": "#/components/schemas/Identity" + }, + "description": "The result list of identities." + } + } + }, + "PassthroughVerifierType": { + "type": "string", + "enum": [ + "JUMIO", + "ALLOY", + "LEXISNEXIS", + "MITEK", + "SUMSUB", + "MICROBILT", + "ONFIDO", + "CUSTOMER", + "EQUIFAX", + "ID3_AUTHENTICATE", + "FIS", + "PROVE", + "PERSONA", + "PLAID" + ] + }, + "PersonDetails": { + "type": "object", + "properties": { + "id_verification_status": { + "$ref": "#/components/schemas/IdentityStatus" + }, + "sanctions_verification_status": { + "$ref": "#/components/schemas/IdentityStatus" + }, + "first_name": { + "type": "string", + "title": "Allowed in create and update", + "maxLength": 200, + "pattern": "^[0-9A-Za-z /?:().,&'+-]+$" + }, + "last_name": { + "type": "string", + "title": "Allowed in create and update", + "maxLength": 200, + "pattern": "^[0-9A-Za-z /?:().,&'+-]+$" + }, + "date_of_birth": { + "type": "string", + "title": "Allowed in create and update", + "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}$" + }, + "govt_id": { + "type": "string", + "title": "DEPRECATED: use cip_id instead", + "maxLength": 200, + "pattern": "^[0-9A-Za-z /?:().,&'+-]+$" + }, + "address": { + "$ref": "#/components/schemas/IdentityMailingAddress" + }, + "phone_number": { + "type": "string", + "title": "Allowed in create and update" + }, + "email": { + "type": "string", + "title": "Allowed in create and update" + }, + "nationality": { + "type": "string", + "description": "Allowed in create and update. Must be an ISO 3166-1 alpha 3 code.", + "pattern": "^[A-Z]{3}$" + }, + "verifier_id": { + "type": "string", + "title": "Allowed in create and update. The id used by the external verifier. For Jumio, this is the \"transaction reference\"" + }, + "verifier_type": { + "$ref": "#/components/schemas/identityprotoVerifierType" + }, + "id_verification_url": { + "type": "string", + "title": "When PAXOS verifier is used, the iframe url returned for ID verification" + }, + "passthrough_verifier_type": { + "$ref": "#/components/schemas/PassthroughVerifierType" + }, + "passthrough_verified_at": { + "type": "string", + "format": "date-time", + "title": "When PASSTHROUGH verifier is used, this specifies the time that ID verification was completed" + }, + "govt_id_type": { + "$ref": "#/components/schemas/PersonDetailsCIPIDType" + }, + "cip_id": { + "type": "string", + "title": "SSN or TIN, unique for each Identity object. Allowed in create and update\nSSN format: xxx-xx-xxxx\nITIN format: xxx-xx-xxxx\nEIN format: xx-xxxxxxx", + "maxLength": 200, + "pattern": "^[0-9A-Za-z /?:().,&'+-]+$" + }, + "cip_id_type": { + "$ref": "#/components/schemas/PersonDetailsCIPIDType" + }, + "cip_id_country": { + "type": "string", + "description": "Allowed in create and update. Must be an ISO 3166-1 alpha 3 code." + }, + "additional_screening_status": { + "$ref": "#/components/schemas/IdentityStatus" + }, + "profession": { + "type": "string", + "description": "Allowed in create and update." + }, + "middle_name": { + "type": "string", + "title": "Allowed in create and update", + "maxLength": 200 + }, + "country_of_birth": { + "type": "string", + "description": "Allowed in create and update." + }, + "passthrough_verification_id": { + "type": "string", + "description": "Unique identifier for the underlying person's ID verification record." + }, + "passthrough_verification_status": { + "$ref": "#/components/schemas/IdentityStatus" + }, + "passthrough_verification_fields": { + "type": "array", + "items": { + "$ref": "#/components/schemas/PassthroughVerificationField" + }, + "description": "List of verification fields used by the external verifier to validate the person's identity." + } + } + }, + "RegulationStatus": { + "type": "string", + "enum": [ + "US_REGULATED", + "INTL_REGULATED", + "NON_REGULATED" + ] + }, + "TINVerificationStatus": { + "type": "string", + "enum": [ + "TIN_VERIFICATION_PENDING", + "TIN_VERIFICATION_ERROR", + "TIN_VERIFICATION_VALID" + ], + "description": "The TIN verification status for the associated `tax_payer_id`." + }, + "TaxDetail": { + "type": "object", + "properties": { + "tax_payer_id": { + "type": "string", + "title": "For U.S. citizens it is the SSN, TIN or EIN. For Brazil citizens, it is the CPF. Allowed in create and update", + "maxLength": 35, + "pattern": "^[0-9A-Za-z /?:().,&'+-]+$" + }, + "tax_payer_country": { + "type": "string", + "title": "Allowed in create and update. Must be an ISO 3166-1 alpha 3 code" + }, + "tin_verification_status": { + "$ref": "#/components/schemas/TINVerificationStatus" + } + } + }, + "TradingType": { + "type": "string", + "enum": [ + "PRIVATE", + "PUBLIC", + "PUBLICLY_TRADED_SUBSIDIARY" + ] + }, + "WealthSource": { + "type": "string", + "enum": [ + "INHERITANCE", + "INVESTMENT_GAINS", + "BUSINESS_OWNERSHIP_DIVIDENDS", + "EMPLOYMENT_INCOME", + "REAL_ESTATE", + "OTHER_SOURCE_OF_WEALTH" + ] + }, + "IdentityControlType": { + "type": "string", + "enum": [ + "CLOSED", + "FROZEN", + "DORMANT" + ] + }, + "IdentityControlController": { + "type": "string", + "enum": [ + "PAXOS", + "CLIENT" + ] + }, + "ClientIdentityControlType": { + "type": "string", + "enum": [ + "CLOSED", + "DORMANT" + ] + }, + "IdentityControlReasonCode": { + "type": "string", + "enum": [ + "OTHER", + "DORMANT", + "END_USER_REQUESTED", + "SANCTIONS" + ] + }, + "IdentityControl": { + "type": "object", + "properties": { + "id": { + "type": "string" + }, + "type": { + "$ref": "#/components/schemas/IdentityControlType" + }, + "controlled_by": { + "$ref": "#/components/schemas/IdentityControlController" + }, + "reason_code": { + "$ref": "#/components/schemas/IdentityControlReasonCode" + }, + "reason": { + "type": "string", + "description": "Reason why this identity control was set" + }, + "created_at": { + "type": "string", + "format": "date-time", + "description": "Time this identity control was created" + } + } + }, + "IdentityControls": { + "type": "array", + "items": { + "$ref": "#/components/schemas/IdentityControl" + }, + "example": [ + { + "id": "59b8e3c5-2b6e-4fa6-afcf-8c685598241d", + "type": "CLOSED", + "controlled_by": "CLIENT", + "reason_code": "END_USER_REQUESTED", + "reason": "some client-set reason", + "created_at": "2006-01-02T15:04:05Z" + }, + { + "id": "5f1eb60c-b292-482c-96fe-9e3e265abcd4", + "type": "CLOSED", + "controlled_by": "PAXOS", + "reason_code": "OTHER", + "reason": "some admin-set reason", + "created_at": "2006-01-02T15:04:05Z" + }, + { + "id": "173fdece-0792-4833-a6bb-232b461a9fa4", + "type": "FROZEN", + "controlled_by": "PAXOS", + "reason_code": "SANCTIONS", + "reason": "some admin-set reason", + "created_at": "2006-01-02T15:04:05Z" + }, + { + "id": "ae54b3b4-cce6-4707-b34b-c9c4f0537798", + "type": "DORMANT", + "controlled_by": "CLIENT", + "reason_code": "DORMANT", + "reason": "some reason", + "created_at": "2006-01-02T15:04:05Z" + } + ] + }, + "CreateIdentityControlRequest": { + "type": "object", + "properties": { + "type": { + "$ref": "#/components/schemas/ClientIdentityControlType" + }, + "reason_code": { + "$ref": "#/components/schemas/IdentityControlReasonCode" + }, + "reason": { + "type": "string", + "description": "Freetext reason for setting or clearing the control" + } + }, + "required": ["type", "reason_code"] + }, + "DeleteIdentityControlRequest": { + "type": "object", + "properties": { + "id": { + "type": "string" + }, + "reason": { + "type": "string", + "description": "Freetext reason for setting or clearing the control" + } + }, + "required": ["id"] + }, + "IdentityRequirementType": { + "type": "string", + "enum": [ + "ID_VERIFICATION", + "SANCTIONS_SCREENING", + "ADDITIONAL_SCREENING", + "ENHANCED_DUE_DILIGENCE", + "RISK_AWARENESS_ASSESSMENT", + "MEMBERS", + "KYC_REFRESH", + "RISK_RATING" + ] + }, + "IdentityRequirement": { + "type": "object", + "properties": { + "type": { + "$ref": "#/components/schemas/IdentityRequirementType" + }, + "message": { + "type": "string" + }, + "metadata": { + "type": "object", + "additionalProperties": { + "type": "string" + } + } + } + }, + "IdentityStatusDetails": { + "type": "object", + "properties": { + "active_controls": { + "$ref": "#/components/schemas/IdentityControls" + }, + "pending_requirements": { + "type": "array", + "items": { + "$ref": "#/components/schemas/IdentityRequirement" + } + }, + "failed_requirements": { + "type": "array", + "items": { + "$ref": "#/components/schemas/IdentityRequirement" + } + } + } + } + }, + "responses": { + "BadRequest": { + "description": "Bad Request", + "content": { + "application/problem+json": { + "schema": { + "$ref": "#/components/examples/Problem_bad_request" + } + } + } + }, + "Unauthorized": { + "description": "Unauthorized", + "content": { + "application/problem+json": { + "schema": { + "$ref": "#/components/examples/Problem_unauthorized" + } + } + } + }, + "Forbidden": { + "description": "Forbidden", + "content": { + "application/problem+json": { + "schema": { + "$ref": "#/components/examples/Problem_forbidden" + } + } + } + }, + "NotFound": { + "description": "Not Found", + "content": { + "application/problem+json": { + "schema": { + "$ref": "#/components/examples/Problem_not_found" + } + } + } + }, + "TooManyRequests": { + "description": "Too Many Requests", + "content": { + "application/problem+json": { + "schema": { + "$ref": "#/components/examples/Problem_too_many_requests" + } + } + } + }, + "InternalServerError": { + "description": "Internal Server Error", + "content": { + "application/problem+json": { + "schema": { + "$ref": "#/components/examples/Problem_internal_server_error" + } + } + } + } + }, + "examples": { + "Problem_bad_request": { + "value": { + "type": "about:blank", + "title": "Bad Request", + "status": 400, + "detail": "Invalid request format or missing required fields" + } + }, + "Problem_unauthorized": { + "value": { + "type": "about:blank", + "title": "Unauthorized", + "status": 401, + "detail": "no authorization header set" + } + }, + "Problem_forbidden": { + "value": { + "type": "about:blank", + "title": "Forbidden", + "status": 403, + "detail": "user account is disabled" + } + }, + "Problem_not_found": { + "value": { + "type": "about:blank", + "title": "Not Found", + "status": 404, + "detail": "identity not found" + } + }, + "Problem_too_many_requests": { + "value": { + "type": "about:blank", + "title": "Too Many Requests", + "status": 429, + "detail": "Too many requests" + } + }, + "Problem_internal_server_error": { + "value": { + "type": "about:blank", + "title": "Internal Server Error", + "status": 500 + } + } + } + } + } \ No newline at end of file diff --git a/docs.json b/docs.json index b1bdcb3..6eacf60 100644 --- a/docs.json +++ b/docs.json @@ -880,6 +880,15 @@ "api-reference/preview/identity-controls/create-identity-control", "api-reference/preview/identity-controls/delete-identity-control" ] + }, + { + "group": "Identity Requirements Preview", + "pages": [ + "api-reference/preview/identity-requirements-overview", + "api-reference/preview/identity-dormancy-lifecycle", + "api-reference/preview/identity-requirements/list-identities", + "api-reference/preview/identity-requirements/get-identity" + ] } ] },