SMS API v2.0.4

SMS API Documentation

Send single and bulk SMS, check delivery status, and use callbacks. RESTful, simple, and ready for Postman or your code.

Download Postman & OpenAPI Get API Keys

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
`clientid`	Your client ID
`clientsecret`	Your client secret
`token`	Wallet/API token
`from`	Sender name (e.g. MyCompany)
`to`	Recipient number (e.g. 23230123456)
`content`	Message text
`reference`	Your reference ID
`callbackUrl`	Optional webhook URL for delivery callbacks

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-Type`	application/json
`X-Wallet`	Token YOUR_TOKEN
`Authorization`	Basic base64(clientid:clientsecret)

Body (JSON)

Field	Required	Description
`From`	Yes	Sender name
`To`	Yes	Recipient number
`Content`	Yes	Message text
`Reference`	No	Your reference
`CallbackUrl`	No	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
`From`	Yes	Sender name
`Content`	Yes	Message text (same for all)
`CallbackUrl`	No	Delivery callback URL
`Recipients`	Yes	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
`ticket`	Transaction/ticket ID from the send response

# Replace TICKET_ID with the ticket from your 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-Type`	application/json
`X-Wallet`	Token YOUR_TOKEN
`Authorization`	Basic 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
`ClientReference`	Your reference (e.g. the `Reference` you sent)
`Ticket`	Transaction ID from Apphive (use with GET /v1/transactions/{ticket}/status if needed)
`Destination`	Recipient number (e.g. 23230588654)
`Cost`	Charge applied to your wallet (e.g. 0.2)
`BalanceBefore`	Wallet balance before this transaction (for accounting)
`BalanceAfter`	Wallet balance after this transaction
`Status`	Final 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"
}

MCP connector

The Model Context Protocol (MCP) lets an AI assistant call tools on the user's behalf. The Apphive connector exposes a signed-in customer's account to Claude, ChatGPT, or any MCP-compatible client so they can manage SMS in natural language — no code required.

Connector URL

https://mcp.apphivesl.com/mcp

Auth: OAuth-protected MCP server (authorization code + PKCE). Users sign in with their existing Apphive account — the same login as the customer portal.
Provisioning: accounts are provisioned by Apphive, not self-serve. Don't have an account yet? Request access on the contact page.
Scope: each connection is limited to the signed-in account's own wallet and own approved sender IDs. There is no cross-account access.

Available tools

Tool	Type	Description
`get_balance`	Read	Current wallet balance and currency
`list_sender_ids`	Read	Sender IDs on the account and their approval status
`get_message_status`	Read	Delivery status for a message by id
`search_messages`	Read	Search message history by date range, status, recipient, or sender ID
`get_rates`	Read	Price to send to a given country
`delivery_insights`	Read	Sent / delivered / failed counts and total spend, grouped by recipient network or by day
`estimate_cost`	Read	Cost of a specific message before sending (segment count × rate)
`send_sms`	Write	Send a single SMS to one recipient — spends from the wallet
`schedule_sms`	Write	Queue a message to send at a future time — spends from the wallet
`cancel_scheduled`	Write	Cancel a scheduled SMS before it sends

Write tools (send_sms, schedule_sms) spend real money from the account wallet and are confirmed by the client before they run. For the customer-facing overview, see the AI Connector page.

Download & integrate

Use the collection in Postman or import the OpenAPI spec into your IDE or code generator.

Postman collection (v2.0.4)

Import into Postman: File → Import → Upload the file, then set your variables (baseUrl, clientid, clientsecret, token, from, to, etc.).

OpenAPI 3.0 spec (v2.0.4)

Use with Swagger UI, code generators, or any OpenAPI 3–compatible tool.