Connection details
Use a server access key from the account settings. Never expose this key in client-side code.
Quick start
This request returns the latest incoming messages. Replace ACCESS_KEY_HERE with a server access key from the account settings.
curl \
--request GET \
--url "https://app.aharon.cloud/api/v1/messages" \
--header "Authorization: Bearer ACCESS_KEY_HERE" \
--header "Accept: application/json"| Field | Value |
|---|---|
| Header | Authorization |
| Value | Bearer ACCESS_KEY_HERE |
| Token type | server |
| Failure | 401 missing_bearer_token or 401 invalid_token |
Endpoints
GET /me
Returns the authenticated account and current SMS credit balance.
GET /numbers
Lists virtual numbers assigned to the authenticated account.
GET /messages
Returns the latest 100 incoming messages, newest first. This is the primary endpoint for receiving SMS.
GET /messages/{id}
Returns one message by identifier when it belongs to the authenticated account.
GET /sms/credits
Returns the current SMS sending credit balance.
POST /senders/state
Marks a sender as spam or blocked.
POST /senders/block
Provides a short route for blocking a sender.
POST /sms/send
Sends SMS from an assigned virtual number. Billing is calculated by recipients and message segments.
GET /messages
| Field | Type | Description |
|---|---|---|
id | number | Message identifier. |
virtual_number_id | number | Identifier of the receiving number. |
from_raw | string | Original sender. |
to_raw | string | Destination number. |
body | string | Message content. |
provider_received_at | datetime | Provider receipt time. |
{
"ok": true,
"messages": [
{
"id": 991,
"virtual_number_id": 12,
"from_raw": "Google",
"from_normalized": "Google",
"from_type": "text",
"to_raw": "0500000000",
"body": "Your code is 123456",
"provider_received_at": "2026-07-05 13:45:00",
"first_seen_at": "2026-07-05 13:45:02"
}
]
}POST /sms/send
During the beta, sending is available on weekdays, closes on Friday at 15:00 and resumes on Saturday at 21:00 Israel time. These hours may change at any time.
| Body | Required | Notes |
|---|---|---|
from | Yes | Assigned sending number. |
message | Yes | Message text. |
phones or to | Yes | Recipients separated by a colon, comma or newline. |
flash | No | Boolean value: flash, sendFlashMessage or send_flash. |
curl \
--request POST \
--url "https://app.aharon.cloud/api/v1/sms/send" \
--header "Authorization: Bearer ACCESS_KEY_HERE" \
--header "Content-Type: application/json" \
--data '{ "from": "0500000000", "to": "0520000000", "message": "Your code is 123456" }'Webhook for incoming SMS
A public HTTPS address can be configured for each number to receive incoming SMS events.
{
"event": "sms.received",
"to": "0500000000",
"from": "Google",
"body": "Your code is 123456",
"received_at": "2026-07-05 13:45:00"
}X-SMS-Timestamp: 1782395100
X-SMS-Signature: sha256=...
HMAC_SHA256(webhook_secret, timestamp + "." + rawBody)Error responses
| Status | Error | Meaning |
|---|---|---|
400 | bad_request, missing_sender | Invalid input or a missing field. |
401 | missing_bearer_token, invalid_token | The key is missing, revoked or invalid. |
402 | insufficient_credits | Not enough sending credits. |
423 | sms_sending_closed_weekend | During the beta, sending is closed from Friday at 15:00 until Saturday at 21:00 Israel time. This schedule may change at any time. |
429 | too_many_recipients | Too many recipients or a rate limit. |
502 | provider_send_failed | The sending provider returned a failure. |
503 | sms_sending_not_enabled | Sending is not enabled. |