# Identities

Use these API operations to manage your identities with **Identity Management v3** (recommended for all new integrations). For more information about identity management, see [Payment identities](/products/payments-direct-2/introduction/concepts/payment-identities) and [Financial instruments](/products/payments-direct-2/introduction/concepts/financial-instruments).
| Operation | Method | Description |
|  --- | --- | --- |
| [Create an identity](#operation/createIdentity) | POST | Create a new identity (INDIVIDUAL/BUSINESS; ORIGINATOR/BENEFICIARY). |
| [Get a list of identities](#operation/getIdentities) | GET | Retrieve a list of identities with optional filters (e.g., `paymentRole`, `identityType`). |
| [Get an identity by ID](#operation/getIdentityById) | GET | Retrieve a specific identity by `identityId` (latest version by default). |
| [Get an identity by internal ID](#operation/getIdentityByInternalId) | GET | Retrieve an active identity by client-provided `internalId`. |
| [Update an identity](#operation/putIdentity) | PUT | Update one or more fields; creates a new version. |
| [Deactivate an identity](#operation/deactivateIdentityV3) | DELETE | Set the identity state to `DEACTIVATED` (cannot be used for new payments). |
| [Add a financial instrument](#operation/createFinancialInstrument) | POST | Add a financial instrument to an identity. |
| [Get a list of financial instruments](#operation/getFinancialInstruments) | GET | Get a list of financial instruments for an identity. |
| [Get a financial instrument by ID](#operation/getFinancialInstrumentById) | GET | Get a specific financial instrument by `financialInstrumentId`. |
| [Update a financial instrument](#operation/putFinancialInstrument) | PUT | Update a financial instrument by `financialInstrumentId`. |
| [Deactivate a financial instrument](#operation/deactivateFinancialInstrumentV3) | DELETE | Deactivate a financial instrument by `financialInstrumentId`. |

 - [POST /v3/identities](https://docs.ripple.com/pt-br/products/payments-direct-2/v2026.03/api-docs/payments-direct-api/payments-direct-2-api/identitiesv3/createidentity.md): Create a new payment identity as an `ORIGINATOR` or `BENEFICIARY` for either an `INDIVIDUAL` or `BUSINESS`. The request body must follow the v3 identity schema and will be validated against corridor r
 - [GET /v3/identities](https://docs.ripple.com/pt-br/products/payments-direct-2/v2026.03/api-docs/payments-direct-api/payments-direct-2-api/identitiesv3/getidentities.md): Retrieve identities for your organization with optional filters. Use `limit` and `next-token` for pagination. The response includes a `data` array and an optional `nextToken`.
 - [GET /v3/identities/{identity-id}](https://docs.ripple.com/pt-br/products/payments-direct-2/v2026.03/api-docs/payments-direct-api/payments-direct-2-api/identitiesv3/getidentitybyid.md): Retrieve a specific identity by ID. If `version` is not provided, the latest version is returned.
 - [PUT /v3/identities/{identity-id}](https://docs.ripple.com/pt-br/products/payments-direct-2/v2026.03/api-docs/payments-direct-api/payments-direct-2-api/identitiesv3/putidentity.md): Update all fields of an existing identity. Supports updates to PII fields and metadata. Each successful PUT creates a new version and preserves prior versions for audit.
 - [DELETE /v3/identities/{identity-id}](https://docs.ripple.com/pt-br/products/payments-direct-2/v2026.03/api-docs/payments-direct-api/payments-direct-2-api/identitiesv3/deactivateidentityv3.md): Deactivate an identity and its financial instruments. Deactivation is permanent and prevents further use in payments. Historical versions remain available for audit.
 - [GET /v3/identities/by-internal-id/{internal-id}](https://docs.ripple.com/pt-br/products/payments-direct-2/v2026.03/api-docs/payments-direct-api/payments-direct-2-api/identitiesv3/getidentitybyinternalid.md): Retrieve a specific identity by its internal ID. **Behavior:** - Only returns identities in the `ACTIVE` state. Deactivated identities will result in an error. - Always returns the latest version of t
 - [POST /v3/identities/{identity-id}/financial-instruments](https://docs.ripple.com/pt-br/products/payments-direct-2/v2026.03/api-docs/payments-direct-api/payments-direct-2-api/identitiesv3/createfinancialinstrument.md): Create a financial instrument for the specified identity. The request body must include the payment rail (financialInstrumentType), currency or asset code, and the rail-specific details (for example,
 - [GET /v3/identities/{identity-id}/financial-instruments](https://docs.ripple.com/pt-br/products/payments-direct-2/v2026.03/api-docs/payments-direct-api/payments-direct-2-api/identitiesv3/getfinancialinstruments.md): List financial instruments for an identity.
 - [GET /v3/identities/{identity-id}/financial-instruments/{financial-instrument-id}](https://docs.ripple.com/pt-br/products/payments-direct-2/v2026.03/api-docs/payments-direct-api/payments-direct-2-api/identitiesv3/getfinancialinstrumentbyid.md): Retrieves one financial instrument associated with the specified identity. In the current release, one instrument is retrieved at most because only a single instrument is allowed per identity.
 - [PUT /v3/identities/{identity-id}/financial-instruments/{financial-instrument-id}](https://docs.ripple.com/pt-br/products/payments-direct-2/v2026.03/api-docs/payments-direct-api/payments-direct-2-api/identitiesv3/putfinancialinstrument.md): Update editable fields of a financial instrument including rail-specific details and labels. The financialInstrumentType is immutable after creation.
 - [DELETE /v3/identities/{identity-id}/financial-instruments/{financial-instrument-id}](https://docs.ripple.com/pt-br/products/payments-direct-2/v2026.03/api-docs/payments-direct-api/payments-direct-2-api/identitiesv3/deactivatefinancialinstrumentv3.md): Deactivate a financial instrument of an Identity. Deactivation is permanent and prevents further use in payments. Historical versions remain available for audit.