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
GET

Verify Token & Profile

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

Quickly test if your API token is valid and view the account name, email, and approved Sender IDs linked to this token.

Example Request

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

Success Response 200 OK

{
  "status": "success",
  "message": "API Token is valid.",
  "developer": "John Doe",
  "email": "developer@example.com",
  "approved_sender_ids": [
    "MyBrand",
    "Textflow"
  ]
}
GET

List Approved Sender IDs

https://textflow.ng/api/v1/sender-ids

Returns all approved Sender IDs available for your account, including the system default Textflow.

Example Request

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

Success Response 200 OK

{
  "status": "success",
  "data": [
    {
      "sender_name": "Textflow",
      "status": "active",
      "is_default": true
    },
    {
      "sender_name": "MyBrand",
      "status": "active",
      "is_default": false
    }
  ]
}
POST

Send SMS

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

Parameters

Name Type Description
sender_id (Optional) string Your approved Sender ID (max 11 characters). Defaults to Textflow if omitted.
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 Validation failure (e.g. unapproved Sender ID, missing message/recipients). {"message": "The selected Sender ID is not approved for your account. Available Sender IDs: MyBrand, Textflow"}
429 Too Many Requests Exceeded the 60 requests per minute limit. {"message": "Too Many Attempts."}