API Reference

Base URL: https://vokryn.com

Authentication

Pass your API key as a Bearer token in the Authorization header.

Authorization: Bearer vk_live_YOUR_API_KEY

# Example with curl:
curl https://vokryn.com/api/v1/messages \
  -H "Authorization: Bearer vk_live_..." \
  -H "Content-Type: application/json" \
  -d '{"to":"+233244123456","body":"Hello!"}'
vk_live_... — Production (real SMS) vk_test_... — Sandbox (no SMS sent)

Error format

{
  "error": "Validation failed",
  "code": "VALIDATION_ERROR",   // machine-readable code
  "status": 422,
  "details": { "errors": { ... } }
}
INVALID_BODY400Malformed JSON
VALIDATION_ERROR422Missing or invalid field
UNAUTHORIZED401Invalid or missing API key
RATE_LIMITED429Too many requests
SEND_FAILED502Carrier rejected the message
NOT_FOUND404Resource does not exist
EXPIRED410OTP code has expired
INVALID_CODE422Wrong OTP code

Endpoints

POST/api/v1/messagesSend SMS

Send a single SMS to any number in Africa or the US.

Request
{
  "to": "+233244123456",
  "body": "Your order is confirmed.",
  "from": "VOKRYN"  // optional sender ID
}
Response
{
  "id": "msg_01abc...",
  "status": "sent",
  "to": "+233244123456",
  "carrier": "africastalking",
  "segments": 1,
  "created_at": "2026-01-01T00:00:00Z"
}
POST/api/v1/messages/bulkBulk SMS

Send to up to 1,000 numbers in one request.

Request
{
  "to": ["+233244123456", "+233201234567"],
  "body": "Your account has been verified.",
  "from": "VOKRYN"
}
Response
{
  "total": 2,
  "sent": 2,
  "failed": 0,
  "results": [
    { "to": "+233244123456", "status": "sent", "message_id": "msg_..." },
    { "to": "+233201234567", "status": "sent", "message_id": "msg_..." }
  ]
}
POST/api/v1/otp/sendSend OTP

Send a one-time verification code to a phone number.

Request
{
  "to": "+233244123456",
  "code_length": 6,       // 4-8, default 6
  "expire_minutes": 5,    // 1-60, default 5
  "message_template": "Your code is {{code}}. Valid for {{expire_minutes}} min."
}
Response
{
  "reference": "otp_3f9a...",
  "to": "+233244123456",
  "expires_at": "2026-01-01T00:05:00Z",
  "status": "sent"
}
POST/api/v1/otp/verifyVerify OTP

Check a code entered by the user. Max 3 attempts.

Request
{
  "reference": "otp_3f9a...",
  "code": "847291"
}
Response
{
  "verified": true,
  "reference": "otp_3f9a...",
  "phone_number": "+233244123456"
}
GET/api/v1/messagesList Messages

Retrieve sent and received messages with pagination.

Request
GET /api/v1/messages?page=1&per_page=20
Response
{
  "data": [ { "id": "msg_...", "status": "delivered", ... } ],
  "meta": { "total": 142, "page": 1, "per_page": 20, "has_more": true }
}
POST/api/v1/numbersProvision Number

Provision a phone number in Ghana (GH) or US.

Request
{
  "country_code": "GH",
  "number_type": "mobile",
  "capabilities": { "sms": true, "voice": false }
}
Response
{
  "id": "num_...",
  "number": "+233244900123",
  "country_code": "GH",
  "monthly_cost": 1.00,
  "status": "active"
}

Node.js quickstart

Phone verification in under 10 lines

// npm install node-fetch  (or use built-in fetch in Node 18+)
const BASE = 'https://vokryn.com/api/v1'
const KEY  = 'vk_live_YOUR_KEY'

const headers = {
  'Authorization': `Bearer ${KEY}`,
  'Content-Type': 'application/json'
}

// 1. Send OTP
const { reference } = await fetch(`${BASE}/otp/send`, {
  method: 'POST', headers,
  body: JSON.stringify({ to: '+233244123456' })
}).then(r => r.json())

// 2. Verify the code the user enters
const result = await fetch(`${BASE}/otp/verify`, {
  method: 'POST', headers,
  body: JSON.stringify({ reference, code: userInput })
}).then(r => r.json())

if (result.verified) {
  console.log('Phone verified:', result.phone_number)
}