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: currency bank_details.account_country id bank_details.name	?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

GET /payments/beneficiaries?currency=EUR&currency=USD&currency=AUD&sort:currency=ASC&sort:bank_details.account_country=DESC

Response Examples

200 - OK

{
   "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
   }
}

404 - Not found

{
   "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
   }
}