# Get an identity by Internal ID (v3)

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.04
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)
    Optional client-provided unique identifier for idempotency and deduplication. 
Must be unique across all active identities within your tenant. Duplicate values will result in a 409 Conflict error.
    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.
    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.

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