# Create an identity (v3)

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 this identity. Required for Originators, optional for Beneficiaries.
    Example: "customer-12345-uuid"

  - `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 are:

- INCORPORATION_CERTIFICATE — Certificate of Incorporation Number  
- TAX_ID — Tax Identification Number
    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"

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

- ALIEN_REGISTRATION — Alien Registration Number  
- CUSTOMER_ID — Customer Identification Number  
- DRIVERS_LICENSE — Driver’s License Number  
- PASSPORT — Passport Number  
- EMPLOYEE_ID — Employee ID  
- NATIONAL_ID_NUMBER — National ID  
- SSN — Social Security Number  
- TAX_ID — Tax ID

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

- MALE — Male identity  
- FEMALE — Female identity  
- OTHER — Other identity

## 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"

## Response 409 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"

## Response 500 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"