Skip to main content

Documentation Index

Fetch the complete documentation index at: https://developers.kulmipay.com/llms.txt

Use this file to discover all available pages before exploring further.

Beneficiaries are recipients that Kulmi Pay automatically saves to your account whenever you successfully disburse money to them. Rather than re-entering account details for every disbursement, you can look up saved recipients by name, account number, or provider — and use their details to pre-fill your next payout batch. Beneficiary accounts are also pre-validated, which reduces rejection rates in bulk disbursements.

​
List your beneficiaries

Retrieve all saved recipients for your account. GET /api/v1/send-money/beneficiaries/
Response
[
  {
    "id": "ben_abc001",
    "name": "Alice Wanjiru",
    "account": "254712345678",
    "provider": "MPESA-B2C",
    "account_reference": null,
    "is_active": true
  },
  {
    "id": "ben_abc002",
    "name": "Nairobi Supplies Ltd",
    "account": "4012345",
    "provider": "PESALINK",
    "account_reference": "ACC-NBI-001",
    "is_active": true
  }
]
FieldTypeDescription
idstringUnique beneficiary identifier
namestringRecipient’s name
accountstringPhone number or bank account number
providerstringPayment provider used (e.g. MPESA-B2C, PESALINK)
account_referencestringOptional reference for PayBill or business accounts
is_activebooleanWhether the beneficiary is available for use

​
Filter by provider

Add a provider query parameter to return only recipients for a specific payment channel. 
GET /api/v1/send-money/beneficiaries/?provider=MPESA-B2C

​
Search by name or account

Use the search query parameter to find a recipient by name, account number, or account reference. 
GET /api/v1/send-money/beneficiaries/?search=Alice
You can combine filters and search in a single request: 
GET /api/v1/send-money/beneficiaries/?provider=MPESA-B2C&search=254712

​
Get your most frequently used recipients

Retrieve the top 5 recipients you disburse to most often for a given provider. Use this endpoint to power a quick-select UI or to pre-populate a bulk disbursement batch. GET /api/v1/send-money/beneficiaries/frequently_used/?provider=MPESA-B2C The provider parameter is required. Replace MPESA-B2C with the provider you want to query.
Response
[
  {
    "id": "ben_abc001",
    "name": "Alice Wanjiru",
    "account": "254712345678",
    "provider": "MPESA-B2C",
    "account_reference": null,
    "is_active": true
  },
  {
    "id": "ben_abc005",
    "name": "John Kamau",
    "account": "254798765432",
    "provider": "MPESA-B2C",
    "account_reference": null,
    "is_active": true
  }
]
Results are ordered by transaction frequency — the recipient you’ve paid most often appears first. Only active beneficiaries (is_active: true) are included.

​
How beneficiaries speed up bulk disbursements

When you include a beneficiary’s account details in a disbursement request, Kulmi Pay skips the account validation step because the account has already been verified through a successful previous transaction. This means:
  • Faster processing — no additional validation round-trip for known accounts.
  • Fewer rejections — you are reusing an account that has received a payment before.
  • Simpler batching — query your frequently used beneficiaries to build disbursement payloads programmatically.
To use a saved beneficiary in a send money request, copy the account, provider, and account_reference fields from the beneficiary record directly into your transaction payload when calling POST /api/v1/send-money/initiate/. You can also pass "validated_account": true in the transaction to signal that the account has already been verified.