Textflow API Reference

Integrate seamless SMS delivery into your application in minutes using our RESTful API. Connect your software, automate campaigns, and track deliveries in real-time.

Authentication

The Textflow API uses API tokens to authenticate requests. You can view and manage your API tokens in your Dashboard Settings.

You must include your API token in the Authorization header of every request as a Bearer token.

Authorization: Bearer YOUR_API_TOKEN
Accept: application/json
POST

Send SMS

https://textflow.ng/api/v1/sms/send

Parameters

Name Type Description
sender_id * string Your approved Sender ID (max 11 characters).
recipients * string Comma or newline separated list of destination phone numbers.
message * string The body of the SMS text message.

Example Request (cURL)

curl -X POST https://textflow.ng/api/v1/sms/send \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "sender_id": "Textflow",
    "recipients": "08012345678,08123456789",
    "message": "Hello, this is a test message via API."
  }'

Success Response 202 Accepted

{
  "status": "success",
  "message": "Messages queued successfully.",
  "data": {
    "batch_id": 1452,
    "total_recipients": 2,
    "total_cost": 8.00,
    "balance_remaining": 492.00
  }
}
GET

Check Wallet Balance

https://textflow.ng/api/v1/balance

Example Request

curl -X GET https://textflow.ng/api/v1/balance \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Accept: application/json"

Success Response 200 OK

{
  "status": "success",
  "data": {
    "currency": "NGN",
    "balance": 500.00
  }
}
GET

Check Batch Status

https://textflow.ng/api/v1/sms/status?batch_id={id}

Example Request

curl -X GET "https://textflow.ng/api/v1/sms/status?batch_id=1452" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Accept: application/json"

Success Response 200 OK

{
  "status": "success",
  "data": {
    "batch_id": 1452,
    "status": "completed",
    "total_recipients": 2,
    "created_at": "2026-06-23T10:00:00Z"
  }
}

Common Error Responses

HTTP Status Reason Example Output
401 Unauthorized Invalid or missing API token. {"message": "Unauthenticated."}
402 Payment Required Wallet balance is too low to process the campaign. {"status": "error", "message": "Insufficient funds."}
422 Unprocessable Missing required parameters (e.g., no sender_id). {"message": "The sender_id field is required."}
429 Too Many Requests Exceeded the 60 requests per minute limit. {"message": "Too Many Attempts."}