Skip to content

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) and Identity matching (v2).

OperationMethodDescription
Create a new identity (v2)POSTCreate a new v2 identity.
Get a list of identities (v2)GETGet a list of existing v2 identities.
Get an identity by ID (v2)GETGet a v2 identity by its unique ID.
Delete an identity (v2)DELETEDeactivate a v2 identity.
Operations

Create a new identity (v2) - Legacy

Request

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, or PrvtId.Othr.Id when it is INDIVIDUAL. The value is normalized (ASCII whitespace and punctuation removed, then uppercased) and hashed per tenant. If an active identity with the same key and identityType already exists, the request does not create a new identity. It writes the new version from the request body in full (piiData and nickName are replaced, not merged) and returns 201 with the existing identityId and its version incremented. If there is no match, a new identity is created at version 1.

If piiData contains no value at that path, no match key is recorded and the request always creates a new identity. Whether the field is present depends on the data requirements for the corridor, currency, use case, and payout method you are sending on.

Two identities cannot share the same match key and identityType within a tenant. To register a second bank account for the same party, deactivate the existing identity first, which is permanent, or use the v3 identities API, which does not match on OrgId.Othr.Id or PrvtId.Othr.Id. v3 keys identities on a client-supplied internalId and rejects a create whose internalId already belongs to an active identity with 409, so two accounts for one party are created with distinct internalId values.

For the full behavior, including how to hold two bank accounts for one payee and what happens when two payees share an ID number, see Identity matching (v2).

Security
Bearer
Bodyapplication/jsonrequired
piiDataobjectrequired

PII data in JSON format.

You must use the correct piiData schema for the type of identity you want to create.

Note: Reach out to your Ripple liaison to get this schema.

identityTypestringrequired

The type of the identity

Enum ValueDescription
BENEFICIARY

Identity associated with the beneficiary.

ORIGINATOR

Identity associated with the party originating the payment.

Example:"BENEFICIARY"
nickNamestring

The nickname for the identity provided at the time of identity creation

Example:"MyCompany"
useCaseTypestringrequired

Classification of the identity: • INDIVIDUAL - A natural person. • BUSINESS - A legal entity such as a company or institution.

Enum:"INDIVIDUAL""BUSINESS"
Example:"BUSINESS"
curl -i -X POST \
  https://docs.ripple.com/_mock/products/payments-direct-2/v2025.11/api-docs/payments-direct-api/payments-direct-2-api/v2/identities \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "piiData": {},
    "identityType": "BENEFICIARY",
    "nickName": "MyCompany",
    "useCaseType": "BUSINESS"
  }'

Responses

successful operation

Bodyapplication/json
identityIdstringrequired

The unique ID of the identity. When the request matched an existing identity, this is that existing identity's ID rather than a new one. Check version to tell the two cases apart.

Example:"2f4ac57f-c5ba-4051-b51f-b3565778717b"
versionintegerrequired

The version number of the identity. 1 means a new identity was created. A value greater than 1 means the request matched an existing identity and a new version was added to it.

Example:2
Response
{
  "identityId": "2f4ac57f-c5ba-4051-b51f-b3565778717b",
  "version": 2
}