From 29d096edcee00138b4fecb549b368b1fc87674d1 Mon Sep 17 00:00:00 2001 From: Lawrence Date: Wed, 10 Sep 2025 02:05:23 -0400 Subject: [PATCH 01/13] RP-4333 identity control preview --- api-reference/preview/rp-4333.openapi.json | 1241 ++++++++++++++++++++ docs.json | 8 +- 2 files changed, 1248 insertions(+), 1 deletion(-) create mode 100644 api-reference/preview/rp-4333.openapi.json diff --git a/api-reference/preview/rp-4333.openapi.json b/api-reference/preview/rp-4333.openapi.json new file mode 100644 index 0000000..8435f0d --- /dev/null +++ b/api-reference/preview/rp-4333.openapi.json @@ -0,0 +1,1241 @@ +{ + "openapi": "3.0.0", + "info": { + "title": "Paxos Identity API", + "version": "identity control preview" + }, + "tags": [ + { + "name": "IdentityPublic" + } + ], + "paths": { + "/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" + } + } + } + } + }, + "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": "Get Identity Controls", + "description": "Get the current control settings for an identity.", + "operationId": "GetIdentityControls", + "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" + } + } + ], + "tags": ["Identity Controls"], + "security": [ + { + "OAuth2": ["identity:read_identity"] + } + ] + }, + "put": { + "summary": "Update Identity Controls", + "description": "Update control settings for an identity including frozen, dormant, and closed states.", + "operationId": "UpdateIdentityControls", + "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/UpdateIdentityControlsRequest" + } + } + }, + "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", + "example": { + "id": "f190b163-208f-4d73-8deb-4fb8b24add00", + "status": "DISABLED", + "status_details": { + "active_controls": [ + { + "control": "CLIENT_DISABLED", + "reason": "some client-set reason" + }, + { + "control": "ADMIN_DISABLED", + "reason": "some admin-set reason" + }, + { + "control": "ADMIN_FROZEN", + "reason": "some admin-set reason" + }, + { + "control": "DORMANT", + "reason": "some reason" + } + ], + "pending_requirements": [ + { + "requirement": "PENDING_ID_VERIFICATION", + "message": "ID Verification" + }, + { + "requirement": "PENDING_SANCTIONS_SCREENING", + "message": "Sanctions Screening" + }, + { + "requirement": "PENDING_ADDITIONAL_SCREENING", + "message": "PEP/Adverse Media Screening" + }, + { + "requirement": "PENDING_MEMBERS", + "message": "Pending members", + "metadata": { + "f190b163-208f-4d73-8deb-000000000001": "PENDING" + } + } + ], + "failed_requirements": [ + { + "requirement": "FAILED_ENHANCED_DUE_DILIGENCE", + "message": "Enhanced Due Diligence" + }, + { + "requirement": "FAILED_RISK_AWARENESS_ASSESSMENT", + "message": "Risk Awareness Assessment" + }, + { + "requirement": "DISABLED_MEMBERS", + "message": "Disabled members", + "metadata": { + "f190b163-208f-4d73-8deb-000000000002": "DISABLED" + } + }, + { + "requirement": "RISK_RATING", + "message": "Jurisdiction not supported by Paxos" + } + ] + } + }, + "properties": { + "id": { + "type": "string", + "title": "The id used for all other interactions with this account" + }, + "metadata": { + "type": "object", + "additionalProperties": { + "type": "string" + }, + "title": "API User-facing metadata" + }, + "summary_status": { + "$ref": "#/components/schemas/IdentityStatus" + }, + "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" + }, + "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." + }, + "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`." + }, + "status": { + "$ref": "#/components/schemas/IdentityStatus" + }, + "status_details": { + "$ref": "#/components/schemas/IdentityStatusDetails" + } + }, + "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" + }, + "summary_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": "" + }, + "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": [ + "CLIENT_DISABLED", + "ADMIN_DISABLED", + "ADMIN_FROZEN", + "DORMANT" + ] + }, + "ClientIdentityControlType": { + "type": "string", + "enum": [ + "CLIENT_DISABLED", + "DORMANT" + ] + }, + "IdentityControlAction": { + "type": "string", + "enum": [ + "SET", + "CLEAR" + ] + }, + "IdentityControl": { + "type": "object", + "properties": { + "control": { + "$ref": "#/components/schemas/IdentityControlType" + }, + "reason": { + "type": "string", + "description": "Reason why this identity control was set" + } + } + }, + "IdentityControls": { + "type": "array", + "items": { + "$ref": "#/components/schemas/IdentityControl" + } + }, + "UpdateIdentityControlsRequest": { + "type": "object", + "properties": { + "control": { + "$ref": "#/components/schemas/ClientIdentityControlType" + }, + "action": { + "$ref": "#/components/schemas/IdentityControlAction" + }, + "reason": { + "type": "string", + "description": "Freetext reason for setting or clearing the control" + } + }, + "required": ["control", "action"] + }, + "IdentityPendingRequirementType": { + "type": "string", + "enum": [ + "PENDING_ID_VERIFICATION", + "PENDING_SANCTIONS_SCREENING", + "PENDING_ADDITIONAL_SCREENING", + "PENDING_ENHANCED_DUE_DILIGENCE", + "PENDING_RISK_AWARENESS_ASSESSMENT", + "PENDING_MEMBERS" + ] + }, + "IdentityFailedRequirementType": { + "type": "string", + "enum": [ + "FAILED_ID_VERIFICATION", + "FAILED_SANCTIONS_SCREENING", + "FAILED_ADDITIONAL_SCREENING", + "FAILED_ENHANCED_DUE_DILIGENCE", + "FAILED_RISK_AWARENESS_ASSESSMENT", + "DISABLED_MEMBERS", + "EXPIRED_KYC_REFRESH", + "RISK_RATING" + ] + }, + "IdentityPendingRequirement": { + "type": "object", + "properties": { + "requirement": { + "$ref": "#/components/schemas/IdentityPendingRequirementType" + }, + "message": { + "type": "string" + }, + "metadata": { + "type": "object", + "additionalProperties": { + "type": "string" + } + } + } + }, + "IdentityFailedRequirement": { + "type": "object", + "properties": { + "requirement": { + "$ref": "#/components/schemas/IdentityFailedRequirementType" + }, + "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/IdentityPendingRequirement" + } + }, + "failed_requirements": { + "type": "array", + "items": { + "$ref": "#/components/schemas/IdentityFailedRequirement" + } + } + } + } + }, + "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 + } + } + } + } +} diff --git a/docs.json b/docs.json index 808d619..834e4e6 100644 --- a/docs.json +++ b/docs.json @@ -834,7 +834,6 @@ }, { "tab": "Previews", - "hidden": true, "groups": [ { "group": "Previews", @@ -848,6 +847,13 @@ "source": "api-reference/preview/paxos-v2-preview-orchestration.openapi.json", "directory": "api-reference/preview" } + }, + { + "group": "RP-4333 Identity Previews", + "openapi": { + "source": "api-reference/preview/rp-4333.openapi.json", + "directory": "api-reference/preview" + } } ] }, From 3a7a50e6b3050ed5942e241bf521088383978549 Mon Sep 17 00:00:00 2001 From: Lawrence Date: Wed, 10 Sep 2025 02:08:32 -0400 Subject: [PATCH 02/13] preview --- docs.json | 13 ------------- 1 file changed, 13 deletions(-) diff --git a/docs.json b/docs.json index 834e4e6..b977026 100644 --- a/docs.json +++ b/docs.json @@ -835,19 +835,6 @@ { "tab": "Previews", "groups": [ - { - "group": "Previews", - "pages": [ - "api-reference/preview/overview" - ] - }, - { - "group": "Orchestration Previews", - "openapi": { - "source": "api-reference/preview/paxos-v2-preview-orchestration.openapi.json", - "directory": "api-reference/preview" - } - }, { "group": "RP-4333 Identity Previews", "openapi": { From 5f6b2e20d4453d4a360282142bcab07c4bba714d Mon Sep 17 00:00:00 2001 From: Lawrence Date: Wed, 10 Sep 2025 02:16:14 -0400 Subject: [PATCH 03/13] example --- api-reference/preview/rp-4333.openapi.json | 20 +++++++++++++++++++- 1 file changed, 19 insertions(+), 1 deletion(-) diff --git a/api-reference/preview/rp-4333.openapi.json b/api-reference/preview/rp-4333.openapi.json index 8435f0d..ebb2631 100644 --- a/api-reference/preview/rp-4333.openapi.json +++ b/api-reference/preview/rp-4333.openapi.json @@ -1029,7 +1029,25 @@ "type": "array", "items": { "$ref": "#/components/schemas/IdentityControl" - } + }, + "example": [ + { + "control": "CLIENT_DISABLED", + "reason": "some client-set reason" + }, + { + "control": "ADMIN_DISABLED", + "reason": "some admin-set reason" + }, + { + "control": "ADMIN_FROZEN", + "reason": "some admin-set reason" + }, + { + "control": "DORMANT", + "reason": "some reason" + } + ] }, "UpdateIdentityControlsRequest": { "type": "object", From 1952f0bbbaf19b4e018b74a06c84bba10cb0d799 Mon Sep 17 00:00:00 2001 From: Lawrence Date: Thu, 11 Sep 2025 08:12:18 -0400 Subject: [PATCH 04/13] variations --- ...3.openapi.json => 2025-09-09.openapi.json} | 2 +- .../preview/2025-09-10-cameron.openapi.json | 1349 ++++++++++++++++ .../preview/2025-09-11-a.openapi.json | 1341 ++++++++++++++++ .../preview/2025-09-11-b.openapi.json | 1358 +++++++++++++++++ docs.json | 27 +- 5 files changed, 4073 insertions(+), 4 deletions(-) rename api-reference/preview/{rp-4333.openapi.json => 2025-09-09.openapi.json} (99%) create mode 100644 api-reference/preview/2025-09-10-cameron.openapi.json create mode 100644 api-reference/preview/2025-09-11-a.openapi.json create mode 100644 api-reference/preview/2025-09-11-b.openapi.json diff --git a/api-reference/preview/rp-4333.openapi.json b/api-reference/preview/2025-09-09.openapi.json similarity index 99% rename from api-reference/preview/rp-4333.openapi.json rename to api-reference/preview/2025-09-09.openapi.json index ebb2631..d85af76 100644 --- a/api-reference/preview/rp-4333.openapi.json +++ b/api-reference/preview/2025-09-09.openapi.json @@ -2,7 +2,7 @@ "openapi": "3.0.0", "info": { "title": "Paxos Identity API", - "version": "identity control preview" + "version": "2025-09-09" }, "tags": [ { diff --git a/api-reference/preview/2025-09-10-cameron.openapi.json b/api-reference/preview/2025-09-10-cameron.openapi.json new file mode 100644 index 0000000..a073598 --- /dev/null +++ b/api-reference/preview/2025-09-10-cameron.openapi.json @@ -0,0 +1,1349 @@ +{ + "openapi": "3.0.0", + "info": { + "title": "Paxos Identity API", + "version": "https://github.com/paxosglobal/docs-mintlify/pull/86" + }, + "tags": [ + { + "name": "IdentityPublic" + } + ], + "paths": { + "/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" + } + } + } + } + }, + "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": "List 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" + } + } + ], + "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/IdentityControl" + }, + "example": { + "control": "FROZEN", + "set_by": "client", + "reason_code": "CUSTOMER_REQUESTED", + "reason": "Customer requested temporary account freeze" + } + } + } + }, + "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/unset a specific control on 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", + "example": { + "id": "f190b163-208f-4d73-8deb-4fb8b24add00", + "status": "DISABLED", + "status_details": { + "active_controls": [ + { + "control": "FROZEN", + "set_by": "client", + "reason_code": "CUSTOMER_REQUESTED", + "reason": "Pending customer verification" + }, + { + "control": "FROZEN", + "set_by": "paxos", + "reason_code": "SANCTIONS_PEP_OR_NN", + "reason": "Potential PEP match requires review" + }, + { + "control": "CLOSED", + "set_by": "client", + "reason_code": "DORMANT", + "reason": "Account inactive for extended period" + } + ], + "pending_requirements": [ + { + "requirement": "PENDING_ID_VERIFICATION", + "message": "ID Verification" + }, + { + "requirement": "PENDING_SANCTIONS_SCREENING", + "message": "Sanctions Screening" + }, + { + "requirement": "PENDING_ADDITIONAL_SCREENING", + "message": "PEP/Adverse Media Screening" + }, + { + "requirement": "PENDING_MEMBERS", + "message": "Pending members", + "metadata": { + "f190b163-208f-4d73-8deb-000000000001": "PENDING" + } + } + ], + "failed_requirements": [ + { + "requirement": "FAILED_ENHANCED_DUE_DILIGENCE", + "message": "Enhanced Due Diligence" + }, + { + "requirement": "FAILED_RISK_AWARENESS_ASSESSMENT", + "message": "Risk Awareness Assessment" + }, + { + "requirement": "DISABLED_MEMBERS", + "message": "Disabled members", + "metadata": { + "f190b163-208f-4d73-8deb-000000000002": "DISABLED" + } + }, + { + "requirement": "RISK_RATING", + "message": "Jurisdiction not supported by Paxos" + } + ] + } + }, + "properties": { + "id": { + "type": "string", + "title": "The id used for all other interactions with this account" + }, + "metadata": { + "type": "object", + "additionalProperties": { + "type": "string" + }, + "title": "API User-facing metadata" + }, + "summary_status": { + "$ref": "#/components/schemas/IdentityStatus" + }, + "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" + }, + "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." + }, + "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`." + }, + "status": { + "$ref": "#/components/schemas/IdentityStatus" + }, + "status_details": { + "$ref": "#/components/schemas/IdentityStatusDetails" + } + }, + "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" + }, + "summary_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": "" + }, + "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": [ + "FROZEN", + "CLOSED" + ] + }, + "ClientIdentityControlType": { + "type": "string", + "enum": [ + "FROZEN", + "CLOSED" + ] + }, + "IdentityControlReasonCode": { + "type": "string", + "enum": [ + "DORMANT", + "CUSTOMER_REQUESTED", + "SANCTIONS_PEP_OR_NN" + ], + "description": "Standardized reason codes for identity control actions" + }, + "IdentityControlAction": { + "type": "string", + "enum": [ + "SET", + "CLEAR" + ] + }, + "IdentityControl": { + "type": "object", + "properties": { + "control": { + "$ref": "#/components/schemas/IdentityControlType" + }, + "set_by": { + "type": "string", + "enum": ["paxos", "client"], + "description": "Who set this control - either 'paxos' or 'client'" + }, + "reason_code": { + "$ref": "#/components/schemas/IdentityControlReasonCode" + }, + "reason": { + "type": "string", + "description": "Additional details about why this identity control was set" + } + } + }, + "IdentityControls": { + "type": "array", + "items": { + "$ref": "#/components/schemas/IdentityControl" + }, + "example": [ + { + "control": "FROZEN", + "set_by": "client", + "reason_code": "CUSTOMER_REQUESTED", + "reason": "Customer requested temporary account freeze" + }, + { + "control": "FROZEN", + "set_by": "paxos", + "reason_code": "SANCTIONS_PEP_OR_NN", + "reason": "Account flagged for sanctions screening" + }, + { + "control": "CLOSED", + "set_by": "client", + "reason_code": "DORMANT", + "reason": "No activity for 12 months" + } + ] + }, + "CreateIdentityControlRequest": { + "type": "object", + "properties": { + "control": { + "$ref": "#/components/schemas/ClientIdentityControlType" + }, + "reason_code": { + "$ref": "#/components/schemas/IdentityControlReasonCode" + }, + "reason": { + "type": "string", + "description": "Additional free text details about the reason for setting the control" + } + }, + "required": ["control", "reason_code"] + }, + "DeleteIdentityControlRequest": { + "type": "object", + "properties": { + "control": { + "$ref": "#/components/schemas/ClientIdentityControlType" + } + }, + "required": ["control"] + }, + "IdentityPendingRequirementType": { + "type": "string", + "enum": [ + "PENDING_ID_VERIFICATION", + "PENDING_SANCTIONS_SCREENING", + "PENDING_ADDITIONAL_SCREENING", + "PENDING_ENHANCED_DUE_DILIGENCE", + "PENDING_RISK_AWARENESS_ASSESSMENT", + "PENDING_MEMBERS" + ] + }, + "IdentityFailedRequirementType": { + "type": "string", + "enum": [ + "FAILED_ID_VERIFICATION", + "FAILED_SANCTIONS_SCREENING", + "FAILED_ADDITIONAL_SCREENING", + "FAILED_ENHANCED_DUE_DILIGENCE", + "FAILED_RISK_AWARENESS_ASSESSMENT", + "DISABLED_MEMBERS", + "EXPIRED_KYC_REFRESH", + "RISK_RATING" + ] + }, + "IdentityPendingRequirement": { + "type": "object", + "properties": { + "requirement": { + "$ref": "#/components/schemas/IdentityPendingRequirementType" + }, + "message": { + "type": "string" + }, + "metadata": { + "type": "object", + "additionalProperties": { + "type": "string" + } + } + } + }, + "IdentityFailedRequirement": { + "type": "object", + "properties": { + "requirement": { + "$ref": "#/components/schemas/IdentityFailedRequirementType" + }, + "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/IdentityPendingRequirement" + } + }, + "failed_requirements": { + "type": "array", + "items": { + "$ref": "#/components/schemas/IdentityFailedRequirement" + } + } + } + } + }, + "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/api-reference/preview/2025-09-11-a.openapi.json b/api-reference/preview/2025-09-11-a.openapi.json new file mode 100644 index 0000000..f404d8f --- /dev/null +++ b/api-reference/preview/2025-09-11-a.openapi.json @@ -0,0 +1,1341 @@ +{ + "openapi": "3.0.0", + "info": { + "title": "Paxos Identity API", + "version": "2025-09-11" + }, + "tags": [ + { + "name": "IdentityPublic" + } + ], + "paths": { + "/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" + } + } + } + } + }, + "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": "Get Identity Controls", + "description": "Get the current control settings for an identity.", + "operationId": "GetIdentityControls", + "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" + } + } + ], + "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", + "example": { + "id": "f190b163-208f-4d73-8deb-4fb8b24add00", + "status": "DISABLED", + "status_details": { + "active_controls": [ + { + "control": "CLIENT_DISABLED", + "reason_code": "END_USER_REQUESTED", + "reason": "some client-set reason" + }, + { + "control": "ADMIN_DISABLED", + "reason_code": "OTHER", + "reason": "some admin-set reason" + }, + { + "control": "ADMIN_FROZEN", + "reason_code": "SANCTIONS", + "reason": "some admin-set reason" + }, + { + "control": "DORMANT", + "reason_code": "DORMANT", + "reason": "some reason" + } + ], + "pending_requirements": [ + { + "requirement": "PENDING_ID_VERIFICATION", + "message": "ID Verification" + }, + { + "requirement": "PENDING_SANCTIONS_SCREENING", + "message": "Sanctions Screening" + }, + { + "requirement": "PENDING_ADDITIONAL_SCREENING", + "message": "PEP/Adverse Media Screening" + }, + { + "requirement": "PENDING_MEMBERS", + "message": "Pending members", + "metadata": { + "f190b163-208f-4d73-8deb-000000000001": "PENDING" + } + } + ], + "failed_requirements": [ + { + "requirement": "FAILED_ENHANCED_DUE_DILIGENCE", + "message": "Enhanced Due Diligence" + }, + { + "requirement": "FAILED_RISK_AWARENESS_ASSESSMENT", + "message": "Risk Awareness Assessment" + }, + { + "requirement": "DISABLED_MEMBERS", + "message": "Disabled members", + "metadata": { + "f190b163-208f-4d73-8deb-000000000002": "DISABLED" + } + }, + { + "requirement": "RISK_RATING", + "message": "Jurisdiction not supported by Paxos" + } + ] + } + }, + "properties": { + "id": { + "type": "string", + "title": "The id used for all other interactions with this account" + }, + "metadata": { + "type": "object", + "additionalProperties": { + "type": "string" + }, + "title": "API User-facing metadata" + }, + "summary_status": { + "$ref": "#/components/schemas/IdentityStatus" + }, + "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" + }, + "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." + }, + "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`." + }, + "status": { + "$ref": "#/components/schemas/IdentityStatus" + }, + "status_details": { + "$ref": "#/components/schemas/IdentityStatusDetails" + } + }, + "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" + }, + "summary_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": "" + }, + "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": [ + "CLIENT_DISABLED", + "ADMIN_DISABLED", + "ADMIN_FROZEN", + "DORMANT" + ] + }, + "ClientIdentityControlType": { + "type": "string", + "enum": [ + "CLIENT_DISABLED", + "DORMANT" + ] + }, + "IdentityControlReasonCode": { + "type": "string", + "enum": [ + "OTHER", + "DORMANT", + "END_USER_REQUESTED", + "SANCTIONS" + ] + }, + "IdentityControl": { + "type": "object", + "properties": { + "control": { + "$ref": "#/components/schemas/IdentityControlType" + }, + "reason_code": { + "$ref": "#/components/schemas/IdentityControlReasonCode" + }, + "reason": { + "type": "string", + "description": "Reason why this identity control was set" + } + } + }, + "IdentityControls": { + "type": "array", + "items": { + "$ref": "#/components/schemas/IdentityControl" + }, + "example": [ + { + "control": "CLIENT_DISABLED", + "reason_code": "END_USER_REQUESTED", + "reason": "some client-set reason" + }, + { + "control": "ADMIN_DISABLED", + "reason_code": "OTHER", + "reason": "some admin-set reason" + }, + { + "control": "ADMIN_FROZEN", + "reason_code": "SANCTIONS", + "reason": "some admin-set reason" + }, + { + "control": "DORMANT", + "reason_code": "DORMANT", + "reason": "some reason" + } + ] + }, + "CreateIdentityControlRequest": { + "type": "object", + "properties": { + "control": { + "$ref": "#/components/schemas/ClientIdentityControlType" + }, + "reason_code": { + "$ref": "#/components/schemas/IdentityControlReasonCode" + }, + "reason": { + "type": "string", + "description": "Freetext reason for setting or clearing the control" + } + }, + "required": ["control", "reason_code"] + }, + "DeleteIdentityControlRequest": { + "type": "object", + "properties": { + "control": { + "$ref": "#/components/schemas/ClientIdentityControlType" + }, + "reason": { + "type": "string", + "description": "Freetext reason for setting or clearing the control" + } + }, + "required": ["control"] + }, + "IdentityPendingRequirementType": { + "type": "string", + "enum": [ + "PENDING_ID_VERIFICATION", + "PENDING_SANCTIONS_SCREENING", + "PENDING_ADDITIONAL_SCREENING", + "PENDING_ENHANCED_DUE_DILIGENCE", + "PENDING_RISK_AWARENESS_ASSESSMENT", + "PENDING_MEMBERS" + ] + }, + "IdentityFailedRequirementType": { + "type": "string", + "enum": [ + "FAILED_ID_VERIFICATION", + "FAILED_SANCTIONS_SCREENING", + "FAILED_ADDITIONAL_SCREENING", + "FAILED_ENHANCED_DUE_DILIGENCE", + "FAILED_RISK_AWARENESS_ASSESSMENT", + "DISABLED_MEMBERS", + "EXPIRED_KYC_REFRESH", + "RISK_RATING" + ] + }, + "IdentityPendingRequirement": { + "type": "object", + "properties": { + "requirement": { + "$ref": "#/components/schemas/IdentityPendingRequirementType" + }, + "message": { + "type": "string" + }, + "metadata": { + "type": "object", + "additionalProperties": { + "type": "string" + } + } + } + }, + "IdentityFailedRequirement": { + "type": "object", + "properties": { + "requirement": { + "$ref": "#/components/schemas/IdentityFailedRequirementType" + }, + "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/IdentityPendingRequirement" + } + }, + "failed_requirements": { + "type": "array", + "items": { + "$ref": "#/components/schemas/IdentityFailedRequirement" + } + } + } + } + }, + "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 + } + } + } + } +} diff --git a/api-reference/preview/2025-09-11-b.openapi.json b/api-reference/preview/2025-09-11-b.openapi.json new file mode 100644 index 0000000..c9d0e11 --- /dev/null +++ b/api-reference/preview/2025-09-11-b.openapi.json @@ -0,0 +1,1358 @@ +{ + "openapi": "3.0.0", + "info": { + "title": "Paxos Identity API", + "version": "2025-09-11" + }, + "tags": [ + { + "name": "IdentityPublic" + } + ], + "paths": { + "/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" + } + } + } + } + }, + "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": "Get Identity Controls", + "description": "Get the current control settings for an identity.", + "operationId": "GetIdentityControls", + "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" + } + } + ], + "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", + "example": { + "id": "f190b163-208f-4d73-8deb-4fb8b24add00", + "status": "DISABLED", + "status_details": { + "active_controls": [ + { + "control": "DISABLED", + "set_by": "CLIENT", + "reason_code": "END_USER_REQUESTED", + "reason": "some client-set reason" + }, + { + "control": "DISABLED", + "set_by": "PAXOS", + "reason_code": "OTHER", + "reason": "some admin-set reason" + }, + { + "control": "FROZEN", + "set_by": "PAXOS", + "reason_code": "SANCTIONS", + "reason": "some admin-set reason" + }, + { + "control": "DORMANT", + "set_by": "CLIENT", + "reason_code": "DORMANT", + "reason": "some reason" + } + ], + "pending_requirements": [ + { + "requirement": "PENDING_ID_VERIFICATION", + "message": "ID Verification" + }, + { + "requirement": "PENDING_SANCTIONS_SCREENING", + "message": "Sanctions Screening" + }, + { + "requirement": "PENDING_ADDITIONAL_SCREENING", + "message": "PEP/Adverse Media Screening" + }, + { + "requirement": "PENDING_MEMBERS", + "message": "Pending members", + "metadata": { + "f190b163-208f-4d73-8deb-000000000001": "PENDING" + } + } + ], + "failed_requirements": [ + { + "requirement": "FAILED_ENHANCED_DUE_DILIGENCE", + "message": "Enhanced Due Diligence" + }, + { + "requirement": "FAILED_RISK_AWARENESS_ASSESSMENT", + "message": "Risk Awareness Assessment" + }, + { + "requirement": "DISABLED_MEMBERS", + "message": "Disabled members", + "metadata": { + "f190b163-208f-4d73-8deb-000000000002": "DISABLED" + } + }, + { + "requirement": "RISK_RATING", + "message": "Jurisdiction not supported by Paxos" + } + ] + } + }, + "properties": { + "id": { + "type": "string", + "title": "The id used for all other interactions with this account" + }, + "metadata": { + "type": "object", + "additionalProperties": { + "type": "string" + }, + "title": "API User-facing metadata" + }, + "summary_status": { + "$ref": "#/components/schemas/IdentityStatus" + }, + "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" + }, + "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." + }, + "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`." + }, + "status": { + "$ref": "#/components/schemas/IdentityStatus" + }, + "status_details": { + "$ref": "#/components/schemas/IdentityStatusDetails" + } + }, + "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" + }, + "summary_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": "" + }, + "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": [ + "DISABLED", + "FROZEN", + "DORMANT" + ] + }, + "IdentityControlCreator": { + "type": "string", + "enum": [ + "PAXOS", + "CLIENT" + ] + }, + "ClientIdentityControlType": { + "type": "string", + "enum": [ + "DISABLED", + "DORMANT" + ] + }, + "IdentityControlReasonCode": { + "type": "string", + "enum": [ + "OTHER", + "DORMANT", + "END_USER_REQUESTED", + "SANCTIONS" + ] + }, + "IdentityControl": { + "type": "object", + "properties": { + "control": { + "$ref": "#/components/schemas/IdentityControlType" + }, + "set_by": { + "$ref": "#/components/schemas/IdentityControlCreator" + }, + "reason_code": { + "$ref": "#/components/schemas/IdentityControlReasonCode" + }, + "reason": { + "type": "string", + "description": "Reason why this identity control was set" + } + } + }, + "IdentityControls": { + "type": "array", + "items": { + "$ref": "#/components/schemas/IdentityControl" + }, + "example": [ + { + "control": "DISABLED", + "set_by": "CLIENT", + "reason_code": "END_USER_REQUESTED", + "reason": "some client-set reason" + }, + { + "control": "DISABLED", + "set_by": "PAXOS", + "reason_code": "OTHER", + "reason": "some admin-set reason" + }, + { + "control": "FROZEN", + "set_by": "PAXOS", + "reason_code": "SANCTIONS", + "reason": "some admin-set reason" + }, + { + "control": "DORMANT", + "set_by": "CLIENT", + "reason_code": "DORMANT", + "reason": "some reason" + } + ] + }, + "CreateIdentityControlRequest": { + "type": "object", + "properties": { + "control": { + "$ref": "#/components/schemas/ClientIdentityControlType" + }, + "reason_code": { + "$ref": "#/components/schemas/IdentityControlReasonCode" + }, + "reason": { + "type": "string", + "description": "Freetext reason for setting or clearing the control" + } + }, + "required": ["control", "reason_code"] + }, + "DeleteIdentityControlRequest": { + "type": "object", + "properties": { + "control": { + "$ref": "#/components/schemas/ClientIdentityControlType" + }, + "reason": { + "type": "string", + "description": "Freetext reason for setting or clearing the control" + } + }, + "required": ["control"] + }, + "IdentityPendingRequirementType": { + "type": "string", + "enum": [ + "PENDING_ID_VERIFICATION", + "PENDING_SANCTIONS_SCREENING", + "PENDING_ADDITIONAL_SCREENING", + "PENDING_ENHANCED_DUE_DILIGENCE", + "PENDING_RISK_AWARENESS_ASSESSMENT", + "PENDING_MEMBERS" + ] + }, + "IdentityFailedRequirementType": { + "type": "string", + "enum": [ + "FAILED_ID_VERIFICATION", + "FAILED_SANCTIONS_SCREENING", + "FAILED_ADDITIONAL_SCREENING", + "FAILED_ENHANCED_DUE_DILIGENCE", + "FAILED_RISK_AWARENESS_ASSESSMENT", + "DISABLED_MEMBERS", + "EXPIRED_KYC_REFRESH", + "RISK_RATING" + ] + }, + "IdentityPendingRequirement": { + "type": "object", + "properties": { + "requirement": { + "$ref": "#/components/schemas/IdentityPendingRequirementType" + }, + "message": { + "type": "string" + }, + "metadata": { + "type": "object", + "additionalProperties": { + "type": "string" + } + } + } + }, + "IdentityFailedRequirement": { + "type": "object", + "properties": { + "requirement": { + "$ref": "#/components/schemas/IdentityFailedRequirementType" + }, + "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/IdentityPendingRequirement" + } + }, + "failed_requirements": { + "type": "array", + "items": { + "$ref": "#/components/schemas/IdentityFailedRequirement" + } + } + } + } + }, + "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 + } + } + } + } +} diff --git a/docs.json b/docs.json index b977026..de5829e 100644 --- a/docs.json +++ b/docs.json @@ -836,10 +836,31 @@ "tab": "Previews", "groups": [ { - "group": "RP-4333 Identity Previews", + "group": "2025-09-11 A", "openapi": { - "source": "api-reference/preview/rp-4333.openapi.json", - "directory": "api-reference/preview" + "source": "api-reference/preview/2025-09-11-a.openapi.json", + "directory": "api-reference/preview/2025-09-11-a" + } + }, + { + "group": "2025-09-11 B", + "openapi": { + "source": "api-reference/preview/2025-09-11-b.openapi.json", + "directory": "api-reference/preview/2025-09-11-b" + } + }, + { + "group": "2025-09-10 cameron", + "openapi": { + "source": "api-reference/preview/2025-09-10-cameron.openapi.json", + "directory": "api-reference/preview/2025-09-10-cameron" + } + }, + { + "group": "2025-09-09", + "openapi": { + "source": "api-reference/preview/2025-09-09.openapi.json", + "directory": "api-reference/preview/2025-09-09" } } ] From c9ee2cb34c3bbb5845e7311970aeb879b09c58b3 Mon Sep 17 00:00:00 2001 From: Cameron Date: Fri, 12 Sep 2025 16:09:00 +0100 Subject: [PATCH 05/13] Cameron / Lawrence Pair --- .../preview/2025-09-12-pair.openapi.json | 1631 +++++++++++++++++ docs.json | 7 + 2 files changed, 1638 insertions(+) create mode 100644 api-reference/preview/2025-09-12-pair.openapi.json diff --git a/api-reference/preview/2025-09-12-pair.openapi.json b/api-reference/preview/2025-09-12-pair.openapi.json new file mode 100644 index 0000000..0d06d6f --- /dev/null +++ b/api-reference/preview/2025-09-12-pair.openapi.json @@ -0,0 +1,1631 @@ +{ + "openapi": "3.0.0", + "info": { + "title": "Paxos Identity API", + "version": "2025-09-11" + }, + "tags": [ + { + "name": "IdentityPublic" + } + ], + "paths": { + "/identity/identities": { + "get": { + "summary": "List Identities", + "description": "This endpoint enables you to fetch a list of Identities. You can use query parameters to filter the results returned by `created_at`, `updated_at`, `summary_status` and `identity_type`.", + "operationId": "ListIdentities", + "responses": { + "200": { + "description": "A successful response.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ListIdentitiesResponse" + } + } + } + }, + "400": { + "$ref": "#/components/responses/BadRequest" + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + }, + "403": { + "$ref": "#/components/responses/Forbidden" + }, + "404": { + "$ref": "#/components/responses/NotFound" + } + }, + "parameters": [ + { + "name": "summary_status", + "description": "Filter by identity status", + "in": "query", + "required": false, + "schema": { + "$ref": "#/components/schemas/IdentityStatus" + } + }, + { + "name": "active_controls", + "description": "Filter by active identity controls", + "in": "query", + "required": false, + "schema": { + "type": "array", + "items": { + "$ref": "#/components/schemas/IdentityControlType" + } + }, + "style": "form", + "explode": true + }, + { + "name": "identity_type", + "description": "Filter by identity type", + "in": "query", + "required": false, + "schema": { + "$ref": "#/components/schemas/IdentityType" + } + }, + { + "name": "created_at.lt", + "description": "Return identities created before this timestamp", + "in": "query", + "required": false, + "schema": { + "type": "string", + "format": "date-time" + } + }, + { + "name": "created_at.lte", + "description": "Return identities created before or at this timestamp", + "in": "query", + "required": false, + "schema": { + "type": "string", + "format": "date-time" + } + }, + { + "name": "created_at.eq", + "description": "Return identities created at exactly this timestamp", + "in": "query", + "required": false, + "schema": { + "type": "string", + "format": "date-time" + } + }, + { + "name": "created_at.gte", + "description": "Return identities created at or after this timestamp", + "in": "query", + "required": false, + "schema": { + "type": "string", + "format": "date-time" + } + }, + { + "name": "created_at.gt", + "description": "Return identities created after this timestamp", + "in": "query", + "required": false, + "schema": { + "type": "string", + "format": "date-time" + } + }, + { + "name": "updated_at.lt", + "description": "Return identities updated before this timestamp", + "in": "query", + "required": false, + "schema": { + "type": "string", + "format": "date-time" + } + }, + { + "name": "updated_at.lte", + "description": "Return identities updated before or at this timestamp", + "in": "query", + "required": false, + "schema": { + "type": "string", + "format": "date-time" + } + }, + { + "name": "updated_at.eq", + "description": "Return identities updated at exactly this timestamp", + "in": "query", + "required": false, + "schema": { + "type": "string", + "format": "date-time" + } + }, + { + "name": "updated_at.gte", + "description": "Return identities updated at or after this timestamp", + "in": "query", + "required": false, + "schema": { + "type": "string", + "format": "date-time" + } + }, + { + "name": "updated_at.gt", + "description": "Return identities updated after this timestamp", + "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", + "minimum": 1, + "maximum": 100, + "default": 50 + } + }, + { + "name": "order", + "description": "Order of results", + "in": "query", + "required": false, + "schema": { + "type": "string", + "enum": ["DESC", "ASC"], + "default": "DESC" + } + }, + { + "name": "order_by", + "description": "Field to order results by", + "in": "query", + "required": false, + "schema": { + "type": "string", + "enum": ["CREATED_AT"], + "default": "CREATED_AT" + } + }, + { + "name": "page_cursor", + "description": "Cursor for pagination", + "in": "query", + "required": false, + "schema": { + "type": "string" + } + } + ], + "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" + } + } + } + } + }, + "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": "List the 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_archived", + "description": "Include archived controls in the response", + "in": "query", + "required": false, + "schema": { + "type": "boolean", + "default": false + } + } + ], + "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", + "example": { + "id": "f190b163-208f-4d73-8deb-4fb8b24add00", + "status": "DISABLED", + "status_details": { + "active_controls": [ + { + "type": "DISABLED", + "controlled_by": "CLIENT", + "reason_code": "END_USER_REQUESTED", + "reason": "some client-set reason" + }, + { + "type": "DISABLED", + "controlled_by": "PAXOS", + "reason_code": "OTHER", + "reason": "some admin-set reason" + }, + { + "type": "FROZEN", + "controlled_by": "PAXOS", + "reason_code": "SANCTIONS", + "reason": "some admin-set reason" + }, + { + "type": "DORMANT", + "controlled_by": "CLIENT", + "reason_code": "DORMANT", + "reason": "some reason" + } + ], + "pending_requirements": [ + { + "requirement": "PENDING_ID_VERIFICATION", + "message": "ID Verification" + }, + { + "requirement": "PENDING_SANCTIONS_SCREENING", + "message": "Sanctions Screening" + }, + { + "requirement": "PENDING_ADDITIONAL_SCREENING", + "message": "PEP/Adverse Media Screening" + }, + { + "requirement": "PENDING_MEMBERS", + "message": "Pending members", + "metadata": { + "f190b163-208f-4d73-8deb-000000000001": "PENDING" + } + } + ], + "failed_requirements": [ + { + "requirement": "FAILED_ENHANCED_DUE_DILIGENCE", + "message": "Enhanced Due Diligence" + }, + { + "requirement": "FAILED_RISK_AWARENESS_ASSESSMENT", + "message": "Risk Awareness Assessment" + }, + { + "requirement": "DISABLED_MEMBERS", + "message": "Disabled members", + "metadata": { + "f190b163-208f-4d73-8deb-000000000002": "DISABLED" + } + }, + { + "requirement": "RISK_RATING", + "message": "Jurisdiction not supported by Paxos" + } + ] + } + }, + "properties": { + "id": { + "type": "string", + "title": "The id used for all other interactions with this account" + }, + "metadata": { + "type": "object", + "additionalProperties": { + "type": "string" + }, + "title": "API User-facing metadata" + }, + "status": { + "$ref": "#/components/schemas/IdentityStatus" + }, + "status_details": { + "$ref": "#/components/schemas/IdentityStatusDetails" + }, + "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" + }, + "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." + }, + "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" + ] + }, + "ListIdentitiesResponse": { + "type": "object", + "properties": { + "items": { + "type": "array", + "items": { + "$ref": "#/components/schemas/Identity" + }, + "description": "List of identities" + }, + "next_page_cursor": { + "type": "string", + "description": "Cursor for the next page of results" + } + }, + "required": ["items"] + }, + "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": "" + }, + "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": [ + "DISABLED", + "FROZEN", + "DORMANT" + ] + }, + "IdentityControlCreator": { + "type": "string", + "enum": [ + "PAXOS", + "CLIENT" + ] + }, + "ClientIdentityControlType": { + "type": "string", + "enum": [ + "DISABLED", + "DORMANT" + ] + }, + "IdentityControlReasonCode": { + "type": "string", + "enum": [ + "OTHER", + "DORMANT", + "END_USER_REQUESTED", + "SANCTIONS" + ] + }, + "IdentityControl": { + "type": "object", + "properties": { + "id": { + "type": "string", + "description": "Unique identifier for this identity control" + }, + "identity_id": { + "type": "string", + "description": "The identity ID this control belongs to" + }, + "type": { + "$ref": "#/components/schemas/IdentityControlType" + }, + "controlled_by": { + "$ref": "#/components/schemas/IdentityControlCreator" + }, + "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": "Timestamp when this control was created" + }, + "archived_at": { + "type": "string", + "format": "date-time", + "description": "Timestamp when this control was archived (if applicable)" + } + } + }, + "IdentityControls": { + "type": "array", + "items": { + "$ref": "#/components/schemas/IdentityControl" + }, + "example": [ + { + "id": "ctrl_1234567890abcdef", + "identity_id": "f190b163-208f-4d73-8deb-4fb8b24add00", + "type": "DISABLED", + "controlled_by": "CLIENT", + "reason_code": "END_USER_REQUESTED", + "reason": "some client-set reason", + "created_at": "2024-01-15T10:30:00Z", + "archived_at": null + }, + { + "id": "ctrl_0987654321fedcba", + "identity_id": "f190b163-208f-4d73-8deb-4fb8b24add00", + "type": "DISABLED", + "controlled_by": "PAXOS", + "reason_code": "OTHER", + "reason": "some admin-set reason", + "created_at": "2024-02-20T14:45:00Z", + "archived_at": null + }, + { + "id": "ctrl_abcdef1234567890", + "identity_id": "f190b163-208f-4d73-8deb-4fb8b24add00", + "type": "FROZEN", + "controlled_by": "PAXOS", + "reason_code": "SANCTIONS", + "reason": "some admin-set reason", + "created_at": "2024-03-10T09:15:00Z", + "archived_at": null + }, + { + "id": "ctrl_fedcba0987654321", + "identity_id": "f190b163-208f-4d73-8deb-4fb8b24add00", + "type": "DORMANT", + "controlled_by": "CLIENT", + "reason_code": "DORMANT", + "reason": "some reason", + "created_at": "2024-04-05T16:20:00Z", + "archived_at": "2024-06-01T10:00:00Z" + } + ] + }, + "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": { + "type": { + "$ref": "#/components/schemas/ClientIdentityControlType" + }, + "reason": { + "type": "string", + "description": "Freetext reason for setting or clearing the control" + } + }, + "required": ["type"] + }, + "IdentityPendingRequirementType": { + "type": "string", + "enum": [ + "PENDING_ID_VERIFICATION", + "PENDING_SANCTIONS_SCREENING", + "PENDING_ADDITIONAL_SCREENING", + "PENDING_ENHANCED_DUE_DILIGENCE", + "PENDING_RISK_AWARENESS_ASSESSMENT", + "PENDING_MEMBERS" + ] + }, + "IdentityFailedRequirementType": { + "type": "string", + "enum": [ + "FAILED_ID_VERIFICATION", + "FAILED_SANCTIONS_SCREENING", + "FAILED_ADDITIONAL_SCREENING", + "FAILED_ENHANCED_DUE_DILIGENCE", + "FAILED_RISK_AWARENESS_ASSESSMENT", + "DISABLED_MEMBERS", + "EXPIRED_KYC_REFRESH", + "RISK_RATING" + ] + }, + "IdentityPendingRequirement": { + "type": "object", + "properties": { + "requirement": { + "$ref": "#/components/schemas/IdentityPendingRequirementType" + }, + "message": { + "type": "string" + }, + "metadata": { + "type": "object", + "additionalProperties": { + "type": "string" + } + } + } + }, + "IdentityFailedRequirement": { + "type": "object", + "properties": { + "requirement": { + "$ref": "#/components/schemas/IdentityFailedRequirementType" + }, + "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/IdentityPendingRequirement" + } + }, + "failed_requirements": { + "type": "array", + "items": { + "$ref": "#/components/schemas/IdentityFailedRequirement" + } + } + } + } + }, + "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 + } + } + } + } +} diff --git a/docs.json b/docs.json index de5829e..976286b 100644 --- a/docs.json +++ b/docs.json @@ -835,6 +835,13 @@ { "tab": "Previews", "groups": [ + { + "group": "2025-09-12 Pair", + "openapi": { + "source": "api-reference/preview/2025-09-12-pair.openapi.json", + "directory": "api-reference/preview/2025-09-12-pair" + } + }, { "group": "2025-09-11 A", "openapi": { From 0545f0e9782f52838b72c2ec7ed30ff406772fe4 Mon Sep 17 00:00:00 2001 From: Lawrence Date: Tue, 16 Sep 2025 15:15:19 -0400 Subject: [PATCH 06/13] 2025-09-16 --- api-reference/preview/2025-09-16.openapi.json | 1620 +++++++++++++++++ docs.json | 7 + 2 files changed, 1627 insertions(+) create mode 100644 api-reference/preview/2025-09-16.openapi.json diff --git a/api-reference/preview/2025-09-16.openapi.json b/api-reference/preview/2025-09-16.openapi.json new file mode 100644 index 0000000..ffeca85 --- /dev/null +++ b/api-reference/preview/2025-09-16.openapi.json @@ -0,0 +1,1620 @@ +{ + "openapi": "3.0.0", + "info": { + "title": "Paxos Identity API", + "version": "2025-09-11" + }, + "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`, `summary_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": "summary_status", + "description": "Summary 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": "active_control_type", + "description": "Optionally filter by active identity control type", + "in": "query", + "required": false, + "schema": { + "$ref": "#/components/schemas/IdentityControlType" + } + }, + { + "name": "active_control_reason_code", + "description": "Optionally filter by active 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" + } + } + } + } + }, + "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_archived", + "description": "Include archived 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", + "example": { + "id": "f190b163-208f-4d73-8deb-4fb8b24add00", + "status": "DISABLED", + "status_details": { + "active_controls": [ + { + "id": "59b8e3c5-2b6e-4fa6-afcf-8c685598241d", + "control_type": "DISABLED", + "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", + "control_type": "DISABLED", + "controlled_by": "PAXOS", + "reason_code": "OTHER", + "reason": "some admin-set reason", + "created_at": "2006-01-02T15:04:05Z" + } + ], + "pending_requirements": [ + { + "requirement": "PENDING_ID_VERIFICATION", + "message": "ID Verification" + }, + { + "requirement": "PENDING_SANCTIONS_SCREENING", + "message": "Sanctions Screening" + }, + { + "requirement": "PENDING_ADDITIONAL_SCREENING", + "message": "PEP/Adverse Media Screening" + }, + { + "requirement": "PENDING_MEMBERS", + "message": "Pending members", + "metadata": { + "f190b163-208f-4d73-8deb-000000000001": "PENDING" + } + } + ], + "failed_requirements": [ + { + "requirement": "FAILED_ENHANCED_DUE_DILIGENCE", + "message": "Enhanced Due Diligence" + }, + { + "requirement": "FAILED_RISK_AWARENESS_ASSESSMENT", + "message": "Risk Awareness Assessment" + }, + { + "requirement": "DISABLED_MEMBERS", + "message": "Disabled members", + "metadata": { + "f190b163-208f-4d73-8deb-000000000002": "DISABLED" + } + }, + { + "requirement": "RISK_RATING", + "message": "Jurisdiction not supported by Paxos" + } + ] + } + }, + "properties": { + "id": { + "type": "string", + "title": "The id used for all other interactions with this account" + }, + "metadata": { + "type": "object", + "additionalProperties": { + "type": "string" + }, + "title": "API User-facing metadata" + }, + "summary_status": { + "$ref": "#/components/schemas/IdentityStatus" + }, + "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" + }, + "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." + }, + "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`." + }, + "status": { + "$ref": "#/components/schemas/IdentityStatus" + }, + "status_details": { + "$ref": "#/components/schemas/IdentityStatusDetails" + } + }, + "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" + }, + "summary_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": [ + "DISABLED", + "FROZEN", + "DORMANT" + ] + }, + "IdentityControlController": { + "type": "string", + "enum": [ + "PAXOS", + "CLIENT" + ] + }, + "ClientIdentityControlType": { + "type": "string", + "enum": [ + "DISABLED", + "DORMANT" + ] + }, + "IdentityControlReasonCode": { + "type": "string", + "enum": [ + "OTHER", + "DORMANT", + "END_USER_REQUESTED", + "SANCTIONS" + ] + }, + "IdentityControl": { + "type": "object", + "properties": { + "id": { + "type": "string" + }, + "control_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" + }, + "archived_at": { + "type": "string", + "format": "date-time", + "description": "Time this identity control was deleted" + } + } + }, + "IdentityControls": { + "type": "array", + "items": { + "$ref": "#/components/schemas/IdentityControl" + }, + "example": [ + { + "id": "59b8e3c5-2b6e-4fa6-afcf-8c685598241d", + "control_type": "DISABLED", + "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", + "control_type": "DISABLED", + "controlled_by": "PAXOS", + "reason_code": "OTHER", + "reason": "some admin-set reason", + "created_at": "2006-01-02T15:04:05Z" + }, + { + "id": "173fdece-0792-4833-a6bb-232b461a9fa4", + "control_type": "FROZEN", + "controlled_by": "PAXOS", + "reason_code": "SANCTIONS", + "reason": "some admin-set reason", + "created_at": "2006-01-02T15:04:05Z", + "archived_at": "2006-01-02T15:04:05Z" + }, + { + "id": "ae54b3b4-cce6-4707-b34b-c9c4f0537798", + "control_type": "DORMANT", + "controlled_by": "CLIENT", + "reason_code": "DORMANT", + "reason": "some reason", + "created_at": "2006-01-02T15:04:05Z", + "archived_at": "2006-01-02T15:04:05Z" + } + ] + }, + "CreateIdentityControlRequest": { + "type": "object", + "properties": { + "control_type": { + "$ref": "#/components/schemas/ClientIdentityControlType" + }, + "reason_code": { + "$ref": "#/components/schemas/IdentityControlReasonCode" + }, + "reason": { + "type": "string", + "description": "Freetext reason for setting or clearing the control" + } + }, + "required": ["control_type", "reason_code"] + }, + "DeleteIdentityControlRequest": { + "type": "object", + "properties": { + "id": { + "type": "string" + }, + "reason": { + "type": "string", + "description": "Freetext reason for setting or clearing the control" + } + }, + "required": ["id"] + }, + "IdentityPendingRequirementType": { + "type": "string", + "enum": [ + "PENDING_ID_VERIFICATION", + "PENDING_SANCTIONS_SCREENING", + "PENDING_ADDITIONAL_SCREENING", + "PENDING_ENHANCED_DUE_DILIGENCE", + "PENDING_RISK_AWARENESS_ASSESSMENT", + "PENDING_MEMBERS" + ] + }, + "IdentityFailedRequirementType": { + "type": "string", + "enum": [ + "FAILED_ID_VERIFICATION", + "FAILED_SANCTIONS_SCREENING", + "FAILED_ADDITIONAL_SCREENING", + "FAILED_ENHANCED_DUE_DILIGENCE", + "FAILED_RISK_AWARENESS_ASSESSMENT", + "DISABLED_MEMBERS", + "EXPIRED_KYC_REFRESH", + "RISK_RATING" + ] + }, + "IdentityPendingRequirement": { + "type": "object", + "properties": { + "requirement": { + "$ref": "#/components/schemas/IdentityPendingRequirementType" + }, + "message": { + "type": "string" + }, + "metadata": { + "type": "object", + "additionalProperties": { + "type": "string" + } + } + } + }, + "IdentityFailedRequirement": { + "type": "object", + "properties": { + "requirement": { + "$ref": "#/components/schemas/IdentityFailedRequirementType" + }, + "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/IdentityPendingRequirement" + } + }, + "failed_requirements": { + "type": "array", + "items": { + "$ref": "#/components/schemas/IdentityFailedRequirement" + } + } + } + } + }, + "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 + } + } + } + } +} diff --git a/docs.json b/docs.json index 976286b..7281fc2 100644 --- a/docs.json +++ b/docs.json @@ -835,6 +835,13 @@ { "tab": "Previews", "groups": [ + { + "group": "2025-09-16", + "openapi": { + "source": "api-reference/preview/2025-09-16.openapi.json", + "directory": "api-reference/preview/2025-09-12" + } + }, { "group": "2025-09-12 Pair", "openapi": { From e4d71afb5ecc4845173126e0fc1e1dc37897e267 Mon Sep 17 00:00:00 2001 From: Lawrence Date: Tue, 16 Sep 2025 15:24:04 -0400 Subject: [PATCH 07/13] 2025-09-16 --- api-reference/preview/2025-09-16.openapi.json | 80 ++++++------------- 1 file changed, 26 insertions(+), 54 deletions(-) diff --git a/api-reference/preview/2025-09-16.openapi.json b/api-reference/preview/2025-09-16.openapi.json index ffeca85..5f6d6e6 100644 --- a/api-reference/preview/2025-09-16.openapi.json +++ b/api-reference/preview/2025-09-16.openapi.json @@ -683,19 +683,19 @@ ], "pending_requirements": [ { - "requirement": "PENDING_ID_VERIFICATION", - "message": "ID Verification" + "requirement_type": "ID_VERIFICATION", + "message": "Pending ID Verification" }, { - "requirement": "PENDING_SANCTIONS_SCREENING", - "message": "Sanctions Screening" + "requirement_type": "SANCTIONS_SCREENING", + "message": "Pending Sanctions Screening" }, { - "requirement": "PENDING_ADDITIONAL_SCREENING", - "message": "PEP/Adverse Media Screening" + "requirement_type": "ADDITIONAL_SCREENING", + "message": "Pending PEP/Adverse Media Screening" }, { - "requirement": "PENDING_MEMBERS", + "requirement_type": "MEMBERS", "message": "Pending members", "metadata": { "f190b163-208f-4d73-8deb-000000000001": "PENDING" @@ -704,22 +704,22 @@ ], "failed_requirements": [ { - "requirement": "FAILED_ENHANCED_DUE_DILIGENCE", - "message": "Enhanced Due Diligence" + "requirement_type": "ENHANCED_DUE_DILIGENCE", + "message": "Failed Enhanced Due Diligence checks" }, { - "requirement": "FAILED_RISK_AWARENESS_ASSESSMENT", - "message": "Risk Awareness Assessment" + "requirement_type": "RISK_AWARENESS_ASSESSMENT", + "message": "Failed Risk Awareness Assessment" }, { - "requirement": "DISABLED_MEMBERS", + "requirement_type": "DISABLED_MEMBERS", "message": "Disabled members", "metadata": { "f190b163-208f-4d73-8deb-000000000002": "DISABLED" } }, { - "requirement": "RISK_RATING", + "requirement_type": "RISK_RATING", "message": "Jurisdiction not supported by Paxos" } ] @@ -1426,52 +1426,24 @@ }, "required": ["id"] }, - "IdentityPendingRequirementType": { + "IdentityRequirementType": { "type": "string", "enum": [ - "PENDING_ID_VERIFICATION", - "PENDING_SANCTIONS_SCREENING", - "PENDING_ADDITIONAL_SCREENING", - "PENDING_ENHANCED_DUE_DILIGENCE", - "PENDING_RISK_AWARENESS_ASSESSMENT", - "PENDING_MEMBERS" - ] - }, - "IdentityFailedRequirementType": { - "type": "string", - "enum": [ - "FAILED_ID_VERIFICATION", - "FAILED_SANCTIONS_SCREENING", - "FAILED_ADDITIONAL_SCREENING", - "FAILED_ENHANCED_DUE_DILIGENCE", - "FAILED_RISK_AWARENESS_ASSESSMENT", - "DISABLED_MEMBERS", - "EXPIRED_KYC_REFRESH", + "ID_VERIFICATION", + "SANCTIONS_SCREENING", + "ADDITIONAL_SCREENING", + "ENHANCED_DUE_DILIGENCE", + "RISK_AWARENESS_ASSESSMENT", + "MEMBERS", + "KYC_REFRESH", "RISK_RATING" ] }, - "IdentityPendingRequirement": { - "type": "object", - "properties": { - "requirement": { - "$ref": "#/components/schemas/IdentityPendingRequirementType" - }, - "message": { - "type": "string" - }, - "metadata": { - "type": "object", - "additionalProperties": { - "type": "string" - } - } - } - }, - "IdentityFailedRequirement": { + "IdentityRequirement": { "type": "object", "properties": { - "requirement": { - "$ref": "#/components/schemas/IdentityFailedRequirementType" + "requirement_type": { + "$ref": "#/components/schemas/IdentityRequirementType" }, "message": { "type": "string" @@ -1493,13 +1465,13 @@ "pending_requirements": { "type": "array", "items": { - "$ref": "#/components/schemas/IdentityPendingRequirement" + "$ref": "#/components/schemas/IdentityRequirement" } }, "failed_requirements": { "type": "array", "items": { - "$ref": "#/components/schemas/IdentityFailedRequirement" + "$ref": "#/components/schemas/IdentityRequirement" } } } From 2df09707ce0392772b70a9e0f16c3bfd4afd0af1 Mon Sep 17 00:00:00 2001 From: Lawrence Date: Tue, 16 Sep 2025 15:30:15 -0400 Subject: [PATCH 08/13] cleanup --- docs.json | 10 ++++++++-- 1 file changed, 8 insertions(+), 2 deletions(-) diff --git a/docs.json b/docs.json index 7281fc2..0d32baf 100644 --- a/docs.json +++ b/docs.json @@ -839,9 +839,15 @@ "group": "2025-09-16", "openapi": { "source": "api-reference/preview/2025-09-16.openapi.json", - "directory": "api-reference/preview/2025-09-12" + "directory": "api-reference/preview/2025-09-16" } - }, + } + ] + }, + { + "tab": "Old Previews", + "hidden": true, + "groups": [ { "group": "2025-09-12 Pair", "openapi": { From 7db23a27fee5c3c349faab5ed8a5ed04ece42c0d Mon Sep 17 00:00:00 2001 From: Lawrence Date: Thu, 18 Sep 2025 08:14:15 -0400 Subject: [PATCH 09/13] 2025-09-18 --- api-reference/preview/2025-09-16.openapi.json | 2 +- api-reference/preview/2025-09-18.openapi.json | 1585 +++++++++++++++++ docs.json | 13 +- 3 files changed, 1596 insertions(+), 4 deletions(-) create mode 100644 api-reference/preview/2025-09-18.openapi.json diff --git a/api-reference/preview/2025-09-16.openapi.json b/api-reference/preview/2025-09-16.openapi.json index 5f6d6e6..124ef72 100644 --- a/api-reference/preview/2025-09-16.openapi.json +++ b/api-reference/preview/2025-09-16.openapi.json @@ -2,7 +2,7 @@ "openapi": "3.0.0", "info": { "title": "Paxos Identity API", - "version": "2025-09-11" + "version": "2025-09-16" }, "tags": [ { diff --git a/api-reference/preview/2025-09-18.openapi.json b/api-reference/preview/2025-09-18.openapi.json new file mode 100644 index 0000000..9313706 --- /dev/null +++ b/api-reference/preview/2025-09-18.openapi.json @@ -0,0 +1,1585 @@ +{ + "openapi": "3.0.0", + "info": { + "title": "Paxos Identity API", + "version": "2025-09-18" + }, + "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`, `summary_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": "summary_status", + "description": "Summary 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": "active_control_type", + "description": "Optionally filter by active identity control type", + "in": "query", + "required": false, + "schema": { + "$ref": "#/components/schemas/IdentityControlType" + } + }, + { + "name": "active_control_reason_code", + "description": "Optionally filter by active 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" + } + } + } + } + }, + "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", + "example": { + "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" + }, + { + "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" + } + ], + "pending_requirements": [ + { + "requirement_type": "ID_VERIFICATION", + "message": "Pending ID Verification" + }, + { + "requirement_type": "SANCTIONS_SCREENING", + "message": "Pending Sanctions Screening" + }, + { + "requirement_type": "ADDITIONAL_SCREENING", + "message": "Pending PEP/Adverse Media Screening" + }, + { + "requirement_type": "MEMBERS", + "message": "Pending members", + "metadata": { + "f190b163-208f-4d73-8deb-000000000001": "PENDING" + } + } + ], + "failed_requirements": [ + { + "requirement_type": "ENHANCED_DUE_DILIGENCE", + "message": "Failed Enhanced Due Diligence checks" + }, + { + "requirement_type": "RISK_AWARENESS_ASSESSMENT", + "message": "Failed Risk Awareness Assessment" + }, + { + "requirement_type": "DISABLED_MEMBERS", + "message": "Disabled members", + "metadata": { + "f190b163-208f-4d73-8deb-000000000002": "DISABLED" + } + }, + { + "requirement_type": "RISK_RATING", + "message": "Jurisdiction not supported by Paxos" + } + ] + } + }, + "properties": { + "id": { + "type": "string", + "title": "The id used for all other interactions with this account" + }, + "metadata": { + "type": "object", + "additionalProperties": { + "type": "string" + }, + "title": "API User-facing metadata" + }, + "summary_status": { + "$ref": "#/components/schemas/IdentityStatus" + }, + "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" + }, + "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." + }, + "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`." + }, + "status": { + "$ref": "#/components/schemas/IdentityStatus" + }, + "status_details": { + "$ref": "#/components/schemas/IdentityStatusDetails" + } + }, + "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" + }, + "summary_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": { + "requirement_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 + } + } + } + } +} diff --git a/docs.json b/docs.json index 0d32baf..d464d29 100644 --- a/docs.json +++ b/docs.json @@ -836,10 +836,10 @@ "tab": "Previews", "groups": [ { - "group": "2025-09-16", + "group": "2025-09-18", "openapi": { - "source": "api-reference/preview/2025-09-16.openapi.json", - "directory": "api-reference/preview/2025-09-16" + "source": "api-reference/preview/2025-09-18.openapi.json", + "directory": "api-reference/preview/2025-09-18" } } ] @@ -848,6 +848,13 @@ "tab": "Old Previews", "hidden": true, "groups": [ + { + "group": "2025-09-16", + "openapi": { + "source": "api-reference/preview/2025-09-16.openapi.json", + "directory": "api-reference/preview/2025-09-16" + } + }, { "group": "2025-09-12 Pair", "openapi": { From 8f4346f00a0f8804e8dde0a782799ed28ce79ee0 Mon Sep 17 00:00:00 2001 From: Lawrence Date: Thu, 18 Sep 2025 08:17:17 -0400 Subject: [PATCH 10/13] requirement_type -> type --- api-reference/preview/2025-09-18.openapi.json | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/api-reference/preview/2025-09-18.openapi.json b/api-reference/preview/2025-09-18.openapi.json index 9313706..d62869b 100644 --- a/api-reference/preview/2025-09-18.openapi.json +++ b/api-reference/preview/2025-09-18.openapi.json @@ -683,19 +683,19 @@ ], "pending_requirements": [ { - "requirement_type": "ID_VERIFICATION", + "type": "ID_VERIFICATION", "message": "Pending ID Verification" }, { - "requirement_type": "SANCTIONS_SCREENING", + "type": "SANCTIONS_SCREENING", "message": "Pending Sanctions Screening" }, { - "requirement_type": "ADDITIONAL_SCREENING", + "type": "ADDITIONAL_SCREENING", "message": "Pending PEP/Adverse Media Screening" }, { - "requirement_type": "MEMBERS", + "type": "MEMBERS", "message": "Pending members", "metadata": { "f190b163-208f-4d73-8deb-000000000001": "PENDING" @@ -704,22 +704,22 @@ ], "failed_requirements": [ { - "requirement_type": "ENHANCED_DUE_DILIGENCE", + "type": "ENHANCED_DUE_DILIGENCE", "message": "Failed Enhanced Due Diligence checks" }, { - "requirement_type": "RISK_AWARENESS_ASSESSMENT", + "type": "RISK_AWARENESS_ASSESSMENT", "message": "Failed Risk Awareness Assessment" }, { - "requirement_type": "DISABLED_MEMBERS", + "type": "DISABLED_MEMBERS", "message": "Disabled members", "metadata": { "f190b163-208f-4d73-8deb-000000000002": "DISABLED" } }, { - "requirement_type": "RISK_RATING", + "type": "RISK_RATING", "message": "Jurisdiction not supported by Paxos" } ] @@ -1435,7 +1435,7 @@ "IdentityRequirement": { "type": "object", "properties": { - "requirement_type": { + "type": { "$ref": "#/components/schemas/IdentityRequirementType" }, "message": { From a5c25738f57913e6f2b157c7e762acaf9f023562 Mon Sep 17 00:00:00 2001 From: Lawrence Date: Tue, 23 Sep 2025 08:08:37 -0400 Subject: [PATCH 11/13] 2025-09-22 wip --- .tool-versions | 2 +- .../2025-09-22/endpoints/events/get-event.mdx | 7 + .../endpoints/events/list-events.mdx | 7 + .../2025-09-22/endpoints/events/overview.mdx | 8 + .../events/identity-status-change-object.mdx | 108 ++ .../preview/2025-09-22/identity.openapi.json | 1585 +++++++++++++++++ .../preview/2025-09-22/webhooks-openapi.json | 268 +++ .../2025-09-22/webhooks/identity-approved.mdx | 16 + .../2025-09-22/webhooks/identity-denied.mdx | 16 + .../2025-09-22/webhooks/identity-disabled.mdx | 16 + docs.json | 54 +- guides/identity/statuses.mdx | 59 +- 12 files changed, 2140 insertions(+), 6 deletions(-) create mode 100644 api-reference/preview/2025-09-22/endpoints/events/get-event.mdx create mode 100644 api-reference/preview/2025-09-22/endpoints/events/list-events.mdx create mode 100644 api-reference/preview/2025-09-22/endpoints/events/overview.mdx create mode 100644 api-reference/preview/2025-09-22/events/identity-status-change-object.mdx create mode 100644 api-reference/preview/2025-09-22/identity.openapi.json create mode 100644 api-reference/preview/2025-09-22/webhooks-openapi.json create mode 100644 api-reference/preview/2025-09-22/webhooks/identity-approved.mdx create mode 100644 api-reference/preview/2025-09-22/webhooks/identity-denied.mdx create mode 100644 api-reference/preview/2025-09-22/webhooks/identity-disabled.mdx diff --git a/.tool-versions b/.tool-versions index 7e96d63..d903414 100644 --- a/.tool-versions +++ b/.tool-versions @@ -1 +1 @@ -nodejs 20.3.0 \ No newline at end of file +nodejs 20.19.0 \ No newline at end of file diff --git a/api-reference/preview/2025-09-22/endpoints/events/get-event.mdx b/api-reference/preview/2025-09-22/endpoints/events/get-event.mdx new file mode 100644 index 0000000..7144fe9 --- /dev/null +++ b/api-reference/preview/2025-09-22/endpoints/events/get-event.mdx @@ -0,0 +1,7 @@ +--- +openapi: get /events/{id} +--- + +```bash OAuth Scope +events:read_event +``` diff --git a/api-reference/preview/2025-09-22/endpoints/events/list-events.mdx b/api-reference/preview/2025-09-22/endpoints/events/list-events.mdx new file mode 100644 index 0000000..163feb5 --- /dev/null +++ b/api-reference/preview/2025-09-22/endpoints/events/list-events.mdx @@ -0,0 +1,7 @@ +--- +openapi: get /events +--- + +```bash OAuth Scope +events:read_event +``` diff --git a/api-reference/preview/2025-09-22/endpoints/events/overview.mdx b/api-reference/preview/2025-09-22/endpoints/events/overview.mdx new file mode 100644 index 0000000..d78087c --- /dev/null +++ b/api-reference/preview/2025-09-22/endpoints/events/overview.mdx @@ -0,0 +1,8 @@ +--- +title: 'Overview' +description: 'Retrieve events from your Paxos account' +--- + +The Events API provides access to event data from your Paxos account. Events are generated when certain actions occur within your account, such as identity status changes, document requirements, or KYC refresh activities. + +Events are immutable records of state changes that occurred in your account. They provide a reliable way to track the history of important activities and integrate with your systems using webhooks. diff --git a/api-reference/preview/2025-09-22/events/identity-status-change-object.mdx b/api-reference/preview/2025-09-22/events/identity-status-change-object.mdx new file mode 100644 index 0000000..4c8bb0e --- /dev/null +++ b/api-reference/preview/2025-09-22/events/identity-status-change-object.mdx @@ -0,0 +1,108 @@ +--- +title: "identity_summary_status_change" +description: "Event object returned for identity status change events" +openapi: "webhooks-openapi.json component schema IdentityStatusChangeObject" +--- + +This object is returned by the [Get Event API](/api-reference/preview/2025-09-22/endpoints/events/get-event) when the event type is `identity.approved`, `identity.denied`, or `identity.disabled`. + +## Object Fields + + +Unique identifier for this event object + + + +Identifier for the affected identity + + + +The previous status of the identity + +**Available options:** `PENDING`, `ERROR`, `APPROVED`, `DENIED`, `DISABLED` + + + +The new status of the identity + +**Available options:** `PENDING`, `ERROR`, `APPROVED`, `DENIED`, `DISABLED` + + + +Detailed info about the new status of the identity + + + + +```json Example +{ + "id": "d840cf31-352f-4190-a476-7522bf3eafda", + "identity_id": "4fd025ab-f29f-47e6-a02e-df90a61c7ec9", + "old_status": "PENDING", + "new_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" + }, + { + "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" + } + ], + "pending_requirements": [ + { + "type": "ID_VERIFICATION", + "message": "Pending ID Verification" + }, + { + "type": "SANCTIONS_SCREENING", + "message": "Pending Sanctions Screening" + }, + { + "type": "ADDITIONAL_SCREENING", + "message": "Pending PEP/Adverse Media Screening" + }, + { + "type": "MEMBERS", + "message": "Pending members", + "metadata": { + "f190b163-208f-4d73-8deb-000000000001": "PENDING" + } + } + ], + "failed_requirements": [ + { + "type": "ENHANCED_DUE_DILIGENCE", + "message": "Failed Enhanced Due Diligence checks" + }, + { + "type": "RISK_AWARENESS_ASSESSMENT", + "message": "Failed Risk Awareness Assessment" + }, + { + "type": "DISABLED_MEMBERS", + "message": "Disabled members", + "metadata": { + "f190b163-208f-4d73-8deb-000000000002": "DISABLED" + } + }, + { + "type": "RISK_RATING", + "message": "Jurisdiction not supported by Paxos" + } + ] + } +} +``` + + \ No newline at end of file diff --git a/api-reference/preview/2025-09-22/identity.openapi.json b/api-reference/preview/2025-09-22/identity.openapi.json new file mode 100644 index 0000000..4b90eae --- /dev/null +++ b/api-reference/preview/2025-09-22/identity.openapi.json @@ -0,0 +1,1585 @@ +{ + "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`, `summary_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": "summary_status", + "description": "Summary 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": "active_control_type", + "description": "Optionally filter by active identity control type", + "in": "query", + "required": false, + "schema": { + "$ref": "#/components/schemas/IdentityControlType" + } + }, + { + "name": "active_control_reason_code", + "description": "Optionally filter by active 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" + } + } + } + } + }, + "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", + "example": { + "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" + }, + { + "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" + } + ], + "pending_requirements": [ + { + "type": "ID_VERIFICATION", + "message": "Pending ID Verification" + }, + { + "type": "SANCTIONS_SCREENING", + "message": "Pending Sanctions Screening" + }, + { + "type": "ADDITIONAL_SCREENING", + "message": "Pending PEP/Adverse Media Screening" + }, + { + "type": "MEMBERS", + "message": "Pending members", + "metadata": { + "f190b163-208f-4d73-8deb-000000000001": "PENDING" + } + } + ], + "failed_requirements": [ + { + "type": "ENHANCED_DUE_DILIGENCE", + "message": "Failed Enhanced Due Diligence checks" + }, + { + "type": "RISK_AWARENESS_ASSESSMENT", + "message": "Failed Risk Awareness Assessment" + }, + { + "type": "DISABLED_MEMBERS", + "message": "Disabled members", + "metadata": { + "f190b163-208f-4d73-8deb-000000000002": "DISABLED" + } + }, + { + "type": "RISK_RATING", + "message": "Jurisdiction not supported by Paxos" + } + ] + } + }, + "properties": { + "id": { + "type": "string", + "title": "The id used for all other interactions with this account" + }, + "metadata": { + "type": "object", + "additionalProperties": { + "type": "string" + }, + "title": "API User-facing metadata" + }, + "summary_status": { + "$ref": "#/components/schemas/IdentityStatus" + }, + "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" + }, + "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." + }, + "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`." + }, + "status": { + "$ref": "#/components/schemas/IdentityStatus" + }, + "status_details": { + "$ref": "#/components/schemas/IdentityStatusDetails" + } + }, + "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" + }, + "summary_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 + } + } + } + } +} diff --git a/api-reference/preview/2025-09-22/webhooks-openapi.json b/api-reference/preview/2025-09-22/webhooks-openapi.json new file mode 100644 index 0000000..b1115e4 --- /dev/null +++ b/api-reference/preview/2025-09-22/webhooks-openapi.json @@ -0,0 +1,268 @@ +{ + "openapi": "3.1.0", + "info": { + "title": "Paxos Webhooks", + "version": "2025-09-22", + "description": "Webhooks allow you to register endpoints to receive asynchronous events from the Paxos Platform. These webhooks are triggered when specific events occur in the system, enabling real-time notifications for your application.\n\n**Important**: Webhook payloads contain only the event metadata. To retrieve the full event object details, use the [Get Event](/api-reference/preview/2025-09-22/events/get-event) REST API endpoint with the event ID from the webhook payload." + }, + "webhooks": { + "identity.approved": { + "post": { + "requestBody": { + "description": "Webhook payload containing event metadata. Use the event ID with the Get Event API to retrieve full details.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/WebhookEvent" + }, + "example": { + "id": "bd019f1c-89a7-4372-9d21-eaad9280dc41", + "type": "identity.approved", + "source": "com.paxos", + "time": "2025-01-07T14:30:02Z", + "object": "event" + } + } + } + }, + "responses": { + "200": { + "description": "Webhook successfully received" + } + }, + "summary": "Identity Approved", + "description": "Triggered when an identity verification process is approved. Your endpoint should respond with a 2xx status code to acknowledge receipt. Use the event ID to call the Get Event API for full details." + } + }, + "identity.denied": { + "post": { + "requestBody": { + "description": "Webhook payload containing event metadata. Use the event ID with the Get Event API to retrieve full details.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/WebhookEvent" + }, + "example": { + "id": "bd019f1c-89a7-4372-9d21-eaad9280dc41", + "type": "identity.denied", + "source": "com.paxos", + "time": "2025-01-07T14:30:02Z", + "object": "event" + } + } + } + }, + "responses": { + "200": { + "description": "Webhook successfully received" + } + }, + "summary": "Identity Denied", + "description": "Triggered when an identity verification process is denied. Your endpoint should respond with a 2xx status code to acknowledge receipt. Use the event ID to call the Get Event API for full details." + } + }, + "identity.disabled": { + "post": { + "requestBody": { + "description": "Webhook payload containing event metadata. Use the event ID with the Get Event API to retrieve full details.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/WebhookEvent" + }, + "example": { + "id": "bd019f1c-89a7-4372-9d21-eaad9280dc41", + "type": "identity.disabled", + "source": "com.paxos", + "time": "2025-01-07T14:30:02Z", + "object": "event" + } + } + } + }, + "responses": { + "200": { + "description": "Webhook successfully received" + } + }, + "summary": "Identity Disabled", + "description": "Triggered when an identity is disabled. Your endpoint should respond with a 2xx status code to acknowledge receipt. Use the event ID to call the Get Event API for full details." + } + } + }, + "components": { + "schemas": { + "WebhookEvent": { + "type": "object", + "title": "Webhook Event", + "description": "The webhook payload structure sent to your endpoint", + "properties": { + "id": { + "type": "string", + "format": "uuid", + "title": "Event ID", + "description": "The event identifier used to query the Events API for full details" + }, + "type": { + "type": "string", + "title": "Event Type", + "description": "The type of event that occurred", + "enum": [ + "identity.documents_required", + "identity.approved", + "identity.denied", + "identity.disabled", + "identity.kyc_refresh.started", + "identity.kyc_refresh.completed", + "identity.kyc_refresh.expired", + "transfer.crypto_deposit.pending", + "transfer.crypto_deposit.completed", + "transfer.crypto_deposit.failed", + "transfer.crypto_withdrawal.pending", + "transfer.crypto_withdrawal.completed", + "transfer.crypto_withdrawal.failed", + "transfer.act_deposit.pending", + "transfer.act_deposit.completed", + "transfer.act_deposit.failed", + "transfer.act_withdrawal.pending", + "transfer.act_withdrawal.completed", + "transfer.act_withdrawal.failed" + ] + }, + "source": { + "type": "string", + "enum": ["com.paxos"], + "title": "Source", + "description": "Always 'com.paxos'" + }, + "time": { + "type": "string", + "format": "date-time", + "title": "Timestamp", + "description": "When the event occurred, RFC3339 format" + }, + "object": { + "type": "string", + "enum": ["event"], + "title": "Object Type", + "description": "Always 'event'" + } + }, + "required": ["id", "type", "source", "time", "object"], + "example": { + "id": "bd019f1c-89a7-4372-9d21-eaad9280dc41", + "type": "identity.approved", + "source": "com.paxos", + "time": "2025-01-07T14:30:02Z", + "object": "event" + } + }, + "IdentityStatusChangeObject": { + "type": "object", + "title": "Identity Status Change Object", + "description": "Object returned by Get Event API for identity status change events", + "properties": { + "id": { + "type": "string", + "format": "uuid", + "title": "Object ID", + "description": "Unique identifier for this event object" + }, + "identity_id": { + "type": "string", + "format": "uuid", + "title": "Identity ID", + "description": "Identifier for the affected identity" + }, + "old_status": { + "type": "string", + "enum": ["PENDING", "ERROR", "APPROVED", "DENIED", "DISABLED"], + "title": "Previous Status", + "description": "The previous status of the identity" + }, + "new_status": { + "type": "string", + "enum": ["PENDING", "ERROR", "APPROVED", "DENIED", "DISABLED"], + "title": "New Status", + "description": "The new status of the identity" + }, + "status_details": { + "type": "object", + "title": "Status Details", + "description": "Detailed info about the new status of the identity" + } + }, + "required": ["id", "identity_id", "old_status", "new_status"], + "example": { + "id": "d840cf31-352f-4190-a476-7522bf3eafda", + "identity_id": "4fd025ab-f29f-47e6-a02e-df90a61c7ec9", + "old_status": "PENDING", + "new_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" + }, + { + "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" + } + ], + "pending_requirements": [ + { + "type": "ID_VERIFICATION", + "message": "Pending ID Verification" + }, + { + "type": "SANCTIONS_SCREENING", + "message": "Pending Sanctions Screening" + }, + { + "type": "ADDITIONAL_SCREENING", + "message": "Pending PEP/Adverse Media Screening" + }, + { + "type": "MEMBERS", + "message": "Pending members", + "metadata": { + "f190b163-208f-4d73-8deb-000000000001": "PENDING" + } + } + ], + "failed_requirements": [ + { + "type": "ENHANCED_DUE_DILIGENCE", + "message": "Failed Enhanced Due Diligence checks" + }, + { + "type": "RISK_AWARENESS_ASSESSMENT", + "message": "Failed Risk Awareness Assessment" + }, + { + "type": "DISABLED_MEMBERS", + "message": "Disabled members", + "metadata": { + "f190b163-208f-4d73-8deb-000000000002": "DISABLED" + } + }, + { + "type": "RISK_RATING", + "message": "Jurisdiction not supported by Paxos" + } + ] + } + } + } + } + } +} \ No newline at end of file diff --git a/api-reference/preview/2025-09-22/webhooks/identity-approved.mdx b/api-reference/preview/2025-09-22/webhooks/identity-approved.mdx new file mode 100644 index 0000000..6cad6e9 --- /dev/null +++ b/api-reference/preview/2025-09-22/webhooks/identity-approved.mdx @@ -0,0 +1,16 @@ +--- +title: "identity.approved" +description: "Webhook triggered when an identity verification is approved" +openapi: "webhooks-openapi.json webhook identity.approved" +--- + +Triggered when identity verification is successfully approved. + + +Webhook payloads contain only event metadata. Use the [Get Event API](/api-reference/preview/2025-09-22/endpoints/events/get-event) with the event ID to retrieve full details. + + +## Event Object Structure + +The Get Event API returns an [`identity_status_change`](/api-reference/preview/2025-09-22/events/identity-status-change-object) object with status transition details. + diff --git a/api-reference/preview/2025-09-22/webhooks/identity-denied.mdx b/api-reference/preview/2025-09-22/webhooks/identity-denied.mdx new file mode 100644 index 0000000..3eff412 --- /dev/null +++ b/api-reference/preview/2025-09-22/webhooks/identity-denied.mdx @@ -0,0 +1,16 @@ +--- +title: "identity.denied" +description: "Webhook triggered when an identity verification is denied" +openapi: "webhooks-openapi.json webhook identity.denied" +--- + +Triggered when identity verification is denied. + + +Webhook payloads contain only event metadata. Use the [Get Event API](/api-reference/preview/2025-09-22/endpoints/events/get-event) with the event ID to retrieve full details. + + +## Event Object Structure + +The Get Event API returns an [`identity_status_change`](/api-reference/preview/2025-09-22/events/identity-status-change-object) object with status transition details. + diff --git a/api-reference/preview/2025-09-22/webhooks/identity-disabled.mdx b/api-reference/preview/2025-09-22/webhooks/identity-disabled.mdx new file mode 100644 index 0000000..b03354f --- /dev/null +++ b/api-reference/preview/2025-09-22/webhooks/identity-disabled.mdx @@ -0,0 +1,16 @@ +--- +title: "identity.disabled" +description: "Webhook triggered when an identity is disabled" +openapi: "webhooks-openapi.json webhook identity.disabled" +--- + +Triggered when a previously approved identity is disabled. + + +Webhook payloads contain only event metadata. Use the [Get Event API](/api-reference/preview/2025-09-22/endpoints/events/get-event) with the event ID to retrieve full details. + + +## Event Object Structure + +The Get Event API returns an [`identity_status_change`](/api-reference/preview/2025-09-22/events/identity-status-change-object) object with status transition details. + diff --git a/docs.json b/docs.json index d464d29..6a72e05 100644 --- a/docs.json +++ b/docs.json @@ -836,11 +836,50 @@ "tab": "Previews", "groups": [ { - "group": "2025-09-18", + "group": "2025-09-22", "openapi": { - "source": "api-reference/preview/2025-09-18.openapi.json", - "directory": "api-reference/preview/2025-09-18" - } + "source": "api-reference/preview/2025-09-22/identity.openapi.json", + "directory": "api-reference/preview/2025-09-22" + }, + "pages": [ + { + "group": "Events", + "pages": [ + { + "group": "Events", + "pages": [ + "api-reference/preview/2025-09-22/endpoints/events/overview", + "api-reference/preview/2025-09-22/endpoints/events/list-events", + "api-reference/preview/2025-09-22/endpoints/events/get-event" + ] + } + ] + }, + { + "group": "Webhooks", + "pages": [ + { + "group": "Identity", + "pages": [ + { + "group": "Hooks", + "pages": [ + "api-reference/preview/2025-09-22/webhooks/identity-approved", + "api-reference/preview/2025-09-22/webhooks/identity-denied", + "api-reference/preview/2025-09-22/webhooks/identity-disabled" + ] + }, + { + "group": "Objects", + "pages": [ + "api-reference/preview/2025-09-22/events/identity-status-change-object" + ] + } + ] + } + ] + } + ] } ] }, @@ -848,6 +887,13 @@ "tab": "Old Previews", "hidden": true, "groups": [ + { + "group": "2025-09-18", + "openapi": { + "source": "api-reference/preview/2025-09-18.openapi.json", + "directory": "api-reference/preview/2025-09-18" + } + }, { "group": "2025-09-16", "openapi": { diff --git a/guides/identity/statuses.mdx b/guides/identity/statuses.mdx index d0bebc1..c84c7c7 100644 --- a/guides/identity/statuses.mdx +++ b/guides/identity/statuses.mdx @@ -63,4 +63,61 @@ that `passthrough_verification_status` can only ever be set to a terminal IDV st The onboarding decision is made based on the identities risk rating and the set of verifications (as exposed in sub-statuses above). Once there is sufficient information to make a decision, the [Identity](/api-reference/endpoints/identity/create-identity) will be `APPROVED` and able to trade or `DENIED` and rejected services. -In the happy path where an [Identity](/api-reference/endpoints/identity/create-identity) is `LOW` \ No newline at end of file +In the happy path where an [Identity](/api-reference/endpoints/identity/create-identity) is `LOW` risk rating and passes all verification checks, the identity will transition to `APPROVED` status. + +## Identity Controls + +Identity Controls provide granular control over identity permissions and are used to manage specific restrictions on identities. These controls supplement the summary status and provide more detailed control over identity operations. + +### Control Types +- **`CLOSED`**: The identity is closed and cannot perform any operations +- **`FROZEN`**: The identity is temporarily frozen, typically for compliance reasons +- **`DORMANT`**: The identity is marked as inactive due to lack of activity + +### Control Controllers +Controls can be managed by different entities: +- **`PAXOS`**: Controls set by Paxos for compliance or risk management +- **`CLIENT`**: Controls that can be set by API clients + +### Control Reason Codes +- **`OTHER`**: General reason not covered by specific codes +- **`DORMANT`**: Identity marked dormant due to inactivity +- **`END_USER_REQUESTED`**: Control requested by the end user +- **`SANCTIONS`**: Control applied due to sanctions screening + +### Client-Manageable Controls +API clients can create and delete the following control types: +- **`CLOSED`**: Close an identity permanently +- **`DORMANT`**: Mark an identity as inactive + +> Use the [Identity Controls API](/api-reference/endpoints/identity/list-identity-controls) to manage identity controls programmatically. + +## Identity Status Details + +The new `status_details` field in identity responses provides comprehensive information about the identity's current state: + +### Active Controls +Lists all currently active controls on the identity, including: +- Control ID and type +- Who set the control (Paxos or client) +- Reason code and description +- Timestamp when the control was created + +### Pending Requirements +Shows what verification steps are still needed: +- **`ID_VERIFICATION`**: Identity verification in progress +- **`SANCTIONS_SCREENING`**: Sanctions check pending +- **`ADDITIONAL_SCREENING`**: PEP/Adverse media screening pending +- **`MEMBERS`**: Institution member verification pending +- **`KYC_REFRESH`**: Periodic KYC refresh required + +### Failed Requirements +Indicates which verification steps have failed: +- **`ENHANCED_DUE_DILIGENCE`**: Failed enhanced due diligence +- **`RISK_AWARENESS_ASSESSMENT`**: Failed risk assessment +- **`RISK_RATING`**: Jurisdiction or risk rating issues +- **`DISABLED_MEMBERS`**: Institution has disabled members + +## Impact on Identity Operations + +The combination of summary status and active controls determines what operations an identity can perform. An identity with `APPROVED` status but active `FROZEN` controls will have restricted functionality similar to `ERROR` status identities. \ No newline at end of file From 6851adb4a6d7064d02f2b4d006f3ee0d5066deb8 Mon Sep 17 00:00:00 2001 From: Lawrence Date: Tue, 23 Sep 2025 08:42:41 -0400 Subject: [PATCH 12/13] events --- .../endpoints/events/list-events.mdx | 7 - .../2025-09-22/endpoints/events/overview.mdx | 8 - .../events/identity-status-change-object.mdx | 2 +- .../preview/2025-09-22/webhooks-openapi.json | 242 ++++++++++++++++++ docs.json | 2 - 5 files changed, 243 insertions(+), 18 deletions(-) delete mode 100644 api-reference/preview/2025-09-22/endpoints/events/list-events.mdx delete mode 100644 api-reference/preview/2025-09-22/endpoints/events/overview.mdx diff --git a/api-reference/preview/2025-09-22/endpoints/events/list-events.mdx b/api-reference/preview/2025-09-22/endpoints/events/list-events.mdx deleted file mode 100644 index 163feb5..0000000 --- a/api-reference/preview/2025-09-22/endpoints/events/list-events.mdx +++ /dev/null @@ -1,7 +0,0 @@ ---- -openapi: get /events ---- - -```bash OAuth Scope -events:read_event -``` diff --git a/api-reference/preview/2025-09-22/endpoints/events/overview.mdx b/api-reference/preview/2025-09-22/endpoints/events/overview.mdx deleted file mode 100644 index d78087c..0000000 --- a/api-reference/preview/2025-09-22/endpoints/events/overview.mdx +++ /dev/null @@ -1,8 +0,0 @@ ---- -title: 'Overview' -description: 'Retrieve events from your Paxos account' ---- - -The Events API provides access to event data from your Paxos account. Events are generated when certain actions occur within your account, such as identity status changes, document requirements, or KYC refresh activities. - -Events are immutable records of state changes that occurred in your account. They provide a reliable way to track the history of important activities and integrate with your systems using webhooks. diff --git a/api-reference/preview/2025-09-22/events/identity-status-change-object.mdx b/api-reference/preview/2025-09-22/events/identity-status-change-object.mdx index 4c8bb0e..e510a2d 100644 --- a/api-reference/preview/2025-09-22/events/identity-status-change-object.mdx +++ b/api-reference/preview/2025-09-22/events/identity-status-change-object.mdx @@ -1,5 +1,5 @@ --- -title: "identity_summary_status_change" +title: "identity_status_change" description: "Event object returned for identity status change events" openapi: "webhooks-openapi.json component schema IdentityStatusChangeObject" --- diff --git a/api-reference/preview/2025-09-22/webhooks-openapi.json b/api-reference/preview/2025-09-22/webhooks-openapi.json index b1115e4..3e4ebc8 100644 --- a/api-reference/preview/2025-09-22/webhooks-openapi.json +++ b/api-reference/preview/2025-09-22/webhooks-openapi.json @@ -5,6 +5,182 @@ "version": "2025-09-22", "description": "Webhooks allow you to register endpoints to receive asynchronous events from the Paxos Platform. These webhooks are triggered when specific events occur in the system, enabling real-time notifications for your application.\n\n**Important**: Webhook payloads contain only the event metadata. To retrieve the full event object details, use the [Get Event](/api-reference/preview/2025-09-22/events/get-event) REST API endpoint with the event ID from the webhook payload." }, + "paths": { + "/events/{id}": { + "get": { + "summary": "Get Event", + "description": "Get an Event by its (event) id, the event must have been created by the system and you must be the owner of the\nthe event, you can get an event id by either listing events or via a webhook integration.", + "operationId": "GetEvent", + "responses": { + "200": { + "description": "Success", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Event" + }, + "example": { + "id": "d99a03ee-6b88-4362-89da-087c2c8cd4a7", + "type": "identity.disabled", + "object_type": "identity_status_change", + "object": { + "id": "d840cf31-352f-4190-a476-7522bf3eafda", + "identity_id": "4fd025ab-f29f-47e6-a02e-df90a61c7ec9", + "old_status": "PENDING", + "new_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" + }, + { + "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" + } + ], + "pending_requirements": [ + { + "type": "ID_VERIFICATION", + "message": "Pending ID Verification" + }, + { + "type": "SANCTIONS_SCREENING", + "message": "Pending Sanctions Screening" + }, + { + "type": "ADDITIONAL_SCREENING", + "message": "Pending PEP/Adverse Media Screening" + }, + { + "type": "MEMBERS", + "message": "Pending members", + "metadata": { + "f190b163-208f-4d73-8deb-000000000001": "PENDING" + } + } + ], + "failed_requirements": [ + { + "type": "ENHANCED_DUE_DILIGENCE", + "message": "Failed Enhanced Due Diligence checks" + }, + { + "type": "RISK_AWARENESS_ASSESSMENT", + "message": "Failed Risk Awareness Assessment" + }, + { + "type": "DISABLED_MEMBERS", + "message": "Disabled members", + "metadata": { + "f190b163-208f-4d73-8deb-000000000002": "DISABLED" + } + }, + { + "type": "RISK_RATING", + "message": "Jurisdiction not supported by Paxos" + } + ] + } + }, + "created_at": "2023-08-25T14:25:41.648489333Z", + "undelivered_webhooks": 12 + } + } + } + }, + "400": { + "description": "Bad Request", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Problem" + }, + "examples": { + "Bad event id": { + "value": { + "type": "about:blank", + "title": "Bad Request", + "status": 400, + "detail": "error parsing event id" + } + } + } + } + } + }, + "403": { + "description": "Insufficient scopes", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Problem" + }, + "examples": { + "Insufficient scopes": { + "value": { + "type": "about:blank", + "title": "Forbidden", + "status": 403, + "detail": "insufficient scopes: found 'identity:read_identity', required one of '[event:read_event]'" + } + } + } + } + } + }, + "404": { + "description": "Not Found", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Problem" + }, + "examples": { + "Not Found": { + "value": { + "status": 404, + "title": "Not Found", + "type": "about:blank" + } + } + } + } + } + } + }, + "parameters": [ + { + "name": "id", + "description": "The unique `id` in the `Event` object.", + "in": "path", + "required": true, + "schema": { + "type": "string" + } + } + ], + "tags": [ + "Events" + ], + "security": [ + { + "OAuth2": [ + "events:read_event" + ] + } + ] + } + } + }, "webhooks": { "identity.approved": { "post": { @@ -93,6 +269,37 @@ }, "components": { "schemas": { + "Event": { + "type": "object", + "properties": { + "id": { + "type": "string", + "description": "The event identifier used to query or refer to a specific event" + }, + "type": { + "type": "string", + "description": "The type of event representing an action in the system" + }, + "object_type": { + "type": "string", + "description": "The type of the `object` associated with the event" + }, + "object": { + "type": "object", + "description": "The structured payload of type `object_type` associated with the event" + }, + "created_at": { + "type": "string", + "format": "date-time", + "description": "The timestamp when the event was first created, RFC3339 format, like `YYYY-MM-DDTHH:MM:SS.sssZ`." + }, + "undelivered_webhooks": { + "type": "integer", + "format": "int32", + "description": "The number of undelivered webhooks" + } + } + }, "WebhookEvent": { "type": "object", "title": "Webhook Event", @@ -262,6 +469,41 @@ ] } } + }, + "Problem": { + "type": "object", + "properties": { + "type": { + "type": "string", + "format": "uri", + "description": "An absolute URI that identifies the problem type. When dereferenced,\nit SHOULD provide human-readable documentation for the problem type\n(e.g., using HTML).\n", + "default": "about:blank", + "example": "https://api.paxos.com/v2/problems/insufficient_funds" + }, + "title": { + "type": "string", + "description": "A short, summary of the problem type. Written in english and readable\nfor engineers (usually not suited for non technical stakeholders and\nnot localized); example: Service Unavailable\n", + "example": "Insufficient Funds" + }, + "status": { + "type": "integer", + "format": "int32", + "description": "The HTTP status code generated by the origin server for this occurrence\nof the problem.\n", + "minimum": 100, + "maximum": 600, + "exclusiveMaximum": true, + "example": 403 + }, + "detail": { + "type": "string", + "description": "A human readable explanation specific to this occurrence of the\nproblem.\n", + "example": "Not enough funds in account." + }, + "meta": { + "type": "object", + "description": "Additional structured metadata about the error.\n" + } + } } } } diff --git a/docs.json b/docs.json index 6a72e05..9c00394 100644 --- a/docs.json +++ b/docs.json @@ -848,8 +848,6 @@ { "group": "Events", "pages": [ - "api-reference/preview/2025-09-22/endpoints/events/overview", - "api-reference/preview/2025-09-22/endpoints/events/list-events", "api-reference/preview/2025-09-22/endpoints/events/get-event" ] } From 926f59feae928c987d91369bec185296d4748900 Mon Sep 17 00:00:00 2001 From: Lawrence Date: Tue, 23 Sep 2025 09:00:52 -0400 Subject: [PATCH 13/13] remove claude guide change --- guides/identity/statuses.mdx | 59 +----------------------------------- 1 file changed, 1 insertion(+), 58 deletions(-) diff --git a/guides/identity/statuses.mdx b/guides/identity/statuses.mdx index c84c7c7..d0bebc1 100644 --- a/guides/identity/statuses.mdx +++ b/guides/identity/statuses.mdx @@ -63,61 +63,4 @@ that `passthrough_verification_status` can only ever be set to a terminal IDV st The onboarding decision is made based on the identities risk rating and the set of verifications (as exposed in sub-statuses above). Once there is sufficient information to make a decision, the [Identity](/api-reference/endpoints/identity/create-identity) will be `APPROVED` and able to trade or `DENIED` and rejected services. -In the happy path where an [Identity](/api-reference/endpoints/identity/create-identity) is `LOW` risk rating and passes all verification checks, the identity will transition to `APPROVED` status. - -## Identity Controls - -Identity Controls provide granular control over identity permissions and are used to manage specific restrictions on identities. These controls supplement the summary status and provide more detailed control over identity operations. - -### Control Types -- **`CLOSED`**: The identity is closed and cannot perform any operations -- **`FROZEN`**: The identity is temporarily frozen, typically for compliance reasons -- **`DORMANT`**: The identity is marked as inactive due to lack of activity - -### Control Controllers -Controls can be managed by different entities: -- **`PAXOS`**: Controls set by Paxos for compliance or risk management -- **`CLIENT`**: Controls that can be set by API clients - -### Control Reason Codes -- **`OTHER`**: General reason not covered by specific codes -- **`DORMANT`**: Identity marked dormant due to inactivity -- **`END_USER_REQUESTED`**: Control requested by the end user -- **`SANCTIONS`**: Control applied due to sanctions screening - -### Client-Manageable Controls -API clients can create and delete the following control types: -- **`CLOSED`**: Close an identity permanently -- **`DORMANT`**: Mark an identity as inactive - -> Use the [Identity Controls API](/api-reference/endpoints/identity/list-identity-controls) to manage identity controls programmatically. - -## Identity Status Details - -The new `status_details` field in identity responses provides comprehensive information about the identity's current state: - -### Active Controls -Lists all currently active controls on the identity, including: -- Control ID and type -- Who set the control (Paxos or client) -- Reason code and description -- Timestamp when the control was created - -### Pending Requirements -Shows what verification steps are still needed: -- **`ID_VERIFICATION`**: Identity verification in progress -- **`SANCTIONS_SCREENING`**: Sanctions check pending -- **`ADDITIONAL_SCREENING`**: PEP/Adverse media screening pending -- **`MEMBERS`**: Institution member verification pending -- **`KYC_REFRESH`**: Periodic KYC refresh required - -### Failed Requirements -Indicates which verification steps have failed: -- **`ENHANCED_DUE_DILIGENCE`**: Failed enhanced due diligence -- **`RISK_AWARENESS_ASSESSMENT`**: Failed risk assessment -- **`RISK_RATING`**: Jurisdiction or risk rating issues -- **`DISABLED_MEMBERS`**: Institution has disabled members - -## Impact on Identity Operations - -The combination of summary status and active controls determines what operations an identity can perform. An identity with `APPROVED` status but active `FROZEN` controls will have restricted functionality similar to `ERROR` status identities. \ No newline at end of file +In the happy path where an [Identity](/api-reference/endpoints/identity/create-identity) is `LOW` \ No newline at end of file