Skip to main content
The Mobile Data Disbursement API enables secure provisioning of mobile data bundles to one or multiple recipients. This endpoint supports both bulk distribution scenarios and individualized allocations while maintaining the same authentication and access control used across all Belio API services. Optionally, you can include SMS notifications to recipients after their data bundle has been successfully disbursed.

​
Prerequisites

Before using this endpoint, ensure you have:
  • An active campaign for mobile data disbursement — available from the Campaigns page.
  • There are two ways to get a Campaign ID:
  • Go to the Campaigns page and copy the ID by clicking the copy icon on the table as shown on the photo below. CampaignTableImage
  • Call the List Campaigns endpoint to retrieve all available campaigns and their IDs.
  • API client authorization — Ensure your API Client includes permission to perform mobile data disbursement via reward.mobile-data.disbursement authorization scope. These can be managed from the API Clients page.

​
Optional SMS Notifications

Messaging is optional. If messaging is omitted, the request disburses data only (no SMS). If messaging is used, SMS is sent after successful data disbursement and consumes SMS units independently of data units.

​
Messaging Configuration

When messaging is provided, messaging.serviceSelection is required.
  • DefaultService — uses an auto-configured/default Belio’s SMS service
  • SelfService — uses an explicitly provided SMS service ID (serviceId). View available services via List Services or Message Introduction .

​
SendToMany

Use SendToMany to send the same denomination to multiple phones. You may include a single messaging.message (max 960 characters) to notify all recipients. 
{
  "type": "SendToMany",
  "phones": ["+254712345678", "+254701234567"],
  "denomination": "1GB"
}

{
  "type": "SendToMany",
  "phones": ["+254712345678", "+254701234567"],
  "denomination": "1GB",
  "messaging": {
    "message": "Your 1GB bundle has been credited.",
    "serviceSelection": { "type": "DefaultService" }
  }
}

​
SendToEach

Use SendToEach to send different denomination values per recipient. Each disbursement may include an optional message, and you can mix recipients with and without messages. If any disbursement includes a message, the top-level messaging configuration becomes mandatory. If no disbursement includes a message, messaging is optional and can be omitted. 
{
  "type": "SendToEach",
  "messaging": {
    "serviceSelection": { "type": "SelfService", "serviceId": "svc_123" }
  },
  "disbursements": [
    { "phone": "+254712345678", "denomination": "2GB", "message": "You’ve received 2GB data." },
    { "phone": "+254701234567", "denomination": "500MB" }
  ]
}
  • API client authorization — Ensure your API Client includes permission to perform SMS sending via message.sms.send.oneway authorization scope. These can be managed from the API Clients page.

​
Delivery Receipts

You can include an optional receiptRequest to receive delivery receipts for data disbursement and (when messaging is used) SMS delivery status. Receipts may be delivered asynchronously and out of order.

​
Optional Delivery Tracking

You may include an optional receiptRequest object in the request body to receive webhook notifications when a disbursement attempt completes. When messaging is enabled, receipts can also cover SMS delivery status. Receipts may be delivered asynchronously and out of order. The receiptRequest object includes:
  • correlator — A unique client-defined identifier used to correlate the delivery receipt with the original request.
  • callbackUrl — A publicly accessible URL where delivery receipts will be pushed.
curl --request POST \
  --url https://api.belio.co.ke/data/{campaignId} \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
    ...
    "receiptRequest": {
      "correlator": "<unique-id>",
      "callbackUrl": "https://example.org/webhook"
    }
  }'
By using the Mobile Data Disbursement API, you can automate bandwidth provisioning workflows, enable bulk allocations, and maintain traceability through correlators and callback receipts—ensuring a reliable and auditable delivery process.