---
toc:
  enable: true
  maxDepth: 2
exclude: true
excludeFromSearch: true
---

# 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](#get-a-list-of-identities) by identity type.
1. [Get an identity by ID](#get-an-identity-by-id) to serve as a business identity.

{% admonition type="info" name="Note" %}
While this tutorial focuses on getting a `BENEFICIARY`, the process is similar for an `ORIGINATOR`.
{% /admonition %}

## Prerequisite

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

* An [access token](/api-docs/tutorials/request-an-access-token/) to access secured API endpoints.

---

## Get a list of identities

To get a list of identities, use the [get a list of identities](/api-docs/payments-direct-api/reference/#operation/getIdentitiesV2) 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.


```bash
curl -i -X GET \
  'https://api.test.ripple.com/v2/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.

{% code-snippet
  file="../payments-direct-api/examples/list-identities-example.json"
  language="yaml"
/%}


---

## Get an identity by ID

<p>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](/api-docs/payments-direct-api/reference/#operation/getIdentityByIdV2) operation to view the details of the identity.</p>

```bash
curl -i -X GET \
  'https://api.test.ripple.com/v2/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.

{% admonition type="info" name="Note" %}
The response will return the latest version of the identity unless you specify a `version` in the query parameter.
{% /admonition %}

{% code-snippet
  file="../payments-direct-api/examples/get-beneficiary-business-identity.json"
  language="yaml"
/%}