API Authentication
To use our API please use Basic Authentication.
Generate API Keys you can here
Our main API server: https://api.tcpalitigatorlist.com
Note: In case of API unexpected fails, you can switch traffic to our backup server. Keep in mind it`s for emergencies, not for constant use: https://api101.tcpalitigatorlist.com
Note: Our public API servers are limiting every client with 50 calls/second. Click here for details.
$api_endpoint = 'https://api.tcpalitigatorlist.com/scrub/phone/tcpa/1000000000';
$api_username = '$api_username';
$api_password = '$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);
- [phone_number] (POST) (required) Phone number to check
- [contact_name] (POST) (optional) Name of contact person
- [type] (POST) (optional) List type to scrub against.
Available values:
- all
- tcpa (default) - Scrub out TCPA, Troll
- dnc - Scrub out DNC complainers
Or array of the values. - [sub_user] (POST)(optional) Request marker
- [state] (POST) (optional) Country states codes array.
If specified application will also be scrubing out phone numbers of requested states DNC lists. Example: ['FL','NY','CA'].
Available states
Note: This option is independent from TYPE parameter. - [return] (POST) (optional) Specifies the format of the returned value. Available values: boolean (1 - match, 0 - clean)
$api_endpoint = 'https://api.tcpalitigatorlist.com/scrub/phone/';
$api_username = '$api_username';
$api_password = '$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' => '2012510414', '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);
Response example:
{ "results": { "first_name": "John", "middle_name": "", "last_name": "", "case_title": "", "multiple_cases": "", "phone_type": "", "status_array": [ "dnc_complainers" ], "phone_status": "", "clean": 0, "is_bad_number": true, "phone_number": "2012510414", "created_at": "", "updated_at": "", "status": "DNC Complainers" } }
- [type] (required) List type to scrub against.
Available values:
- all
- tcpa (default) - Scrub out TCPA, Troll
- dnc - Scrub out DNC complainers
Or array of the values. - [phone_number] (required) Phone number to check
- [contact_name] (optional) Name of contact person
- [state] (optional) Country states code.
If specified application will also be scrubing out phone numbers of requested states DNC lists. Example: 'FL'.
Available states
Note: This option is independent from TYPE parameter.
$api_endpoint = 'https://api.tcpalitigatorlist.com/scrub/phone/all/2012510414/John';
$api_username = '$api_username';
$api_password = '$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);
Response example:
{ "results": { "first_name": "John", "middle_name": "", "last_name": "", "case_title": "", "multiple_cases": "", "phone_type": "", "status_array": [ "dnc_complainers" ], "phone_status": "", "clean": 0, "is_bad_number": true, "phone_number": "2012510414", "created_at": "", "updated_at": "", "status": "DNC Complainers" } }
- [type] (required) List type to scrub against.
Available values:
- all
- tcpa (default) - Scrub out TCPA, Troll
- dnc - Scrub out DNC complainers
Or array of the values. - [contact_name] (optional) Name of contact person
$api_endpoint = 'https://api.tcpalitigatorlist.com/scrub/name/tcpa/John vitorino';
$api_username = '$api_username';
$api_password = '$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);
Response example:
{ "results": { "first_name": "John", "middle_name": "", "last_name": "Vitorino", "case_title": "", "multiple_cases": "1", "phone_type": "Mobile", "status_array": [ "tcpa", "federal_dnc" ], "phone_status": "Listed in Complaint", "clean": 0, "is_bad_number": true, "phone_number": "7276089538", "created_at": "2018-07-27 10:31:16", "updated_at": "2018-07-27 10:31:16", "status": "TCPA | Federal DNC", "name": "John Vitorino" } }
{ "results": { "first_name": "John", "middle_name": "", "last_name": "Vitorino", "case_title": "", "multiple_cases": "1", "phone_type": "Mobile", "status_array": [ "tcpa", "federal_dnc" ], "phone_status": "Listed in Complaint", "clean": 0, "is_bad_number": true, "phone_number": "7276089538", "created_at": "2018-07-27 10:31:16", "updated_at": "2018-07-27 10:31:16", "status": "TCPA | Federal DNC", "name": "John Vitorino" } }Match DNC Complainers or Federal DNC:
{ "results": { "first_name": "", "middle_name": "", "last_name": "", "case_title": "", "multiple_cases": "", "phone_type": "", "status_array": [ "dnc_complainers" ], "phone_status": "", "clean": 0, "is_bad_number": true, "phone_number": "2012510414", "created_at": "", "updated_at": "", "status": "DNC Complainers" } }Clean:
{ "results": { "phone_number": 9258492311, "clean": 1, "is_bad_number": false } }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 } }
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 /scrub/phones/).
If want to scrub small list, you need to do next steps:
- Send your phone numbers with /scrub/phones/ endpoint, using the small_list param
- As result you will get clean and match phone numbers.
For example:{ "results" : { { "phone_number": "6024223200" "clean": "1" }, { "phone_number": "6028912045" "clean": "1" }, { "phone_number": "6319796917", "status": "TCPA", "first_name":"John", "middle_name":"", "last_name":"Vitorino", "case_title": "", "multiple_cases": "0", "phone_type": "Mobile", "phone_status":"Listed In Complaint", "created_at": "2018-07-27 10:31:15", "updated_at": "2018-07-27 10:31:15", "status_array": [ "federal_dnc", "tcpa" ], "is_bad_number": true, "clean": 0 } } }
If want to scrub big list, you need to do next steps:
- Send your phone numbers with /scrub/phones/ 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" }
-
Check the job with the key you got earlier until you get the job result. To check a job status use /scrub/phones/get/ or /scrub/phones/jobs/ endpoint.
Example you can find here /scrub/phones/.
- [phones] (required) (POST) Phone numbers list
- [type] (optional) (POST) List type to scrub against.
Available values:
- all
- tcpa (default) - Scrub out TCPA, Troll
- dnc - Scrub out DNC complainers
Or array of the values. - [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
- [state] (POST) (optional) Country states codes array.
If specified application will also be scrubing out phone numbers of requested states DNC lists. Example: ['FL','NY','CA'].
Available states
Note: This option is independent from TYPE parameter.
Small list (up to 3000) scrub example
$api_endpoint = 'https://api.tcpalitigatorlist.com/scrub/phones';
$api_username = '$api_username';
$api_password = '$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);
Response example:
{ "results" : { { "phone_number": "6024223200" "clean": "1" }, { "phone_number": "6028912045" "clean": "1" }, { "phone_number": "6319796917", "status": "TCPA", "first_name":"John", "middle_name":"", "last_name":"Vitorino", "case_title": "", "multiple_cases": "0", "phone_type": "Mobile", "phone_status":"Listed In Complaint", "created_at": "2018-07-27 10:31:15", "updated_at": "2018-07-27 10:31:15", "status_array": [ "federal_dnc", "tcpa" ], "is_bad_number": true, "clean": 0 } } }
Big list (over 3000) scrub example
$api_endpoint = 'https://api.tcpalitigatorlist.com/scrub/phones';
$api_username = '$api_username';
$api_password = '$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);
Response example:
{ "status": "in_queue", "job_key": "3e3c21b74b5de356c6a0c42190836c6f" }
$api_endpoint = 'https://api.tcpalitigatorlist.com/scrub/phones/get/';
$api_username = '$api_username';
$api_password = '$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);
Response example:
{ "results" : { { "phone_number": "6024223200" "clean": "1" }, { "phone_number": "6028912045" "clean": "1" }, { "phone_number": "6319796917", "status": "TCPA", "first_name":"John", "middle_name":"", "last_name":"Vitorino", "case_title": "", "multiple_cases": "0", "phone_type": "Mobile", "phone_status":"Listed In Complaint", "created_at": "2018-07-27 10:31:15", "updated_at": "2018-07-27 10:31:15", "status_array": [ "federal_dnc", "tcpa" ], "is_bad_number": true, "clean": 0 } } }
- [key] (required) A key of the job
$api_endpoint = 'https://api.tcpalitigatorlist.com/scrub/phones/get/';Response example:
$api_username = '$api_username';
$api_password = '$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);
{ "results" : { { "phone_number": "6024223200" "clean": "1" }, { "phone_number": "6028912045" "clean": "1" }, { "phone_number": "6319796917", "status": "TCPA", "first_name":"John", "middle_name":"", "last_name":"Vitorino", "case_title": "", "multiple_cases": "0", "phone_type": "Mobile", "phone_status":"Listed In Complaint", "created_at": "2018-07-27 10:31:15", "updated_at": "2018-07-27 10:31:15", "status_array": [ "federal_dnc", "tcpa" ], "is_bad_number": true, "clean": 0 } } }
$api_endpoint = 'https://api.tcpalitigatorlist.com/scrub/phones/jobs';
$api_username = '$api_username';
$api_password = '$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);
Response example:
{ "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" } ] }
- [start_date] (optional) Start date. Format: YYYY-MM-DD
- [end_date] (optional) End date. Format: YYYY-MM-DD
$api_endpoint = 'https://api.tcpalitigatorlist.com/scrub/stats/2020-05-16/2020-05-16';
$api_username = '$api_username';
$api_password = '$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);
Response:
{ "total": { "count": "1", "price": 0 }, "user": { "count": "0", "price": 0 }, "sub_users": [ { "sub_user": "someone", "count": 1, "price": 0 } ], "applied_dates": { "start": "2022-12-10", "end": "2023-01-09" } }
- [start_date] (optional) Start date. Format: YYYY-MM-DD
- [end_date] (optional) End date. Format: YYYY-MM-DD
$api_endpoint = 'https://api.tcpalitigatorlist.com/scrub/stats/';
$api_username = '$api_username';
$api_password = '$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('start_date' => '2020-05-16', 'end_date' => '2020-06-16')));
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);
$info = curl_getinfo($ch);
curl_close($ch);
$response_array = json_decode($output,true);
Response:
{ "total": { "count": "1", "price": 0 }, "user": { "count": "0", "price": 0 }, "sub_users": [ { "sub_user": "someone", "count": 1, "price": 0 } ], "applied_dates": { "start": "2022-12-10", "end": "2023-01-09" } }
- TCPA Trolls Description
- TCPA Attorney Description
- Associated with Litigator Description
- Listed in Complaint Description
- Landline A landline phone is an apparatus that is connected to the landline network to communicate.
- Mobile A mobile phone is a phone that is portable and works through radio technology.
- Voip A VoIP phone is a phone that is connected to internet to call.
- TCPA
- TCPA troll
- DNC Complainers
- Federal DNC
- tcpa TCPA
- troll TCPA Troll
- dnc_complainers DNC Complainers
- federal_dnc Federal DNC
Array scrub example
$api_endpoint = 'https://api.tcpalitigatorlist.com/scrub/phones/all/';
$api_username = '$api_username';
$api_password = '$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
{ "results": { "first_name": "Ken", "middle_name": "", "last_name": "Murakami", "case_title": "", "multiple_cases": "1", "phone_type": "Landline", "status_array": [ "tcpa" ], "phone_status": "Associated with Litigator", "clean": 0, "is_bad_number": true, "phone_number": "9257350671", "created_at": "2019-02-09 09:06:13", "updated_at": "2019-02-09 09:06:13", "status": "TCPA", "name": "Ken Murakami" } }
{ "results": { { "phone_number": "92573506711", "clean": 1, } } }
Easily scrub your phone numbers using our API SDK
Our repository you can find here https://github.com/StreetYo/TCPA-SDKAPI SDK
SDK stands for software development kit or devkit for short. It’s a set of software tools and programs used by developers to create applications for specific platforms.
SDK tools will include a range of things, including libraries, documentation, code samples, processes, and guides that developers can use and integrate into their own apps.
Make it before use
Login to your account. Generate your API keys here if you don't have them yet.
ExampleSet your API login and password. You can run this code with the GET phone or phones parameters and get their scrub statuses.
if ( isset($_GET['phone']) ){ print_r(tcpa_scrub_single_number($_GET['phone'])); } if ( isset($_GET['phones']) ){ print_r(tcpa_mass_scrub(explode(',', $_GET['phones']))); } function tcpa_scrub_single_number($phone_number, $fields = []){ $api_config = [ 'api_username' => 'YOUR API LOGIN', 'api_password' => 'YOUR API PASSWORD', 'response_format' => 'json', 'response_type' => isset($_GET['boolean']) ? 'boolean' : 'regular', 'check_types' => isset($_GET['type']) ? [$_GET['type']] : ['all'], ]; $api = new TCPA_API($api_config); return $api->request_single_number($phone_number, $fields); } function tcpa_mass_scrub($phone_numbers, $fields = []) { $api_config = [ 'api_username' => 'YOUR API LOGIN', 'api_password' => 'YOUR API PASSWORD', 'check_types' => isset($_GET['type']) ? [$_GET['type']] : ['all'], ]; $api = new TCPA_API($api_config); return $api->mass_scrub($phone_numbers, $fields); }
Our public API servers are limiting every client with 50 calls/second.
You can get a dedicated API for your account with no limits!
Contact us to request your dedicated server!