Developer documentation
Fewsecond SMS API
Send Cameroon SMS, retrieve delivery status and receive HTTPS delivery callbacks through a JSON REST API.
Quick start
All REST request and response bodies use JSON. The base URL is:
https://www.fewsecond.net/webservices/api/v1- Exchange your account credentials for an eight-hour bearer token.
- Submit an SMS with a unique
Idempotency-Key. - Poll the message resource, or provide a public HTTPS callback URL.
Authentication
/auth/tokencurl -X POST 'https://www.fewsecond.net/webservices/api/v1/auth/token' \
-H 'Content-Type: application/json' \
-d '{"username":"YOUR_USERNAME","password":"YOUR_PASSWORD"}'The response contains access_token, token_type: Bearer and expires_in: 28800. Never place credentials or tokens in URLs, logs or shared source code.
Send an SMS
/messagescurl -X POST 'https://www.fewsecond.net/webservices/api/v1/messages' \
-H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
-H 'Content-Type: application/json' \
-H 'Idempotency-Key: order-20260901-0001' \
-d '{
"to": "237690032763",
"content": "Your verification code is 482915",
"sender": "SKYSOFT",
"client_id": "order-20260901-0001",
"callback_url": "https://client.example.com/webhooks/fewsecond"
}'callback_url, client_id and Idempotency-Key when you do not need a client callback. Fewsecond still records provider delivery updates.Fields
| Field | Required | Description |
|---|---|---|
to | Yes | Cameroon MSISDN, nine local digits or 12 digits beginning with 237. |
content | Yes | Message text, maximum 1600 bytes. |
sender | No | Requested Sender ID. Operator approval and fallback rules determine the value actually used. |
callback_url | No | Public HTTPS URL. Requires client_id and an idempotency key. |
client_id | With callback | Your reference, returned in delivery callbacks. |
A successful submission returns HTTP 202 Accepted with the Fewsecond message_id, applied sender and initial accepted status.
Message status
/messages/{message_id}curl 'https://www.fewsecond.net/webservices/api/v1/messages/MESSAGE_ID' \
-H 'Authorization: Bearer YOUR_ACCESS_TOKEN'The aggregate status is pending, delivered, failed or partial. Recipient records include provider ID and status date.
Delivery callbacks
When a callback URL was supplied, Fewsecond sends an HTTPS POST with the header X-Fewsecond-Event: sms.delivery.updated.
{
"id": "MESSAGE_ID",
"client_id": "order-20260901-0001",
"telephone": "237690032763",
"status": "delivered",
"provider_id": "PROVIDER_MESSAGE_ID",
"date": "2026-09-01T10:42:18+01:00",
"description": ""
}Return an HTTP 2xx quickly and process callbacks idempotently. A later delivered or failed event may replace pending.
Endpoint reference
| Method | Path | Purpose |
|---|---|---|
| GET | /health | Service health and API version |
| POST / DELETE | /auth/token | Issue or revoke a token |
| GET | /balance | Remaining SMS credit |
| POST | /messages | Send one SMS with optional callback |
| POST | /messages/bulk | Submit a legacy-compatible recipient expression |
| GET | /messages/{id} | Current status and recipients |
| GET / DELETE | /reports/deliveries[/{id}] | Delivery history |
| GET | /reports/transactions, /reports/ledger | Transactions and account ledger |
| GET / POST / PUT / DELETE | /address-book/groups, /address-book/contacts | Address book management |
| GET / POST / DELETE | /address-book/senders | Account Sender IDs |
| GET / POST | /accounts/availability, /accounts | Check username and register |
| GET | /account/profile | Authenticated account profile |
Protected endpoints require Authorization: Bearer <access_token>. Contact support before relying on bulk or account-management endpoints in a new integration.
Error handling
{"success":false,"error":{"code":"validation_error","message":"One or more fields are invalid","details":{"to":"A valid Cameroon MSISDN is required"}}}| HTTP | Meaning |
|---|---|
| 400 / 415 | Invalid JSON or unsupported content type |
| 401 | Invalid credentials or expired token |
| 402 / 403 | Insufficient balance or sending forbidden |
| 404 / 409 | Resource not found or duplicate submission |
| 422 | Field validation failed |
| 502 / 503 | Provider or service temporarily unavailable |
Legacy SOAP API
The SOAP 1.1 endpoint remains available for existing integrations at https://www.fewsecond.net/webservices/sms.php?wsdl. New integrations should use REST v1.