Quick start
Base URL for all requests:
https://api.apphivesl.com
Authentication:
POST endpoints : HTTP Basic Auth (client ID = username, client secret = password) plus header X-Wallet: Token YOUR_TOKEN.GET (status) : Basic Auth only (clientid/clientsecret).
Common variables (set these in Postman or your app):
Variable Description
clientidYour client ID clientsecretYour client secret tokenWallet/API token fromSender name (e.g. MyCompany) toRecipient number (e.g. 23230123456) contentMessage text referenceYour reference ID callbackUrlOptional webhook URL for delivery callbacks
Endpoints
POST /v1/messages/sms Send a single SMS with a JSON body. Uses Basic Auth (clientid/clientsecret) and X-Wallet: Token YOUR_TOKEN header.
Headers
Header Value
Content-Typeapplication/json X-WalletToken YOUR_TOKEN AuthorizationBasic base64(clientid:clientsecret)
Body (JSON)
Field Required Description
FromYes Sender name ToYes Recipient number ContentYes Message text ReferenceNo Your reference CallbackUrlNo Delivery callback URL
curl -X POST "https://api.apphivesl.com/v1/messages/sms" \
-H "Content-Type: application/json" \
-H "X-Wallet: Token YOUR_TOKEN" \
-u "clientid:clientsecret" \
-d '{"From":"MyApp","To":"23230123456","Content":"Hello","Reference":"ref_1"}'
Response (JSON)
{
"Cost": 0.0,
"Destination": "23230123456",
"Id": "5f6f9a96-d766-4787-ba08-1fa0939b7166",
"Ticket": "5f6f9a96-d766-4787-ba08-1fa0939b7166",
"ClientReference": "my_reference_1",
"Status": "pending"
}
POST /v1/messages/sms/bulk/otm Send one message to many recipients. Same auth as POST /v1/messages/sms (Basic + X-Wallet).
Body (JSON)
Field Required Description
FromYes Sender name ContentYes Message text (same for all) CallbackUrlNo Delivery callback URL RecipientsYes Array of { To, Reference }
{
"From": "MyApp",
"Content": "Hello everyone",
"CallbackUrl": "https://myapp.com/callback",
"Recipients": [
{ "To": "23230123456", "Reference": "ref_1" },
{ "To": "23230765432", "Reference": "ref_2" }
]
}
Response (JSON) — array of one object per recipient
[
{
"Cost": 0.0,
"Destination": "23230123456",
"Id": "5f6f9a96-d766-4787-ba08-1fa0939b7166",
"Ticket": "5f6f9a96-d766-4787-ba08-1fa0939b7166",
"ClientReference": "ref_1",
"Status": "pending"
}
]
GET /v1/transactions/{ticket}/status Fetch status and details for a ticket returned by send requests. Uses Basic Auth (clientid/clientsecret).
Path parameter Description
ticketTransaction/ticket ID from the send response
curl -X GET "https://api.apphivesl.com/v1/transactions/TICKET_ID/status" -u "clientid:clientsecret"
Response (JSON)
{
"Type": "SMS",
"MessageId": "5f6f9a96-d766-4787-ba08-1fa0939b7166",
"Status": "success",
"Content": "hello customer",
"To": "23230588654",
"From": "MyCompany",
"Reference": "my_reference_1",
"Cost": 150,
"DateCreated": "2026-02-26T11:01:30.324Z",
"EffectedAt": "2026-02-26T11:01:30.644Z",
"BalanceBefore": 102,
"BalanceAfter": 101.8
}
GET /v1/account/balance Fetch your current wallet balance. Uses Basic Auth (clientid/clientsecret) and X-Wallet: Token YOUR_TOKEN header.
Headers
Header Value
Content-Typeapplication/json X-WalletToken YOUR_TOKEN AuthorizationBasic base64(clientid:clientsecret)
curl -X GET "https://api.apphivesl.com/v1/account/balance" \
-H "Content-Type: application/json" \
-H "X-Wallet: Token YOUR_TOKEN" \
-u "clientid:clientsecret"
Response (JSON)
{
"balance": 774.18,
"currency": "SLE",
"asOf": "2026-07-21T18:13:58.3306883Z"
}
Delivery callback payload
When you provide CallbackUrl (or callbackUrl) on a send request, we POST a JSON payload to your URL when the transaction is finalized. Use it to update your records or trigger downstream logic.
Payload fields
Field Description
ClientReferenceYour reference (e.g. the Reference you sent) TicketTransaction ID from Apphive (use with GET /v1/transactions/{ticket}/status if needed) DestinationRecipient number (e.g. 23230588654) CostCharge applied to your wallet (e.g. 0.2) BalanceBeforeWallet balance before this transaction (for accounting) BalanceAfterWallet balance after this transaction StatusFinal status of the transaction (e.g. success)
Example payload
{
"ClientReference": "my_reference_1",
"Ticket": "5f6f9a96-d766-4787-ba08-1fa0939b7166",
"Destination": "23230588654",
"Cost": 0.2,
"BalanceBefore": 102,
"BalanceAfter": 101.8,
"Status": "success"
}
Download & integrate
Use the collection in Postman or import the OpenAPI spec into your IDE or code generator.
Import into Postman: File → Import → Upload the file, then set your variables (baseUrl, clientid, clientsecret, token, from, to, etc.).