Anti-Spam "check_newuser" API method

This API method is best suited to detect spam registrations, subscriptions, and other forms where there are no additional fields for user input or where you do not need to check these fields (polls, eCommerce orders, etc.).

It is part of the CleanTalk Anti-Spam API - a spam detection API you can call from any backend. Client libraries and integration examples are on the CleanTalk for developers page. To check comments, reviews and any form with a message field, use check_message().

1. Collect web-form data.
2. Send data JSON via a POST request to https://moderate.cleantalk.org/api2.0
3. Parse the response and make a decision.

Request

• Data JSON Example
• Data Processing
• Required Parameters
• Additional parameters

Response

• Response example
• Response Explanation

Limits and response time

Related methods

Code Examples

• curl
• Wget
• PHP 
• Python
• NodeJS
• C#
• GoLang

FAQ

Related Links

Request

Data JSON Example

{
	"method_name":"check_newuser",
	"auth_key":"your_access_key",
	"sender_email":"stop_email@example.com",
	"sender_nickname":"John Doe",
	"sender_ip":"127.0.0.1",
	"event_token":"sha_256_string_of_event_token"
	"submit_time":15,
	"sender_info": {
		"REFFERRER": "https:/referrer-site.com",
		"USER_AGENT": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/77.0.3835.0 Safari/537.36"
		}
}

Data Processing

Necessary information about the data processing

Required Parameters

The method will not work without these parameters

Additional parameters

These parameters are necessary for filtering spam

Response

Response example

The server's response is independent of the platform.

{
	"version" : "7.47",
	"inactive" : 0,
	"js_disabled" : 0,
	"blacklisted" : 1,
	"comment" : "*** Forbidden. Sender blacklisted. ***",
	"codes" : "FORBIDDEN BL",
	"fast_submit" : 0,
	"id" : "5a49267e202169b3a4d9ddefee190065",
	"account_status" : 1,
	"allow" : 0
}

Response Explanation

In the server response code, you can also see the result of checking an email address for existence. If a blocked request contains a non-existent e-mail address, you will see the next text in the API response code field: "FORBIDDEN EMAIL_NOT_EXISTS" 

Please note, that this code will be displayed only if a non-existent email is the main reason for blocking.

Limits and response time

• Endpoint: https://moderate.cleantalk.org/api2.0, one HTTPS POST per registration or form submission.
• Response time: about 0.1 second from Europe. Set a client timeout of 3 to 5 seconds.
• If the cloud does not answer: let the registration through. A missing verdict should never block a real user.
• Database methods (spam_check(), email_check()) run on https://api.cleantalk.org and have a documented call limit of 100 calls per 60 seconds. Above that the API returns {"error_message":"Calls limit exceeded.","error_no":10}.
• Authentication: your CleanTalk Access Key in the auth_key parameter. The same key works for every method.

Related methods

The check_newuser() spam registration API is one of several methods of the CleanTalk Anti-Spam API. Depending on what you need to check, use:

• check_message() - spam check for comments, reviews and any form with a message field.
• check_bot() - tells whether a specific submission was made by a bot.
• spam_check() - checks an IP address or email against the CleanTalk spam database.
• email_check() - checks whether an email address actually exists.
• send_feedback() - sends the final verdict back to the cloud so the filter learns from your decisions.

Ready-made client libraries for PHP, Python, Ruby, C#, Perl, Laravel and Yii are listed on the CleanTalk for developers page.

Code Examples

To integrate CleanTalk with your project, please use our official libraries.
All examples are available in GitHub repositories (see README files for usage):

• PHP: CleanTalk/php-antispam
• Python: CleanTalk/python-antispam
• Django: CleanTalk/django-antispam-no-recaptcha-captcha
• Node.js: westtrade/cleantalk
• C#: CleanTalk/csharp-antispam

Using curl

CLI example

curl -X POST https://moderate.cleantalk.org/api2.0 \
  -H "Content-Type: application/json" \
  -d '{
    "method_name": "check_newuser",
    "auth_key": "your_access_key",
    "sender_email": "stop_email@example.com",
    "sender_nickname": "John Doe",
    "sender_ip": "127.0.0.1",
    "js_on": 1,
    "submit_time": 15
  }'

Wget

CLI example

wget -O- --post-data='{"method_name":"check_newuser","auth_key":"your_acccess_key","sender_email":"stop_email@example.com","sender_nickname":"John Doe","sender_ip":"127.0.0.1","js_on":1,"submit_time":15}' https://moderate.cleantalk.org/api2.0

Using GoLang

Backend (GoLang)

package main

import (
	"encoding/json"
	"fmt"
	"io"
	"io/ioutil"
	"net/http"
	"strings"
)

var authKey string = "enter_your_key"
var configUrg string = "http://moderate.cleantalk.org/api2.0/"
var agent string = "golang-api"

type newUserInputData struct {
	AuthKey        string `json:"auth_key"`
	Agent          string `json:"agent"`
	SenderEmail    string `json:"sender_email"`
	SenderIp       string `json:"sender_ip"`
	SenderNickname string `json:"sender_nickname"`
	JsOn           uint   `json:"js_on"`
	SubmitTime     uint   `json:"submit_time"`
}

type NewUserResultData struct {
	Version       string `json:"version"`
	Inactive      uint   `json:"inactive"`
	JsDisabled    uint   `json:"js_disabled"`
	Blacklisted   string `json:"blacklisted"`
	Comment       string `json:"comment"`
	Codes         string `json:"codes"`
	FastSubmit    uint   `json:"fast_submit"`
	Id            string `json:"id"`
	AccountStatus uint   `json:"account_status"`
	Allow         uint   `json:"allow"`
}

func main() {
	inputData := newUserInputData{
		MethodName:     "check_newuser",
		AuthKey:        authKey,
		Agent:          agent,
		SenderEmail:    "stop_email@example.com",
		SenderIp:       "192.168.0.1",
		SenderNickname: "testuser",
		JsOn:           1,
		SubmitTime:     5,
	}

	resultData, err := CheckNewuser(inputData)
	if err != nil {
		fmt.Println(err.Error())
		return
	}
	if resultData.Allow == 1 {
		fmt.Println(fmt.Sprintf("User allowed. Reason %s", resultData.Comment))
		return
	}
	fmt.Println(fmt.Sprintf("User forbidden. Reason %s", resultData.Comment))
}

func CheckNewuser(inputData newUserInputData) (NewUserResultData, error) {
	inputDataBytes, err := json.Marshal(inputData)
	var resultData NewUserResultData
	if err != nil {
		return resultData, err
	}
	var body io.Reader = strings.NewReader(string(inputDataBytes))
	req, err := http.NewRequest(http.MethodPost, configUrg, body)
	if err != nil {
		return resultData, err
	}
	req.Header.Set("Content-Type", "application/json")

	client := &http.Client{}
	resp, err := client.Do(req)
	if err != nil {
		return resultData, err
	}
	defer resp.Body.Close()

	answer, err := ioutil.ReadAll(resp.Body)
	if err != nil {
		return resultData, err
	}
	err = json.Unmarshal(answer, &resultData)
	return resultData, nil
}

Frontend (HTML)

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <title>Title</title>
    <script src="https://moderate.cleantalk.org/ct-bot-detector-wrapper.js" id="ct-bot-detector-js></script>
</head>
<body>
  <form method="post" action="chek_newuser.php">
      <label for="login">Login:</label>
      <input type="text" name="login" id="login" /> <br />
      <label for="email">Email:</label>
      <input type="text" name="email" id="email" value="" /> <br />
      <input type="submit" />
  </form>
</body>
</html>

FAQ

What is a spam registration API?

A spam registration API lets your backend check a signup before the account is created. You send the sender data - email, nickname, IP and behavioral signals - to a remote service, and it returns whether the registration looks like spam. CleanTalk's check_newuser() is such a spam detection API for registrations, subscriptions and forms without a message field.

How does the check_newuser() spam filter API work?

You send an HTTPS POST with the sender data as JSON to the CleanTalk cloud. The API checks it against a global spam database and behavioral signals and returns allow=1 (legitimate) or allow=0 (spam), with the reason in the codes field. Authentication is done with your CleanTalk Access Key.

Does it check whether the email really exists?

Yes. If a blocked registration uses a non-existent address, the response code contains DENIED EMAIL_NOT_EXISTS. Disposable addresses are reported as EMAIL_DOMAIN_DISPOSABLE.

Is there a free anti-spam API?

Yes. CleanTalk offers a free trial, after which the Anti-Spam service continues on an annual plan - see pricing. The same Access Key powers all API methods.

Which programming languages are supported?

Any language that can send an HTTPS POST. The examples above cover curl, Wget, PHP, Python, Node.js, C# and GoLang. To check messages and comments use the check_message() spam detection API method; for the full method list see the CleanTalk Anti-Spam API.

Related Links

Available features related to the method:

• CleanTalk's Personal Blacklist or Whitelist feature helps you block unwanted users and allow users who were recognized as spammers.
• The Stop-Word feature allows you to block comments and nicknames that contain any word from your Stop-Word List.
• Country Blacklist allows you to block all comments and registrations coming from selected countries.

Stop-Word and Country Blacklist features are available after purchasing our Extra Package. Go to your Renewal License Page to see the details.