Api reference
Get SMS Send History
Retrieve paginated SMS send records for a service
Get SMS Send History
Returns paginated send records for a service. Filter by status, batch, or date range.
Endpoint
POST https://api.bridgeagw.com/sms/historyRequest Headers
Authorization: Basic <base64_encoded_credentials>
Content-Type: application/jsonRequest Body
{
"service_id": 1,
"page": 1,
"limit": 10,
"batch_id": "BATCH_123"
}Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
service_id | integer | Yes | Your TheBridge service identifier |
page | integer | No | Page number (default: 1) |
limit | integer | No | Records per page (default applies if omitted) |
status | string | No | Filter by status: QUEUED, SENT, FAILED, REFUNDED (or Q, S, F, R) |
batch_id | string | No | Filter by bulk batch ID from Send Bulk SMS |
start_date | string | No | Start date, inclusive (YYYY-MM-DD) |
end_date | string | No | End date, inclusive (YYYY-MM-DD) |
Response
Success (response_code: 393)
{
"response_code": "393",
"response_message": "SMS history retrieved successfully",
"response_data": [
{
"processing_id": "PROC_123",
"batch_id": "BATCH_123",
"customer_number": "233XXXXXXXXX",
"message": "Your payment was received. Thank you.",
"sender_id": "MMDA",
"char_count": 35,
"page_count": 1,
"units_charged": 1,
"status": "QUEUED",
"status_code": "Q",
"provider_code": null,
"error_message": null,
"source": "CLIENT",
"source_code": "C",
"created_at": "2026-05-30T17:18:19Z",
"sent_at": null
}
],
"pagination": {
"total_no_of_records": 15,
"total_pages": 2,
"current_page": 1,
"items_per_page": 10
}
}| Field | Description |
|---|---|
processing_id | Unique send reference |
batch_id | Bulk batch ID, or null for single sends |
customer_number | Recipient mobile number |
message | Message text sent |
sender_id | Sender ID used |
char_count / page_count / units_charged | Message size and units billed |
status / status_code | QUEUED/Q, SENT/S, FAILED/F, or REFUNDED/R |
provider_code | Provider response code when available |
error_message | Failure reason when status is FAILED |
source / source_code | Origin of the send (CLIENT / C) |
created_at | UTC timestamp when the request was created |
sent_at | UTC timestamp when the message was sent, or null while queued |
pagination | Page metadata for the result set |
Error response
{
"response_code": "<ERROR_CODE>",
"response_message": "<ERROR_MESSAGE>"
}Example Usage
curl -X POST "https://api.bridgeagw.com/sms/history" \
-H "Authorization: Basic <your_credentials>" \
-H "Content-Type: application/json" \
-d '{
"service_id": 1,
"page": 1,
"limit": 10,
"batch_id": "BATCH_123"
}'const response = await fetch('https://api.bridgeagw.com/sms/history', {
method: 'POST',
headers: {
'Authorization': 'Basic <your_credentials>',
'Content-Type': 'application/json'
},
body: JSON.stringify({
service_id: 1,
page: 1,
limit: 10,
batch_id: "BATCH_123"
})
});
const result = await response.json();
console.log(result);import requests
url = "https://api.bridgeagw.com/sms/history"
headers = {
"Authorization": "Basic <your_credentials>",
"Content-Type": "application/json"
}
data = {
"service_id": 1,
"page": 1,
"limit": 10,
"batch_id": "BATCH_123"
}
response = requests.post(url, headers=headers, json=data)
result = response.json()
print(result)Sandbox testing
In sandbox mode, SMS delivery is simulated asynchronously. After a send returns 370 ACKNOWLEDGED, the status transitions to its final state after approximately 800ms. Querying history before that window may show ACKNOWLEDGED; query again shortly after to see the final outcome.
SMS status lifecycle in sandbox:
| Stage | status | status_code | When |
|---|---|---|---|
| Request accepted | ACKNOWLEDGED | A | Immediately on send |
| Delivered (simulated) | SENT | S | ~800ms later (number ending 0–8) |
| Failed + refund | REFUNDED | R | ~800ms later (number ending 9) |
Filter history with the status parameter using ACKNOWLEDGED, SENT, REFUNDED, or the single-character codes A, S, R.
Notes
- Use
processing_idfrom Send SMS to look up individual sends. - Use
batch_idfrom Send Bulk SMS to filter batch results.