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 URLhttps://api.sms.pitrontech.et/v1
FormatJSON requests and responses, UTF-8. Amharic and other Unicode text is supported.
NumbersEthiopian mobile numbers. Send them as 251911234567, +251911234567 or 0911234567; responses always use 251….
TimesISO 8601 in UTC, e.g. 2026-11-13T10:24:44.119Z
MoneyEthiopian birr (ETB)
Success
{ "success": true, "data": { … }, "timestamp": "…", "correlationId": "…" }
Error
{
  "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

  1. Create an account. It starts in test mode, so you can build straight away.
  2. In the portal, open Settings → API keys and create a test key. Copy it: it is shown only once.
  3. Send your first message. With a test key nothing reaches a phone and nothing is charged, but you get the same responses and webhooks.
  4. 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:

201 Created
{
  "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.

KeyWhat 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.

ScopeAllows
sms.sendSend messages and one-time codes
sms.readRead message status and history
sender_ids.readList your sender IDs
webhooks.manageCreate, change and delete webhooks
templates.manageCreate, change and delete templates
opt_outs.manageAdd, 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 DELIVERED within a second. Nothing is sent and cost stays null.
  • 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 as testCode.
  • You still need an approved sender ID in the from field, because the API checks it the same way.

Send a message

POST/v1/messagesscope: sms.send
FieldDescription
tostringRecipient. Ethiopian mobile number in any of the formats above.
fromstringOne of your approved sender IDs, up to 11 characters.
textstringMessage text, up to 1,530 characters. Required unless you send templateId.
templateIduuidSend a saved template instead of text.
templateParamsobjectValues for the template's {{placeholders}}, e.g. {"first_name":"Hana"}.
sendAtISO 8601Schedule the message, up to 30 days ahead. Omit to send now.
callbackUrlhttps URLReceive 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

CodeStatusMeaning
SENDER_ID_NOT_APPROVED404The from value is not one of your approved sender IDs.
RECIPIENT_OPT_OUT422The number replied STOP or was opted out. Do not retry.
INSUFFICIENT_BALANCE402Your wallet cannot cover the message. Top up and retry.
TEMPLATE_VARIABLE_MISSING422templateParams does not include every placeholder.
SCHEDULE_TOO_FAR422sendAt is more than 30 days ahead.
INVALID_CALLBACK_URL422callbackUrl is not a public https address.
ACCOUNT_NOT_ACTIVE403Your account is suspended. Contact support.
VALIDATION_ERROR400A field is missing or malformed; meta.errors lists each problem.

Send a batch

POST/v1/messages/batchscope: sms.send

Send 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
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" }
    ]
  }'
201 Created
{
  "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.

StatusMeaning
QUEUEDAccepted and waiting to be sent (or waiting for its sendAt time).
SUBMITTINGBeing handed to the network.
SUBMITTEDThe network accepted it; waiting for the delivery receipt.
DELIVEREDThe phone received it. Final.
FAILEDThe network could not deliver it, e.g. the phone is off for too long or the number does not exist. error says why. Final.
EXPIREDIt 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

GET/v1/messages/{id}scope: sms.read

Returns one message in the same shape as the send response. Use it to check a status, or to confirm a callback.

GET/v1/messagesscope: sms.read
FieldDescription
pageintegerPage number, from 1.
limitintegerMessages per page, 1–100. Default 20.
statusstringOnly this status, e.g. DELIVERED.
statusesstringSeveral statuses, comma-separated, e.g. FAILED,EXPIRED.
recipientstringOnly messages to this number.
from / toISO 8601Only messages created in this time range.
directionstringoutbound (default view) or inbound for replies you received.
200 OK
{
  "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

POST/v1/otpscope: sms.send
FieldDescription
tostringThe number to verify.
languagestringen (default) or am for Amharic.
cURL
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

POST/v1/otp/{otpId}/verifyscope: sms.send
cURL
curl 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" } }
CodeStatusMeaning
OTP_CODE_INVALID422Wrong code. meta.attemptsLeft says how many tries remain.
OTP_TOO_MANY_ATTEMPTS429Too many wrong codes. Send a new one.
OTP_EXPIRED410The code expired. Send a new one.
OTP_ALREADY_USED409This code was already verified.
OTP_RESEND_LIMIT429Too many codes sent to this number recently.
OTP_IP_LIMIT429Too many codes requested from one IP address.
INVALID_PHONE422Not a valid Ethiopian mobile number.
SENDER_ID_NOT_APPROVED422You 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.

POST/v1/public-api/webhooksscope: webhooks.manage
cURL
curl 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_…" } }
EventSent whendata
message.queuedA message was accepted.messageId, to, from
message.deliveredA message reached the phone.messageId, deliveredAt, cost, currency
message.failedA message failed or expired.messageId, status, errorCode, reason, permanent
message.inboundSomeone replied to your sender ID.messageId, from, to, text, receivedAt
POST to your URL
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?

Rotate it in the portal under Settings → Webhooks. The new secret is shown once and the old one stops working.

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.

POST to your callbackUrl
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

Anyone who learns the URL could post to it. Before acting on a callback, confirm the status with 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:

GET/v1/public-api/sender-idsscope: sender_ids.read
GET/v1/public-api/sender-ids/{id}scope: sender_ids.read

Templates

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.

POST/v1/public-api/templatesscope: templates.manage
FieldDescription
namestringUnique name, up to 100 characters.
bodystringText with {{placeholders}}.
categorystringOptional label, e.g. otp, transactional, promotional.
GET/v1/public-api/templatesscope: templates.manage
GET/v1/public-api/templates/{id}scope: templates.manage
PUT/v1/public-api/templates/{id}scope: templates.manage
DELETE/v1/public-api/templates/{id}scope: templates.manage

Opt-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:

POST/v1/public-api/opt-outsscope: opt_outs.manage
FieldDescription
phoneNumberstringThe number to opt out.
reasonstringOptional, up to 100 characters.
GET/v1/public-api/opt-outsscope: opt_outs.manage
DELETE/v1/public-api/opt-outs/{phoneNumber}scope: opt_outs.manage

Only 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.

HTTPMeaningWhat to do
400The request is malformed (VALIDATION_ERROR).Fix the request; retrying won't help.
401Missing, wrong or revoked API key.Check the X-API-Key header.
402Not enough balance (INSUFFICIENT_BALANCE).Top up, then retry.
403The key lacks a scope, or the account is suspended.Use a key with the right scope.
404Not found, or a sender ID that isn't yours or isn't approved.Check the ID or sender ID.
409Conflict, e.g. IDEMPOTENCY_IN_PROGRESS or OTP_ALREADY_USED.Wait and retry, or stop.
422Understood but refused, e.g. RECIPIENT_OPT_OUT.Don't retry the same request.
429Rate limited.Wait for Retry-After seconds.
5xxA 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:

HeaderMeaning
X-RateLimit-LimitRequests allowed per minute for this key.
X-RateLimit-RemainingRequests left in the current minute.
X-RateLimit-ResetWhen the minute resets (ISO 8601).
Retry-AfterOn 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

EndpointScopeDoes
POST /v1/messagessms.sendSend a message
POST /v1/messages/batchsms.sendSend up to 1,000 messages
GET /v1/messagessms.readList messages
GET /v1/messages/{id}sms.readGet one message
POST /v1/otpsms.sendSend a one-time code
POST /v1/otp/{id}/verifysms.sendCheck a code
GET /v1/public-api/sender-idssender_ids.readList sender IDs
GET /v1/public-api/sender-ids/{id}sender_ids.readGet one sender ID
POST /v1/public-api/webhookswebhooks.manageCreate a webhook
GET /v1/public-api/webhookswebhooks.manageList webhooks
GET /v1/public-api/webhooks/{id}webhooks.manageGet one webhook
PUT /v1/public-api/webhooks/{id}webhooks.manageChange or pause a webhook
DELETE /v1/public-api/webhooks/{id}webhooks.manageDelete a webhook
POST /v1/public-api/templatestemplates.manageCreate a template
GET /v1/public-api/templatestemplates.manageList templates
GET /v1/public-api/templates/{id}templates.manageGet one template
PUT /v1/public-api/templates/{id}templates.manageChange a template
DELETE /v1/public-api/templates/{id}templates.manageDelete a template
POST /v1/public-api/opt-outsopt_outs.manageOpt a number out
GET /v1/public-api/opt-outsopt_outs.manageList opted-out numbers
DELETE /v1/public-api/opt-outs/{phoneNumber}opt_outs.manageRemove an opt-out

Questions?

Include the correlationId from the response when you contact us. It points us to the exact request.