Allows systems to search a specific Campaign or Global DNC List to see if a Lead phone number exists in that List.
Endpoint:
GET https://api.convoso.com/v1/dnc/search
🔒 Authentication
- Parameter Name: auth_token
- Type: Query Parameter
- Required: Yes
🔎 Query Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| auth_token | string | Yes | authorization token |
| id | integer | No | Filter by the unique DNC record ID. |
| campaign_id | string | No | Filter by campaign ID (for campaign-specific DNC entries). |
| phone_number | string | No | Filter by the phone number (digits only, no formatting). |
| phone_code | string | No | Country phone code. Example: "1" for US/Canada. |
| insert_date | string | No | Filter records by insert date (YYYY-MM-DD). |
| offset | integer | No | Starting index for paginated results (default: 0). |
| limit | integer | No | Max number of results to return (default: 100, max: 1000). |
| reason | string | No | DNC Reason . To get records with Empty or Non Empty Reason use the reserved words '-BLANK-' or '-NOTBLANK-' |
| purpose | string | No | DNC Purpose. To get records with Empty or Non Empty Purpose use the reserved words '-BLANK-' or '-NOTBLANK-' |
⚠️ Error Codes
| Code | Message |
|---|---|
6006 | Invalid Campaign ID |
7231 | Invalid offset value |
6008 | The phone number already exists. |
6026 | Missing or invalid Country Code |
6056 | Missing or invalid value for ID |
6057 | Invalid Purpose Provided |
6058 | Invalid Reason Provided |
Example Request
GET https://api.convoso.com/v1/dnc/search?auth_token=YOUR_AUTH_TOKEN&id=&campaign_id=&phone_number=9999999999&phone_code=1&insert_date=&offset=&limit=
Response Format (JSON)
{
"success": true,
"id": 1
}Response Field Definitions
Response Top-Level Object
| Field | Type | Description |
|---|---|---|
| success | boolean | Indicates if request was successful. |
| data | object | Contains pagination and result data. |
Data Object
| Field | Type | Description |
|---|---|---|
| offset | integer | Current offset for pagination. |
| limit | integer | Number of entries returned. |
| total | integer | Total number of DNC records matching the filters. |
| entries | array | List of DNC record objects. |
DNC Entry Object
| Parameter | Type | Description |
|---|---|---|
| id | string | Unique ID of the DNC record. |
| phone_number | string | The phone number on the DNC list. |
| campaign_id | string | Campaign ID associated with the entry (0 = global). |
| insert_date | string | Date/time the record was added (YYYY-MM-DD HH:mm:ss). |
| phone_code | string | Country code of the phone number (e.g., 1 for U.S. / Canada). |
| campaign_uid | string | Unique identifier of the campaign (if available). |
| campaign_name | string | Name of the campaign (if available). |
| campaign_type | string | Type of the campaign (if available). |