Skip to main content
GET
List recipients

Authorizations

Authorization
string
header
required

Server API key, scoped. pk_test_ keys hit the sandbox tenant.

Headers

X-Request-Id
string

Optional client correlation id, up to 128 characters. It is not echoed: the response's X-Request-Id is always our own req_… id. We log your value with the request as client_request_id, so support can find a request by either id. A longer value is refused with 400 parameter_invalid.

Maximum string length: 128

Query Parameters

limit
integer
default:25

Page size, 1–100.

Required range: 1 <= x <= 100
after
string

Cursor from the previous page's next_cursor. Returns older items. Don't send with before.

before
string

Cursor for the reverse direction: returns the items newer than this one. The page is still sorted newest first; has_more and next_cursor then continue in the same (newer) direction, so pass next_cursor as before to keep paging towards the newest items. Don't send with after.

q
string

Free-text search.

Maximum string length: 200
include
enum<string>

Set to total_count to add total_count to the list response.

Available options:
total_count
status
string[]

Comma-separated. Default active.

Examples:
currency
enum<string>

Only recipients in this currency. ISO 4217. Only NGN is live at launch; others return 422 currency_not_enabled.

Available options:
NGN,
USD,
GBP,
EUR,
GHS,
KES
sort
enum<string>
default:-created_at

-created_at (default, newest first) or -last_paid_at (most recently paid first, never-paid last; the order of the Recipients table and the "Saved" chips in Pay).

Available options:
-created_at,
-last_paid_at

Response

A page of recipients.

Cursor page. Domain files compose this with allOf and set data.items.

object
string
required
Allowed value: "list"
data
object[]
required

Recipients.

has_more
boolean
required

True when another page exists.

next_cursor
string | null

Cursor for the next page in the same direction: pass it as after if this page was read with after (or no cursor), as before if it was read with before. Null when has_more is false.

total_count
integer

Only when include=total_count was sent.