Get an identity

In this tutorial, we'll step through the API calls required to view the details of an existing identity.

Identities in Ripple Payments are objects that correspond to payment participants, such as payment originators and beneficiaries of payments. They contain all of the personally identifiable information (PII) connected to a specific individual or business to ensure proper compliance and proper routing.

This guide walks you through the API calls required to get an identity.

  1. Get a list of identities by identity type.
  2. Get an identity by ID to serve as a business identity.
Note
While this tutorial focuses on getting a BENEFICIARY, the process is similar for an ORIGINATOR.

Prerequisite

The following must be addressed before you can carry out the instructions in this tutorial:


Get a list of identities

To get a list of identities, use the get a list of identities operation.

By default the API returns a list of all identity types, but this tutorial narrows the result to beneficiaries.

To do this, we'll set identityType=BENEFICIARY as the query parameter.
Copy
Copied!
curl -i -X GET \
  'https://[customer-name].test.rnc.ripplenet.com/v4/identities?identityType=BENEFICIARY' \
  -H 'Authorization: YOUR_API_KEY_HERE'

Get a list of identities response

The API responds with a list of identities that have the identity type set to BENEFICIARY.

For this tutorial we're going to get more details about the identity whose nickName is "Successful Business Beneficiary". To do that, let's store the identityId value 11111111-abcd-2222-efgh-333333333333 for the beneficiary with a BUSINESS use case.

{
  • "data": [
    • {
      • "identityId": "11111111-abcd-2222-efgh-333333333333",
      • "nickName": "Successful Business Beneficiary",
      • "createdAt": "2023-11-02T18:26:00.000Z",
      • "identityType": "BENEFICIARY",
      • "useCaseType": "BUSINESS"
      },
    • {
      • "identityId": "11111111-abcd-4444-efgh-444444444444",
      • "nickName": "Successful Individual Beneficiary",
      • "createdAt": "2023-11-02T18:26:00.000Z",
      • "identityType": "BENEFICIARY",
      • "useCaseType": "INDIVIDUAL"
      }
    ]
}

Get an identity by ID

To get more details about a specific identity, let's use the identityId value 11111111-abcd-2222-efgh-333333333333 we stored in the previous step with the get an identity by ID operation to view the details of the identity.

Copy
Copied!
curl -i -X GET \
  'https://[customer-name].test.rnc.ripplenet.com/v4/identities/11111111-abcd-2222-efgh-333333333333' \
  -H 'Authorization: YOUR_API_KEY_HERE'

Get an identity by ID response

Here, the API response contains the full piiData structure and current status of the identity.

Note
The response will return the latest version of the identity unless you specify a version in the query parameter.
{
  • "identityId": "11111111-abcd-2222-efgh-333333333333",
  • "identityType": "BENEFICIARY",
  • "createdAt": "2023-11-02T18:26:00.000Z",
  • "identityState": "ACTIVE",
  • "nickName": "Successful Business Beneficiary",
  • "useCaseType": "BUSINESS",
  • "piiData": {
    },
  • "version": 2
}