Developer API

Plug the MBOS Communications Portal into MethodBox, Alternata, a marketplace listing or your own software. Every key belongs to a single workspace, so a request can only ever see that workspace's campaigns, people, rewards and results. Version 2.5.0,

Document version

Current

Published 2026-08-25 with portal release v2.4.0, This is the wording in force today.

Terms of use

Says plainly that you may invite more people than you have rewards for, and that rewards go to the first people to finish, up to the limit you set.
Confirms that the reward limit is enforced by the system itself, even when many people finish at the same moment.
Adds that SMS charges are shown before you send and recorded against each message.

Privacy notice

Explains which roles may see names, mobile numbers, message wording and link clicks, owner, campaign managers and reward managers only.
Confirms live dashboard updates carry counts and statuses only, never names, numbers or message wording.
Describes read-only developer keys receiving partly hidden mobile numbers and never a redeemable reward code.
Describes the answer-quality measurements taken during a survey, and what is deliberately not recorded.

API & developer docs

Reward codes are masked for read-only keys.
Keys can be given an expiry date and every call is logged.
Delivery receipts and reply webhooks require a per-workspace security header.

1. Get a key

A super admin creates one under Settings → Developer API. The key is shown once. Read-only keys see mobile numbers partly hidden and never receive a redeemable reward code; keys that may make changes see both in full.

2. Send it with every call

Header Authorization: Bearer YOUR_KEY (or x-api-key),

Base address https://www.methodbox.co.za

3. Handle the answers

Success returns { data: … }. Problems return { error: "plain message" } with 400, 401, 403, 404, 409 or 429. Every call is logged for the workspace to see.

Endpoints

GET

/api/public/v1/campaigns

read only

List the campaigns in the workspace the key belongs to.

Optional filters

status, Filter by campaign status, e.g. draft, active, closed.
limit, How many to return (max 200, default 50).

Example

curl -H "Authorization: Bearer $MBOS_API_KEY" \
  "https://www.methodbox.co.za/api/public/v1/campaigns?status=active"

What comes back

{ "data": [ { "id": "…", "name": "August NPS", "status": "active", "reward_cap": 500 } ], "count": 1 }

GET

/api/public/v1/campaigns/{id}

read only

One campaign with live totals for people, messages and rewards.

Example

curl -H "Authorization: Bearer $MBOS_API_KEY" \
  "https://www.methodbox.co.za/api/public/v1/campaigns/CAMPAIGN_ID"

What comes back

{ "data": { "id": "…", "totals": { "people": 1200, "completed": 431, "rewards_issued": 431 } } }

POST

/api/public/v1/campaigns/{id}/activate

needs change permission

Take a campaign live. Refused with 409 when there are not enough reward codes for the promise you made.

Example

curl -X POST -H "Authorization: Bearer $MBOS_API_KEY" \
  "https://www.methodbox.co.za/api/public/v1/campaigns/CAMPAIGN_ID/activate"

What comes back

{ "data": { "id": "…", "status": "active", "warning": null } }

GET

/api/public/v1/respondents

read only

List the people on a campaign. Mobile numbers are masked unless the key has write permission.

Optional filters

campaign_id, Limit to one campaign.
limit, How many to return (max 500, default 100).

Example

curl -H "Authorization: Bearer $MBOS_API_KEY" \
  "https://www.methodbox.co.za/api/public/v1/respondents?campaign_id=CAMPAIGN_ID"

What comes back

{ "data": [ { "id": "…", "name": "Thabo", "phone": "+27•••••7866", "status": "sent" } ], "numbers_masked": true }

POST

/api/public/v1/respondents

needs change permission

Add people to a campaign in bulk (up to 5 000 per call). Numbers are normalised to South African format and duplicates are skipped.

What you send

{ "campaign_id": "…", "people": [ { "name": "Thabo", "phone": "083 776 7866" } ] }

Example

curl -X POST -H "Authorization: Bearer $MBOS_API_KEY" -H "content-type: application/json" \
  -d '{"campaign_id":"CAMPAIGN_ID","people":[{"name":"Thabo","phone":"0837767866"}]}' \
  "https://www.methodbox.co.za/api/public/v1/respondents"

What comes back

{ "data": { "added": 1, "rejected": [] } }

GET

/api/public/v1/rewards

read only

List reward records and whether each one is still available, allocated or issued.

Optional filters

campaign_id, Limit to one campaign.

Example

curl -H "Authorization: Bearer $MBOS_API_KEY" \
  "https://www.methodbox.co.za/api/public/v1/rewards?campaign_id=CAMPAIGN_ID"

What comes back

{ "data": [ { "id": "…", "code": "VCHR-1", "status": "available" } ], "count": 1 }

POST

/api/public/v1/rewards

needs change permission

Load reward codes or links in bulk (up to 5 000 per call).

What you send

{ "campaign_id": "…", "rewards": [ { "code": "VCHR-1", "value": "R50", "type": "voucher_code" } ] }

Example

curl -X POST -H "Authorization: Bearer $MBOS_API_KEY" -H "content-type: application/json" \
  -d '{"campaign_id":"CAMPAIGN_ID","rewards":[{"code":"VCHR-1","value":"R50"}]}' \
  "https://www.methodbox.co.za/api/public/v1/rewards"

What comes back

{ "data": { "added": 1, "rejected": [] } }

GET

/api/public/v1/messages

read only

Delivery status and cost of every SMS, for reconciliation.

Optional filters

campaign_id, Limit to one campaign.
status, Filter by delivery status, e.g. delivered, failed.
since, ISO timestamp, only messages created after this.

Example

curl -H "Authorization: Bearer $MBOS_API_KEY" \
  "https://www.methodbox.co.za/api/public/v1/messages?status=delivered&since=2026-08-01T00:00:00Z"

What comes back

{ "data": [ { "id": "…", "status": "delivered", "provider_charge": 0.21, "provider_currency": "ZAR" } ] }

GET

/api/public/v1/reports/{campaignId}

read only

Reporting totals for a campaign: people, delivery, answers, rewards and spend.

Example

curl -H "Authorization: Bearer $MBOS_API_KEY" \
  "https://www.methodbox.co.za/api/public/v1/reports/CAMPAIGN_ID"

What comes back

{ "data": { "people_total": 1200, "responses_total": 431, "estimated_spend": 264.5, "currency": "ZAR" } }

POST

/api/public/webhooks/sms-status

needs change permission

Delivery receipts from an SMS network. Authenticated with the workspace delivery key header, not an API key.

Example

curl -X POST -H "x-mbos-webhook-secret: $DELIVERY_KEY" -H "content-type: application/json" \
  -d '{"messageId":"…","status":"DELIVERED"}' \
  "https://www.methodbox.co.za/api/public/webhooks/sms-status"

What comes back

{ "ok": true, "updated": 1 }

POST

/api/public/webhooks/sms-reply

needs change permission

Inbound replies from an SMS network. Uses the same delivery key header.

Example

curl -X POST -H "x-mbos-webhook-secret: $DELIVERY_KEY" -H "content-type: application/json" \
  -d '{"from":"+27837767866","text":"STOP"}' \
  "https://www.methodbox.co.za/api/public/webhooks/sms-reply"

What comes back

{ "ok": true }

Good manners

Mobile numbers may be sent in any South African format; we tidy them up to +27… before storing.
Bulk calls take up to 5 000 records. Send larger lists in batches.
Taking a campaign live is refused when there are fewer reward codes than the number of rewards you promised. load more rewards and try again.
Store keys as secrets in your own system, never in front-end code or a public repository.
Remove a key the moment an integration is retired; removal takes effect immediately.
Reward codes are money. A read-only key gets code: null with code_hidden: true, ask for a change-permission key if your integration must redeem them.
You may invite far more people than you have rewards; only the first finishers, up to your limit, are rewarded.

See also our compliance summary and privacy notice.