# Update an identity (v3)

Update all fields of an existing identity. Supports updates to PII fields and metadata.
Each successful PUT creates a new version and preserves prior versions for audit.

Endpoint: PUT /v3/identities/{identity-id}
Version: 2026.03
Security: Bearer

## Path parameters:

  - `identity-id` (string, required)
    The ID of the identity to update.
    Example: "2f4ac57f-c5ba-4051-b51f-b3565778717b"

## Request fields (application/json):

  - `nickName` (string)
    The new 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"]

  - `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 200 fields (application/json):

  - `identityId` (string)
    Server-generated unique identifier of the identity.
    Example: "2f4ac57f-c5ba-4051-b51f-b3565778717b"

  - `identityState` (string)
    The state of the identity.
    Example: "ACTIVE"

  - `nickName` (string)
    Optional human-readable alias set by the client.
    Example: "nickName"

  - `tags` (array)
    Optional labels used to categorize or filter identities.
    Example: ["tag1"]

  - `validatePayoutRails` (array)
    List of payout methods where this identity is considered valid. Use this to indicate which payout methods (for example, US_ACH, EU_SEPA) the identity can be used with in payments.
    Example: ["BR_PIX"]

  - `version` (string)
    Sequential version number. Each successful PUT creates a higher version.
    Example: 2

  - `schemaVersion` (string)
    Schema version used to validate this identity, for example 1.0.0.
    Example: "1.0.0"

  - `createdAt` (string)
    RFC 3339 timestamp when the identity was created.
    Example: "2023-11-02T18:26:00.000Z"

  - `updatedAt` (string)
    RFC 3339 timestamp when the identity was last updated.
    Example: "2023-11-03T18:26:00.000Z"

  - `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 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 404 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"