Developers
A2PSMS API
Send SMS, verify phone numbers with one-time codes and get delivery receipts in your own systems. Everything here works with a free test key first.
Introduction
The API is JSON over HTTPS. Every request is authenticated with an API key, and every response uses the same envelope, so you can handle success and errors in one place.
| Details | |
|---|---|
| Base URL | https://api.sms.pitrontech.et/v1 |
| Format | JSON requests and responses, UTF-8. Amharic and other Unicode text is supported. |
| Numbers | Ethiopian mobile numbers. Send them as 251911234567, +251911234567 or 0911234567; responses always use 251…. |
| Times | ISO 8601 in UTC, e.g. 2026-11-13T10:24:44.119Z |
| Money | Ethiopian birr (ETB) |
{ "success": true, "data": { … }, "timestamp": "…", "correlationId": "…" }{
"success": false,
"error": "Recipient has opted out of messages",
"code": "RECIPIENT_OPT_OUT",
"statusCode": 422,
"timestamp": "2026-11-13T10:25:25.093Z",
"correlationId": "1b481ed4-7267-4c3a-8ab7-2dbcac00ba00"
}Every response has a correlationId (also in the X-Correlation-Id header). Quote it when you contact support and we can find the exact request.
Quick start
- Create an account. It starts in test mode, so you can build straight away.
- In the portal, open Settings → API keys and create a test key. Copy it: it is shown only once.
- Send your first message. With a test key nothing reaches a phone and nothing is charged, but you get the same responses and webhooks.
- Request a sender ID under Sender IDs. Once it is approved and your wallet has funds, create a live key and the same code sends real messages.
curl https://api.sms.pitrontech.et/v1/messages \
-H "X-API-Key: a2psms_sk_live_…" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: order-48213-ready" \
-d '{
"to": "251911234567",
"from": "ACME",
"text": "Your order #48213 is ready for pickup at our Bole branch."
}'The message is accepted straight away and delivered in the background:
{
"success": true,
"data": {
"id": "96e4582c-46ca-4535-a44e-8644db866a59",
"to": "251911234567",
"from": "ACME",
"text": "Your order #48213 is ready for pickup at our Bole branch.",
"status": "QUEUED",
"segments": 1,
"operation_mode": "live",
"createdAt": "2026-11-13T10:24:44.119Z",
"submittedAt": null,
"deliveredAt": null,
"cost": null,
"failedAt": null,
"error": null
},
"timestamp": "2026-11-13T10:24:44.294Z",
"correlationId": "9e1dbcde-7b69-47c0-9b1a-5e1f2c3d4a5b"
}Authentication
Send your key in the X-API-Key header on every request. Keep keys on your server; never put them in a mobile app or a web page.
| Key | What it does |
|---|---|
a2psms_sk_live_… | Sends real messages from your approved sender IDs and charges your wallet. |
a2psms_sk_test_… | Same API, simulated: messages never reach a phone and nothing is charged. |
Each key has scopes. A request outside a key's scopes is refused with 403. Give each system only what it needs.
| Scope | Allows |
|---|---|
| sms.send | Send messages and one-time codes |
| sms.read | Read message status and history |
| sender_ids.read | List your sender IDs |
| webhooks.manage | Create, change and delete webhooks |
| templates.manage | Create, change and delete templates |
| opt_outs.manage | Add, list and remove opted-out numbers |
Rotate a key from the portal at any time. The old key keeps working for a short grace period so you can switch without downtime. A missing, wrong or revoked key gets 401 UNAUTHORIZED.
Test mode
Requests made with a test key behave like live ones, with these differences:
- Messages are simulated and move to
DELIVEREDwithin a second. Nothing is sent andcoststaysnull. - Webhooks and callbacks still fire, so you can test your receiver end to end. The message has
"operation_mode": "test". - One-time codes are always
482913(for the default 6 digits), and the send response includes the code astestCode. - You still need an approved sender ID in the
fromfield, because the API checks it the same way.
Send a message
/v1/messagesscope: sms.send| Field | Type | Description |
|---|---|---|
| tostring | string | Recipient. Ethiopian mobile number in any of the formats above. |
| fromstring | string | One of your approved sender IDs, up to 11 characters. |
| textstring | string | Message text, up to 1,530 characters. Required unless you send templateId. |
| templateIduuid | uuid | Send a saved template instead of text. |
| templateParamsobject | object | Values for the template's {{placeholders}}, e.g. {"first_name":"Hana"}. |
| sendAtISO 8601 | ISO 8601 | Schedule the message, up to 30 days ahead. Omit to send now. |
| callbackUrlhttps URL | https URL | Receive this message's final status at your own URL. See callbacks. |
Segments and length
Long messages are split into segments and joined again on the phone. You pay per segment. English and other text in the GSM alphabet fits 160 charactersin one segment, or 153 per segment when longer. Amharic (Ge'ez script) and emoji use Unicode: 70 characters, or 67 per segment when longer. One Amharic character in an otherwise English message switches the whole message to Unicode. The segments field in the response tells you the count.
What can go wrong
| Code | Status | Meaning |
|---|---|---|
| SENDER_ID_NOT_APPROVED | 404 | The from value is not one of your approved sender IDs. |
| RECIPIENT_OPT_OUT | 422 | The number replied STOP or was opted out. Do not retry. |
| INSUFFICIENT_BALANCE | 402 | Your wallet cannot cover the message. Top up and retry. |
| TEMPLATE_VARIABLE_MISSING | 422 | templateParams does not include every placeholder. |
| SCHEDULE_TOO_FAR | 422 | sendAt is more than 30 days ahead. |
| INVALID_CALLBACK_URL | 422 | callbackUrl is not a public https address. |
| ACCOUNT_NOT_ACTIVE | 403 | Your account is suspended. Contact support. |
| VALIDATION_ERROR | 400 | A field is missing or malformed; meta.errors lists each problem. |
Send a batch
/v1/messages/batchscope: sms.sendSend up to 1,000 messages from one sender ID in a single request. Each message succeeds or fails on its own: an invalid number or an opted-out recipient fails only that message. Results come back in the order you sent them.
curl https://api.sms.pitrontech.et/v1/messages/batch \
-H "X-API-Key: a2psms_sk_live_…" \
-H "Content-Type: application/json" \
-d '{
"from": "ACME",
"messages": [
{ "to": "0911000777", "text": "Hi Hana, your order is ready." },
{ "to": "12", "text": "This number is invalid" },
{ "to": "251911444555", "text": "This person opted out" }
]
}'{
"success": true,
"data": {
"results": [
{ "to": "251911000777", "id": "60ed83e9-…", "status": "QUEUED" },
{ "to": "12", "error": { "code": "INVALID_RECIPIENT", "message": "Not an Ethiopian mobile number, e.g. 251911234567 or 0911234567." } },
{ "to": "251911444555", "error": { "code": "RECIPIENT_OPT_OUT", "message": "Recipient has opted out of messages" } }
]
}
}Status and billing
A message moves through these statuses. Only the last three are final.
| Status | Meaning |
|---|---|
| QUEUED | Accepted and waiting to be sent (or waiting for its sendAt time). |
| SUBMITTING | Being handed to the network. |
| SUBMITTED | The network accepted it; waiting for the delivery receipt. |
| DELIVERED | The phone received it. Final. |
| FAILED | The network could not deliver it, e.g. the phone is off for too long or the number does not exist. error says why. Final. |
| EXPIRED | It could not be sent within 24 hours, or no receipt came back within 72 hours. Final. |
You pay only for delivered messages. When a live message is accepted, its price is held from your wallet. It is charged when the message is delivered and returned in full if it fails or expires. cost shows the amount charged once the message is delivered. Your current price per segment is on the Billing page in the portal.
Get and list messages
/v1/messages/{id}scope: sms.readReturns one message in the same shape as the send response. Use it to check a status, or to confirm a callback.
/v1/messagesscope: sms.read| Field | Type | Description |
|---|---|---|
| pageinteger | integer | Page number, from 1. |
| limitinteger | integer | Messages per page, 1–100. Default 20. |
| statusstring | string | Only this status, e.g. DELIVERED. |
| statusesstring | string | Several statuses, comma-separated, e.g. FAILED,EXPIRED. |
| recipientstring | string | Only messages to this number. |
| from / toISO 8601 | ISO 8601 | Only messages created in this time range. |
| directionstring | string | outbound (default view) or inbound for replies you received. |
{
"success": true,
"data": [ { "id": "…", "status": "DELIVERED", "cost": 0.28, … } ],
"total": 935,
"page": 1,
"limit": 20,
"totalPages": 47
}Safe retries
Networks fail. To retry a send without risking a duplicate SMS or a double charge, add an Idempotency-Key header with a value that is unique to that message, such as your order ID. It works on POST /v1/messages and POST /v1/messages/batch.
- Repeating a request with the same key and the same body within 24 hours returns the original response, with the header
Idempotent-Replay: true. No new message is sent. - The same key with a different body is refused with
422 IDEMPOTENCY_KEY_REUSED. - A retry that arrives while the first request is still running gets
409 IDEMPOTENCY_IN_PROGRESS. Wait a moment and retry. - Keys can be up to 255 characters.
One-time codes (OTP)
Let us generate, send and check verification codes, so you never store them yourself. Codes are single-use, expire, and lock after too many wrong attempts.
1. Send a code
/v1/otpscope: sms.send| Field | Type | Description |
|---|---|---|
| tostring | string | The number to verify. |
| languagestring | string | en (default) or am for Amharic. |
curl https://api.sms.pitrontech.et/v1/otp \
-H "X-API-Key: a2psms_sk_live_…" \
-H "Content-Type: application/json" \
-d '{ "to": "0911234567", "language": "en" }'
# 201 Created
# { "success": true, "data": { "otpId": "eafe67b4-…", "to": "251911234567", "expiresAt": "2026-11-13T10:29:49.510Z" } }2. Check what the user typed
/v1/otp/{otpId}/verifyscope: sms.sendcurl https://api.sms.pitrontech.et/v1/otp/eafe67b4-…/verify \
-H "X-API-Key: a2psms_sk_live_…" \
-H "Content-Type: application/json" \
-d '{ "code": "482913" }'
# 200 OK
# { "success": true, "data": { "verified": true, "otpId": "eafe67b4-…", "to": "251911234567" } }| Code | Status | Meaning |
|---|---|---|
| OTP_CODE_INVALID | 422 | Wrong code. meta.attemptsLeft says how many tries remain. |
| OTP_TOO_MANY_ATTEMPTS | 429 | Too many wrong codes. Send a new one. |
| OTP_EXPIRED | 410 | The code expired. Send a new one. |
| OTP_ALREADY_USED | 409 | This code was already verified. |
| OTP_RESEND_LIMIT | 429 | Too many codes sent to this number recently. |
| OTP_IP_LIMIT | 429 | Too many codes requested from one IP address. |
| INVALID_PHONE | 422 | Not a valid Ethiopian mobile number. |
| SENDER_ID_NOT_APPROVED | 422 | You need an approved sender ID before sending codes. |
By default codes have 6 digits, expire after 5 minutes, allow 3 attempts and at most 3 codes per number in 15 minutes. Change these, the sender ID and the message wording (English and Amharic) on the OTP page in the portal.
Webhooks
Webhooks push events to your server as they happen, so you don't have to poll. Create them in the portal under Settings → Webhooks, or with the API.
/v1/public-api/webhooksscope: webhooks.managecurl https://api.sms.pitrontech.et/v1/public-api/webhooks \
-H "X-API-Key: a2psms_sk_live_…" \
-H "Content-Type: application/json" \
-d '{ "url": "https://api.example.et/a2psms/webhooks", "events": ["message.delivered", "message.failed", "message.inbound"] }'
# 201 Created: the signing secret is returned only in this response. Store it.
# { "success": true, "data": { "id": "283b5f3d-…", "url": "…", "events": [ … ], "status": "ACTIVE", "secret": "whsec_…" } }| Event | Sent when | data |
|---|---|---|
| message.queued | A message was accepted. | messageId, to, from |
| message.delivered | A message reached the phone. | messageId, deliveredAt, cost, currency |
| message.failed | A message failed or expired. | messageId, status, errorCode, reason, permanent |
| message.inbound | Someone replied to your sender ID. | messageId, from, to, text, receivedAt |
X-Webhook-Event: message.delivered
X-Webhook-Delivery: de333f22-e49b-4cac-b60b-53a26007a375
X-Webhook-Timestamp: 1763029502
X-Webhook-Signature: sha256=4d7c60958d133…
Content-Type: application/json
{
"event": "message.delivered",
"data": {
"messageId": "96e4582c-46ca-4535-a44e-8644db866a59",
"deliveredAt": "2026-11-13T10:24:44.822Z",
"cost": 0.28,
"currency": "ETB"
},
"timestamp": "2026-11-13T10:24:44.830Z"
}Answer quickly, process later
Reply with any 2xxwithin 10 seconds. Anything else, or no answer, is retried after 1 minute, 5 minutes, 30 minutes, 2 hours and 8 hours. After that the delivery is dropped, and you can still read the message's status with the API. A delivery can arrive more than once, so use X-Webhook-Deliveryto ignore repeats. Change a webhook's URL or events, or pause it, with PUT /v1/public-api/webhooks/{id}.
Verifying signatures
Every webhook is signed with its secret so you can be sure it came from us. The signature is an HMAC-SHA256 of the timestamp, a dot and the raw body: sha256=hex(HMAC(secret, timestamp + "." + body)). Compute it over the exact bytes you received, before parsing the JSON, and reject timestamps older than 5 minutes to stop replays.
import crypto from "node:crypto";
import express from "express";
const app = express();
const SECRET = process.env.A2PSMS_WEBHOOK_SECRET; // whsec_…
// Keep the raw body: the signature is computed over the exact bytes sent.
app.post("/a2psms/webhooks", express.raw({ type: "application/json" }), (req, res) => {
const ts = req.get("X-Webhook-Timestamp");
const sig = req.get("X-Webhook-Signature") ?? "";
const body = req.body.toString("utf8");
const expected =
"sha256=" + crypto.createHmac("sha256", SECRET).update(`${ts}.${body}`).digest("hex");
const fresh = Math.abs(Date.now() / 1000 - Number(ts)) < 300; // 5 minutes
const valid =
sig.length === expected.length &&
crypto.timingSafeEqual(Buffer.from(sig), Buffer.from(expected));
if (!fresh || !valid) return res.sendStatus(400);
const event = JSON.parse(body);
// Use X-Webhook-Delivery to ignore a delivery you have already handled.
handle(event).catch(console.error); // do the work after answering
res.sendStatus(200);
});Lost the secret?
Per-message callbacks
If you send a message with callbackUrl, we also POST its final status there, in addition to any webhooks. Callbacks are handy for one-off integrations, but they are not signed.
X-A2PSMS-Event: message.status
Content-Type: application/json
{ "messageId": "9b5f48c1-…", "status": "DELIVERED", "errorCode": null, "cost": 0.28, "currency": "ETB", "timestamp": "2026-11-13T10:30:12.000Z" }Treat callbacks as a hint
GET /v1/messages/{messageId}, or use signed webhooks instead.Sender IDs
A sender ID is the name your customers see instead of a number, up to 11 characters. Request one in the portal with your trade license and a signed authorization letter; we review it and register it with the network. List the ones you can use:
/v1/public-api/sender-idsscope: sender_ids.read/v1/public-api/sender-ids/{id}scope: sender_ids.readTemplates
Save message wording once and send it by ID with templateId and templateParams. Placeholders look like {{first_name}}; every placeholder must be given a value or the send is refused with TEMPLATE_VARIABLE_MISSING.
/v1/public-api/templatesscope: templates.manage| Field | Type | Description |
|---|---|---|
| namestring | string | Unique name, up to 100 characters. |
| bodystring | string | Text with {{placeholders}}. |
| categorystring | string | Optional label, e.g. otp, transactional, promotional. |
/v1/public-api/templatesscope: templates.manage/v1/public-api/templates/{id}scope: templates.manage/v1/public-api/templates/{id}scope: templates.manage/v1/public-api/templates/{id}scope: templates.manageOpt-outs
When someone replies STOP, UNSUBSCRIBE, አቁም or ይቁም, we opt them out automatically; START or ጀምር opts them back in. Messages to an opted-out number are refused with RECIPIENT_OPT_OUT and never charged. Keep the list in step with your own records:
/v1/public-api/opt-outsscope: opt_outs.manage| Field | Type | Description |
|---|---|---|
| phoneNumberstring | string | The number to opt out. |
| reasonstring | string | Optional, up to 100 characters. |
/v1/public-api/opt-outsscope: opt_outs.manage/v1/public-api/opt-outs/{phoneNumber}scope: opt_outs.manageOnly remove a number if the person asked to receive messages again.
Errors
Errors use the envelope from the introduction. Branch on code, not on the message text, which may change. Validation errors list every problem in meta.errors.
| HTTP | Meaning | What to do |
|---|---|---|
| 400 | The request is malformed (VALIDATION_ERROR). | Fix the request; retrying won't help. |
| 401 | Missing, wrong or revoked API key. | Check the X-API-Key header. |
| 402 | Not enough balance (INSUFFICIENT_BALANCE). | Top up, then retry. |
| 403 | The key lacks a scope, or the account is suspended. | Use a key with the right scope. |
| 404 | Not found, or a sender ID that isn't yours or isn't approved. | Check the ID or sender ID. |
| 409 | Conflict, e.g. IDEMPOTENCY_IN_PROGRESS or OTP_ALREADY_USED. | Wait and retry, or stop. |
| 422 | Understood but refused, e.g. RECIPIENT_OPT_OUT. | Don't retry the same request. |
| 429 | Rate limited. | Wait for Retry-After seconds. |
| 5xx | A problem on our side. | Retry with backoff and the same Idempotency-Key. |
Rate limits
Each API key can make a set number of requests a minute; the number depends on your plan. Every response tells you where you stand:
| Header | Meaning |
|---|---|
| X-RateLimit-Limit | Requests allowed per minute for this key. |
| X-RateLimit-Remaining | Requests left in the current minute. |
| X-RateLimit-Reset | When the minute resets (ISO 8601). |
| Retry-After | On 429 only: seconds to wait before trying again. |
Need more? Use batch sends (one request, up to 1,000 messages) or contact us about a higher limit.
All endpoints
| Endpoint | Scope | Does |
|---|---|---|
| POST /v1/messages | sms.send | Send a message |
| POST /v1/messages/batch | sms.send | Send up to 1,000 messages |
| GET /v1/messages | sms.read | List messages |
| GET /v1/messages/{id} | sms.read | Get one message |
| POST /v1/otp | sms.send | Send a one-time code |
| POST /v1/otp/{id}/verify | sms.send | Check a code |
| GET /v1/public-api/sender-ids | sender_ids.read | List sender IDs |
| GET /v1/public-api/sender-ids/{id} | sender_ids.read | Get one sender ID |
| POST /v1/public-api/webhooks | webhooks.manage | Create a webhook |
| GET /v1/public-api/webhooks | webhooks.manage | List webhooks |
| GET /v1/public-api/webhooks/{id} | webhooks.manage | Get one webhook |
| PUT /v1/public-api/webhooks/{id} | webhooks.manage | Change or pause a webhook |
| DELETE /v1/public-api/webhooks/{id} | webhooks.manage | Delete a webhook |
| POST /v1/public-api/templates | templates.manage | Create a template |
| GET /v1/public-api/templates | templates.manage | List templates |
| GET /v1/public-api/templates/{id} | templates.manage | Get one template |
| PUT /v1/public-api/templates/{id} | templates.manage | Change a template |
| DELETE /v1/public-api/templates/{id} | templates.manage | Delete a template |
| POST /v1/public-api/opt-outs | opt_outs.manage | Opt a number out |
| GET /v1/public-api/opt-outs | opt_outs.manage | List opted-out numbers |
| DELETE /v1/public-api/opt-outs/{phoneNumber} | opt_outs.manage | Remove an opt-out |
Questions?
correlationId from the response when you contact us. It points us to the exact request.