List beneficiaries

GET

/api/global/beneficiaries

cURL

curl "https://api.payhero.africa/api/global/beneficiaries?page=1&per=20&kyc_level=tier_0&term=john" \
  -u "API_USERNAME:API_PASSWORD"

Returns the beneficiaries belonging to the account behind your API key, newest first. All filters combine.

Authorizations

basicAuth

Parameters

Query Parameters

page

integer

default: 1

1-indexed page number.

Example

per

integer

default: 20

Page size.

Example

term

string

Free-text search over first name, last name, email, phone and external reference.

Example

john

kyc_level

string

Allowed values: tier_0 full

Filter by KYC level.

Example

tier_0

is_active

boolean

Filter by the active flag.

Example

true

uuid

string format: uuid

Exact-match on a beneficiary UUID.

from

string format: date

Start of a created-at window. Must be sent together with to.

Example

2026-01-01

string format: date

End of a created-at window. Must be sent together with from.

Example

2026-09-05

Responses

200

A page of beneficiaries.

application/json

object

beneficiaries

Array<object>

A stored counterparty. Note that a few fields are named differently on the way out than on the way in: phone is returned as phone_number, and id_number as national_id.

object

integer

uuid

Send this as customer.customer_uuid on payments.

string format: uuid

first_name

string

last_name

string

surname

string | null

national_id

The id_number you sent.

string | null

date_of_birth

string | null format: date-time

gender

string | null

phone_number

The phone you sent.

string | null

email

string format: email

address

string | null

country

string

account_id

The PayHero account that owns this beneficiary, derived from your API key.

integer

account_name

string | null

account_number

string | null

account_type

string | null

customer_type

string

kyc_level

Recomputed on every write from the metadata actually present. Never settable.

string

Allowed values: tier_0 full

tier_0_lifetime_usd

number

is_active

boolean

created_at

string format: date-time

updated_at

string format: date-time

kyc

The beneficiary’s KYC standing, recomputed on every write. Read-only.

object

level

string

Allowed values: tier_0 full

full_kyc

boolean

missing_full_kyc_fields

Fields still needed to reach full. Send these to the update endpoint.

Array<string>

missing_reduced_kyc_fields

Fields still needed to reach tier_0. Non-empty only on a rejected create.

Array<string>

tier_0_lifetime_usd

Lifetime USD total this beneficiary has transacted while at tier_0.

number

tier_0_remaining_usd

Headroom left before full KYC becomes mandatory.

number

tier_0_limit_reached

boolean

tier_0_max_transaction_usd

Per-transaction ceiling while at tier_0.

number

tier_0_excluded_currencies

Currencies a tier_0 beneficiary can never transact in.

Array<string>

requires_additional_id

True when the country needs a second ID (Nigeria) and it has not been supplied.

boolean

pagination

object

count

integer

page

integer

per

integer

num_pages

integer

next_page

integer | null

prev_page

integer | null

Example

{
  "beneficiaries": [
    {
      "id": 94,
      "uuid": "a2e0434e-17ae-41b1-a1cf-1694ad63ee99",
      "first_name": "John",
      "last_name": "Doe",
      "national_id": "32460968",
      "date_of_birth": "1997-10-03T00:00:00Z",
      "phone_number": "+254712345678",
      "email": "john.doe@example.com",
      "address": "Moi Drive, Umoja",
      "country": "KE",
      "account_id": 63,
      "account_name": "John Doe",
      "account_number": "+254712345678",
      "account_type": "momo",
      "customer_type": "retail",
      "kyc_level": "tier_0",
      "tier_0_lifetime_usd": 0,
      "is_active": true,
      "kyc": {
        "level": "tier_0",
        "full_kyc": false,
        "missing_full_kyc_fields": [
          "address",
          "date_of_birth",
          "id_number",
          "id_type",
          "phone"
        ],
        "missing_reduced_kyc_fields": [],
        "tier_0_lifetime_usd": 0,
        "tier_0_remaining_usd": 200,
        "tier_0_limit_reached": false,
        "tier_0_max_transaction_usd": 20,
        "tier_0_excluded_currencies": [
          "BWP",
          "NGN",
          "ZAR"
        ],
        "requires_additional_id": false
      }
    }
  ],
  "pagination": {
    "count": 16,
    "page": 1,
    "per": 20,
    "num_pages": 1
  }
}

401

Missing or invalid Basic auth credentials.

application/json

object

error_code

string

error_message

string

status_code

integer

Example

{
  "error_code": "invalid_argument",
  "error_message": "the transaction amount is insufficient as it wont cater for cost: (4.62)",
  "status_code": 400
}