> For the complete documentation index, see [llms.txt](https://developers.textcus.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developers.textcus.com/readme.md).

# Introduction

TextCus lets you reach customers in Ghana over SMS, email and WhatsApp. These pages cover the APIs you can call from your own applications.

## Getting Started <a href="#getting-started" id="getting-started"></a>

{% hint style="info" %}
To send SMS using our APIs, you need to have a TextCus SMS Messaging account.

**Step 1: Create a TextCus SMS Messaging account (if you don't already have one)**

* Visit <https://sms.textcus.com/signup> to create a new SMS account.
* Follow the steps provided to activate your account.
  {% endhint %}

<figure><img src="https://2145235815-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1q7GngEbFdRj8vMLfNig%2Fuploads%2FPfw26AQkKtK7fakYfZQI%2FScreenshot%202026-09-09%20at%208.59.12%E2%80%AFAM.png?alt=media&amp;token=557c4eaf-a2de-4aa4-a3ff-9c0195048892" alt=""><figcaption></figcaption></figure>

## Overview

Our APIs are designed to integrate seamlessly with your systems and applications. This document is a comprehensive reference for all the features accessible through our APIs for adding and fetching data. It's designed around the primary resources you'll need most frequently and is made with RESTful standards in mind.

<table data-card-size="large" data-view="cards"><thead><tr><th></th><th></th><th></th></tr></thead><tbody><tr><td><p><mark style="color:yellow;"><strong><code>POST</code></strong></mark></p><p>To add new user data to the system, use this request.</p></td><td></td><td></td></tr><tr><td><mark style="color:green;"><strong><code>GET</code></strong></mark></td><td>To add and retrieve user data from the system, use this request.</td><td></td></tr></tbody></table>

## Authentication

Confirms your API key is valid and returns your account profile. Useful as a health check\
during integration.

**Reference your API Key**

{% hint style="info" %}
**Reference your API Key**

* Log in to your TextCus SMS Messaging account
* Go to API > API Access or visit <https://sms.textcus.com/api-access>
* Copy your API key for future reference
  {% endhint %}

The following format should be used for authorisation headers:

`Authorization: Bearer API_KEY`

{% hint style="info" %}
**Sample Authorization Header**

Authorization: Bearer 92857043717beff382ae75c8dc7514162f04
{% endhint %}

```bash
curl https://api.textcus.com/api/v2/user/authenticate \
  -H "Authorization: Bearer YOUR_API_KEY"
```

```json
{
  "status": true,
  "message": "Authenticated User",
  "user": { "id": 1, "firstname": "Watts", "email": "you@example.com", "...": "..." }
}
```

An invalid or missing key returns `401`:

```json
{ "error": "Unauthorized: Invalid API Key" }
```

{% hint style="warning" %}
This response contains your full account record, including your API key. Call it from your server only, and never log or forward the response.
{% endhint %}

### Available APIs

| API          | What it does                                                                           |
| ------------ | -------------------------------------------------------------------------------------- |
| SMS API      | Send SMS and one-time passcodes.                                                       |
| Senders API  | Register sender names and check their approval status.                                 |
| WhatsApp API | Send template and free-form WhatsApp messages, track delivery, and check your balance. |
| Email API    | Send email, track per-recipient delivery, and check your email credits.                |
| Account API  | Balances and API key verification.                                                     |

All endpoints live under `https://api.textcus.com/api/v2`.

## Requests and Response <a href="#authentication-1" id="authentication-1"></a>

The format of the response and request payloads is JSON. Responses will always have `application/json` as their content type. Each response will typically follow this format:

## Response Formats

<table><thead><tr><th width="255">Response</th><th>Data type</th><th>Description</th></tr></thead><tbody><tr><td>status</td><td>number</td><td>The HTTP status code indicating a status operation.</td></tr><tr><td>message</td><td>string</td><td>This gives you detailed explaination on the request sent. The interpretation of the status code.</td></tr><tr><td>data</td><td>object</td><td>An object holding any data that the API returned after receiving the request.</td></tr></tbody></table>

## **Status Codes and Interpretation**

| Status Code | Interpretation                                            |
| ----------- | --------------------------------------------------------- |
| `200`       | Standard for successful request.                          |
| `201`       | Used for requests as a result of creation.                |
| `204`       | Indicates that a request has succeeded or been processed. |
| `400`       | For bad requests.                                         |
| `401`       | For unathorized.                                          |
| `402`       | For payment required.                                     |
| `404`       | For not found.                                            |
| `500`       | For internal server errors.                               |

### A note on response codes

The SMS and Senders endpoints predate the WhatsApp API and behave differently: they reply with **HTTP 200 even on failure**, so you must check the `status` field in the body. The WhatsApp API uses conventional status codes (`402` for insufficient balance, `404` for a missing template, and so on). Handle both by checking `status` first, then the HTTP code.

### Need help?

Email <support@textcus.com> with the endpoint you called and the `message` from the response — that is usually enough for us to spot the problem immediately.