API Documentation

Our API is RESTful, accepts JSON payloads, and returns JSON responses.

Base URL: https://gatewire.net/api/v1

Authentication

Pass your API token in the Authorization header on every request.

Authorization: Bearer YOUR_API_TOKEN

Create a free account to get your API token.

1. Send OTP

POST /send-otp

Dispatch a verification code to a phone number. Returns immediately with a reference_id — the SMS is sent asynchronously by an available node device.

Use Message Templates

Pass a template_key to use a pre-approved message template instead of a raw body.

Request Body

Field	Type	Description
phone	string	Required Recipient number (e.g. `+213555123456`)
template_key	string	OTP template key (e.g. `login_otp`). Omit to use the default.

curl -X POST "https://gatewire.net/api/v1/send-otp" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"phone": "+2135550123", "template_key": "login_otp"}'

$response = $client->post('https://gatewire.net/api/v1/send-otp', [
    'headers' => ['Authorization' => 'Bearer YOUR_TOKEN'],
    'json'    => ['phone' => '+2135550123', 'template_key' => 'login_otp'],
]);
$data = json_decode($response->getBody(), true);
$referenceId = $data['reference_id'];

import requests
r = requests.post(
    "https://gatewire.net/api/v1/send-otp",
    headers={"Authorization": "Bearer YOUR_TOKEN"},
    json={"phone": "+2135550123", "template_key": "login_otp"}
)
reference_id = r.json()["reference_id"]

const { reference_id } = await fetch('https://gatewire.net/api/v1/send-otp', {
    method: 'POST',
    headers: { 'Authorization': 'Bearer YOUR_TOKEN', 'Content-Type': 'application/json' },
    body: JSON.stringify({ phone: '+2135550123', template_key: 'login_otp' })
}).then(r => r.json());

Response 200 OK

{
  "reference_id": "wg_01HX...",  // Store this for verification
  "status": "pending"
}

2. Verify Code

POST /verify-otp

Validate the code your user entered. Use the reference_id from step 1.

Request Body

Field	Type	Description
reference_id	string	The ID returned by `/send-otp`.
code	string	The 4–8 digit code entered by the user.

curl -X POST "https://gatewire.net/api/v1/verify-otp" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"reference_id": "wg_01HX...", "code": "4827"}'

$response = $client->post('https://gatewire.net/api/v1/verify-otp', [
    'headers' => ['Authorization' => 'Bearer YOUR_TOKEN'],
    'json'    => ['reference_id' => 'wg_01HX...', 'code' => '4827'],
]);
// 200 = verified, 400 = wrong code / expired

const res = await fetch('https://gatewire.net/api/v1/verify-otp', {
    method: 'POST',
    headers: { 'Authorization': 'Bearer YOUR_TOKEN', 'Content-Type': 'application/json' },
    body: JSON.stringify({ reference_id: 'wg_01HX...', code: '4827' })
});
if (res.ok) { /* verified */ } else { /* wrong code */ }

Responses

// 200 OK

{ "status": "verified", "message": "Success" }

// 400 Bad Request

{ "error": "Invalid or expired code." }

3. Check Status

GET /status/{reference_id}

Poll the delivery status of an OTP request. Useful when implementing your own polling loop.

curl "https://gatewire.net/api/v1/status/wg_01HX..." \
  -H "Authorization: Bearer YOUR_TOKEN"

Status values

Status	Meaning
pending	Queued, waiting for a device
dispatched	Assigned to a device, sending in progress
sent	Device confirmed SMS submitted to carrier
verified	User entered the correct code ✓
failed	Delivery failed after all attempts
expired	Time window passed without verification
cancelled	Superseded by a newer send request

API Développeur