https://api.reach.voidxhq.com/v1

Developer API & Integration Guide

Integrate high-speed SMS dispatches, login OTPs, order notifications, and voice robocalls directly into your website, online store, or backend application.

1. Authentication & Base URL

All API requests must be made over HTTPS and authenticated using a Bearer token in the Authorization request header. Each Reach account has a unique, authenticated secret key tied directly to its prepaid wallet.

Base URL: https://api.reach.voidxhq.com/v1

Authorization: Bearer reach_live_sec_xxx

Content-Type: application/json

2. Quick Start: Send an SMS

POST /v1/sms/send

curl -X POST https://api.reach.voidxhq.com/v1/sms/send \
  -H "Authorization: Bearer reach_live_sec_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "sender_id": "MY-BRAND",
    "recipient": "0241234567",
    "message": "Hello Kofi, your order #1042 has been dispatched via Bolt delivery."
  }'

3. Endpoint: POST /v1/sms/send

Dispatch a single SMS or bulk recipients under your approved alphanumeric Sender ID.

Field	Type	Required	Description
sender_id	string	Yes	Your 11-character approved brand header (e.g. "MY-STORE").
recipient	string \| array	Yes	Ghanaian phone number (e.g. "0241234567" or "+233241234567") or array of numbers.
message	string	Yes	Text message content (up to 160 characters per segment).
schedule	string	Optional	ISO 8601 timestamp (e.g. "2026-10-15T08:00:00Z") for scheduled dispatch.

Success Response (200 OK)

{
  "status": "success",
  "message_id": "msg_01k7j48x9n2q8v1",
  "recipient": "233241234567",
  "units": 1,
  "rate_ghs": 0.045,
  "balance_remaining_ghs": 42.50
}

4. Endpoint: POST /v1/voice/send

Trigger simultaneous voice calls that play your pre-recorded audio note when answered.

curl -X POST https://api.reach.voidxhq.com/v1/voice/send \
  -H "Authorization: Bearer reach_live_sec_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "caller_id": "MY-BRAND",
    "recipients": ["0241234567", "0509876543"],
    "audio_url": "https://yourdomain.com/audio/announcement.mp3"
  }'

Auto-Refund Shield:You are charged GH₵ 0.10 only for calls that are answered. If a phone is busy, switched off, or rings without answer, the credit is immediately refunded back to your account.

5. Integration How-To Guides

How to Format Ghanaian Phone Numbers

Reach accepts local formats (024 123 4567), international with leading zero (+233241234567), or raw digits (233241234567). The API automatically strips spaces, dashes, and normalizes them for Tier-1 telco routing.

How to Calculate SMS Segments (GSM-7 Standard)

A single text message contains up to 160 characters. If your message exceeds 160 characters, it automatically concatenates into multiple segments (153 characters per segment) according to global telecom standards.

How to Register Your Sender ID for API Use

Under Ghana NCA anti-spoofing regulations, your alphanumeric Sender ID must be whitelisted before sending production traffic. Submit your Letter of Authorization through your Sender ID dashboard. Whitelisting takes up to 72 hours across MTN, Telecel, and AT networks.

6. HTTP Status & Error Codes

Status Code	Meaning	Resolution
200 OK	Message Accepted	Queued for carrier dispatch.
400 Bad Request	Missing Parameters	Verify required fields: sender_id, recipient, message.
401 Unauthorized	Invalid API Key	Check your Authorization Bearer token header.
402 Payment Required	Insufficient Balance	Top up your Mobile Money wallet on the dashboard.
422 Unprocessable	Unapproved Sender ID	Submit authorization letter for carrier whitelisting.

Need developer assistance?

Need help integrating the API into your website or e-commerce store? Get in touch directly with the developer.

Contact Developer