Skip to main content
GET
List Recipients
Provide account_id as a query parameter, or X-Account-Code as a header. If both are present, the query parameter takes precedence. Results are scoped to that authorized account and your organization, ordered by creation date, newest first. Use merchant_recipient_id for an exact match, optionally combined with country and national_entity. Every successful response contains data as an array and pagination as an object, including when only one recipient matches. No match returns HTTP 200 with data: [] and pagination.total: 0. limit defaults to 20 and accepts 1 to 100. offset defaults to 0 and accepts any nonnegative integer. Empty or repeated filter values are invalid. Each item contains the recipient’s base fields. Related collections such as withdrawal_methods, documentation, legal_representatives and onboardings are not enriched. Use Get Recipient for the full recipient.
Listing results, including merchant-ID filters, are eventually consistent. A recipient you just created, updated or deleted may take time to reflect in the list. Use Get Recipient by its Yuno ID for an immediate read from the primary store. Listing data-access failures return 503; they are not represented as empty results.
This list is available at GET /v1/recipients/list. The existing Get Recipient by Merchant ID lookup (GET /v1/recipients?merchant_recipient_id=...) remains unchanged: it returns a top-level recipient object and 400 RECIPIENT_NOT_FOUND when no recipient matches. Existing lookup callers do not need to migrate. GET by Yuno ID and PATCH/DELETE contracts are unchanged.

Authorizations

public-api-key
string
header
default:<Your public-api-key>
required
private-secret-key
string
header
default:<Your private-secret-key>
required

Headers

X-Account-Code
string<uuid>

Authorized account UUID when account_id is omitted. If both are present, account_id takes precedence.

Query Parameters

limit
integer
default:20

Maximum number of recipients to return

Required range: 1 <= x <= 100
offset
integer
default:0

Number of recipients to skip for pagination

Required range: x >= 0
national_entity
enum<string>

Filter recipients by national entity type

Available options:
INDIVIDUAL,
ENTITY
country
string

Filter recipients by country

merchant_recipient_id
string

Exact merchant recipient ID filter. Returns the same data array and pagination envelope; no match returns an empty array with total 0.

Minimum string length: 1
account_id
string<uuid>

Authorized account UUID. Required unless X-Account-Code is supplied in the request header.

Response

List of recipients retrieved successfully

data
object[]
pagination
object