1. Home
  2. Help
  3. Personal Lists APIs by CleanTalk

How to Use the CleanTalk APIs for Your Personal Lists

 

API for managing Personal Lists. The interface is available here: cleantalk.org/my/show_private

Guide for the interface: cleantalk.org/help/blacklist-usage

 

Content:

General Information API методы для работы с персональными списками

API private_list_get API методы для работы с персональными списками

API private_list_add API методы для работы с персональными списками

API private_list_delete API методы для работы с персональными списками

API private_list_update API методы для работы с персональными списками

General Information

Protocol - HTTPS

Hostname - api.cleantalk.org

API private_list_get

Input Parameters

Transfer parameters methods GET and POST.

 

Necessary

method_name allowed value: private_list_get

user_token allowed values: you can get it in your dashboard in your CleanTalk Control Panel.

service_type allowed values: antispam, spamfirewall, securityfirewall

 

Example:

https://api.cleantalk.org/?method_name=private_list_get&user_token=USER_TOKEN&service_type=antispam

 

Optional

service_id list filtration by the selected website, you can get your value in Anti-Spam Dashboard or in your Security Dashboard.

 

Example:

https://api.cleantalk.org/?method_name=private_list_get&user_token=USER_TOKEN&service_type=antispam&service_id=314956

 

record_type list filtration by the record type, allowed values:

  • for service_type=antispam - 1, 2, 3, 4, 5, 7, 8, 9
  • for service_type=spamfirewall - 6, 10
  • for service_type=securityfirewall - 1, 3, 7

 

Example:

https://api.cleantalk.org/?method_name=private_list_get&user_token=USER_TOKEN&service_type=antispam&record_type=1

record_ids list filtration by the record ID

  • Data array, example: record_ids[]=3985411&record_ids[]=3985397
  • String, comma as a separator, example: record_ids=3985411,3985397

 

status list filtration by the record status, allowed values: allow, deny

created[lte] and created[gte] list filtration by the record creation date, allowed values: unix timestamp format

updated[lte] and updated[gte] list filtration by the record creation update, allowed values: unix timestamp format

search[value] search by the field "record", full or partial coincidence

start shift for the first record of the list, by default is 0

length limit of record quantity in the response, by default is 100, allowed values: 10, 25, 50, 100

order[0][dir] sorting direction of the records, allowed values: asc, desc

order[0][column] field index, records are being sorted by it

columns[0][data] field name of the record sorting, allowed values: record, record_type, created, updated, hits, status, product_id, hostname, note

draw arbitrary value, will be sent in the response for the asynchronous requests.

mode if its value is csv, the response will be an CSV file

 

Example:

https://api.cleantalk.org/?method_name=private_list_get&user_token=USER_TOKEN&service_type=antispam&mode=csv

 

Output Parameters

recordsTotal number of records without any filters

recordsFiltered number of records when filters are applied

draw arbitrary value, input parameters value

data record array:

  • record_id record ID
  • service_id website ID
  • hostname website hosname
  • record record value
  • countrycode country code
  • countryname country name
  • hits number of hits for the past 7 days
  • created record creation time
  • updated record update time
  • status record status
  • record_type record type
  • product_id product type
  • note record note
  • expired record lifespan

 

Example:

https://api.cleantalk.org/?method_name=private_list_get&user_token=USER_TOKEN&draw=10&columns[0][data]=hits&columns[1][data]=record&columns[2][data]=record_type&columns[3][data]=created&order[0][column]=3&order[0][dir]=asc&start=0&length=10&service_type=antispam&service_id=314956&record_type=1

{"data":[{"record_id":"3689885","service_id":"314956","hostname":"example.com","record":"1.2.3.3","countrycode":"US","countryname":"United States","hits":null,"created":"2019-10-28 12:14:41","updated":"2019-10-28 12:14:41","status":"deny","record_type":"1","product_id":"1","note":"123","expired":null},{"record_id":"3890626","service_id":"314956","hostname":"example.com","record":"1.2.3.4","countrycode":"US","countryname":"United States","hits":null,"created":"2019-11-19 15:19:26","updated":"2019-11-19 15:19:26","status":"deny","record_type":"1","product_id":"1","note":"","expired":null}],"draw":"10","recordsTotal":"8","recordsFiltered":"2","currentPage":0}

 

Possible Errors

https://api.cleantalk.org/?method_name=private_list_get

{"data":{"result":"FAIL","notice":"User token not found","operation_code":"51"}}

 

https://api.cleantalk.org/?method_name=private_list_get&user_token=USER_TOKEN

{"data":{"result":"FAIL","notice":"service_type is required and value must be in (antispam,spamfirewall,securityfirewall)","operation_code":"31"}}

 

API private_list_add

Input Parameters

 

Necessary

method_name allowed value: private_list_add

user_token allowed value: you can get it in your dashboard in your CleanTalk Control Panel.

service_id website ID, use all to add to every website in your CleanTalk profile.

service_type service type, allowed values: antispam, spamfirewall, securityfirewall

product_id product ID, allowed values: 1 for service_type=antispam or service_type=spamfirewall, 4 for service_type=securityfirewall

record_type record type, allowed values:

  • for service_type=antispam:
    • 1 IP-address
    • 2 E-mail
    • 3 Country
    • 4 Domain
    • 5 Top-level domain
    • 7 IP-network
    • 8 Stop-word
    • 9 Language
  • for service_type=spamfirewall:
    • 6 IP-network
    • 10 Country
  • for service_type=securityfirewall:
    • 1 IP-address
    • 3 Country
    • 7 IP-network

records

  • Data array, example: records[]=192.168.1.1&records[]=192.168.1.2
  • String, comma as a separator, example: records=192.168.1.1,192.168.1.2
  • File in the CSV format

 

Example:

https://api.cleantalk.org/?method_name=private_list_add&user_token=USER_TOKEN&service_id=all&service_type=antispam&product_id=1&record_type=1&records=192.168.1.1

{"data":{"records":[{"record_id":3985397,"record":"192.168.1.1","created":"2019-12-13 18:08:41","updated":"2019-12-13 18:08:41","service_id":"314956","service_type":"antispam","record_type":"1","product_id":"1","status":"deny","note":"","expired":"","countrycode":"","operation_status":"SUCCESS"}]}}

 

Optional

note record note, no more than 2048 symbols

status record status, allowed values: allow, deny (default values), deny_except (allowed for countries only, excludes everything except the selected one)

expired date string, record lifespan

 

Example:

https://api.cleantalk.org/?method_name=private_list_add&user_token=USER_TOKEN&service_id=all&service_type=antispam&product_id=1&record_type=1&records=192.168.1.2&status=allow&note=note&expired=2019-12-13 17:10:00

{"data":{"records":[{"record_id":3985411,"record":"192.168.1.2","created":"2019-12-13 19:11:02","updated":"2019-12-13 19:11:02","service_id":"314956","service_type":"antispam","record_type":"1","product_id":"1","status":"allow","note":"note","expired":"''2019-12-14 17:10:00''","countrycode":"","operation_status":"SUCCESS"}]}}

 

Output Parameters

records record array:

  • record_id record ID
  • service_id website ID
  • hostname website hosname
  • record record value
  • countrycode country code
  • created record creation time
  • updated record update time
  • status record status
  • record_type record type
  • product_id product type
  • note record note
  • expired record lifespan
  • operation_status operation status

 

Example:

https://api.cleantalk.org/?method_name=private_list_add&user_token=USER_TOKEN&service_id=all&service_type=antispam&product_id=1&record_type=1&records=192.168.1.2&status=allow&note=note&expired=2019-12-13 17:10:00

{"data":{"records":[{"record_id":3985411,"record":"192.168.1.2","created":"2019-12-13 19:11:02","updated":"2019-12-13 19:11:02","service_id":"314956","service_type":"antispam","record_type":"1","product_id":"1","status":"allow","note":"note","expired":"''2019-12-14 17:10:00''","countrycode":"","operation_status":"SUCCESS"}]}}

 

Possible Errors

https://api.cleantalk.org/?method_name=private_list_add

{"data":{"result":"FAIL","notice":"User token not found","operation_code":"51"}}

 

https://api.cleantalk.org/?method_name=private_list_add&user_token=USER_TOKEN

{"data":{"result":"FAIL","notice":"service_id is required","operation_code":"2"}}

 

https://api.cleantalk.org/?method_name=private_list_add&user_token=USER_TOKEN&service_id=all

{"data":{"result":"FAIL","notice":"service_type is required and value must be in (antispam,spamfirewall,securityfirewall)","operation_code":"3"}}

 

https://api.cleantalk.org/?method_name=private_list_add&user_token=USER_TOKEN&service_id=all&service_type=antispam

{"data":{"result":"FAIL","notice":"product_id is required and value must be in (1,4)","operation_code":"4"}}

 

https://api.cleantalk.org/?method_name=private_list_add&user_token=USER_TOKEN&service_id=all&service_type=antispam&product_id=1

{"data":{"result":"FAIL","notice":"record_type is required and value must be in (1,2,3,4,5,7,8,9)","operation_code":"5"}}

 

https://api.cleantalk.org/?method_name=private_list_add&user_token=USER_TOKEN&service_id=all&service_type=spamfirewall&product_id=1

{"data":{"result":"FAIL","notice":"record_type is required and value must be in (6,10)","operation_code":"5"}}

 

https://api.cleantalk.org/?method_name=private_list_add&user_token=USER_TOKEN&service_id=all&service_type=securityfirewall&product_id=4

{"data":{"result":"FAIL","notice":"record_type is required and value must be in (1,3,7)","operation_code":"5"}}

 

https://api.cleantalk.org/?method_name=private_list_add&user_token=USER_TOKEN&service_id=all&service_type=antispam&product_id=1&record_type=1

{"data":{"result":"FAIL","notice":"records is required","operation_code":"6"}}

 

https://api.cleantalk.org/?method_name=private_list_add&user_token=USER_TOKEN&service_id=all&service_type=antispam&product_id=1&record_type=1&records=mail@example.com

{"data":{"records":[{"record":"mail@example.com","service_id":"314956","service_type":"antispam","record_type":"1","product_id":"1","operation_status":"FAILED","operation_message":"Wrong format","operation_code":"7"}]}}

 

https://api.cleantalk.org/?method_name=private_list_add&user_token=USER_TOKEN&service_id=all&service_type=antispam&product_id=1&record_type=1&records=1.1.1.4

{"data":{"records":[{"record":"1.1.1.4","service_id":"314956","service_type":"antispam","record_type":"1","product_id":"1","operation_status":"FAILED","operation_message":"This IP address belongs to networks of payment systems, searching systems or other important services. It is forbidden to add such address to your personal lists.","operation_code":"10"}]}}

 

https://api.cleantalk.org/?method_name=private_list_add&user_token=USER_TOKEN&service_id=all&service_type=antispam&product_id=1&record_type=1&records=192.168.1.1

{"data":{"records":[{"record_id":"3985397","record":"192.168.1.1","created":"2019-12-13 18:08:41","updated":"2019-12-13 18:08:41","service_id":"314956","service_type":"antispam","record_type":"1","product_id":"1","status":"deny","note":"","expired":"","countrycode":"","operation_status":"FAILED","operation_message":"Record already exists","operation_code":"9"}]}}

 

API private_list_delete

Input Parameters

method_name allowed value: private_list_delete

user_token allowed values: you can get it in your dashboard in your CleanTalk Control Panel.

record_ids

  • Data array, example: record_ids[]=3985411&record_ids[]=3985397
  • String, comma as a separator, example: record_ids=3985411,3985397

 

Example:

https://api.cleantalk.org/?method_name=private_list_delete&user_token=USER_TOKEN&record_ids=3985411,3985397

{"data":{"records":[{"record_id":"3985411","operation_status":"SUCCESS"},{"record_id":"3985397","operation_status":"SUCCESS"}]}}

 

Output Parameters

records record array:

  • record_id record ID
  • operation_status operation status

 

Example:

https://api.cleantalk.org/?method_name=private_list_delete&user_token=USER_TOKEN&record_ids=3985411,3985397

{"data":{"records":[{"record_id":"3985411","operation_status":"SUCCESS"},{"record_id":"3985397","operation_status":"SUCCESS"}]}}

 

Possible Errors

https://api.cleantalk.org/?method_name=private_list_delete&user_token=USER_TOKEN

{"data":{"result":"FAIL","notice":"record_ids is required","operation_code":"22"}}

https://api.cleantalk.org/?method_name=private_list_delete&user_token=USER_TOKEN&record_ids=3985411,3985397

{"data":{"records":[{"record_id":"3985411","operation_status":"FAILED","operation_message":"Record not found","operation_code":"21"},{"record_id":"3985397","operation_status":"FAILED","operation_message":"Record not found","operation_code":"21"}]}}

 

API private_list_update

Input Parameters

method_name allowed value: private_list_update

user_token allowed values: you can get it in your dashboard in your CleanTalk Control Panel.

status[record_id] allowed values: allow и deny

note[record_id] maximum length is no more than 2048 symbols

 

Example:

https://api.cleantalk.org/?method_name=private_list_update&user_token=USER_TOKEN&status[3803794]=deny&status[3982786]=deny

{"data":{"records":[{"record_id":"3803794","operation_status":"SUCCESS"},{"record_id":"3982786","operation_status":"SUCCESS"}]}}

 

Output Parameters

records record array:

  • record_id record ID
  • operation_status operation status

 

Example:

https://api.cleantalk.org/?method_name=private_list_update&user_token=USER_TOKEN&status[3803794]=deny&note[3803794]=test

{"data":{"records":[{"record_id":"3803794","operation_status":"SUCCESS"}]}}

 

Possible Errors

https://api.cleantalk.org/?method_name=private_list_update&user_token=USER_TOKEN

{"data":{"result":"FAIL","notice":"record list is empty","operation_code":"43"}}

https://api.cleantalk.org/?method_name=private_list_update&user_token=USER_TOKEN&note[3985397]=note

{"data":{"records":[{"record_id":"3985397","operation_status":"FAILED","operation_message":"Record not found","operation_code":"42"}]}}

https://api.cleantalk.org/?method_name=private_list_update&user_token=USER_TOKEN&status[3803794]=allow

{"data":{"records":[{"record_id":"3803794","operation_status":"FAILED","operation_message":"status allow disabled for record_type in (3,8,6,10)","operation_code":"41"}]}}

 

 

Create an account
Your CleanTalk Dashboard

Was this information helpful?

No

Yes



Perhaps it would also be interesting