Beneficiaries

A beneficiary is a saved payout destination — a bank account, mobile-money number, or wallet — with a currency and optional default flag. Saving one lets you pay it with POST /v1/withdrawals using only beneficiary_id.

Only two operations are exposed on the public API: list and create. Editing and deleting beneficiaries are dashboard-only actions.

Endpoints

Method	Path	Scope	Success
GET	/v1/beneficiaries	read	200
POST	/v1/beneficiaries	payouts:write	201

Create a beneficiary

POST /v1/beneficiaries

Field	Type	Required	Notes
name	string	Yes	Account holder name
currency	string	Yes	Uppercased before storage
account_number	string	Yes	Destination account
bank_code	string	No	Bank code from GET /v1/banks
bank_name	string	No	Display name
country	string	No	Defaults to NG
kind	string	No	bank, mobile_money, or wallet. Defaults to bank
is_default	boolean	No	Marks this as the default for its currency

curl -X POST https://api.nuansis.co/v1/beneficiaries \
  -H "Authorization: Bearer $NUANSIS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Adaeze Okafor",
    "currency": "NGN",
    "account_number": "0123456789",
    "bank_code": "058",
    "bank_name": "Guaranty Trust Bank",
    "kind": "bank",
    "is_default": true
  }'

201 Created

{
  "data": {
    "id": 17,
    "name": "Adaeze Okafor",
    "currency": "NGN",
    "country": "NG",
    "account_number": "0123456789",
    "bank_code": "058",
    "bank_name": "Guaranty Trust Bank",
    "kind": "bank",
    "is_default": true,
    "created_at": "2026-10-18T10:26:07.412Z",
    "updated_at": "2026-10-18T10:26:07.412Z"
  },
  "meta": { "request_id": "6a7b8c9d-0e1f-4a2b-8c3d-4e5f6a7b8c9d" }
}

Setting is_default: true clears the default flag on every other beneficiary with the same currency, so there is at most one default per currency.

List beneficiaries

GET /v1/beneficiaries

Returns active beneficiaries, default first, then newest. There is no pagination parameter.

{
  "data": [
    {
      "id": 17,
      "name": "Adaeze Okafor",
      "currency": "NGN",
      "country": "NG",
      "account_number": "0123456789",
      "bank_code": "058",
      "bank_name": "Guaranty Trust Bank",
      "kind": "bank",
      "is_default": true,
      "created_at": "2026-10-18T10:26:07.412Z",
      "updated_at": "2026-10-18T10:26:07.412Z"
    }
  ],
  "meta": { "request_id": "7b8c9d0e-1f2a-4b3c-8d4e-5f6a7b8c9d0e" }
}

Deleted beneficiaries are soft-deleted (is_active = 0) and excluded from this list. There is no public endpoint to fetch a single beneficiary; keep the id you need, or match on account_number.

Use with withdrawals

curl -X POST https://api.nuansis.co/v1/withdrawals \
  -H "Authorization: Bearer $NUANSIS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "currency": "NGN", "amount": 25000, "beneficiary_id": 17 }'

See Payouts for the response and the pre-flight checks.

Common errors

Status	Code	Cause
400	invalid_request	Missing name/currency/account number, invalid kind, invalid is_default type
401	unauthorized	Missing or invalid API key
403	insufficient_scope	Key lacks payouts:write
429	rate_limited	Request budget exhausted