Developer API Documentation

Overview

The XeroSMS Developer API lets external platforms access our SMS services programmatically. Generate an API key from your profile page and use it to authenticate all API requests.

All API responses follow a consistent envelope format withsuccess,statusCode, andmessagefields.

Authentication

Before using the API, generate an API key from your profile page. Every request must include the key in the header:

Headerhttp

X-Api-Key: xero_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Security tip

Store API keys in backend environment variables or encrypted storage. Never expose them in client-side code.

SMS Service

Base URL:/api/v1/public/sms-service

GET/api/v1/public/sms-service/services

Get all services

Retrieve the list of supported SMS services.

Responsejson

{
  "success": true,
  "statusCode": 200,
  "message": "services retrieved successfully",
  "data": [
    { "ID": 1, "name": "Service Name", "favourite": 0 }
  ]
}

GET/api/v1/public/sms-service/services/:serviceId/countries

Get available countries

Retrieve pricing and availability for a specific service by country.

Responsejson

{
  "success": true,
  "statusCode": 200,
  "message": "service countries retrieved successfully",
  "data": [
    {
      "country": 1,
      "success_rate": "95.00",
      "price": "1.25",
      "low_price": "1.10",
      "country_id": 1,
      "name": "United States",
      "short_name": "US"
    }
  ]
}

The price and low_price already include the service charge markup configured in the system.

POST/api/v1/public/sms-service/order

Place an order

Place a new SMS service order. The cost is deducted atomically from the API key owner's balance.

Cost is calculated from the displayed country price.
Balance is deducted atomically from the key owner.

Requestjson

{
  "serviceId": "123",
  "countryId": "US"
}

Responsejson

{
  "success": true,
  "statusCode": 200,
  "message": "order created successfully",
  "data": {
    "order": {
      "id": "uuid",
      "serviceId": "123",
      "countryId": "US",
      "orderId": "sub-order-id",
      "phoneNumber": "+1234567890",
      "number": "1234567890",
      "pool": "1",
      "cc": "1",
      "country": "United States",
      "service": "Service Name",
      "status": "pending",
      "cost": 1.25, 
      "createdAt": "...",
      "updatedAt": "..."
    },
    "remainingBalance": 48.75
  }
}

GET/api/v1/public/sms-service/orders

List API orders

Returns only orders placed with the authenticated API key.

Optional query params:

searchTerm — search by orderId, country, service, phoneNumber, number
status — pending, completed, cancelled, refunded, expired
page, limit, sortBy, sortOrder

GET/api/v1/public/sms-service/orders/:orderId

Get single order

Retrieve local order information and live provider details. Pool in every 5s if local status is pending

Responsejson

{
  "success": true,
  "statusCode": 200,
  "message": " order retrieved successfully",
  "data": {
    "info": { /* local Order record */ },
    "details": { /* live info and sms text from provider if available */ }
  }
}

PATCH/api/v1/public/sms-service/orders/:orderId

Update order (refund)

Cancel and refund an order placed via the API.

Requestjson

{
  "status": "refunded"
}

Important Notes

Key Storage

The raw API key is shown only once during creation or regeneration. Store it securely and never expose it in frontend client-side code.

Error Handling

Common errors: 401 Unauthorized, 400 Bad Request (insufficient balance), 502 Bad Gateway (provider failure with auto-refund).