# 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/products/payments-direct-2/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/products/payments-direct-2/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/products/payments-direct-2/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/products/payments-direct-2/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. The request body replaces the identity's metadata and PII, so send every field the identity should keep. Optiona
 - [DELETE /v3/identities/{identity-id}](https://docs.ripple.com/products/payments-direct-2/api-docs/payments-direct-api/payments-direct-2-api/identitiesv3/deactivateidentityv3.md): Deactivate an identity. Deactivation is permanent and prevents further use in payments. The identity's financial instrument remains readable, but you can no longer update or deactivate it, or add a n
 - [GET /v3/identities/by-internal-id/{internal-id}](https://docs.ripple.com/products/payments-direct-2/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/products/payments-direct-2/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/products/payments-direct-2/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/products/payments-direct-2/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/products/payments-direct-2/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 request replaces the label and the rail-specific details, so include the rail-specific object with all
 - [DELETE /v3/identities/{identity-id}/financial-instruments/{financial-instrument-id}](https://docs.ripple.com/products/payments-direct-2/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.
