To add new user data to the system, use this request. | ||
GET | To add and retrieve user data from the system, use this request. |
| Response | Data type | Description |
|---|---|---|
| status | number | The HTTP status code indicating a status operation. |
| message | string | This gives you detailed explaination on the request sent. The interpretation of the status code. |
| data | object | An object holding any data that the API returned after receiving the request. |
| Parameters | Type | Description |
|---|---|---|
type | Required | It indicates the type of message. Values for "type" include: 0 : Plain text (GSM 3.38 Character encoding) 1 : Flash (GSM 3.38 Character encoding) 2 : Unicode 3 : Reserved 5 : Plain text (ISO-8859-1 Character encoding) 6 : Unicode Flash 7 : Flash (ISO-8859-1 Character encoding) |
source | Required | The source address that should appear in the message. - Max Length of 18 if numeric. - Max Length of 11 if alphanumeric. To prefix the plus sign (+) to the sender’s address when the message is displayed on their mobile phone, please prefix the plus sign to your sender’s address while submitting the message. Note: You need to URL encode the plus sign. The SMSC may enforce additional restrictions on this field. |
destination | Required | Recipient phone number Must be a valid MSIDSN Must be in the international telephone number format (may or may not include a plus [+] sign) symbol. e.g. 233241234567 or +233241234567 Multiple mobile numbers need to be separated by a comma (,) (the comma should be URL encoded). |
dlr | Required | Indicates whether the client wants a delivery report for this message. The values for "dlr" include: 0 : No delivery report required 1 : Delivery report required |
message | Required | The message to be sent. Must be URL encoded. |
time | Optional | To schedule the message to be sent sometime or date in the future Format: YYYY-MM-DD HH:MM:SS or UNIX TIMESTAMP The Scheduled time must be at least 10 minutes ahead of the current time in UTC |
POST | To send SMS data to the system, use this request. | /pages/VKoxXUuYkMlaEUWxibdi#request-parameters |
GET | To retrieve SMS data from the system, use this request. | /pages/VKoxXUuYkMlaEUWxibdi#request-parameters |
| Parameters | Type | Description |
|---|---|---|
type | Required | It indicates the type of message. Values for "type" include: 0 : Plain text (GSM 3.38 Character encoding) 1 : Flash (GSM 3.38 Character encoding) 2 : Unicode 3 : Reserved 5 : Plain text (ISO-8859-1 Character encoding) 6 : Unicode Flash 7 : Flash (ISO-8859-1 Character encoding) |
source | Required | The source address that should appear in the message. - Max Length of 18 if numeric. - Max Length of 11 if alphanumeric. To prefix the plus sign (+) to the sender’s address when the message is displayed on their mobile phone, please prefix the plus sign to your sender’s address while submitting the message. Note: You need to URL encode the plus sign. The SMSC may enforce additional restrictions on this field. |
destination | Required | Recipient phone number Must be a valid MSIDSN Must be in the international telephone number format (may or may not include a plus [+] sign) symbol. e.g. 233241234567 or +233241234567 Multiple mobile numbers need to be separated by a comma (,) (the comma should be URL encoded). |
dlr | Required | Indicates whether the client wants a delivery report for this message. The values for "dlr" include: 0 : No delivery report required 1 : Delivery report required |
message | Required | The message to be sent. Must be URL encoded. |
time | Optional | To schedule the message to be sent sometime or date in the future Format: YYYY-MM-DD HH:MM:SS or UNIX TIMESTAMP The Scheduled time must be at least 10 minutes ahead of the current time in UTC |
POST | To add new sender data to the system, use this request. | /pages/WY2RKyopOdlYqEnL3pge |
GET | To retrieve sender data from the system, use this request. | /pages/E0dlsDwa2TG7Hogewzh8 |
apikey
string
| Required | Your unique API key is required to retrieve your TextCus Sender IDs | ## Sample Requests {% tabs %} {% tab title="PHP" %} ```php $url, CURLOPT_RETURNTRANSFER => true, CURLOPT_ENCODING => '', CURLOPT_MAXREDIRS => 10, CURLOPT_TIMEOUT => 0, CURLOPT_FOLLOWLOCATION => true, CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1, CURLOPT_CUSTOMREQUEST => 'GET', CURLOPT_HTTPHEADER => array( 'Authorization: Bearer API_KEY' // Replace 'API_KEY' with your actual API key ), )); $response = curl_exec($curl); curl_close($curl); echo $response; ?> ``` {% endtab %} {% tab title="NodeJS" %} ```javascript const axios = require('axios'); const config = { method: 'get', url: `https://api.textcus.com/api/v2/senders`, headers: { 'Authorization': 'Bearer API_KEY' // Replace 'API_KEY' with your actual API key } }; axios(config).then(function(response) { console.log(JSON.stringify(response.data)); }).catch(function(error) { console.error(error); }); ``` {% endtab %} {% tab title="Python" %} ```python import requests url = f'https://api.textcus.com/api/v2/senders' headers = { "Authorization": "Bearer API_KEY" # Replace 'API_KEY' with your actual API key } try: response = requests.get(url, headers=headers) print(response.json()) except requests.exceptions.RequestException as e: print(e) ``` {% endtab %} {% tab title="Dart" %} ```dart import 'dart:convert'; import 'package:http/http.dart' as http; void main() async { String url = 'https://api.textcus.com/api/v2/senders'; try { final response = await http.get( Uri.parse(url), headers: { 'Authorization': 'Bearer API_KEY', // Replace 'API_KEY' with your actual API Key }, ); if (response.statusCode == 200) { // If the server returns an OK response, parse the JSON print(response.body); } else { // If the server did not return a 200 OK response, throw an exception. print('Failed to load balance. Status code: ${response.statusCode}'); } } catch (e) { print('Error: $e'); } } ``` {% endtab %} {% tab title="Java" %} ```java import java.net.URI; import java.net.http.HttpClient; import java.net.http.HttpRequest; import java.net.http.HttpResponse; import java.net.http.HttpHeaders; import java.net.http.HttpResponse.BodyHandlers; public class CheckBalance { public static void main(String[] args) { String url = "https://api.textcus.com/api/v2/senders/"; try { // Create HttpClient HttpClient client = HttpClient.newHttpClient(); // Build the GET request HttpRequest request = HttpRequest.newBuilder() .uri(URI.create(url)) .header("Authorization", "Bearer API_KEY") // Replace 'API_KEY' with your actual API Key .GET() .build(); // Send the request and get the response HttpResponsesender\_name
string
| Required | Your 11 character sender ID name. eg. `TextCus` | |description
string
| Required | The purpose of the sender ID | ## Sample Requests {% tabs %} {% tab title="PHP" %} ```php "TextCus", // 11 Characters Only 'description' => "For business SMS to my customers", ]; $url = 'https://api.textcus.com/api/v2/senders/add'; $curl = curl_init(); curl_setopt_array($curl, array( CURLOPT_URL => $url, CURLOPT_RETURNTRANSFER => true, CURLOPT_ENCODING => '', CURLOPT_MAXREDIRS => 10, CURLOPT_TIMEOUT => 0, CURLOPT_FOLLOWLOCATION => true, CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1, CURLOPT_CUSTOMREQUEST => 'POST', CURLOPT_POSTFIELDS => $data, CURLOPT_HTTPHEADER => array( 'Authorization: Bearer API_KEY', // Replace 'API_KEY' with your actual API key 'Content-Type: application/json' ), )); $response = curl_exec($curl); curl_close($curl); echo $response; ?> ``` {% endtab %} {% tab title="NodeJS" %} ```javascript const axios = require('axios'); const data = { sender_name: "TextCus", // 11 Characters Only description: "For business SMS to my customers" }; const url = 'https://api.textcus.com/api/v2/senders/add'; axios.post(url, data, { headers: { 'Authorization': 'Bearer API_KEY', // Replace 'API_KEY' with your actual API key 'Content-Type': 'application/json' } }) .then(response => { console.log(response.data); }) .catch(error => { console.error('Error:', error); }); ``` {% endtab %} {% tab title="Python" %} ```python import requests url = 'https://api.textcus.com/api/v2/senders/add' data = { 'sender_name': 'TextCus', # 11 Characters Only 'description': 'For business SMS to my customers' } headers = { 'Authorization': 'Bearer API_KEY', # Replace 'API_KEY' with your actual API key 'Content-Type': 'application/json' } response = requests.post(url, json=data, headers=headers) print(response.text) ``` {% endtab %} {% tab title="Dart" %} ```dart import 'dart:convert'; import 'package:http/http.dart' as http; void sendSMS() async { var url = Uri.parse('https://api.textcus.com/api/v2/senders/add'); var data = { 'sender_name': 'TextCus', // 11 Characters Only 'description': 'For business SMS to my customers' }; var response = await http.post( url, headers: { 'Authorization': 'Bearer API_KEY', // Replace 'API_KEY' with your actual API key 'Content-Type': 'application/json', }, body: jsonEncode(data), ); if (response.statusCode == 200) { print('Response: ${response.body}'); } else { print('Error: ${response.statusCode}'); } } ``` {% endtab %} {% tab title="Java" %} ```java import java.io.OutputStream; import java.net.HttpURLConnection; import java.net.URL; import java.nio.charset.StandardCharsets; public class Main { public static void main(String[] args) { try { String url = "https://api.textcus.com/api/v2/senders/add"; URL obj = new URL(url); HttpURLConnection con = (HttpURLConnection) obj.openConnection(); con.setRequestMethod("POST"); con.setRequestProperty("Authorization", "Bearer API_KEY"); // Replace 'API_KEY' con.setRequestProperty("Content-Type", "application/json"); // Request body String jsonInputString = "{\"sender_name\": \"TextCus\", \"description\": \"For business SMS to my customers\"}"; con.setDoOutput(true); try (OutputStream os = con.getOutputStream()) { byte[] input = jsonInputString.getBytes(StandardCharsets.UTF_8); os.write(input, 0, input.length); } int responseCode = con.getResponseCode(); System.out.println("Response Code: " + responseCode); } catch (Exception e) { e.printStackTrace(); } } } ``` {% endtab %} {% tab title="VB.Net" %} ```vbnet Imports System.Net Imports System.Text Imports System.IO Module Module1 Sub Main() Dim url As String = "https://api.textcus.com/api/v2/senders/add" Dim request As HttpWebRequest = CType(WebRequest.Create(url), HttpWebRequest) request.Method = "POST" request.ContentType = "application/json" request.Headers.Add("Authorization", "Bearer API_KEY") ' Replace 'API_KEY' ' JSON data Dim postData As String = "{""sender_name"": ""TextCus"", ""description"": ""For business SMS to my customers""}" Dim byteArray As Byte() = Encoding.UTF8.GetBytes(postData) request.ContentLength = byteArray.Length Dim dataStream As Stream = request.GetRequestStream() dataStream.Write(byteArray, 0, byteArray.Length) dataStream.Close() Dim response As HttpWebResponse = CType(request.GetResponse(), HttpWebResponse) Dim reader As New StreamReader(response.GetResponseStream()) Dim responseText As String = reader.ReadToEnd() Console.WriteLine(responseText) reader.Close() response.Close() End Sub End Module ``` {% endtab %} {% endtabs %} ## Sample Response {% tabs %} {% tab title="Success" %} ```json { "status": 200, "message": "Sender ID added", "data": { "sender_name": "TextCus", "description": "For business SMS to my customers", "status": "no" } } ``` {% endtab %} {% tab title="Errors" %} ```json { "status": 401, "error": "Authentication invalid" }, { "status": 401, "error": "Unauthorized: Invalid API Key" } ``` {% endtab %} {% endtabs %} # Check Sender Status A sender's status may be obtained using this endpoint for emphasis on specific results on sender status and whitelisting status. ### Endpoint **`POST`** `https://api.textcus.com/api/v2/senders/check-status` ### Headers `Authorization: Bearer API_KEY` ### **Body Parameters** | Parameters | Type | Description | | ---------------------------------------------------------- | -------- | ----------------------------------------------- | |sender\_name
string
| Required | Your 11 character sender ID name. eg. `TextCus` | ## Sample Requests {% tabs %} {% tab title="PHP" %} ```php "TextCus", // 11 Characters Only ]; $curl = curl_init(); curl_setopt_array($curl, array( CURLOPT_URL => $url, CURLOPT_RETURNTRANSFER => true, CURLOPT_ENCODING => '', CURLOPT_MAXREDIRS => 10, CURLOPT_TIMEOUT => 0, CURLOPT_FOLLOWLOCATION => true, CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1, CURLOPT_CUSTOMREQUEST => 'POST', CURLOPT_POSTFIELDS => $data, CURLOPT_HTTPHEADER => array( 'Authorization: Bearer API_KEY' // Replace 'API_KEY' with your actual API key ), )); $response = curl_exec($curl); curl_close($curl); echo $response; ?> ``` {% endtab %} {% tab title="NodeJS" %} ```javascript const axios = require('axios'); const data = { sender_name: "TextCus", // 11 Characters Only }; const url = 'https://api.textcus.com/api/v2/senders/check-status'; axios.post(url, data, { headers: { 'Authorization': 'Bearer API_KEY', // Replace 'API_KEY' with your actual API key 'Content-Type': 'application/json' } }) .then(response => { console.log(response.data); }) .catch(error => { console.error('Error:', error); }); ``` {% endtab %} {% tab title="Python" %} ```python import requests url = 'https://api.textcus.com/api/v2/senders/check-status' data = { 'sender_name': 'TextCus', # 11 Characters Only } headers = { 'Authorization': 'Bearer API_KEY', # Replace 'API_KEY' with your actual API key 'Content-Type': 'application/json' } response = requests.post(url, json=data, headers=headers) print(response.text) ``` {% endtab %} {% tab title="Dart" %} ```dart import 'dart:convert'; import 'package:http/http.dart' as http; void checkSenderStatus() async { var url = Uri.parse('https://api.textcus.com/api/v2/senders/check-status'); var data = { 'sender_name': 'TextCus', // 11 Characters Only }; var response = await http.post( url, headers: { 'Authorization': 'Bearer API_KEY', // Replace 'API_KEY' with your actual API key 'Content-Type': 'application/json', }, body: jsonEncode(data), ); if (response.statusCode == 200) { print('Response: ${response.body}'); } else { print('Error: ${response.statusCode}'); } } ``` {% endtab %} {% tab title="Java" %} ```java import java.net.URI; import java.net.http.HttpClient; import java.net.http.HttpRequest; import java.net.http.HttpResponse; import java.net.http.HttpHeaders; import java.net.http.HttpResponse.BodyHandlers; public class CheckSenderStatus { public static void main(String[] args) { try { String url = "https://api.textcus.com/api/v2/senders/check-status"; URL obj = new URL(url); HttpURLConnection con = (HttpURLConnection) obj.openConnection(); con.setRequestMethod("POST"); con.setRequestProperty("Authorization", "Bearer API_KEY"); // Replace 'API_KEY' con.setRequestProperty("Content-Type", "application/json"); // Request body String jsonInputString = "{\"sender_name\": \"TextCus\"}"; con.setDoOutput(true); try (OutputStream os = con.getOutputStream()) { byte[] input = jsonInputString.getBytes(StandardCharsets.UTF_8); os.write(input, 0, input.length); } int responseCode = con.getResponseCode(); System.out.println("Response Code: " + responseCode); } catch (Exception e) { e.printStackTrace(); } } } ``` {% endtab %} {% tab title="VB.Net" %} ```vbnet Imports System.Net Imports System.Text Imports System.IO Module Module1 Sub Main() Dim url As String = "https://api.textcus.com/api/v2/senders/check-status" Dim request As HttpWebRequest = CType(WebRequest.Create(url), HttpWebRequest) request.Method = "POST" request.ContentType = "application/json" request.Headers.Add("Authorization", "Bearer API_KEY") ' Replace 'API_KEY' ' JSON data Dim postData As String = "{""sender_name"": ""TextCus""}" Dim byteArray As Byte() = Encoding.UTF8.GetBytes(postData) request.ContentLength = byteArray.Length Dim dataStream As Stream = request.GetRequestStream() dataStream.Write(byteArray, 0, byteArray.Length) dataStream.Close() Dim response As HttpWebResponse = CType(request.GetResponse(), HttpWebResponse) Dim reader As New StreamReader(response.GetResponseStream()) Dim responseText As String = reader.ReadToEnd() Console.WriteLine(responseText) reader.Close() response.Close() End Sub End Module ``` {% endtab %} {% endtabs %} ## Sample Response {% tabs %} {% tab title="Success" %} ```json { "status": 200, "message": "Sender statuses for TextCus retrieved", "data": { "sender_name": "TextCus", "status": "yes", "whitelist_status": "yes" } } ``` {% endtab %} {% tab title="Errors" %} ```json { "status": 401, "error": "Authentication invalid" }, { "status": 401, "error": "Unauthorized: Invalid API Key" } ``` {% endtab %} {% endtabs %} # Account Balance TextCus Balance API allows you to retrieve your total sms, email & wallet balance information from your account. This endpoint can also help you create notifications when your balance is going low. ### Endpoint **`GET`** `https://api.textcus.com/api/v2/balance` ### Headers `Authorization: Bearer API_KEY` ### **Header Parameters** | Parameters | Type | Description | | ---------------------------------------------------- | -------- | ---------------------------------------------------------------- | |apikey
string
| Required | Your unique API key is required to retrieve your TextCus balance | ## Sample Requests {% tabs %} {% tab title="PHP" %} ```php $url, CURLOPT_RETURNTRANSFER => true, CURLOPT_ENCODING => '', CURLOPT_MAXREDIRS => 10, CURLOPT_TIMEOUT => 0, CURLOPT_FOLLOWLOCATION => true, CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1, CURLOPT_CUSTOMREQUEST => 'GET', CURLOPT_HTTPHEADER => array( 'Authorization: Bearer API_KEY' // Replace 'API_KEY' with your actual API key ), )); $response = curl_exec($curl); curl_close($curl); echo $response; ?> ``` {% endtab %} {% tab title="NodeJS" %} ```javascript const axios = require('axios'); const config = { method: 'get', url: `https://api.textcus.com/api/v2/balance`, headers: { 'Authorization': 'Bearer API_KEY' // Replace 'API_KEY' with your actual API key } }; axios(config).then(function(response) { console.log(JSON.stringify(response.data)); }).catch(function(error) { console.error(error); }); ``` {% endtab %} {% tab title="Python" %} ```python import requests url = f'https://api.textcus.com/api/v2/balance' headers = { "Authorization": "Bearer API_KEY" # Replace 'API_KEY' with your actual API key } try: response = requests.get(url, headers=headers) print(response.json()) except requests.exceptions.RequestException as e: print(e) ``` {% endtab %} {% tab title="Dart" %} ```dart import 'dart:convert'; import 'package:http/http.dart' as http; void main() async { String url = 'https://api.textcus.com/api/v2/balance'; try { final response = await http.get( Uri.parse(url), headers: { 'Authorization': 'Bearer API_KEY', // Replace 'API_KEY' with your actual API Key }, ); if (response.statusCode == 200) { // If the server returns an OK response, parse the JSON print(response.body); } else { // If the server did not return a 200 OK response, throw an exception. print('Failed to load balance. Status code: ${response.statusCode}'); } } catch (e) { print('Error: $e'); } } ``` {% endtab %} {% tab title="Java" %} ```java import java.net.URI; import java.net.http.HttpClient; import java.net.http.HttpRequest; import java.net.http.HttpResponse; import java.net.http.HttpHeaders; import java.net.http.HttpResponse.BodyHandlers; public class CheckBalance { public static void main(String[] args) { String url = "https://api.textcus.com/api/v2/balance"; try { // Create HttpClient HttpClient client = HttpClient.newHttpClient(); // Build the GET request HttpRequest request = HttpRequest.newBuilder() .uri(URI.create(url)) .header("Authorization", "Bearer API_KEY") // Replace 'API_KEY' with your actual API Key .GET() .build(); // Send the request and get the response HttpResponse| Parameters | Type | Description |
|---|---|---|
expiry | Required | This is your OTP from TextCus: %otp_code%. The code will expire in %expiry% minutes. |
length | Required | This parameter specifies the number of characters or digits in the generated code. |
message | Required | Enter your message content here. One message page equals 160 characters — for example, a 200-character message will count as 2 pages. Be sure to include the %otp_code% placeholder where the generated code should appear in the message. |
medium | Required | Enum: "sms" or "email" |
phone_number | Required | The phone number of the contact. |
sender_id | Required | A Sender ID is the name or number that appears as the sender of an SMS message. This field must not exceed 11 characters, including spaces — exceeding this limit may cause your messages to fail. |
type | Required | Enum: "numeric" or "alphanumeric" |