# Get an identity by Internal ID

Retrieve a specific identity by its internal ID.

Behavior:
- Only returns identities in the ACTIVE state. Deactivated identities will result in an error.
- Always returns the latest version of the identity. Historical versions are not accessible through this endpoint.
- If no active identity exists for the given internal-id, a 404 is returned.

Endpoint: GET /v3/identities/by-internal-id/{internal-id}
Version: 2026.03
Security: Bearer

## Path parameters:

  - `internal-id` (string, required)
    The Internal ID of the identity to retrieve.
    Example: "customer-12345-uuid"

## 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
  * ACTIVE
  * DEACTIVATED
    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 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. Only sent to payout partners for ORIGINATOR identities.

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)
    State, province, or county of the business address, as defined by postal services.
    Example: "Massachusetts"

  - `business.address.postalCode` (string)
    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"

  - `business.localized` (object)
    Identity fields supplied in a non-Latin script, in addition to the Latin-script values
elsewhere on the identity. Populate the script block that the destination corridor
requires.

  - `business.localized.hanzi` (object)
    Localized identity fields in Chinese Hanzi characters (汉字).

  - `business.localized.hanzi.businessName` (string)
    Business legal name in Chinese Hanzi characters.
    Example: "上海示例贸易有限公司"

  - `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)
    Information that locates and identifies the state / county for the party, as defined by postal services
    Example: "Massachusetts"

  - `individual.address.postalCode` (string)
    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)
    Identification documents for the identity, such as a passport, national ID, or tax ID. Required for ORIGINATOR and BENEFICIARY identities on some corridors and optional on others; see the Payload schema utility for the corridors that require it. Also required for ORIGINATOR identities when your organization is configured for the Brazil (BR) jurisdiction, on every corridor, including corridors that do not otherwise require it. Jurisdiction comes from your organization's configuration, not from a value in the request. Where the field is required, omitting it fails identity create and update with 400 Bad Request (USR_111).
For accepted document types per corridor and role, see Accepted document types by corridor.

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

  - `individual.localized` (object)
    Identity fields supplied in a non-Latin script, in addition to the Latin-script values
elsewhere on the identity. Populate the script block that the destination corridor
requires.

  - `individual.localized.hanzi` (object)
    Localized identity fields in Chinese Hanzi characters (汉字).

  - `individual.localized.hanzi.firstName` (string)
    Individual given name in Chinese Hanzi characters.
    Example: "伟"

  - `individual.localized.hanzi.lastName` (string)
    Individual family name in Chinese Hanzi characters.
    Example: "张"

  - `individual.localized.hanzi.businessName` (string)
    Business name associated with the individual in Chinese Hanzi characters, for
trade payments.
    Example: "上海示例贸易有限公司"

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