Getting Started with the API

Welcome to SignupSentinel! This guide will help you get started with configuring and using our API. SignupSentinel can be implemented using a single API call and can be configured to work best for your use case. Below you will learn how to utilize the API and how each of the API Token customization options function.

Understanding the Results

Before diving into the details of how to configure and use the API, it's important to first understand the results the API returns. There are two main result fields, an objective success/failure boolean called blocked and a subjective score called risk_score. Both results will be present in your API responses.

blocked: A boolean value that indicates whether the signup is considered suspicious/fraudulent and should be blocked (true) or not (false). SignupSentinel has a myriad of built-in checks to determine the validity of a signup, and you can select which checks an individual API Token uses (see below). If any selected check finds a detection, the blocked field will return true.
risk_score: A numerical value that represents the overall risk score of the request with a maximum of 10. The risk score is calculated based on the results of individual checks, such as free email services, disposable email services, VPNs, and more. While it is up to you to use the results as you see fit, one example classification you can use is: 0-5 Low Risk, 5-7 Medium Risk, 8-10 High Risk. By default, a risk score of 7 or more will result in blocked being sent to true. You can override this.

API Token Configurations

You can find, configure, and add new API Tokens on your settings page. There is one API Token automatically generated for you on account creation, and you can add, edit and disable tokens whenever you like. API Tokens are set up so that you can modify them with new settings without having to update your own code. If you want to add or remove a validation check, you can navigate to this settings page and update the token in question, and on the next API call, SignupSentinel will respect the new configuration.

API Tokens can be customized with the following options:

Token Name: A display name for the token. You will see this used in reporting and analytics if you utilize mulitiple tokens.
Free Email Services: Automatically fail validation if the included email address is found to be from a free email service.
Disposable Email Services: Automatically fail validation if the included email address is found to be from a disposable email service.
Invalid DNS Records: Automatically fail validation if the included domain has invalid DNS records.
VPN/Proxies: Automatically fail validation if the included IP address is from a VPN or Proxy service.
Known Malware IP Addresses: Automatically fail validation if the included IP address is known to be associated with malware.
Known Abuser IP Addresses: Automatically fail validation if the included IP address is known to be associated with abusive behavior.
Suspicious User Agents: Automatically fail validation if the included user agent is flagged as suspicious.
Blocked Countries: Automatically fail validation if the included IP address is from a blocked country.

How to Use the API

To use the API, you need to send HTTP requests to the following endpoints:

Create Risk Assessment: POST /api/v1/resources/risk_assessment

Properties of Risk Assessment

The RiskAssessment model has the following properties:

ip: The IP address of the user.
email_address: The email address of the user.
user_agent: The user agent string of the user's browser.
api_token: The associated API token string.

Example Request

For full Documentation, check out the API Documentation page.


curl -X POST https://app.signupsentinel.com/api/v1/resources/risk_assessment 
     -H "Content-Type: application/json" 
     -H "X-API-Key: [API_KEY]" 
     -d '{
           "ip_address": "192.168.1.1",
           "email_address": "test@example.com",
           "user_agent": "Mozilla/5.0"
         }'

Example Result

Below you will see an example response from the API. The response shows individual results for each check, where true means SignupSentinel found a matching record in our database of suspicious IP Addresses, User agents, etc. For example, seeing "detected_malware_ip": true means the IP address included in the API call was found in our list of IP addresses associated with Malware. You will also see a reason property which will contain a text string describing the reason why validation failed for that request. You can use this reason to display messages to your users, or log results in your own logs, and they can be customized on the configuration page.


  "risk_assessment": {
    "id": 12345,
    "ip": "192.168.1.1",
    "domain_name": "gmail.com",
    "user_agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/58.0.3029.110 Safari/537.3",
    "risk_score": 3,
    "blocked": true,
    "detected_free_email": true,
    "detected_disposable_email": false,
    "detected_invalid_dns_records": true,
    "detected_vpn": false,
    "detected_malware_ip": false,
    "detected_abuser_ip": false,
    "created_at": "2024-07-30T20:39:42.845Z",
    "updated_at": "2024-07-30T20:39:42.888Z",
    "blocked_reason": "Free email services are not allowed",
    "detected_blocked_country": false,
    "detected_suspicious_user_agent": false
  }

Retrieving User Agent and IP Address Information

Here's how you can retrieve the user agent information in different programming languages and systems:


  user_agent = request.user_agent
  ip_address = request.remote_ip


  import requests

  response = requests.get('https://httpbin.org/user-agent')
  user_agent = response.json()['user-agent']
  ip_address = response.json()['origin']


  const http = require('http');

  http.createServer((req, res) => {
    const user_agent = req.headers['user-agent'];
    const ip_address = req.connection.remoteAddress;
    // Use the user_agent and ip_address variables as needed
  }).listen(3000);


  $user_agent = $_SERVER['HTTP_USER_AGENT'];
  $ip_address = $_SERVER['REMOTE_ADDR'];


  string user_agent = Request.UserAgent;
  string ip_address = Request.UserHostAddress;


  String user_agent = request.getHeader("User-Agent");
  String ip_address = request.getRemoteAddr();


  import org.springframework.web.bind.annotation.GetMapping;
  import org.springframework.web.bind.annotation.RequestHeader;
  import org.springframework.web.bind.annotation.RestController;

  @RestController
  public class UserController {

    @GetMapping("/user-agent")
    public String getUserAgent(@RequestHeader("User-Agent") String userAgent) {
      return userAgent;
    }
    
    @GetMapping("/ip-address")
    public String getIpAddress(@RequestHeader("X-Forwarded-For") String ipAddress) {
      return ipAddress;
    }
  }

Backend Implementation

We recommend implementing this in your backend code, wherever you're doing form validations for your signups. For example, in a Ruby on Rails web application, we'd include it as a validation in the User model. This way, you have easy access to the IP, User Agent, and Email, and can use the "block_reason" as feedback to the user.