# Identities (v2)

Use these API operations to manage your identities for **existing integrations** built on **Identity Management v2.**
**Versioning notes**
- v2 identities remain fully supported for ongoing operations.
- New integrations should use **v3**.

**Before you create identities:** `POST /v2/identities` matches on a party ID taken from `piiData`. A request that matches an existing identity adds a version to it instead of creating a second one, and the new version is built from the request body in full, replacing `piiData` and `nickName` rather than merging them. See [Create a new identity (v2)](#operation/createIdentityV2) and [Identity matching (v2)](../concepts/identity-matching.md).
| Operation | Method | Description |
|  --- | --- | --- |
| [Create a new identity (v2)](#operation/createIdentityV2) | POST | Create a new v2 identity. |
| [Get a list of identities (v2)](#operation/getIdentitiesV2) | GET | Get a list of existing v2 identities. |
| [Get an identity by ID (v2)](#operation/getIdentityByIdV2) | GET | Get a v2 identity by its unique ID. |
| [Delete an identity (v2)](#operation/deactivateIdentityV2) | DELETE | Deactivate a v2 identity. |

 - [POST /v2/identities](https://docs.ripple.com/pt-br/products/payments-direct-2/v2025.11/api-docs/payments-direct-api/payments-direct-2-api/identitiesv2/createidentityv2.md): Create a new identity, or add a new version to an existing one when the request matches. Before writing, the service derives a match key from `piiData`: `OrgId.Othr.Id` when `useCaseType` is `BUSINESS
 - [GET /v2/identities](https://docs.ripple.com/pt-br/products/payments-direct-2/v2025.11/api-docs/payments-direct-api/payments-direct-2-api/identitiesv2/getidentitiesv2.md): Get a list of identities that match the query parameters. **Note**: Depending on the number of identities in your account, not all of them may be returned even if they match your query parameters.
 - [GET /v2/identities/{identity-id}](https://docs.ripple.com/pt-br/products/payments-direct-2/v2025.11/api-docs/payments-direct-api/payments-direct-2-api/identitiesv2/getidentitybyidv2.md): Retrieve a specific identity by ID. If `version` is not provided, the latest version is returned.
 - [DELETE /v2/identities/{identity-id}](https://docs.ripple.com/pt-br/products/payments-direct-2/v2025.11/api-docs/payments-direct-api/payments-direct-2-api/identitiesv2/deactivateidentityv2.md): Deactivate an identity. Deactivation is permanent and prevents further use in payments. Historical versions remain available for audit. Deactivation also releases the identity's match key, so a later