API Documentation

# Recommended
Authorization: Bearer bms_live_your_api_key_here

# Alternative
X-API-Key: bms_live_your_api_key_here

curl -X POST 'https://your-domain.com/api/v1/sms/send' \
  -H 'Authorization: Bearer bms_live_your_api_key' \
  -H 'Content-Type: application/json' \
  -d '{
    "recipients": ["0201234567", "0241234567"],
    "message": "Hello from FlashSMS!",
    "senderId": "MyBrand",
    "campaignName": "Welcome Campaign"
  }'

{
  "success": true,
  "data": {
    "messageId": "cmjveqxgf0001jr04abc123",
    "recipientsSent": 2,
    "invalidRecipients": [],
    "creditsUsed": 2,
    "remainingCredits": 998,
    "scheduled": false,
    "scheduleDate": null
  }
}

curl 'https://your-domain.com/api/v1/balance' \
  -H 'Authorization: Bearer bms_live_your_api_key'

{
  "success": true,
  "data": {
    "balance": 1000,
    "currency": "credits",
    "accountName": "John Doe",
    "accountPhone": "0201234567"
  }
}

curl 'https://your-domain.com/api/v1/sms?page=1&limit=20&status=DELIVERED' \
  -H 'Authorization: Bearer bms_live_your_api_key'

{
  "success": true,
  "data": {
    "messages": [
      {
        "id": "cmjveqxgf0001jr04abc123",
        "message": "Hello from FlashSMS! (truncated to 160 chars)",
        "recipientCount": 2,
        "status": "DELIVERED",
        "creditsUsed": 2,
        "senderId": "MyBrand",
        "scheduledAt": null,
        "sentAt": "2024-12-21T10:30:00Z",
        "createdAt": "2024-12-21T10:30:00Z"
      }
    ],
    "pagination": {
      "page": 1,
      "limit": 20,
      "total": 150,
      "totalPages": 8,
      "hasMore": true
    }
  }
}

{
  "success": true,
  "data": {
    "id": "cmjveqxgf0001jr04abc123",
    "status": "DELIVERED",
    "recipientCount": 2,
    "message": "Hello from FlashSMS!",
    "senderId": "MyBrand",
    "creditsUsed": 2,
    "scheduledAt": null,
    "sentAt": "2024-12-21T10:30:00Z",
    "createdAt": "2024-12-21T10:30:00Z"
  }
}

{
  "success": true,
  "data": {
    "message": {
      "length": 145,
      "parts": 1,
      "encoding": "GSM-7"
    },
    "recipientCount": 500,
    "creditsRequired": 500,
    "currentBalance": 1000,
    "canAfford": true
  }
}

{
  "success": true,
  "data": {
    "messageId": "cmjveqxgf0001jr04abc123",
    "status": "DELIVERED",
    "recipientCount": 3,
    "recipients": [
      { "phone": "233201234567", "status": "DELIVERED", "sentAt": "2024-12-21T10:30:00Z" },
      { "phone": "233241234567", "status": "FAILED",    "sentAt": null }
    ],
    "stats": {
      "delivered": 2,
      "failed": 1,
      "pending": 0,
      "deliveryRate": 66.7
    }
  }
}

# List contacts
curl 'https://your-domain.com/api/v1/contacts?page=1&limit=50' \
  -H 'Authorization: Bearer bms_live_your_api_key'

# Create a contact
curl -X POST 'https://your-domain.com/api/v1/contacts' \
  -H 'Authorization: Bearer bms_live_your_api_key' \
  -H 'Content-Type: application/json' \
  -d '{"phone": "0201234567", "firstName": "Kofi", "lastName": "Mensah"}'

# Bulk import
curl -X POST 'https://your-domain.com/api/v1/contacts/import' \
  -H 'Authorization: Bearer bms_live_your_api_key' \
  -H 'Content-Type: application/json' \
  -d '{"contacts": [{"phone": "0201234567", "firstName": "Kofi"}, {"phone": "0241234567", "firstName": "Ama"}], "groupId": "grp_abc123"}'

# Delete a contact (soft delete)
curl -X DELETE 'https://your-domain.com/api/v1/contacts/cnt_abc123' \
  -H 'Authorization: Bearer bms_live_your_api_key'

{
  "success": true,
  "data": {
    "imported": 9,
    "created": 7,
    "skipped": 2,
    "invalid": 1,
    "total": 10
  }
}

# List groups
curl 'https://your-domain.com/api/v1/contacts/groups' \
  -H 'Authorization: Bearer bms_live_your_api_key'

# Create a group
curl -X POST 'https://your-domain.com/api/v1/contacts/groups' \
  -H 'Authorization: Bearer bms_live_your_api_key' \
  -H 'Content-Type: application/json' \
  -d '{"name": "VIP Customers"}'

# Delete a group (contacts are NOT deleted)
curl -X DELETE 'https://your-domain.com/api/v1/contacts/groups/grp_abc123' \
  -H 'Authorization: Bearer bms_live_your_api_key'

{
  "success": true,
  "data": {
    "groups": [
      { "id": "grp_abc123", "name": "VIP Customers", "contactCount": 142, "createdAt": "2024-12-01T09:00:00Z" },
      { "id": "grp_def456", "name": "Newsletter",     "contactCount": 830, "createdAt": "2024-11-15T14:00:00Z" }
    ]
  }
}

curl 'https://your-domain.com/api/v1/sender-ids' \
  -H 'Authorization: Bearer bms_live_your_api_key'

{
  "success": true,
  "data": {
    "senderIds": [
      { "id": "sid_abc123", "name": "MyBrand", "status": "APPROVED", "createdAt": "2024-10-01T00:00:00Z", "approvedAt": "2024-10-03T12:00:00Z" }
    ]
  }
}

# List templates
curl 'https://your-domain.com/api/v1/templates' \
  -H 'Authorization: Bearer bms_live_your_api_key'

# Create a template
curl -X POST 'https://your-domain.com/api/v1/templates' \
  -H 'Authorization: Bearer bms_live_your_api_key' \
  -H 'Content-Type: application/json' \
  -d '{"name": "Welcome Message", "content": "Hi {{name}}, welcome to our platform!"}'

# Delete a template
curl -X DELETE 'https://your-domain.com/api/v1/templates/tpl_abc123' \
  -H 'Authorization: Bearer bms_live_your_api_key'

curl 'https://your-domain.com/api/v1/transactions?page=1&limit=20&type=USAGE' \
  -H 'Authorization: Bearer bms_live_your_api_key'

{
  "success": true,
  "data": {
    "transactions": [
      {
        "id": "txn_abc123",
        "type": "USAGE",
        "amount": -50,
        "balance": 950,
        "description": "API SMS: Welcome Campaign (50 recipients)",
        "reference": "cmjveqxgf0001jr04abc123",
        "createdAt": "2024-12-21T10:30:00Z"
      }
    ],
    "pagination": {
      "page": 1,
      "limit": 20,
      "total": 84,
      "totalPages": 5,
      "hasMore": true
    }
  }
}

{
  "success": false,
  "error": "A description of what went wrong"
}

const API_KEY = 'bms_live_your_api_key';
const BASE_URL = 'https://your-domain.com/api/v1';
const headers = {
  'Authorization': `Bearer ${API_KEY}`,
  'Content-Type': 'application/json',
};

async function sendSms(recipients, message, senderId = 'FlashSMS') {
  const res = await fetch(`${BASE_URL}/sms/send`, {
    method: 'POST',
    headers,
    body: JSON.stringify({ recipients, message, senderId }),
  });
  return res.json();
}

async function sendToGroup(groupId, message) {
  const res = await fetch(`${BASE_URL}/sms/send`, {
    method: 'POST',
    headers,
    body: JSON.stringify({ groupId, message }),
  });
  return res.json();
}

async function checkBalance() {
  const res = await fetch(`${BASE_URL}/balance`, { headers });
  return res.json();
}

async function listContacts(page = 1) {
  const res = await fetch(`${BASE_URL}/contacts?page=${page}&limit=50`, { headers });
  return res.json();
}

// Usage
const result = await sendSms(['0201234567'], 'Hello from FlashSMS!');
console.log(`Sent: ${result.data.recipientsSent} messages — ${result.data.creditsUsed} credits used`);

const groupResult = await sendToGroup('grp_abc123', 'Promotion for VIP customers!');
console.log(`Group send: ${groupResult.data.recipientsSent} recipients`);

const { data } = await checkBalance();
console.log(`Balance: ${data.balance} credits`);