This API retrieves SMS Opt-Out records based on filter criteria. It supports filtering by ID, phone number, campaign, reason, purpose, and insert date, and supports pagination via offset and limit.
Endpoint
POST https://api.convoso.com/v1/sms-opt-out/search🔒 Authentication
| Field | Type | Required | Description |
|---|---|---|---|
auth_token | string | Yes | API authentication token |
Token must be retrieved from the login endpoint.
🔎 Query Parameters
| Field | Type | Required | Description |
|---|---|---|---|
auth_token | string | Yes | API token |
id | string | Optional | SMS Opt-Out record ID |
campaign_id | integer | Optional | Campaign ID (0 for global) |
phone_number | string | Optional | Phone number to filter |
phone_code | string | Optional | Country/area code |
reason | string | Optional | SMS Opt-Out reason (use -BLANK- or -NOTBLANK- to filter by empty/non-empty) |
purpose | string | Optional | SMS Opt-Out purpose (use -BLANK- or -NOTBLANK- to filter by empty/non-empty) |
insert_date | string | Optional | Filter by date when record was inserted (format varies by implementation) |
offset | integer | Optional | Row offset for pagination (default 0, max 1,000,000) |
limit | integer | Optional | Max number of records to return (default 100, max 1000) |
HTTP Method
POSTError Codes
| Code | Message |
|---|---|
6006 | Invalid Campaign ID |
7231 | Invalid offset value |
6008 | The phone number already exists |
6026 | Missing or Invalid Country Code |
6057 | Invalid Purpose Provided |
6058 | Invalid Purpose Provided |
Example PHP Usage
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, 'https://api.convoso.com/v1/sms-opt-out/search');
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS, http_build_query([
'auth_token' => 'd2e482d21311c72-08434465f22526c3a758661',
'phone_code' => '1',
'phone_number' => '8181233567',
'reason' => 'SMS Opt-Out reason',
'purpose' => 'SMS Opt-Out purpose'
]));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
$result = curl_exec($ch);
curl_close($ch);
Example JSON Response
{
"success": true,
"offset": "0",
"limit": "10",
"total": "1",
"records": [
{
"id": "2778557",
"phone_number": "8181233567",
"phone_code": "1",
"reason": "SMS Opt-Out reason",
"purpose": "SMS Opt-Out purpose",
"insert_date": "2024-04-22 17:01:31",
"campaign_id": "0",
"campaign_name": ""
}
]
}
Response Field Definitions
| Field | Type | Description |
|---|---|---|
| success | boolean | Indicates whether the search was successful |
| offset | integer | Starting row in the result set |
| limit | integer | Number of records returned in this batch |
| total | string | Total number of matching records found |
| records[] | array | List of returned SMS opt-out records |
| records[].id | string | ID of the opt-out record |
| records[].phone_number | string | Opted-out phone number |
| records[].phone_code | string | Country/area code |
| records[].reason | string | The opt-out reason (if any) |
| records[].purpose | string | The opt-out purpose (if any) |
| records[].insert_date | string | Timestamp of when the opt-out was added |
| records[].campaign_id | string | Campaign ID linked to the opt-out (0 = global) |
| records[].campaign_name | string | Name of the campaign (blank if not set) |