# Create a new identity (v2) - Legacy

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).

Endpoint: POST /v2/identities
Version: 2025.11
Security: Bearer

## Request fields (application/json):

  - `piiData` (object, required)
    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.

  - `identityType` (string, required)
    The type of the identity
    Enum: "SENDER", "BENEFICIARY", "ORIGINATOR"

  - `nickName` (string)
    The nickname for the identity provided at the time of identity creation
    Example: "MyCompany"

  - `useCaseType` (string, required)
    Classification of the identity:
  • INDIVIDUAL - A natural person.
  • BUSINESS - A legal entity such as a company or institution.
    Enum: "INDIVIDUAL", "BUSINESS"

## Response 201 fields (application/json):

  - `identityId` (string, required)
    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"

  - `version` (integer, required)
    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 400 fields (application/json):

  - `status` (integer, required)
    The HTTP status code of the error
    Example: 404

  - `errors` (array, required)

  - `errors.code` (string, required)
    Unique identifier of an error
    Example: "SYS_100"

  - `errors.title` (string, required)
    Error message providing a brief summary of the error
    Example: "No identity exists for identityId"

  - `errors.type` (string, required)
    Identifies the problem type
    Example: "USER_VALIDATION_ERROR"

  - `errors.description` (string, required)
    Provides more technical information
    Example: "Unable to get identity. Identity ID should be in UUID format"

  - `errors.timestamp` (string, required)
    The time when this error occurred, specified in UTC.
    Example: "2023-11-02T18:26:00.000123Z"

  - `timestamp` (string)
    The timestamp of the error
    Example: "2023-11-02T18:26:00.000Z"