# Participant directory API reference

Source: https://docs.settlemint.com/docs/api-reference/reference/participant-directory
List an organization's participants for a given address purpose and classify their wallet addresses as externally owned or smart wallets through the DALP Platform API.



A participant is any person, organization, asset, claim issuer, or add-on the platform tracks in an organization, and each one owns one or more wallet addresses. A recipient picker needs two things: the list of participants a caller is allowed to select, and the right wallet address for each one. The participant directory provides both. One endpoint lists participants for a chosen address purpose, with filtering, sorting, search, and optional token eligibility. A second endpoint returns a lookup map that labels each org wallet as an externally owned account or a smart wallet, so an interface can show the correct address pill without a per-row call.

Both endpoints are read-only. They report participants and wallet classifications that already exist. They do not create participants, register identities, or move assets. For authentication and base URL setup, see [Getting started](/docs/api-reference/reference/getting-started).

## Endpoints [#endpoints]

| Endpoint                                 | Use it for                                                                             |
| ---------------------------------------- | -------------------------------------------------------------------------------------- |
| `GET /api/v2/participants`               | List participants for an address purpose, with filtering, sorting, search, and paging. |
| `GET /api/v2/participants/address-kinds` | Look up which org wallet addresses are externally owned accounts versus smart wallets. |

The list endpoint uses the collection envelope with `data`, `meta`, and pagination `links`. The address-kinds endpoint uses the single-resource envelope with `data` and `links.self`. The active organization and system context bound every read, as described in [Organization and system scope](/docs/api-reference/reference/organization-system-scope).

## List participants [#list-participants]

`GET /api/v2/participants` returns participants for a single address purpose. The purpose decides which address the platform resolves for each participant, so it is required on every call.

| Purpose       | Address returned                                                    |
| ------------- | ------------------------------------------------------------------- |
| `transfer`    | The address that signs and pays for a transfer for the participant. |
| `identity`    | The participant's on-chain identity contract address.               |
| `participant` | The participant's primary wallet address.                           |

Each row in the result carries the resolved address for the requested purpose.

```bash
curl --globoff "https://your-platform.example.com/api/v2/participants?purpose=transfer&filter[kind]=person" \
  -H "x-api-key: YOUR_API_KEY"
```

```json
{
  "data": [
    {
      "id": "par_01HXYZ",
      "kind": "person",
      "address": "0x2546BcD3c84621e976D8185a91A922aE77ECEc30",
      "displayName": "Ada Lovelace"
    }
  ],
  "meta": {
    "total": 1
  },
  "links": {
    "self": "/v2/participants?purpose=transfer&page[offset]=0&page[limit]=50",
    "first": "/v2/participants?purpose=transfer&page[offset]=0&page[limit]=50",
    "prev": null,
    "next": null,
    "last": "/v2/participants?purpose=transfer&page[offset]=0&page[limit]=50"
  }
}
```

### Participant fields [#participant-fields]

| Field         | Type             | Description                                                                                          |
| ------------- | ---------------- | ---------------------------------------------------------------------------------------------------- |
| `id`          | string           | The participant identifier.                                                                          |
| `kind`        | string           | The participant kind, such as `person`, `organisation`, `asset`, `claim_issuer`, or `addon`.         |
| `address`     | string or `null` | The resolved address for the requested purpose. `null` when no address is resolved for that purpose. |
| `displayName` | string           | The human-readable name for the participant.                                                         |

### Query controls [#query-controls]

| Parameter                     | Description                                                                                 |
| ----------------------------- | ------------------------------------------------------------------------------------------- |
| `purpose`                     | Required. One of `transfer`, `identity`, or `participant`. Selects the resolved address.    |
| `filter[kind]`                | Restrict the list to one kind. Use `filter[kind][inArray]=person,organisation` for several. |
| `filter[q]`                   | Global search across the participant's searchable fields.                                   |
| `sortBy`                      | Sort by `displayName`, `address`, or `kind`. Defaults to `displayName`.                     |
| `sortDirection`               | `asc` or `desc`. Defaults to `asc`.                                                         |
| `page[offset]`, `page[limit]` | Page through the result. The default page is 50 rows, up to 200.                            |

The list returns a single global `meta.total` for the current filters. It does not return per-kind facet counts, because the directory is built for address selection rather than kind breakdowns.

### Filter to eligible token recipients [#filter-to-eligible-token-recipients]

Add the `eligibleForToken` filter to narrow the list to participants who can receive a specific token. Supply the token address and the recipient action you want to check, such as a transfer or a mint.

```bash
curl --globoff "https://your-platform.example.com/api/v2/participants?purpose=transfer&eligibleForToken[tokenAddress]=0x71C7656EC7ab88b098defB751B7401B5f6d8976F&eligibleForToken[action]=transfer" \
  -H "x-api-key: YOUR_API_KEY"
```

| Parameter                        | Description                                                                                              |
| -------------------------------- | -------------------------------------------------------------------------------------------------------- |
| `eligibleForToken[tokenAddress]` | The token to check recipients against.                                                                   |
| `eligibleForToken[action]`       | The recipient action to evaluate: `transfer`, `mint`, or `burn`. Defaults to `transfer`.                 |
| `eligibleForToken[reveal]`       | Set to `true` to keep address resolution active but show ineligible participants instead of hiding them. |

When the filter hides ineligible participants, the response reports how many were removed in `meta.eligibilityHiddenCount`. Use `reveal=true` to build a show-all view that still resolves the registered recipient address for each row.

### Who can list which participants [#who-can-list-which-participants]

What a caller sees depends on the `userSearch` permission for the active system.

* A caller with the `userSearch` permission sees the full participant directory, including people, organizations, and claim issuers.
* A caller without that permission sees only `asset` and `addon` participants, the entries that do not expose the organization's member directory.

When a kind filter requests only kinds the caller cannot see, the endpoint returns a valid empty result rather than an error: `data` is empty and `meta.total` is `0`. Treat a blank directory you did not expect as a possible permission gap, not proof that the organization has no participants.

## Classify participant wallet addresses [#classify-participant-wallet-addresses]

`GET /api/v2/participants/address-kinds` returns a lookup map that labels each person and organization participant wallet as an externally owned account or a smart wallet. A picker reads it once and renders the correct label per address, with no extra call per row.

```bash
curl --globoff "https://your-platform.example.com/api/v2/participants/address-kinds" \
  -H "x-api-key: YOUR_API_KEY"
```

```json
{
  "data": {
    "0x2546bcd3c84621e976d8185a91a922ae77ecec30": "eoa",
    "0x71c7656ec7ab88b098defb751b7401b5f6d8976f": "smart-wallet"
  },
  "links": {
    "self": "/v2/participants/address-kinds"
  }
}
```

The `data` object maps each lowercase wallet address to its kind. The kind is `eoa` for an externally owned account and `smart-wallet` for a smart wallet. The map covers the EOA and smart-wallet addresses owned by person and organization participants in the active organization.

This endpoint is gated on the same `userSearch` permission as the directory list. A caller without the permission receives an empty map: `data` is `{}` and `links.self` still points at the endpoint. An empty map for a caller you expected to be privileged points to a permission gap rather than an organization with no wallets.

## When to use it [#when-to-use-it]

Use these endpoints when you need to:

* Populate a recipient or address picker with the participants a caller is allowed to select.
* Resolve the right address for a given purpose by choosing `transfer`, `identity`, or `participant`.
* Narrow a recipient list to participants eligible to receive a specific token for a transfer, mint, or burn.
* Label each address in a picker as an externally owned account or a smart wallet from a single lookup map.

To read a single participant's activity feed rather than the directory, see [Participant activity](/docs/api-reference/reference/participant-activity). To read a participant's role assignments, see [Participant role assignments](/docs/api-reference/reference/participant-role-assignments).