{"templateId":"markdown","versions":[{"version":"v2026.03","label":"v2026.03","link":"/products/payments-direct-2/api-docs/tutorials/create-and-manage-identities","default":true,"active":true,"folderId":"eb16255d"},{"version":"v2025.11","label":"v2025.11","link":"/products/payments-direct-2/v2025.11/api-docs/tutorials/create-and-manage-identities","default":false,"active":false,"folderId":"eb16255d"}],"sharedDataIds":{"sidebar":"sidebar-products/payments-direct-2/@v2025.11/sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":["admonition"]},"type":"markdown"},"seo":{"title":"Create and manage identities","description":"User guides, API reference, and support resources.","siteUrl":"https://docs.ripple.com/products/custody","lang":"en-US","llmstxt":{"hide":false,"sections":[{"title":"Table of contents","includeFiles":["**/*"],"excludeFiles":[]}],"excludeFiles":[]}},"dynamicMarkdocComponents":[],"compilationErrors":[],"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"create-and-manage-identities","__idx":0},"children":["Create and manage identities"]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"info","name":"Identity Management v3"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["This topic describes the v3 identity model. ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Identity Management v3"]}," is recommended for all new integrations."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The supported payment corridors are:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["US • USD"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["EU • EUR"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["MX • MXN"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["BR • BRL"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["CO • COP"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["CA • CAD"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["GB • GBP"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["NG • NGN"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["SWIFT • USD"]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["This tutorial shows how to use the ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Identity Management v3"]}," identity endpoints to:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Create a new identity"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Retrieve an identity by ID (and by version)"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["List identities with filters and pagination"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Update identity details"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Deactivate an identity"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["It builds on the model described in ",{"$$mdtype":"Tag","name":"a","attributes":{"href":"/products/payments-direct-2/api-docs/concepts/payment-identities"},"children":["Payment identities"]}," and focuses on the v3 identity schema."]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"warning","name":"internalId"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["A key behavior in v3 is that ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["at most one ACTIVE identity"]}," in your environment can use a given ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["internalId"]},". Attempts to create or update an identity so that its ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["internalId"]}," collides with another ACTIVE identity result in ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["409 Conflict"]},"."]}]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"before-you-begin","__idx":1},"children":["Before you begin"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["To follow these examples, you need:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Base URL for the Identity Management (for example, ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["https://{base-url}"]},")"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["An access token with the following scopes (or equivalent):",{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["participants:create "]},"for creating identities"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["participants:read"]}," for reading and listing identities"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["participants:update"]}," for updating and deactivating identities"]}]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["The v3 identity model from ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Payment identities"]}," (INDIVIDUAL vs BUSINESS and ORIGINATOR vs BENEFICIARY)"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["In all examples below, replace:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["{base-url}"]}," with your actual PII base URL"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["<access_token>"]}," with a valid OAuth2 access token"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["{identity-id} "]},"with a real ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["identityId"]}," returned by the API"]}]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"create-an-identity","__idx":2},"children":["Create an identity"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Use ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["POST /v3/identities"]}," to create a new identity."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["At minimum, you must provide:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["identityType"]}," – INDIVIDUAL or BUSINESS"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["paymentRole"]}," – ORIGINATOR or BENEFICIARY"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Either individual or business details, depending on ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["identityType"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["internalId"]}," for ORIGINATOR identities (required by corridor rules)"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["For ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["BENEFICIARY"]}," identities, ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["internalId"]}," is optional, but recommended if you want to link beneficiaries to your own customer records."]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"info","name":"Deduplication via internalId"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Identity Management v3 enforces that at most one ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["ACTIVE"]}," identity per organization can use a given ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["internalId"]},"."]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["If you try to create an identity and the provided ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["internalId"]}," is already used by another ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["ACTIVE"]}," identity, the request fails with ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["409 Conflict"]},"."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["You can handle this error in your integration to surface “duplicate customer” conditions or guide users to reuse the existing identity."]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Optionally, you can also:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Set a friendly ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["nickName"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["tags"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Add ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["validatePayoutRails"]}," to validate the identity against specific payout rails (for example, ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["US_ACH"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["BR_PIX"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["MX_SPEI"]},")"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Example: Create an INDIVIDUAL ORIGINATOR"]}]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","header":{"controls":{"copy":{}}},"source":"curl -X POST \"https://{base-url}/v3/identities\" \\\n  -H \"Authorization: Bearer <access_token>\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"identityType\": \"INDIVIDUAL\",\n    \"paymentRole\": \"ORIGINATOR\",\n    \"internalId\": \"customer-12345-uuid\",\n    \"nickName\": \"Alice Sender USD\",\n    \"tags\": [\"sender\", \"priority\"],\n    \"validatePayoutRails\": [\"US_ACH\"],\n    \"individual\": {\n      \"firstName\": \"Alice\",\n      \"lastName\": \"Chen\",\n      \"dateOfBirth\": \"1990-05-14\",\n      \"citizenship\": \"US\",\n      \"address\": {\n        \"streetAddress\": [\"123 Main Street\"],\n        \"city\": \"San Francisco\",\n        \"stateOrProvince\": \"CA\",\n        \"postalCode\": \"94105\",\n        \"country\": \"US\"\n      }\n    }\n  }'\n","lang":"bash"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Response (201 Created)"]}]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"identityId\": \"99254c4f-f207-4792-a846-06928825018c\",\n  \"version\": \"1\"\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"warning","name":"Deduplication via internalId"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["If you send another ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["POST /v3/identities"]}," with the same ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["internalId"]}," while this identity is still ACTIVE, the service returns:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["409 Conflict"]}," – indicating that another ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["ACTIVE"]}," identity already uses that ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["internalId"]},"."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Handle 409 as a signal that you should look up and reuse the existing identity instead of creating a duplicate."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Example: Create a BUSINESS BENEFICIARY"]}]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","header":{"controls":{"copy":{}}},"source":"curl -X POST \"https://{base-url}/v3/identities\" \\\n  -H \"Authorization: Bearer <access_token>\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"identityType\": \"BUSINESS\",\n    \"paymentRole\": \"BENEFICIARY\",\n    \"internalId\": \"counterparty-7890\",\n    \"nickName\": \"Widgets Org MX\",\n    \"tags\": [\"beneficiary\", \"mx\"],\n    \"validatePayoutRails\": [\"MX_SPEI\"],\n    \"business\": {\n      \"businessName\": \"Widgets Org\",\n      \"incorporationCountry\": \"US\",\n      \"registration\": [\n        {\n          \"number\": \"123ABC\",\n          \"type\": \"INCORPORATION_CERTIFICATE\"\n        }\n      ],\n      \"email\": \"fake@example.com\",\n      \"phone\": \"+1234567890\",\n      \"address\": {\n        \"streetAddress\": [\"123 Example MA\"],\n        \"city\": \"Boston\",\n        \"stateOrProvince\": \"MS\",\n        \"postalCode\": \"12345\",\n        \"country\": \"US\"\n      }\n    }\n  }'\n","lang":"bash"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Response (201 Created)"]}]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"identityId\": \"0116bacc-ffbf-4fa2-a29c-ecd9ea346806\",\n  \"version\": \"1\"\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"warning","name":"Missing or invalid PII"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["If any required PII is missing or invalid for the rails in ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["validatePayoutRails"]},", the API returns a 400 error describing which fields failed validation."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Example: Validation failure for missing required fields"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["If you try to create an identity with ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["validatePayoutRails: [\"US_ACH\"]"]}," but omit required fields like ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["dateOfBirth"]}," or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["identityDocuments"]},", you'll receive:"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Response (400 Bad Request)"]}]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"code\": \"VALIDATION_ERROR\",\n  \"title\": \"Identity validation failed\",\n  \"description\": \"The identity is missing required fields for the specified payout rails.\",\n  \"details\": [\n    {\n      \"field\": \"individual.dateOfBirth\",\n      \"message\": \"Date of birth is required for US_ACH beneficiary identities\"\n    },\n    {\n      \"field\": \"individual.identityDocuments\",\n      \"message\": \"At least one identity document (SSN or Tax ID) is required for US_ACH beneficiary identities\"\n    }\n  ]\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["To fix this, add the missing fields and retry the request."]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"handling-internalid-conflicts-409-conflict","__idx":3},"children":["Handling ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["internalId"]}," conflicts (409 Conflict)"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["When you create or update an identity with an ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["internalId"]}," that's already used by another ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["ACTIVE"]}," identity, the API returns ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["409 Conflict"]},"."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["This is a ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["deduplication feature"]}," that prevents you from accidentally creating multiple identities for the same customer."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"example-duplicate-internalid-on-create","__idx":4},"children":["Example: Duplicate ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["internalId"]}," on create"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Request:"]}]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","header":{"controls":{"copy":{}}},"source":"curl -X POST \"https://{base-url}/v3/identities\" \\\n  -H \"Authorization: Bearer <access_token>\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"identityType\": \"INDIVIDUAL\",\n    \"paymentRole\": \"BENEFICIARY\",\n    \"internalId\": \"customer-12345-uuid\",\n    \"individual\": {\n      \"firstName\": \"Bob\",\n      \"lastName\": \"Smith\",\n      \"address\": {\n        \"streetAddress\": [\"456 Oak Ave\"],\n        \"city\": \"Austin\",\n        \"stateOrProvince\": \"TX\",\n        \"postalCode\": \"78701\",\n        \"country\": \"US\"\n      }\n    }\n  }'\n","lang":"bash"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Response (409 Conflict)"]}]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"code\": \"CONFLICT\",\n  \"title\": \"Identity conflict\",\n  \"description\": \"An identity with the provided internalId already exists.\",\n  \"details\": [\n    {\n      \"field\": \"internalId\",\n      \"message\": \"An ACTIVE identity with internalId 'customer-12345-uuid' already exists (identityId: 99254c4f-f207-4792-a846-06928825018c)\"\n    }\n  ]\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"how-to-handle-409-conflict","__idx":5},"children":["How to handle 409 Conflict"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["When you receive a 409 Conflict:"]},{"$$mdtype":"Tag","name":"ol","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Look up the existing identity"]}," using the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["identityId"]}," from the error message"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Reuse the existing identity"]}," instead of creating a new one"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Update the existing identity"]}," if needed (for example, to add new PII or change ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["validatePayoutRails"]},")"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Investigate your upstream systems"]}," if you're unexpectedly getting conflicts (this may indicate duplicate customer records in your CRM or database)"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Example: Look up the existing identity"]}]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","header":{"controls":{"copy":{}}},"source":"curl -X GET \"https://{base-url}/v3/identities/99254c4f-f207-4792-a846-06928825018c\" \\\n  -H \"Authorization: Bearer <access_token>\"\n","lang":"bash"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["If the existing identity is correct, use it for your payment or financial instrument creation. If it needs updates, use ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["PUT /v3/identities/{identity-id}"]}," to modify it."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"example-duplicate-internalid-on-update","__idx":6},"children":["Example: Duplicate ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["internalId"]}," on update"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Request:"]}]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","header":{"controls":{"copy":{}}},"source":"curl -X PUT \"https://{base-url}/v3/identities/1d927c62-45fa-4f42-b9f8-8210e1a111bb\" \\\n  -H \"Authorization: Bearer <access_token>\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"internalId\": \"customer-99999\"\n  }'\n","lang":"bash"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["If ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["customer-99999"]}," is already used by a different ACTIVE identity:"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Response (409 Conflict)"]}]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"code\": \"CONFLICT\",\n  \"title\": \"Identity conflict\",\n  \"description\": \"The provided internalId already exists on a different identity.\",\n  \"details\": [\n    {\n      \"field\": \"internalId\",\n      \"message\": \"An ACTIVE identity with internalId 'customer-99999' already exists (identityId: 7ea3399c-1234-5678-8d8f-d320ea406630)\"\n    }\n  ]\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"best-practices-for-internalid-conflicts","__idx":7},"children":["Best practices for ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["internalId"]}," conflicts"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Use stable upstream keys"]}," – Use your CRM customer ID, core banking customer ID, or KYC master record ID as ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["internalId"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Implement idempotent create logic"]}," – When creating identities, catch 409 errors and look up the existing identity instead of failing"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Avoid PII in ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["internalId"]}]}," – Don't use emails, phone numbers, or national IDs directly; use opaque identifiers"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Monitor conflicts"]}," – Track 409 errors in your logs to identify data quality issues in upstream systems"]}]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"get-an-identity-by-id-and-version","__idx":8},"children":["Get an identity by ID (and version)"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Use ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["GET /v3/identities/{identity-id}"]}," to retrieve a specific identity."]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["If you omit the version query parameter, the latest version is returned."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["To retrieve a specific version, include ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["?version={version-number}"]},"."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Example: Get the latest version"]}]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","header":{"controls":{"copy":{}}},"source":"curl -X GET \"https://{base-url}/v3/identities/9d839f58-7fd3-4913-a27e-48d31973d3f9\" \\\n  -H \"Authorization: Bearer <access_token>\"\n","lang":"bash"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Response (200 OK)"]}]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"identityId\": \"9d839f58-7fd3-4913-a27e-48d31973d3f9\",\n  \"identityState\": \"ACTIVE\",\n  \"nickName\": \"nickName\",\n  \"tags\": [\"tag1\"],\n  \"version\": \"2\",\n  \"schemaVersion\": \"1.0.0\",\n  \"createdAt\": \"2025-10-01T18:46:41.833Z\",\n  \"updatedAt\": \"2025-10-01T18:46:47.430Z\",\n  \"identityType\": \"BUSINESS\",\n  \"paymentRole\": \"BENEFICIARY\",\n  \"internalId\": \"counterparty-7890\",\n  \"business\": {\n    \"businessName\": \"Widgets Org\",\n    \"address\": {\n      \"streetAddress\": [\"123 Example MA\"],\n      \"country\": \"US\",\n      \"city\": \"Boston\",\n      \"stateOrProvince\": \"MS\",\n      \"postalCode\": \"12345\"\n    },\n    \"email\": \"fake@example.com\",\n    \"phone\": \"+1234567890\",\n    \"registration\": [\n      {\n        \"number\": \"123ABC\",\n        \"type\": \"INCORPORATION_CERTIFICATE\"\n      }\n    ],\n    \"incorporationCountry\": \"US\"\n  }\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Example: Get a specific version"]}]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","header":{"controls":{"copy":{}}},"source":"curl -X GET \"https://{base-url}/v3/identities/9d839f58-7fd3-4913-a27e-48d31973d3f9?version=1\" \\\n  -H \"Authorization: Bearer <access_token>\"\n","lang":"bash"},"children":[]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"info","name":"Versioned lookups"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Use versioned lookups when you need to:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Compare changes over time for audit"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Reconcile payments that used an earlier version of an identity"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["If the identity or version does not exist, the service returns ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["404 Not Found"]},"."]}]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"get-an-identity-by-internal-id","__idx":9},"children":["Get an identity by internal ID"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Use ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["GET /v3/identities/by-internal-id/{internal-id}"]}," to look up an identity directly by your client-provided ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["internalId"]},", without needing to know the server-generated ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["identityId"]}," first."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["This endpoint is especially useful for:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Resolving the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["identityId"]}," of an existing customer identity when you only have your own reference (for example, a CRM customer ID)."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Implementing idempotent create-or-fetch workflows without storing ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["identityId"]}," separately."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Handling 409 Conflict responses by immediately looking up the conflicting identity."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Example: Look up an identity by internal ID"]}]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","header":{"controls":{"copy":{}}},"source":"curl -X GET \"https://{base-url}/v3/identities/by-internal-id/customer-12345-uuid\" \\\n  -H \"Authorization: Bearer <access_token>\"\n","lang":"bash"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Response (200 OK)"]}]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"identityId\": \"99254c4f-f207-4792-a846-06928825018c\",\n  \"identityState\": \"ACTIVE\",\n  \"identityType\": \"INDIVIDUAL\",\n  \"paymentRole\": \"ORIGINATOR\",\n  \"internalId\": \"customer-12345-uuid\",\n  \"nickName\": \"Alice Sender USD\",\n  \"tags\": [\"sender\", \"priority\"],\n  \"version\": \"1\",\n  \"schemaVersion\": \"1.0.0\",\n  \"createdAt\": \"2025-10-01T18:46:41.833Z\",\n  \"updatedAt\": \"2025-10-01T18:46:47.430Z\",\n  \"individual\": {\n    \"firstName\": \"Alice\",\n    \"lastName\": \"Chen\",\n    \"dateOfBirth\": \"1990-05-14\",\n    \"citizenship\": \"US\",\n    \"address\": {\n      \"streetAddress\": [\"123 Main Street\"],\n      \"city\": \"San Francisco\",\n      \"stateOrProvince\": \"CA\",\n      \"postalCode\": \"94105\",\n      \"country\": \"US\"\n    }\n  }\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"info","name":"Only ACTIVE identities"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["This endpoint returns the identity only if it is currently ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["ACTIVE"]},". If the identity exists but has been deactivated or blocked, the service returns ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["404 Not Found"]},"."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The lookup is scoped to your organization. ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["internalId"]}," values from other organizations do not conflict."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Error responses:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["404 Not Found"]}," – no ACTIVE identity with the specified ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["internalId"]}," exists in your organization"]}]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"list-identities","__idx":10},"children":["List identities"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Use ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["GET /v3/identities"]}," to retrieve identities for your organization with optional filters and pagination."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Supported query parameters:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["payment-role"]}," – filter by payment role (ORIGINATOR or BENEFICIARY)"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["nick-name"]}," – filter by nickname (exact match)"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["limit"]}," – maximum number of identities to return (1–100, default 10)"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["next-token"]}," – opaque token returned from a previous response, used to fetch the next page"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Example: List identities by role"]}]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","header":{"controls":{"copy":{}}},"source":"curl -X GET \"https://{base-url}/v3/identities?payment-role=BENEFICIARY&limit=2\" \\\n  -H \"Authorization: Bearer <access_token>\"\n","lang":"bash"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Response (200 OK)"]}]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"data\": [\n    {\n      \"identityId\": \"0116bacc-ffbf-4fa2-a29c-ecd9ea346806\",\n      \"identityType\": \"BUSINESS\",\n      \"paymentRole\": \"BENEFICIARY\",\n      \"createdAt\": \"2025-10-01T16:14:13.200Z\",\n      \"updatedAt\": \"2025-10-01T16:14:15.763Z\",\n      \"identityState\": \"ACTIVE\",\n      \"nickName\": \"testNickName\",\n      \"tags\": [\"tag1\"],\n      \"version\": 2,\n      \"schemaVersion\": \"1.0.0\",\n      \"internalId\": \"counterparty-7890\"\n    },\n    {\n      \"identityId\": \"1d927c62-45fa-4f42-b9f8-8210e1a111bb\",\n      \"identityType\": \"INDIVIDUAL\",\n      \"paymentRole\": \"ORIGINATOR\",\n      \"createdAt\": \"2025-10-01T17:20:05.111Z\",\n      \"updatedAt\": \"2025-10-01T17:20:06.500Z\",\n      \"identityState\": \"ACTIVE\",\n      \"nickName\": \"Alice Originator\",\n      \"tags\": [\"sender\", \"priority\"],\n      \"version\": 1,\n      \"schemaVersion\": \"1.0.0\",\n      \"internalId\": \"customer-12345-uuid\"\n    }\n  ],\n  \"nextToken\": \"eyJrZXkxIjoidmFsdWUifQ==\"\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["If you receive a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["nextToken"]},", pass it back as ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["next-token"]}," to fetch the next page:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","header":{"controls":{"copy":{}}},"source":"curl -X GET \"https://{base-url}/v3/identities?payment-role=BENEFICIARY&limit=2&next-token=eyJrZXkxIjoidmFsdWUifQ==\" \\\n  -H \"Authorization: Bearer <access_token>\"\n","lang":"bash"},"children":[]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"warning","name":"No identities found"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["If no identities match your filters, the service returns ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["404 Not Found"]},"."]}]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"update-an-identity","__idx":11},"children":["Update an identity"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Use ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["PUT /v3/identities/{identity-id}"]}," to update an existing identity."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Each successful update creates a ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["new identity version"]},". The ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["identityId"]}," never changes, and previous versions remain available for retrieval and audit. The request body supports ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["partial updates"]},". Only include the fields you want to change."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["You can update:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Metadata: ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["nickName"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["tags"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["PII: any field within ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["individual"]}," or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["business"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["internalId"]}," (must remain unique across all ACTIVE identities)"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["validatePayoutRails"]}," (re-validates PII against the specified rails)"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["identityType"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["paymentRole"]}," cannot be changed after creation."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["For complete examples, error handling, and guidance on updating BLOCKED identities, see ",{"$$mdtype":"Tag","name":"a","attributes":{"href":"/products/payments-direct-2/api-docs/tutorials/update-an-identity"},"children":["Update an identity"]},"."]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"deactivate-an-identity","__idx":12},"children":["Deactivate an identity"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Use ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["DELETE /v3/identities/{identity-id}"]}," to deactivate an identity."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Deactivation:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Sets the identity’s state to ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["DEACTIVATED"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Deactivates the identity’s associated ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["financial instruments"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Prevents any ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["new payments"]}," from using this identity"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Keeps historical versions available for audit"]}]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"warning","name":"Permanent"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Deactivation is ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["permanent"]},"; you cannot reactivate a deactivated identity."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Example: Deactivate an identity"]}]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","header":{"controls":{"copy":{}}},"source":"curl -X DELETE \"https://{base-url}/v3/identities/146f3c51-c313-47ce-b6f2-691c5a238b3e\" \\\n  -H \"Authorization: Bearer <access_token>\"\n","lang":"bash"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Response (204 No Content) – the identity is successfully deactivated."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Error responses:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["400 Bad Request"]}," – malformed request or invalid ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["identityId"]}," format"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["404 Not Found"]}," – identity does not exist"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["422 Unprocessable Entity"]}," – identity is already deactivated or cannot be deactivated (for example, due to internal constraints)"]}]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"error-handling-and-validation","__idx":13},"children":["Error handling and validation"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["All identity endpoints use a standard error response schema with:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["code"]}," – machine-readable error code"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["title"]}," – short human-readable summary"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["description"]}," – detailed explanation and remediation hints"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Common cases:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["400"]}," – missing or invalid fields in the request, or identity failing corridor-specific validation rules"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["404"]}," – identity not found (for a specific ID, version, or query)"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["409"]}," – ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["internalId"]}," conflict (another ACTIVE identity already uses the same ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["internalId"]},")"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["422"]}," – invalid lifecycle transition (for example, attempting to deactivate an already deactivated identity)"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["500"]}," – internal processing error; retry or contact support if persistent"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Refer to the general ",{"$$mdtype":"Tag","name":"a","attributes":{"href":"/products/payments-direct-2/api-docs/error-codes/api-errors"},"children":["Error handling"]}," section of the API docs for the full list of error codes."]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"next-steps","__idx":14},"children":["Next steps"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["For a deeper explanation of the identity model, see ",{"$$mdtype":"Tag","name":"a","attributes":{"href":"/products/payments-direct-2/api-docs/concepts/payment-identities"},"children":["Payment identities"]},"."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["For full update examples and guidance on immutable versioning, payout rail validation, and BLOCKED identity reactivation, see ",{"$$mdtype":"Tag","name":"a","attributes":{"href":"/products/payments-direct-2/api-docs/tutorials/update-an-identity"},"children":["Update an identity"]},"."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["To learn how to attach payout account details to identities (bank accounts, wallets, local payout rails), continue with ",{"$$mdtype":"Tag","name":"a","attributes":{"href":"/products/payments-direct-2/api-docs/tutorials/create-and-manage-financial-instruments"},"children":["Create and manage financial instruments"]},"."]}]}]},"headings":[{"value":"Create and manage identities","id":"create-and-manage-identities","depth":1},{"value":"Before you begin","id":"before-you-begin","depth":2},{"value":"Create an identity","id":"create-an-identity","depth":2},{"value":"Handling internalId conflicts (409 Conflict)","id":"handling-internalid-conflicts-409-conflict","depth":2},{"value":"Example: Duplicate internalId on create","id":"example-duplicate-internalid-on-create","depth":3},{"value":"How to handle 409 Conflict","id":"how-to-handle-409-conflict","depth":3},{"value":"Example: Duplicate internalId on update","id":"example-duplicate-internalid-on-update","depth":3},{"value":"Best practices for internalId conflicts","id":"best-practices-for-internalid-conflicts","depth":3},{"value":"Get an identity by ID (and version)","id":"get-an-identity-by-id-and-version","depth":2},{"value":"Get an identity by internal ID","id":"get-an-identity-by-internal-id","depth":2},{"value":"List identities","id":"list-identities","depth":2},{"value":"Update an identity","id":"update-an-identity","depth":2},{"value":"Deactivate an identity","id":"deactivate-an-identity","depth":2},{"value":"Error handling and validation","id":"error-handling-and-validation","depth":2},{"value":"Next steps","id":"next-steps","depth":2}],"frontmatter":{"title":"Create and manage identities","toc":{"enable":true,"maxDepth":2},"seo":{"title":"Create and manage identities"}},"lastModified":"2026-04-03T15:45:06.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/products/payments-direct-2/api-docs/tutorials/create-and-manage-identities","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}