Skip to content

Get an identity by ID

Request

Retrieve a specific identity by ID.

If version is not provided, the latest version is returned.

Security
Bearer
Path
identity-idstringrequired

The ID of the identity to retrieve.

Example:2f4ac57f-c5ba-4051-b51f-b3565778717b
Query
versionstring

Specific version to retrieve. If omitted, returns the latest version.

Example:version=2
curl -i -X GET \
  'https://docs.ripple.com/_mock/products/payments-direct-2/api-docs/payments-direct-api/payments-direct-2-api/v3/identities/2f4ac57f-c5ba-4051-b51f-b3565778717b?version=2' \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>'

Responses

Identity details.

Bodyapplication/json
identityTypestringrequired

The type of the identity

Enum ValueDescription
BUSINESS

Identity associated with an institution or business

INDIVIDUAL

Identity associated with an individual

Example:"BUSINESS"
paymentRolestringrequired

The payment role of the identity

Enum ValueDescription
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 ValueDescription
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": "BENEFICIARY",
  "business": {
    "businessName": "Widgets Org",
    "address": { … },
    "email": "fake@example.com",
    "phone": "+1234567890",
    "registration": [ … ],
    "incorporationCountry": "US"
  }
}