# Create an identity

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 rules where applicable.

On success, the API returns the new identityId and its initial version.

Endpoint: POST /v3/identities
Version: 2026.03
Security: Bearer

## Request fields (application/json):

  - `nickName` (string)
    The nickname for the identity
    Example: "nickName"

  - `validatePayoutRails` (array)
    The payout rails to validate the identity against
    Example: ["BR_PIX"]

  - `tags` (array)
    Tags are used to categorize the identity.
    Example: ["tag1"]

  - `identityType` (string, required)
    The type of the identity
    Example: "BUSINESS"

  - `paymentRole` (string, required)
    The payment role of the identity
    Example: "BENEFICIARY"

  - `internalId` (string)
    Client-provided unique identifier for idempotency and deduplication. Required for
ORIGINATOR identities; optional for BENEFICIARY identities. Must be unique across
all active identities in your organization. Duplicate values will result in a 409
Conflict error.

This is your own reference key, not the originator's account number. Use
originatorAccountNumber for that.
    Example: "customer-12345-uuid"

  - `originatorAccountNumber` (string)
    The originator's account number, or your customer identifier for the originator.
Required for ORIGINATOR identities on USD payments to China (CN_CFXPS);
optional elsewhere.

Must be unique across all active identities in your organization, including
BENEFICIARY identities. Duplicate values return a 409 Conflict error.

Corridor length and character limits apply to this value but are not enforced on
this field. See the corridor's Integration resources page.
    Example: "6222021001125874"

  - `business` (object)
    PII data to support business and institutional identities

  - `business.businessName` (string, required)
    Business Legal Name
    Example: "Widgets Org"

  - `business.address` (object, required)
    Holds general information about the business

  - `business.address.streetAddress` (array, required)
    Allows the street address of the business to be held
    Example: ["123 Example St. Boston, MA"]

  - `business.address.country` (string, required)
    Allows the country of the business to be held. Use Alpha-2 Code as defined in the [ISO CountryCode ISO 3166-1](https://www.iso.org/obp/ui/#search) list.
    Example: "US"

  - `business.address.city` (string, required)
    City
    Example: "Boston"

  - `business.address.stateOrProvince` (string, required)
    Information that locates and identifies the state / county for the individual, as defined by postal services.
    Example: "Massachusetts"

  - `business.address.postalCode` (string, required)
    Postal code for the business
    Example: "12345"

  - `business.email` (string)
    Address for electronic mail (e-mail).
    Example: "fake@example.com"

  - `business.phone` (string)
    Phone Number
    Example: 1234567890

  - `business.registration` (array)
    Unique and unambiguous way to identify a business or organization. An array of objects, each containing unique identification of an organization, as assigned by an institution, using an identification scheme.

  - `business.registration.number` (string, required)
    The unique identifier of the organization
    Example: "123ABC"

  - `business.registration.type` (string, required)
    Type of business identification document. Accepted values may vary by corridor and payment role. Some corridors accept only a subset of this list. See Ripple Docs for corridor-specific requirements.
    Example: "INCORPORATION_CERTIFICATE"

  - `business.incorporationCountry` (string)
    Information that locates and identifies the country, as defined by postal services where the organization was incorporated. Use Alpha-2 Code as defined in the ISO CountryCode ISO 3166-1 list.
    Example: "US"

  - `business.incorporationDate` (string)
    The date when the business was incorporated.
    Example: "2020-01-15"

  - `business.legalEntityType` (string)
    Type of legal entity to distinguish between Financial Institutions and Non-Financial Institutions.

This classification is used to determine regulatory treatment and compliance requirements for certain payment corridors.
    Example: "BANK_CENTRAL"

  - `individual` (object)
    Data for an individual

  - `individual.firstName` (string, required)
    First name of the individual
    Example: "John"

  - `individual.lastName` (string, required)
    Last name of the individual
    Example: "Smith"

  - `individual.address` (object, required)
    Holds general information about the individual

  - `individual.address.streetAddress` (array, required)
    Allows the street address of the individual to be held
    Example: ["123 Example St. Boston, MA"]

  - `individual.address.country` (string, required)
    Allows the Country of the individual to be held. Use Alpha-2 Code as defined in the [ISO CountryCode ISO 3166-1](https://www.iso.org/obp/ui/#search) list.
    Example: "US"

  - `individual.address.city` (string, required)
    City
    Example: "Boston"

  - `individual.address.stateOrProvince` (string, required)
    Information that locates and identifies the state / county for the party, as defined by postal services
    Example: "Massachusetts"

  - `individual.address.postalCode` (string, required)
    Postal code for the individual's address
    Example: "12345"

  - `individual.email` (string)
    Address for electronic mail (e-mail).
    Example: "fake@example.com"

  - `individual.phone` (string)
    Phone Number
    Example: 1234567890

  - `individual.identityDocuments` (array)
    Gathers identifying documentation

  - `individual.identityDocuments.idNumber` (string, required)
    Identification Number.
    Example: "123ABC"

  - `individual.identityDocuments.idType` (string, required)
    The type of identification document used to identify the identity. Accepted values may vary by corridor and payment role. Some corridors accept only a subset of this list. See Ripple Docs for corridor-specific requirements.

  - `individual.identityDocuments.expiryDate` (string)
    Expiration date of the identification document.
    Example: "2030-01-15"

  - `individual.dateOfBirth` (string)
    Date of Birth.
    Example: "2001-01-24"

  - `individual.countryOfBirth` (string)
    Country of Birth. Use Alpha-2 Code as defined in the [ISO CountryCode ISO 3166-1](https://www.iso.org/obp/ui/#search) list.
    Example: "US"

  - `individual.citizenship` (string)
    Alpha-2 country code for the nationality of the individual in ISO 3166-1 format.
    Example: "US"

  - `individual.gender` (string)
    Gender of the identity.
    Example: "FEMALE"

## Response 201 fields (application/json):

  - `identityId` (string, required)
    The unique ID of the identity
    Example: "2f4ac57f-c5ba-4051-b51f-b3565778717b"

  - `version` (string, required)
    The version number of the identity
    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"