> For the complete documentation index, see [llms.txt](https://docs.papayaglobal.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.papayaglobal.com/api-reference/beneficiaries-management/get-beneficiaries-list.md). # Get Beneficiaries List The API is utilized to retrieve beneficiaries' details and fetch comprehensive information about all the beneficiaries associated with the organization account, with optional filters. Results are paginated, with a default list limit of 50 results. **`GET`** /payments/beneficiaries **Body Parameters Request** | Name | Location | Type | Format / Values | Description | Example | | -------- | ------------- | ------- | -------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------- | | skip | url parameter | integer | | The number of items to skip from result set | `?skip=3` | | take | url parameter | integer | default = 50 | The max number of items to return in the result set | `?take=50` | | id | url parameter | array | string | an array of specific id’s to return | `?id=15&id=34` | | country | url parameter | array | 2 letter ISO country code | a list of country id’s to filter by | `?country=US&country=GB&country=FR` | | currency | url parameter | array | 3 letter ISO currency code | a list of currency codes to filter by | `?currency=EUR` | | tag | url parameter | array | tag:name={value} | A list of tags and their values to filter by | `?tag:department=sales&tag:department=marketing` | | sort | url parameter | array | sort:field={direction} |

List of fields to sort by.
includes:

| `?sort:currency=ASC&sort:bank_details.account_country=DESC` | **Body Parameters Response** | Name | Type | Format / Values | Description | | -------------------------- | ----------- | ------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------- | | facets | object | | | | facets.countries | object | | Breakdown of countries and the count of beneficiaries mapping to them in the entire result set | | facets.currencies | object | | Breakdown of currencies and the count of beneficiaries mapping to them in the entire result set | | facets.user\_tags | object | | Breakdown of user tags and the count of beneficiaries mapping to them in the entire result set | | items | array | object | | | items\[] | object | | | | items\[].payee.source.type | string | contact | Entity type (contact) | | items\[].id | string | | Unique id of beneficiary | | items\[].entity\_type | string | INDIVIDUAL, BUSINESS | | | items\[].name | | | | | items\[].account\_country | string | | | | items\[].currency | string | /^(\[A-Z]{3,3})$/ | The 3 letter ISO currency code | | items\[].active | boolean | | Is this beneficiary active for payments | | items\[].status | ActiveState | ACTIVE, ACTIVATING, REQUIRES\_INPUT, REQUIRES\_ATTENTION, DISABLED | | | items\[].user\_tags | object | | | | paging | Paging | | | | paging.skip | integer | | The number of items to skip in the result set | | paging.take | integer | | The max number of items to return in the result set | | paging.total | integer | | The total number of results matching the filters | **Request Example** ```json GET /payments/beneficiaries?currency=EUR¤cy=USD¤cy=AUD&sort:currency=ASC&sort:bank_details.account_country=DESC ``` **Response Examples** {% tabs %} {% tab title="200 - OK" %} ```json { "facets": { "countries": { "AU": 10, "FR": 1, "US": 5 }, "currencies": { "AUD": 10, "EUR": 1, "USD": 5 }, "user_tags": { "department": 16 } }, "items": [ { "type": "contact", "id": "6", "entity_type": "INDIVIDUAL", "name": "Jordan Anderson", "account_country": "AU", "currency": "AUD", "active": true, "status": "ACTIVE", "user_tags": { "department": "R&D" } }, { "type": "contact", "id": "12", "entity_type": "INDIVIDUAL", "name": "Brandon Taylor", "account_country": "AU", "currency": "AUD", "active": true, "status": "ACTIVE", "user_tags": { "department": "Marketing" } }, { "type": "contact", "id": "8", "entity_type": "INDIVIDUAL", "name": "Oliver Reynolds", "account_country": "AU", "currency": "AUD", "active": true, "status": "ACTIVE", "user_tags": { "department": "Marketing" } }, { "type": "contact", "id": "14", "entity_type": "INDIVIDUAL", "name": "Xavier Turner", "account_country": "AU", "currency": "AUD", "active": true, "status": "ACTIVE", "user_tags": { "department": "R&D" } }, { "type": "contact", "id": "10", "entity_type": "INDIVIDUAL", "name": "Caleb Rodriguez", "account_country": "AU", "currency": "AUD", "active": true, "status": "ACTIVE", "user_tags": { "department": "R&D" } }, { "type": "contact", "id": "7", "entity_type": "INDIVIDUAL", "name": "Natalie Clarke", "account_country": "AU", "currency": "AUD", "active": true, "status": "ACTIVE", "user_tags": { "department": "Operations" } }, { "type": "contact", "id": "13", "entity_type": "INDIVIDUAL", "name": "Lily Chang", "account_country": "AU", "currency": "AUD", "active": true, "status": "ACTIVE", "user_tags": { "department": "Sales" } }, { "type": "contact", "id": "9", "entity_type": "INDIVIDUAL", "name": "Maya Patel", "account_country": "AU", "currency": "AUD", "active": true, "status": "ACTIVE", "user_tags": { "department": "Sales" } }, { "type": "contact", "id": "15", "entity_type": "INDIVIDUAL", "name": "Sophia Brooks", "account_country": "AU", "currency": "AUD", "active": true, "status": "ACTIVE", "user_tags": { "department": "Operations" } }, { "type": "contact", "id": "11", "entity_type": "INDIVIDUAL", "name": "Stella Martinez", "account_country": "AU", "currency": "AUD", "active": true, "status": "ACTIVE", "user_tags": { "department": "Operations" } }, { "type": "contact", "id": "16", "entity_type": "INDIVIDUAL", "name": "Jean Dupont", "account_country": "FR", "currency": "EUR", "active": true, "status": "ACTIVE", "user_tags": { "department": "Marketing" } }, { "type": "contact", "id": "2", "entity_type": "INDIVIDUAL", "name": "Jason Patel", "account_country": "US", "currency": "USD", "active": true, "status": "ACTIVE", "user_tags": { "department": "R&D" } }, { "type": "contact", "id": "4", "entity_type": "INDIVIDUAL", "name": "Ethan Wang", "account_country": "US", "currency": "USD", "active": true, "status": "ACTIVE", "user_tags": { "department": "Marketing" } }, { "type": "contact", "id": "1", "entity_type": "INDIVIDUAL", "name": "Emily Anderson", "account_country": "US", "currency": "USD", "active": true, "status": "ACTIVE", "user_tags": { "department": "Sales" } }, { "type": "contact", "id": "3", "entity_type": "INDIVIDUAL", "name": "Olivia Garcia", "account_country": "US", "currency": "USD", "active": true, "status": "ACTIVE", "user_tags": { "department": "Operations" } }, { "type": "contact", "id": "5", "entity_type": "INDIVIDUAL", "name": "Sophia Rodriguez", "account_country": "US", "currency": "USD", "active": true, "status": "ACTIVE", "user_tags": { "department": "Sales" } } ], "paging": { "skip": 0, "take": 50, "total": 16 } } ``` {% endtab %} {% tab title="404 - Not found" %} ```json { "error": "not_found", "description": "Status standalone.api.job_202000_2662bee9-f30f-484e-b0a0-63689266bff6 could not be found", "error_code": 404, "error_info": { "error": "not_found", "description": "Status standalone.api.job_202000_2662bee9-f30f-484e-b0a0-63689266bff6 could not be found", "error_code": 404 } } ``` {% endtab %} {% endtabs %}