Ctech SMS
HomeWorkspace →
Ctech SMS API / v1

Build messaging into
your everyday workflows.

A practical guide to authentication, SMS requests, credit usage and delivery tracking.

Integration reference

Getting started

Connect your application to Ctech SMS in three steps.

01

Get your credentials

Ask your administrator to activate your account and provide a Client ID and API client secret and assign your gateway connection.

02

Send a request

Use HTTPS, provide a Bearer credential and include a unique Idempotency-Key for every business event.

03

Track the result

Save the request_id and check recipient outcomes. Configure an approved callback for completion notifications.

API base URLhttps://sms-gateway-api.ctechapp.com/api/v1

Replace example values with your issued credentials. Keep credentials on your application's server.

Open the SMS tester →
Integration reference

Authentication

Exchange your Client ID and API client secret for a temporary access token. Use that token for API requests. Your manually assigned gateway API key is configured by your administrator and is never used as a Bearer token. Once assigned, view or copy it from API & integrations after confirming your sign-in password.

Use your access token

Send the access_token returned by /auth/token in the Authorization header. Treat the complete value as a secret.

Authorization: Bearer YOUR_ACCESS_TOKEN

Obtain an access token · Client ID and API client secret

POST/auth/token
FieldTypeRequiredDescription
client_idstringYesYour stable integration identifier.
client_secretstringYesYour API client secret, separate from your sign-in password.
curl -X POST "https://sms-gateway-api.ctechapp.com/api/v1/auth/token"   -H "Accept: application/json"   -H "Content-Type: application/json"   -d '{"client_id":"YOUR_CLIENT_ID","client_secret":"YOUR_CLIENT_SECRET"}'
{
  "status": "success",
  "access_token": "YOUR_ACCESS_TOKEN",
  "token_type": "Bearer",
  "expires_at": "2026-10-17T12:00:00.000000Z"
}

Use access_token as your Bearer credential until expires_at. After expiry, request a new token. Changing the client secret revokes existing access tokens. Your manually assigned gateway API key remains unchanged.

Integration reference

Send SMS

Submit a common message, or personalise the text for each recipient.

POST/sms/requests
FieldTypeRequiredDescription
recipientsarrayYes1–1,000 recipient objects. Duplicate normalised numbers are rejected.
recipients[].phonestringYesMalawi local number (0999123456) or international format (+265999123456).
recipients[].external_referencestringNoYour reference for this recipient, up to 255 characters.
messagestringConditionalCommon message, up to 1,000 characters. Required unless every recipient has a message.
recipients[].messagestringConditionalOverrides the common message for this recipient.
sender_idstringNoAn assigned sender ID. Omit to use your default.
callback_urlHTTPS URLNoMust exactly match the callback URL approved for your account.
metadataobjectNoYour business context, returned with the request and completion callback.
curl -X POST "https://sms-gateway-api.ctechapp.com/api/v1/sms/requests"   -H "Authorization: Bearer YOUR_ACCESS_TOKEN"   -H "Accept: application/json"   -H "Content-Type: application/json"   -H "Idempotency-Key: application-42-notification"   -d '{"message":"Your application has been received.","recipients":[{"phone":"0999123456","external_reference":"application-42"}]}'

Accepted response · HTTP 202

{"status":"processing","request_id":"01931e12-0000-7000-8000-000000000042"}
Save request_id

Acceptance means your request has entered processing. It does not confirm delivery to the recipient's handset.

Integration reference

Personalised messages

Send different text within the same request.

{
  "recipients": [
    {"phone":"0999123456","message":"Hello Ruth, your application is ready."},
    {"phone":"0888123456","message":"Hello Alex, your application is ready."}
  ],
  "metadata": {"campaign":"application-updates"}
}

Each recipient is charged according to their message length and your account rate. Invalid numbers are reported as failures and do not consume credits. A request containing only invalid numbers is rejected.

Integration reference

Safe retries & idempotency

Prevent duplicate requests when your application retries a business event.

Idempotency-Key: application-42-notification
SituationResult
New key and valid requestHTTP 202 with a new request_id.
Same key and matching payloadHTTP 200 with the existing request_id; no duplicate submission.
Same key and changed payloadHTTP 409. Use a new key only for a genuinely new event.

Keys are scoped to your account, limited to 120 characters and retained with the request. Keep the request payload unchanged when retrying. If the network response is lost, reuse the same key rather than inventing a new one.

Do not resend uncertain messages blindly

Check request status and recipient outcomes first. An unknown submission may already have been sent and needs support review.

Integration reference

Request status

Use the returned request_id to follow processing.

GET/sms/requests/{request_id}
{
  "data": {
    "request_id": "01931e12-0000-7000-8000-000000000042",
    "request_status": "completed",
    "total_count": 1,
    "success_count": 1,
    "failure_count": 0,
    "sender_id": "CTECH",
    "metadata": null,
    "created_at": "2026-10-16T12:00:00.000000Z"
  }
}
StatusMeaning
processingOne or more recipients are queued, being submitted or awaiting reconciliation.
completedSubmission processing is complete. Final delivery updates may still arrive.

Poll at a moderate interval, for example every five seconds, and stop when your application has enough information. Every status request counts towards your API rate limit.

Integration reference

Recipient outcomes

Inspect the outcome and credit state for each recipient.

GET/sms/requests/{request_id}/recipients?page=1

Results are paginated, with up to 100 recipients per page. Follow next_page_url when it is present.

{
  "current_page": 1,
  "data": [{
    "phone": "0999123456",
    "normalized_phone": "+265999123456",
    "message": "Your application has been received.",
    "status": "delivered",
    "external_reference": "application-42",
    "credit_units": 1,
    "billing_status": "charged",
    "error_reason": null
  }],
  "next_page_url": null,
  "per_page": 100,
  "total": 1
}
Recipient statusMeaning
pendingWaiting for submission.
sendingSubmission is in progress.
sentThe message submission was accepted.
deliveredDelivery has been confirmed.
failedSubmission or delivery failed; inspect billing_status separately.
unknownThe submission outcome is uncertain; contact support before resending.
Integration reference

Account & credits

Read your available balance before a larger send.

GET/account
{
  "client_id": "YOUR_CLIENT_ID",
  "name": "Example School",
  "balance": 1000,
  "reserved": 10,
  "available": 990,
  "credits_per_segment": 1,
  "sender_id": "CTECH"
}

Available credits equal balance minus reserved credits. Credits are reserved when your request enters processing, charged when submission is accepted, and released if submission is rejected. An uncertain outcome keeps its reservation until reviewed.

The rate is an integer number of credits per SMS segment. Standard text uses up to 160 characters in a single segment; longer text normally uses 153 characters per segment. Unicode uses up to 70 UTF-16 units in a single segment, or 67 per concatenated segment. Some symbols use extra space.

A later delivery failure does not automatically refund an accepted submission. Changing a rate affects new submissions; existing reservations keep their original rate.

Integration reference

Completion callbacks

Receive a signed notification when submission processing completes.

Ask your administrator to approve your public HTTPS callback URL. The URL in a send request must match that approved value. Your endpoint should return a successful HTTP response promptly and process repeated notifications idempotently by request_id.

{
  "status":"completed",
  "request_id":"01931e12-0000-7000-8000-000000000042",
  "success_count":1,
  "failure_count":0,
  "failures":[],
  "metadata":{"event":"application-42"},
  "completed_at":"2026-10-16T12:01:00.000000Z"
}

Verify the signature

Use the callback signing secret issued with your gateway credentials. The X-SMS-Gateway-Signature header contains a hexadecimal HMAC-SHA256 over the compact JSON representation of the parsed payload, preserving field order and Unicode escaping while leaving forward slashes unescaped. Do not sign the incoming whitespace-formatted text directly.

$payload = json_decode($rawBody, true, 512, JSON_THROW_ON_ERROR);
$canonical = json_encode($payload, JSON_UNESCAPED_SLASHES);
$expected = hash_hmac('sha256', $canonical, $callbackSigningSecret);
if (!hash_equals($expected, $receivedSignature)) {
    http_response_code(401);
    exit;
}

Callbacks describe submission completion. Use recipient status checks for later delivery outcomes. Failed callback delivery may be retried, so duplicates must be safe.

Integration reference

Errors & troubleshooting

Use the HTTP status and validation fields to decide what to do next.

HTTPMeaningNext step
400Missing or invalid Idempotency-Key.Provide a nonempty key of up to 120 characters.
401Missing, expired or invalid credentials.Check your key or exchange your client credentials again.
403Account access, IP policy or permission denied.Check account activation, allowed IPs and credential permissions.
404Resource was not found.Check the request_id and account.
409Request conflict or messaging setup pending.Inspect the message; do not change retry keys blindly.
422Invalid payload or insufficient credits.Correct the fields in errors, or top up your account.
429API request rate exceeded.Slow down and respect the Retry-After response header.
500 / 503Temporary service error.Check status before retrying, preserving the original key.
{
  "message":"Insufficient available SMS credits.",
  "errors":{"credits":["Insufficient available SMS credits."]}
}

Keep secrets out of error reports. When contacting support, include the request_id, time and your own business reference.

Integration reference

Integration tools

Download the reference files or test from your workspace.

OpenAPI reference

Import the endpoint definitions into your preferred API tool.

Download OpenAPI

Postman collection

Set your base URL and credentials before making a request.

Download collection

SMS tester

Verify credentials, inspect segment estimates and follow your request.

Open tester