Textify Africa

https://docs.textify.africa
Admin
Textify Africa is a bulk SMS platform for businesses in Africa that enables sending transactional...
Tokens:6,478
Snippets:57
Trust Score:4.6
Update:2 months ago
Show doc for...
Tokens:
Raw
### List Messages Response Format

Source: https://docs.textify.africa/sms-api

Example JSON response structure returned by the GET /messages endpoint.

```json
{  "success": true,  "status_code": 200,  "status_text": "OK",  "message": "messages have been fetched",  "data": {  "data": [  {  "id": "6b2f6e2a-4b0e-4e9a-9a2e-1a2b3c4d5e6f",  "sender_name_id": "9a1c...",  "sender_name": "MYBRAND",  "contact_id": "3d4e...",  "phone_number": "255712345678",  "contact_name": "Asha M",  "content": "Hello Asha, your order is ready",  "count": 1,  "status": "delivered",  "is_scheduled": false,  "scheduled_date": null,  "message_id": "AT-8817263",  "failure_reason": null,  "created_by": "c62f7e2a-...",  "created_by_name": "jane@example.com",  "created_at": "2026-07-10T08:12:41Z",  "updated_at": "2026-07-10T08:13:05Z"  }  ],  "total": 42,  "page": 1,  "limit": 20,  "total_pages": 3,  "has_next_page": true,  "has_previous_page": false,  "next_page": 2,  "previous_page": null  } }
```

--------------------------------

### Get Message by ID Response

Source: https://docs.textify.africa/sms-api

Example JSON response returned upon a successful 200 OK request.

```json
{  "success": true,  "status_code": 200,  "status_text": "OK",  "message": "message has been fetched",  "data": {  "id": "6b2f6e2a-4b0e-4e9a-9a2e-1a2b3c4d5e6f",  "sender_name_id": "9a1c...",  "sender_name": "MYBRAND",  "contact_id": "3d4e...",  "phone_number": "255712345678",  "contact_name": "Asha M",  "content": "Hello Asha, your order is ready",  "count": 1,  "status": "delivered",  "is_scheduled": false,  "scheduled_date": null,  "message_id": "AT-8817263",  "whatsapp_number": null,  "next_check_at": null,  "failure_reason": null,  "created_by": "c62f7e2a-...",  "created_by_name": "jane@example.com",  "created_at": "2026-07-10T08:12:41Z",  "updated_by": null,  "updated_by_name": null,  "updated_at": "2026-07-10T08:13:05Z"  } }
```

--------------------------------

### Authenticated Request

Source: https://docs.textify.africa/authentication

Example of how to include the API key in the Authorization header using curl.

```bash
curl https://portal.textify.africa/api/v1/messages \  -H "Authorization: Bearer txf_92c58d699610fc2233f871f05fcb5b78b5f07a483a449525b53c71732af0caf6"
```

--------------------------------

### POST /api/v1/messages

Source: https://docs.textify.africa/request-response-format

Example of sending a message request to the API.

```APIDOC
## POST /api/v1/messages

### Description
Sends a message to a specified receiver.

### Method
POST

### Endpoint
https://portal.textify.africa/api/v1/messages

### Request Body
- **sender_name** (string) - Required - The name of the sender.
- **messages** (array) - Required - A list of message objects.
  - **receiver** (string) - Required - The recipient's phone number.
  - **content** (string) - Required - The message content.

### Request Example
{
  "sender_name": "MYBRAND",
  "messages": [
    {
      "receiver": "0712345678",
      "content": "Hi"
    }
  ]
}
```

--------------------------------

### Send a POST request

Source: https://docs.textify.africa/request-response-format

Example of sending a message using cURL with the required headers and JSON body.

```bash
curl -X POST https://portal.textify.africa/api/v1/messages \  -H "Authorization: Bearer $API_KEY" \  -H "Content-Type: application/json" \  -d '{ "sender_name": "MYBRAND", "messages": [ { "receiver": "0712345678", "content": "Hi" } ] }'
```

--------------------------------

### List Messages via cURL

Source: https://docs.textify.africa/sms-api

Retrieves a paginated list of messages using the GET /messages endpoint with authorization headers.

```bash
curl "https://portal.textify.africa/api/v1/messages?page=1&limit=20&status=delivered&sort_dir=desc" \  -H "Authorization: Bearer $API_KEY"
```

--------------------------------

### GET /messages

Source: https://docs.textify.africa/sms-api

Retrieves a paginated list of messages owned by the caller.

```APIDOC
## GET /messages

### Description
Paginated list of messages the caller owns (or all messages, for admins).

### Method
GET

### Endpoint
https://portal.textify.africa/api/v1/messages

### Parameters
#### Query Parameters
- **page** (int) - Optional - Page number. Default 1.
- **limit** (int) - Optional - Records per page. Default 10, max 1000.
- **sort_by** (string) - Optional - One of status, count, is_scheduled, scheduled_date, created_at, updated_at. Default created_at.
- **sort_dir** (string) - Optional - asc or desc. Default desc.
- **status** (string) - Optional - Filter by exact status, e.g. delivered, sent, failed.
- **scheduled** (boolean) - Optional - true returns only scheduled messages.

### Request Example
curl "https://portal.textify.africa/api/v1/messages?page=1&limit=20&status=delivered&sort_dir=desc" -H "Authorization: Bearer $API_KEY"

### Response
#### Success Response (200)
- **success** (boolean) - Indicates request success
- **data** (object) - Contains the list of messages and pagination metadata

#### Response Example
{
  "success": true,
  "status_code": 200,
  "status_text": "OK",
  "message": "messages have been fetched",
  "data": {
    "data": [
      {
        "id": "6b2f6e2a-4b0e-4e9a-9a2e-1a2b3c4d5e6f",
        "sender_name": "MYBRAND",
        "phone_number": "255712345678",
        "content": "Hello Asha, your order is ready",
        "status": "delivered",
        "created_at": "2026-07-10T08:12:41Z"
      }
    ],
    "total": 42,
    "page": 1,
    "limit": 20
  }
}
```

--------------------------------

### GET /messages/{id}

Source: https://docs.textify.africa/sms-api

Fetch a single message, including its joined sender name, recipient and contact name.

```APIDOC
## GET /messages/{id}

### Description
Fetch a single message, including its joined sender name, recipient and contact name.

### Method
GET

### Endpoint
https://portal.textify.africa/api/v1/messages/{id}

### Parameters
#### Path Parameters
- **id** (uuid) - Required - Message id.

### Request Example
curl https://portal.textify.africa/api/v1/messages/6b2f6e2a-4b0e-4e9a-9a2e-1a2b3c4d5e6f \
  -H "Authorization: Bearer $API_KEY"

### Response
#### Success Response (200)
- **success** (boolean) - Status of the request
- **data** (object) - The message object containing id, status, content, count, sender_name, phone_number, contact_name, is_scheduled, scheduled_date, message_id, failure_reason, and created_at.

#### Response Example
{
  "success": true,
  "status_code": 200,
  "status_text": "OK",
  "message": "message has been fetched",
  "data": {
    "id": "6b2f6e2a-4b0e-4e9a-9a2e-1a2b3c4d5e6f",
    "sender_name": "MYBRAND",
    "phone_number": "255712345678",
    "contact_name": "Asha M",
    "content": "Hello Asha, your order is ready",
    "count": 1,
    "status": "delivered",
    "is_scheduled": false,
    "scheduled_date": null,
    "message_id": "AT-8817263",
    "failure_reason": null,
    "created_at": "2026-07-10T08:12:41Z"
  }
}
```

--------------------------------

### GET /messages/search

Source: https://docs.textify.africa/sms-api

Searches messages based on content and recipient.

```APIDOC
## GET /messages/search

### Description
Searches for messages matching the provided search query against message content and recipient.

### Method
GET

### Endpoint
https://portal.textify.africa/api/v1/messages/search

### Parameters
#### Query Parameters
- **search** (string) - Required - The search term to match against content and recipient.
- **page** (int) - Optional - Page number.
- **limit** (int) - Optional - Records per page.
```

--------------------------------

### Get Message by ID Request

Source: https://docs.textify.africa/sms-api

Use this cURL command to retrieve a specific message by its UUID. Requires a valid API key in the Authorization header.

```bash
curl https://portal.textify.africa/api/v1/messages/6b2f6e2a-4b0e-4e9a-9a2e-1a2b3c4d5e6f \  -H "Authorization: Bearer $API_KEY"
```

--------------------------------

### Authentication Overview

Source: https://docs.textify.africa/authentication

Details on how to use API keys for authenticating requests and handling authentication errors.

```APIDOC
## Authentication

### Description
Most endpoints require an API key for authentication. The key must be sent in the `Authorization` header, prefixed with `Bearer `.

### Usage
Include the `Authorization` header in your request:
`Authorization: Bearer <your_api_key>`

### Authentication Errors
If a request is missing or has an invalid key, the API returns a `401 Unauthorized` status code with a machine-readable `error` field.

| Status | Error | Meaning |
|---|---|---|
| 401 | missing_token | No Authorization header was sent. |
| 401 | invalid_token | The API key doesn't match any account. |
| 401 | account_not_found | The account tied to the key no longer exists. |
| 401 | account_disabled | The account has been disabled by an administrator. |
| 401 | account_not_verified | The account has not completed OTP verification yet. |
```

--------------------------------

### Pagination Parameters

Source: https://docs.textify.africa/request-response-format

Standard query parameters for list endpoints.

```APIDOC
### Parameters
#### Query Parameters
- **page** (integer) - Optional - Page number (Default: 1).
- **limit** (integer) - Optional - Records per page, max 1000 (Default: 10).
- **sort_by** (string) - Optional - Column to sort by (Default: created_at).
- **sort_dir** (string) - Optional - Sort direction, asc or desc (Default: desc).
- **search** (string) - Optional - Search query (Required on /search endpoints).
```

--------------------------------

### Success response

Source: https://docs.textify.africa/sms-api

The API returns a 201 Created status upon successful queuing of messages.

```json
{  "success": true,  "status_code": 201,  "status_text": "Created",  "message": "messages have been created",  "data": null }
```

--------------------------------

### POST /messages

Source: https://docs.textify.africa/sms-api

Creates and queues one or many messages atomically. The sender name must be approved and owned by the caller, and balance or postpaid limits are checked during the transaction.

```APIDOC
## POST /messages

### Description
Creates and queues one or many messages atomically. Unknown recipients are auto-created as contacts, and balance or postpaid limits are verified.

### Method
POST

### Endpoint
https://portal.textify.africa/api/v1/messages

### Parameters
#### Request Body
- **sender_name** (string) - Optional - An approved sender name you own or are assigned to.
- **messages** (array) - Required - One or more { receiver, content } objects.
- **messages[].receiver** (string) - Required - Recipient phone number in international format.
- **messages[].content** (string) - Required - Message text (160 characters = 1 unit).
- **is_scheduled** (boolean) - Optional - Defaults to false.
- **scheduled_date** (string) - Optional - Required when is_scheduled is true (ISO 8601).

### Request Example
{
  "sender_name": "MYBRAND",
  "is_scheduled": false,
  "messages": [
    { "receiver": "0712345678", "content": "Hello Asha, your order is ready" }
  ]
}

### Response
#### Success Response (201)
- **success** (boolean) - Indicates operation success.
- **status_code** (integer) - 201.
- **status_text** (string) - Created.
- **message** (string) - Confirmation message.

#### Response Example
{
  "success": true,
  "status_code": 201,
  "status_text": "Created",
  "message": "messages have been created",
  "data": null
}
```

--------------------------------

### POST /otps/verify

Source: https://docs.textify.africa/otp-api

Verifies a 6-digit OTP code. This endpoint is public and does not require an API key.

```APIDOC
## POST /otps/verify

### Description
Consumes a code to verify an OTP. Each OTP can only be verified once.

### Method
POST

### Endpoint
https://portal.textify.africa/api/v1/otps/verify

### Parameters
#### Request Body
- **code** (number) - Required - The 6-digit OTP code.
- **phone_number** (string) - Optional - Must match the number the OTP was sent to.
- **email_address** (string) - Optional - Alternative match target if the OTP was also emailed.

### Request Example
{
  "code": 484895,
  "phone_number": "0712345678"
}

### Response
#### Success Response (200)
- **success** (boolean) - Indicates if the verification was successful.
- **message** (string) - Confirmation message.

#### Response Example
{
  "success": true,
  "status_code": 200,
  "status_text": "OK",
  "message": "otp has been verified",
  "data": null
}
```

--------------------------------

### Base URL

Source: https://docs.textify.africa/base-url

The base URL for all API endpoints and the current versioning information.

```APIDOC
## Base URL

### Description
All API endpoints are relative to the following base URL. All traffic must be sent over HTTPS.

### Base URL
`https://portal.textify.africa/api/v1`

### Versioning
`/api/v1` is the current and only stable version. Breaking changes will be introduced under a new version prefix.
```

--------------------------------

### Schedule an SMS

Source: https://docs.textify.africa/sms-api

Set is_scheduled to true and provide a valid ISO 8601 scheduled_date to queue a message for future delivery.

```json
{  "sender_name": "MYBRAND",  "is_scheduled": true,  "scheduled_date": "2026-07-20T08:00:00Z",  "messages": [  { "receiver": "0712345678", "content": "Reminder: your appointment is tomorrow" }  ] }
```

--------------------------------

### Verify OTP via cURL

Source: https://docs.textify.africa/otp-api

Verifies a 6-digit OTP code. This endpoint is public and does not require an API key.

```bash
curl -X POST https://portal.textify.africa/api/v1/otps/verify \
  -H "Content-Type: application/json" \
  -d '{ "code": 484895, "phone_number": "0712345678" }'
```

--------------------------------

### Send OTP Success Response

Source: https://docs.textify.africa/otp-api

The JSON response returned upon a successful OTP dispatch.

```json
{
  "success": true,
  "status_code": 200,
  "status_text": "OK",
  "message": "otp has been sent",
  "data": null
}
```

--------------------------------

### Verify OTP Success Response

Source: https://docs.textify.africa/otp-api

The JSON response returned upon successful verification of an OTP.

```json
{
  "success": true,
  "status_code": 200,
  "status_text": "OK",
  "message": "otp has been verified",
  "data": null
}
```

--------------------------------

### POST /otps

Source: https://docs.textify.africa/otp-api

Sends a 6-digit OTP code to a specified phone number and optional email address. Branded OTPs require an approved sender name and are billed to the caller's balance.

```APIDOC
## POST /otps

### Description
Sends a 6-digit code by SMS (and by email, if email_address is provided). Without sender_name, the code is delivered for free via the system sender.

### Method
POST

### Endpoint
https://portal.textify.africa/api/v1/otps

### Parameters
#### Request Body
- **phone_number** (string) - Required - Recipient phone number. Normalized to 255… international format.
- **email_address** (string) - Optional - When set, the OTP is also emailed to this address.
- **sender_name** (string) - Optional - An approved sender name you own. Omit to send free from the system sender.
- **brand_name** (string) - Optional - Brand name interpolated into the OTP message.

### Request Example
{
  "phone_number": "0712345678",
  "email_address": "customer@example.com",
  "sender_name": "MYBRAND",
  "brand_name": "My Brand"
}

### Response
#### Success Response (200)
- **success** (boolean) - Indicates if the request was successful.
- **message** (string) - Confirmation message.

#### Response Example
{
  "success": true,
  "status_code": 200,
  "status_text": "OK",
  "message": "otp has been sent",
  "data": null
}
```

--------------------------------

### Send OTP via cURL

Source: https://docs.textify.africa/otp-api

Sends a 6-digit OTP to a phone number and optional email address. Requires a bearer token for authentication.

```bash
curl -X POST https://portal.textify.africa/api/v1/otps \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
     "phone_number": "0712345678",
     "email_address": "customer@example.com",
     "sender_name": "MYBRAND",
     "brand_name": "My Brand"
   }'
```

--------------------------------

### POST <your webhook_url>

Source: https://docs.textify.africa/webhooks

The callback endpoint that receives JSON payloads when a message status changes to delivered or undelivered.

```APIDOC
## POST <your webhook_url>

### Description
Textify Africa sends an HTTP POST request to your registered webhook URL whenever a message transitions to 'delivered' or 'undelivered'.

### Method
POST

### Parameters
#### Request Body
- **id** (uuid) - Required - The message id.
- **status** (string) - Required - The message's new status: delivered or undelivered.

### Request Example
{
  "id": "6b2f6e2a-4b0e-4e9a-9a2e-1a2b3c4d5e6f",
  "status": "delivered"
}

### Response
#### Success Response (2xx)
- Acknowledge receipt of the callback.
```

--------------------------------

### Send an SMS via cURL

Source: https://docs.textify.africa/

Sends a single or bulk SMS message using the /messages endpoint. Requires a valid API key in the Authorization header.

```bash
curl -X POST https://portal.textify.africa/api/v1/messages \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
     "sender_name": "MYBRAND",
     "is_scheduled": false,
     "messages": [
       { "receiver": "0712345678", "content": "Hello Asha, your order is ready" }
     ]
   }'
```

--------------------------------

### API Key Generation Response

Source: https://docs.textify.africa/authentication

The JSON response structure returned after successfully generating a new API key.

```json
{  "success": true,  "status_code": 200,  "status_text": "OK",  "message": "api key has been generated",  "data": {  "api_key": "txf_92c58d699610fc2233f871f05fcb5b78b5f07a483a449525b53c71732af0caf6"  } }
```

--------------------------------

### API Response Envelopes

Source: https://docs.textify.africa/request-response-format

Standard JSON response structures for successful operations and error states.

```json
{  "success": true,  "status_code": 200,  "status_text": "OK",  "message": "message has been sent",  "data": { } }
```

```json
{  "success": false,  "status_code": 400,  "status_text": "Bad Request",  "message": "no receiver has been provided",  "error": "validation_error" }
```

--------------------------------

### 401 Unauthorized Error Response

Source: https://docs.textify.africa/authentication

The JSON response structure returned when authentication fails.

```json
{  "success": false,  "status_code": 401,  "status_text": "Unauthorized",  "message": "invalid api key",  "error": "invalid_token" }
```

--------------------------------

### Send bulk SMS messages

Source: https://docs.textify.africa/sms-api

Include multiple objects in the messages array to send to several recipients in one request.

```json
{  "sender_name": "MYBRAND",  "is_scheduled": false,  "messages": [  { "receiver": "0711111111", "content": "Hello Asha, your order is ready" },  { "receiver": "0722222222", "content": "Hi, your order is ready" }  ] }
```

--------------------------------

### POST /api/v1/messages

Source: https://docs.textify.africa/

Sends one or more SMS messages to specified recipients, either immediately or scheduled for a future date.

```APIDOC
## POST /api/v1/messages

### Description
Sends bulk or single SMS messages to recipients. Supports custom sender names and scheduling.

### Method
POST

### Endpoint
https://portal.textify.africa/api/v1/messages

### Request Body
- **sender_name** (string) - Required - The approved brand name to send the message under.
- **is_scheduled** (boolean) - Required - Whether the message is scheduled for a future date.
- **messages** (array) - Required - A list of message objects containing receiver and content fields.
```

--------------------------------

### Paginated Response Structure

Source: https://docs.textify.africa/request-response-format

The structure of the data field when a list endpoint returns paginated results.

```json
{  "success": true,  "status_code": 200,  "status_text": "OK",  "message": "messages retrieved",  "data": {  "data": [ { "id": "…", "status": "delivered" } ],  "total": 42,  "page": 1,  "limit": 10,  "total_pages": 5,  "has_next_page": true,  "has_previous_page": false,  "next_page": 2,  "previous_page": null  } }
```

--------------------------------

### Message Status Callback Payload

Source: https://docs.textify.africa/webhooks

The JSON structure sent to your webhook URL when a message status changes to delivered or undelivered.

```json
{  "id": "6b2f6e2a-4b0e-4e9a-9a2e-1a2b3c4d5e6f",  "status": "delivered" }
```
Tokens:
Raw