Get an identity by Internal ID

Request

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.

Security

Bearer

Path

internal-idstringrequired

The Internal ID of the identity to retrieve.

Example:customer-12345-uuid

curl -i -X GET \
  https://docs.ripple.com/_mock/products/payments-direct-2/api-docs/payments-direct-api/payments-direct-2-api/v3/identities/by-internal-id/customer-12345-uuid \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>'

Responses

Identity details.

Bodyapplication/json

identityTypestringrequired

The type of the identity

Enum Value	Description
BUSINESS	Identity associated with an institution or business
INDIVIDUAL	Identity associated with an individual

Example:"BUSINESS"

paymentRolestringrequired

The payment role of the identity

Enum Value	Description
ORIGINATOR	Refers to originator identity
BENEFICIARY	Refers to beneficiary identity

Example:"BENEFICIARY"

internalIdstring

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"

originatorAccountNumberstring

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"

businessobject

PII data to support business and institutional identities

individualobject

Data for an individual

identityIdstring

Server-generated unique identifier of the identity.

Example:"2f4ac57f-c5ba-4051-b51f-b3565778717b"

identityStatestring

The state of the identity

ACTIVE
DEACTIVATED

Enum Value	Description
ACTIVE	The identity requested exists and is active.
DEACTIVATED	The identity requested has been deactivated.

Example:"ACTIVE"

nickNamestring

Optional human-readable alias set by the client.

Example:"nickName"

tagsArray of strings, <= 25 items

Optional labels used to categorize or filter identities.

validatePayoutRailsArray of strings

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.

versionstring

Sequential version number. Each successful PUT creates a higher version.

Example:2

schemaVersionstring

Schema version used to validate this identity, for example 1.0.0.

Example:"1.0.0"

createdAtstring, (date-time)

RFC 3339 timestamp when the identity was created.

Example:"2023-11-02T18:26:00.000Z"

updatedAtstring, (date-time)

RFC 3339 timestamp when the identity was last updated.

Example:"2023-11-03T18:26:00.000Z"

Response

{
  "identityId": "9d839f58-7fd3-4913-a27e-48d31973d3f9",
  "identityState": "ACTIVE",
  "nickName": "nickName",
  "tags": [
    "tag1"
  ],
  "version": "2",
  "schemaVersion": "1.0.0",
  "createdAt": "2025-10-01T18:46:41.833Z",
  "updatedAt": "2025-10-01T18:46:47.430Z",
  "identityType": "BUSINESS",
  "paymentRole": "ORIGINATOR",
  "internalId": "customer-12345-uuid",
  "business": {
    "businessName": "Widgets Org",
    "address": { … },
    "email": "fake@example.com",
    "phone": "+1234567890",
    "registration": [ … ],
    "incorporationCountry": "US"
  }
}