SMS API v2.0.2

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.sierrahive.com

Authentication:

POST endpoints: HTTP Basic Auth (client ID = username, client secret = password) plus header X-Wallet: Token YOUR_TOKEN.
GET (single SMS): Credentials can be passed as query parameters: clientid, clientsecret, 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

GET/v1/messages/sms

Send a single SMS using URL parameters. No HTTP Basic Auth required; credentials are sent as query params.

Query parameters

Parameter	Required	Description
`clientid`	Yes	Client ID
`clientsecret`	Yes	Client secret
`token`	Yes	API token
`from`	Yes	Sender name
`to`	Yes	Recipient number (e.g. 23230123456)
`content`	Yes	Message body
`reference`	No	Your reference
`callbackUrl`	No	Webhook URL for delivery callback

# Example (replace credentials and params)

                        curl -X GET "https://api.sierrahive.com/v1/messages/sms?clientid=YOUR_ID&clientsecret=YOUR_SECRET&token=YOUR_TOKEN&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

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.sierrahive.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.sierrahive.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
}

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"
}

Download & integrate

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

Postman collection (v2.0.2)

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

OpenAPI 3.0 spec

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