API documentation – TCPA Litigator List

Easily scrub your phone numbers using our API SDK

Our repository you can find here https://github.com/StreetYo/TCPA-SDK

API Authentication

To use our API please use Basic Authentication
PHP Example
$api_endpoint = 'https://api.tcpalitigatorlist.com/scrub/phone/tcpa/1000000';
$api_username;
$api_password;

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $api_endpoint);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_USERPWD, "$api_username:$api_password");
curl_setopt($ch, CURLOPT_HTTPAUTH, CURLAUTH_BASIC);
$output = curl_exec($ch);
$info = curl_getinfo($ch);
curl_close($ch);
$response_array = json_decode($output,true);

API Endpoints

Single record scrub

https://api.tcpalitigatorlist.com/scrub/phone/
Method: POST

Params:
  • [type] (POST) (optional) Scrub against list type. Available values: tcpa, dnc and array of the values. Default: tcpa.
  • [phone_number] (POST) (required) Phone number to check
  • [contact_name] (POST) (optional) Name of contact person
  • [return] (POST) (optional) Specifies the format of the returned value. Available values: boolean (1 - match, 0 - clean)
Check if phone number is in our TCPA/DNC list
PHP Example
$api_endpoint = 'https://api.tcpalitigatorlist.com/scrub/phone/';
$api_username;
$api_password;

$types = ["tcpa", "dnc"];

$ch = curl_init();

curl_setopt($ch, CURLOPT_URL,$api_endpoint);
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS, http_build_query(array('type' => json_encode($types), 'phone_number' => '9258492311', 'contact_name' => 'John')));
curl_setopt($ch, CURLOPT_USERPWD, "$api_username:$api_password");
curl_setopt($ch, CURLOPT_HTTPAUTH, CURLAUTH_BASIC);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

$output = curl_exec($ch);
curl_close ($ch);

$response_array = json_decode($output,true); Return: 
{
    "clean": {
        "9258492311": {
            "phone_number": "9258492311"
        }
    }
}
https://api.tcpalitigatorlist.com/scrub/phone/[type]/[phone_number]/[contact_name]
https://tcpalitigatorlist.com/wp-json/scrub/phone/[type]/[phone_number]/[contact_name] Deprecated!
Method: GET

Params:
  • [type] (required) Scrub against list type. Available values: all, tcpa, dnc
  • [phone_number] (required) Phone number to check
  • [contact_name] (optional) Name of contact person
Check if phone number is in our TCPA/DNC list
PHP Example
$api_endpoint = 'https://api.tcpalitigatorlist.com/scrub/phone/all/9258492311/John';
$api_username;
$api_password;

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $api_endpoint);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_USERPWD, "$api_username:$api_password");
curl_setopt($ch, CURLOPT_HTTPAUTH, CURLAUTH_BASIC);
$output = curl_exec($ch);
$info = curl_getinfo($ch);
curl_close($ch);
$response_array = json_decode($output,true); Return: 
{
    "clean": {
        "9258492311": {
            "phone_number": "9258492311"
        }
    }
}
https://api.tcpalitigatorlist.com/scrub/name/[type]/[contact_name]
https://tcpalitigatorlist.com/wp-json/scrub/name/[type]/[contact_name] Deprecated!
Method: GET

Params:
  • [type] (required) Scrub against list type. Available values: all, tcpa, dnc
  • [contact_name] (optional) Name of contact person
Check if contact name is in our TCPA/DNC list
PHP Example
$api_endpoint = 'https://api.tcpalitigatorlist.com/scrub/name/tcpa/John vitorino';
$api_username;
$api_password;

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $api_endpoint);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_USERPWD, "$api_username:$api_password");
curl_setopt($ch, CURLOPT_HTTPAUTH, CURLAUTH_BASIC);
$output = curl_exec($ch);
$info = curl_getinfo($ch);
curl_close($ch);
$response_array = json_decode($output,true); Return: 
{
    "match": {
        "7276089538": {
            "phone_number": 7276089538,
            "status": "TCPA",
            "name": "John  Vitorino",
            "first_name": null,
            "middle_name": null,
            "last_name": null,
            "case_title": "",
            "multiple_cases": "1",
            "phone_type": "",
            "phone_status": "Listed In Complaint",
            "filling_date": "0000-00-00",
            "added": "2018 Jul 27"
        }
    }
}
Match tcpa: 
{
    "match": {
        "1231231231": {
            "phone_number": 1231231231,
            "status": "TCPA",
            "name": "John Pradhan",
            "first_name": "John",
            "middle_name": "",
            "last_name": "Pradhan",
            "case_title": "",
            "multiple_cases": "1",
            "phone_type": "Landline",
            "phone_status": "Listed In Complaint",
            "filling_date": "0000-00-00",
            "added": "2018 Jul 27"
        }
    }
}
Match DNC Complainers or Federal DNC: 
{
    "match": {
        "1231231231": {
            "phone_number": "1231231231",
            "type": "Federal DNC"
        }
    }
}
Clean: 
{
    "clean": {
        "9258492311": {
            "phone_number": "9258492311"
        }
    }
}
Not enough credits: 
{
    "error": "You do not have enough credits"
}
API subscription is not active or incorrect API credentials: 
{
    "code": "rest_forbidden",
    "message": "Sorry, you are not allowed to do that.",
    "data": {
        "status": 401
    }
}
Too many requests: 
{
    "error": "Too many requests"
}

Mass records scrub

How to do mass scrub?

There are two ways to do mass scrub for small lists and big lists (take a look at difference here).

If want to scrub small list, you need to do next steps:

  1. Send your phone numbers with this endpoint, using the small_list param
  2. As result you will get clean and match phone numbers.
    For example: 
    {
    "match": {
        "6319796917": {
            "phone_number": "6319796917",
            "status": "DNC_COMPLAINERS"
        }
    },
    "clean": {
        "6028912045": {
            "phone_number": "6028912045"
        },
        "6024223200": {
            "phone_number": "6024223200"
        }
    }
}

If want to scrub big list, you need to do next steps:

  1. Send your phone numbers with this endpoint.
    As result you will get a unique key. The key is an id of your job in jobs queue. With the key you can check the job status and get its result.
    For example: 
    {
    "status": "in_queue",
    "job_key": "2959996d31374622d45c20f57388912f"
}
  2. Check the job with the key you got earlier until you get the job result. To check a job status use this or this endpoint.
    Example you can find here.
https://api.tcpalitigatorlist.com/scrub/phones/
https://api.tcpalitigatorlist.com/scrub/phones/[type]/ Deprecated!
https://tcpalitigatorlist.com/wp-json/scrub/phones/[type]/ Deprecated!
Method: POST

Params:
  • [type] (optional) (POST) Scrub against list type. Available values: tcpa, dnc and array of the values. Default: tcpa.
  • [phones] (required) (POST) Phone numbers list
  • [sub_user] (optional) (POST) Request marker
  • [small_list] (optional) (POST) If true, scrub result will be returned immediately. Available values: true, false
  • [use_suppression_list] (optional) (POST) Use your suppression list uploaded on the site or not. Available values: true, false
How to scrub?
Check if phone numbers are in our TCPA/DNC list. There are two ways to do mass scrub for small lists (less then 3000 phone numbers) and big lists (more then 3000 phone numbers).
The different between them is if you use this endpoint with small_list flag, you will get result right away, but there is 3000 phone numbers limit.
If you use this endpoint without small_list flag, you will be added in common queue and as response you will get a unique key, with that key you can get scrub result in the future.
To get scrub result you need to send request to this endpoint with the key you got earlier. Using this endpoint without small_list flag, you have no limits.

What does sub_user means?
The sub_user param is a request marker. This marker is needed for grouping requests. Here you can find statistics of these groups.

The big list scrub speed test
790K numbers - TCPA = 1 minute 10 seconds
790K numbers - DNC = 56 seconds
790K numbers - DNC FED = 1 minute 7 seconds
790K numbers - ALL = 1 minute 53 seconds
PHP Example
$api_endpoint = 'https://api.tcpalitigatorlist.com/scrub/phones';
$api_username;
$api_password;

$numbers = ["6319796917", "6024223200", "6028912045"];

$types = ["tcpa", "dnc"];

$ch = curl_init();

curl_setopt($ch, CURLOPT_URL,$api_endpoint);
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS, http_build_query(array('phones' => json_encode($numbers), 'type' => json_encode($types), 'sub_user' => 'Some user', 'small_list' => 'true')));
curl_setopt($ch, CURLOPT_USERPWD, "$api_username:$api_password");
curl_setopt($ch, CURLOPT_HTTPAUTH, CURLAUTH_BASIC);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

$output = curl_exec($ch);
curl_close ($ch);

$response_array = json_decode($output,true); Return: 
{
        "match": {
            "6319796917": {
                "phone_number": "6319796917",
                "status": "DNC_COMPLAINERS"
            }
        },
        "clean": {
            "6024223200": {
                "phone_number": "6024223200"
            },
            "6028912045": {
                "phone_number": "6028912045"
            }
        }
    }

PHP Example
$api_endpoint = 'https://api.tcpalitigatorlist.com/scrub/phones';
$api_username;
$api_password;

$numbers = ["6319796917", "6024223200", "6028912045"];

$types = ["tcpa", "dnc"];

$ch = curl_init();

curl_setopt($ch, CURLOPT_URL,$api_endpoint);
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS, http_build_query(array('phones' => json_encode($numbers), 'type' => json_encode($types), 'sub_user' => 'Some user')));
curl_setopt($ch, CURLOPT_USERPWD, "$api_username:$api_password");
curl_setopt($ch, CURLOPT_HTTPAUTH, CURLAUTH_BASIC);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

$output = curl_exec($ch);
curl_close ($ch);

$response_array = json_decode($output,true); Return: 
{
    "status": "in_queue",
    "job_key": "3e3c21b74b5de356c6a0c42190836c6f"
}
Get result
$api_endpoint = 'https://api.tcpalitigatorlist.com/scrub/phones/get/';
$api_username;
$api_password;
$ch = curl_init();

curl_setopt($ch, CURLOPT_URL,$api_endpoint);
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS, http_build_query(array('key' => "'3e3c21b74b5de356c6a0c42190836c6f'")));
curl_setopt($ch, CURLOPT_USERPWD, "$api_username:$api_password");
curl_setopt($ch, CURLOPT_HTTPAUTH, CURLAUTH_BASIC);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

$interval = 10;

while(true) {
    sleep($interval);
    $output = curl_exec($ch);
    $response_array = json_decode($output,true);
    if(
        isset($response_array['status']) &&
        ($response_array['status'] == 'in_queue' || $response_array['status'] == 'processing')
    ) {
        //Result not ready yet
        continue;
    } else if(isset($response_array['match'])) {
        //Result ready
        $result = $response_array;
        break;
    } else {
        //Something went wrong
        break;
    }
}
curl_close ($ch);

$response_array = json_decode($output,true);
Return: 
{
    "match": {
        "6319796917": {
            "phone_number": "6319796917",
            "status": "DNC_COMPLAINERS"
        }
    },
    "clean": {
        "6024223200": {
            "phone_number": "6024223200"
        },
        "6028912045": {
            "phone_number": "6028912045"
        }
    }
}
https://api.tcpalitigatorlist.com/scrub/phones/get/
https://tcpalitigatorlist.com/wp-json/scrub/phones/get/ Deprecated!
Method: POST

Params:
  • [key] (required) A key of the job
Get result of the job
PHP Example
$api_endpoint = 'https://api.tcpalitigatorlist.com/scrub/phones/get/';
$api_username;
$api_password;

$ch = curl_init();

curl_setopt($ch, CURLOPT_URL,$api_endpoint);
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS, http_build_query(array('key' => '972a569d8bdcaeee1ac30404c05054aa')));
curl_setopt($ch, CURLOPT_USERPWD, "$api_username:$api_password");
curl_setopt($ch, CURLOPT_HTTPAUTH, CURLAUTH_BASIC);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

$output = curl_exec($ch);
curl_close ($ch);

$response_array = json_decode($output,true); Return: 
{
        "match": {
            "6319796917": {
                "phone_number": "6319796917",
                "status": "DNC_COMPLAINERS"
            }
        },
        "clean": {
            "6028912045": {
                "phone_number": "6028912045"
            },
            "6024223200": {
                "phone_number": "6024223200"
            }
        }
    }
https://api.tcpalitigatorlist.com/scrub/phones/jobs
https://tcpalitigatorlist.com/wp-json/scrub/phones/jobs Deprecated!
Method: POST

Get all queue jobs
PHP Example
$api_endpoint = 'https://api.tcpalitigatorlist.com/scrub/phones/jobs';
$api_username;
$api_password;
$ch = curl_init();

curl_setopt($ch, CURLOPT_URL,$api_endpoint);
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_USERPWD, "$api_username:$api_password");
curl_setopt($ch, CURLOPT_HTTPAUTH, CURLAUTH_BASIC);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

$output = curl_exec($ch);
curl_close ($ch);

$response_array = json_decode($output,true); Return: 
{
    "jobs": [
        {
            "key": "b8c6e9f019be06b581e888c0474eafee",
            "status": "result_ready",
            "create_ts": "2020-05-15 07:46:18"
        },
        {
            "key": "0700d5c294e6fb31e36e826b471e536c",
            "status": "result_ready",
            "create_ts": "2020-05-15 07:46:51"
        },
        {
            "key": "8da181132f2b63d53972b49f44dd7fc4",
            "status": "result_ready",
            "create_ts": "2020-05-15 08:00:11"
        }
    ]
}
https://api.tcpalitigatorlist.com/scrub/stats/[start_date]/[end_date]
https://tcpalitigatorlist.com/wp-json/scrub/stats/[start_date]/[end_date] Deprecated!
Method: GET

Params:
  • [start_date] (optional) Start date
  • [end_date] (optional) End date
Show API statistics
PHP Example
$api_endpoint = 'https://api.tcpalitigatorlist.com/scrub/stats/2020-05-16/2020-05-16';
$api_username;
$api_password;

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $api_endpoint);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_USERPWD, "$api_username:$api_password");
curl_setopt($ch, CURLOPT_HTTPAUTH, CURLAUTH_BASIC);
$output = curl_exec($ch);
$info = curl_getinfo($ch);
curl_close($ch);
$response_array = json_decode($output,true); Return: 
{
        "total": {
            "count": "0",
            "price": 0
        },
        "user": {
            "count": "0",
            "price": 0
        },
        "sub_users": []
    }
https://tcpalitigatorlist.com/wp-json/scrub/updates/[type]/[date] Deprecated!
Search desired date for updates

Array scrub example

To use our API please use Basic Authentication
PHP Example
$api_endpoint = 'https://api.tcpalitigatorlist.com/scrub/phones/all/';
$api_username;
$api_password;

$numbers = ["6319796917", "6038980045", "6014250300"];

$ch = curl_init();

curl_setopt($ch, CURLOPT_URL,$api_endpoint);
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS, http_build_query(array('phones' => json_encode($numbers), 'small_list' => 'true')));
curl_setopt($ch, CURLOPT_USERPWD, "$api_username:$api_password");
curl_setopt($ch, CURLOPT_HTTPAUTH, CURLAUTH_BASIC);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

$output = curl_exec($ch);
curl_close ($ch);

$response_array = json_decode($output,true);

Results examples

TCPA Match 
{
    "match":{
        "9257350671":{
            "phone_number":9257350671,
            "status":"TCPA",
            "name":"Carolyn Murakami",
            "serial":"0",
            "phone_type":"Landline",
            "phone_status":"Associated With Litigator",
            "filling_date":"",
            "added":"2019 Feb 09"
        }
    }
}
Clean phone number 
{
    "clean": {
        "92573506711": {
            "phone_number": "92573506711"
        }
    }
}