Build with SMS, OTP and voice

One API key lets your app send text messages, one-time codes and voice calls to phones in Ghana. Requests and responses are JSON.

Introduction

The SyntraX API is a small REST API. Every endpoint lives under /v1 on the site you signed up on. In the examples below we use:

Quick start

You can send your first test message in about five minutes.

1. Create an account. Sign up in the portal. New accounts get a few free welcome credits.
2. Create an API key. Open API keys in the portal and create a key. Copy it right away. We show the full key only once.
3. Test in sandbox. Add "sandbox": true to your request. Nothing is sent to a real phone and nothing is charged.
4. Go live. Remove the sandbox flag. Make sure you have SMS credits or main balance, and the message goes out for real.

Here is a sandbox SMS. Swap in your own key and run it.

Authentication

Send your API key as a Bearer token in the Authorization header on every request.

Keys start with sx_live_ followed by 32 characters. Keep them on your server. Never put a key in a mobile app or in browser code.

Key settings

Each key has its own settings. You change them in the portal under API keys. There is no API endpoint for managing keys.

You can also roll a key (get a new secret, the old one stops working), reset its usage counters, or revoke it.

Sandbox mode

Sandbox lets you test your integration for free. Turn it on per request in either of these ways:

• Add "sandbox": true to the JSON body.
• Send the header X-Sandbox: 1.

In sandbox:

• Nothing reaches a real phone and nothing is charged.
• SMS and voice get a simulated final status straight away. Most numbers come back delivered, a few come back failed. The same number always gives the same result, so your tests stay stable.
• The OTP code is always 123456. Verify it with sandbox turned on too.
• Sender ID rules still apply. Use SyntraX or one of your approved sender IDs.
• Key limits are still checked, but sandbox calls do not use them up.

Idempotency

Networks fail. To retry a send safely, add an Idempotency-Key header with a value that is unique to that send, like your order number.

• If we already handled a successful request with that key, we return the first response again and add "idempotent_replay": true. You are not charged twice.
• Failed requests are not saved, so you can fix the problem and retry with the same key.
• Keys are shared across your whole account, not per API key.
• It works on POST /v1/messages, POST /v1/otp and POST /v1/voice.

Phone numbers

Send numbers in any of these formats. We turn them all into +233241234567.

Spaces, dashes and brackets are removed. A number starting with 00 is read as an international number.

Billing

Your account has two balances: SMS credits and a main balance in Ghana cedis (GHS). You top up both in the portal.

• Every send response has a charged object showing what was taken and what is left.
• If credits come from bundles with an expiry date, the ones closest to expiry are used first.
• If you cannot cover the cost, the call fails with insufficient_funds and nothing is taken.

Automatic refunds

You get your credits and cash back automatically when a message:

• fails at the gateway while sending (refunded at once),
• is reported failed, rejected or undelivered by the network, or
• stays in sent for more than 24 hours and is marked expired.

Check your balance

Returns your balances, how many messages you can send right now, and your current rates. Credits are counted first, then main balance.

Rate limits

You can make up to 120 requests per minute to /v1 from one IP address. Every response tells you where you stand:

• X-RateLimit-Limit: requests allowed per minute.
• X-RateLimit-Remaining: requests left in this minute.

Go over and you get 429 with error rate_limited, a Retry-After header and retry_after_seconds in the body. Wait that long, then try again.

Send text messages

Send one SMS per request and track it until it is delivered.

Send an SMS

Sends one message to one phone number. To reach many people, make one call per number.

Optional headers: Idempotency-Key and X-Sandbox: 1.

Response fields

Message length and parts

Long messages are split into parts. You pay 1 credit per part.

Check message status

Look up any message on your account (SMS, OTP or voice). Use the SyntraX id or the provider_message_id.

If the message is not on your account you get 404 with {"error": "not_found"}.

Status values

The network may also report rejected or undelivered. Treat these like failed. They are refunded too.

We update statuses from the network's delivery reports and by checking pending messages in the background. Want updates pushed to you? Set up webhooks.

One-time codes

Send a login or confirmation code by SMS, then check the code your user types back.

How it works

1. You call POST /v1/otp with the phone number.
2. We create the code and text it. The code is made by our delivery network. Neither you nor SyntraX ever sees it.
3. Your user types the code into your app.
4. You call POST /v1/otp/verify with the number and the code. We tell you if it matches.

By default codes are 6 digits and stay valid for 5 minutes. The default message is:

Send a code

The response has the same fields as an SMS send. It may also include ussd_code when the network returns one. Sandbox responses do not include it. The code itself is never in the response.

Verify a code

A wrong or expired code still returns 200, with "verified": false. When the network gives a reason, it is in detail. Always check verified, not just the status code.

Verifying is free. The Idempotency-Key header is ignored on this endpoint.

Testing OTP

Send the code with sandbox on, then verify with sandbox on and the code 123456. Any other code returns "verified": false.

Voice calls

Call a phone number and have your text read aloud. Good for reminders and for people who prefer to listen.

Before you start

• Turn on voice for your key. It is off by default. Open API keys in the portal and switch voice on. Without it you get 403 voice_disabled.
• Top up your main balance. Each call costs GHS 2.50 and is paid from main balance only. SMS credits are not used.

Make a call

Here cost_cash is 250 pesewas, which is GHS 2.50.

Tracking calls

Use GET /v1/messages/{id} with the call's id. Voice uses the same status values as SMS. If your key has a webhook URL, it is passed to the network with each call so call events can reach you.

Sender IDs

The sender ID is the name your customers see as the sender of your SMS, like your business name.

Default sender

Every account can use SyntraX straight away. If you leave out sender, we use it for you. No approval needed.

Get your own sender ID

Request custom sender IDs in the portal under Sender IDs. This is portal only. There is no API endpoint to request, list or delete sender IDs.

1. Pick a name. 3 to 11 characters, letters and numbers only, with at least one letter. No spaces.
2. Explain the use. Tell us what you will send and to whom. Clear reasons are approved faster.
3. Wait for approval. The request shows as pending until it is approved or rejected. Rejections come with a reason.
4. Start using it. Pass the name in the sender field.

Names that copy networks, banks, payment brands or government bodies (for example MTN, Telecel, MoMo, GRA or Police) are blocked.

Using a sender ID

Write the name exactly as it was approved, with the same capital letters. If it does not match, the send fails and you are not charged:

The same rules apply in sandbox.

Webhooks

Let SyntraX tell your server when a message is delivered, fails or expires, and when your balance runs low.

Set up a webhook

Webhooks are set per API key in the portal under API keys. Add your HTTPS URL. We then show a signing secret that starts with whsec_. Save it. You need it to check that events really come from us.

Message events go to the webhook of the key that sent the message. Account events go to every active key that has a webhook URL.

Events

Payload

We send a POST with a JSON body. Every event has the same outer shape: event, timestamp (ISO 8601, UTC) and data.

Each request also has Content-Type: application/json and User-Agent: SyntraX-Webhooks/1.0.

Verify the signature

Every request carries an X-SyntraX-Signature header. It is the HMAC-SHA256 of the raw request body, using your whsec_ secret as the key, written as lowercase hex.

To check it, compute the same HMAC over the raw body (before you parse the JSON) and compare. If they differ, reject the request.

Responding and retries

• Reply with any 2xx status within 10 seconds. Do slow work after you reply.
• If we get an error, a timeout or no answer, we try again after 1, 5, 30 and 120 minutes. After 5 failed attempts we stop.
• The same event can arrive more than once. Use data.id and event to skip ones you already handled.

Errors

When something goes wrong you get a non-2xx status and a JSON body that says why.

Error format

Every error has an error field. Some also have message (a human-readable note) or detail (extra data).

HTTP status codes

Error codes

Retrying safely

• Retry on 429 rate_limited, 402 gateway_error and network timeouts. Wait a little longer each time.
• Do not retry 400, 401 or 403 without fixing the request first. It will fail the same way.
• Always send an Idempotency-Key on sends, so a retry never charges or texts twice.