Apility.io API Reference Guide NAV Navbar
shell
  • What is Apility.io
  • How to use the API
  • IP Check
  • Domain Check
  • Email Check
  • Geo IP look up
  • Autonomous System look up
  • Quarantined Objects
  • Resource History
  • WHOIS query
  • Objects
  • Errors
  • What is Apility.io

    Apility.io can be defined as Threat Intelligence SaaS for developers and product companies that want to know in realtime if their existing or potential users have been classified as 'abusers' by one or more of these lists.

    Automatic extraction processes extracts all the information in realtime, keeping the most up to date data available, saving yourself the hassle of extract and update regularly all these lists and the data.

    We have several language bindings! You can view code examples in the dark area to the right, and you can switch the programming language of the examples with the tabs in the top right.

    This example API documentation page was created with Slate. Feel free to edit it and submit pull requests if you want to improve this documentation.

    What does Apility.io offer?

    Apility.io offers an extremely simple and minimalistic REST style API to access in realtime to these lists and do the following simple question about the resource?

    Is this IP, domain or email stored in any blacklist?

    The answers to this question can be:

    A bad resource implies some kind of action from developers' side. A clean resource does not need any action from their side.

    What resources are listed?

    There are several different type of resources that will grow in time:

    What blacklists are in use?

    Blacklists change on a daily basis. Please follow the links in the main page.

    Where are the API endpoints servers deployed?

    There are multiple servers deployed worldwide in different Cloud Providers, scaling up and down automatically to handle peaks and valleys usage. If you don't care about using a non secure connection then the api can be reached at

    But if you care about non using a secured connection you can use SSL-terminated endpoints at:

    When you perform a request to this endpoint, thanks to the magic of DNS Anycast and latency-based resolution you will be served with the closest server available.

    How to use the API

    Design principles

    The access to the API has been developed to be simple, minimalistic and fast. We have followed the Keep it Simple (KISS) approach, with several different ways to access the data.

    To use the API you will need a API Key or Token that you will pass along your request. You need to sign up to get it, and yes, there is a free plan you can use as long as you want.

    API is restricted by this API Key. Each subscription plan is limited to a number of API requests per day. If you exceed that limit in a 24 hour period the service will return a 429 HTTP status code. If you need to make more requests you should consider a paid plan with more quota. You can know in real time the quota consumed daily from the Dashboard.

    There is also an ANONYMOUS PLAN. The platform applies this plan if a developer does not pass any API Token when doing a request. So you can test the API right way before signing up!

    Please read more details about Plans, Pricing and limits by day and hour

    The Administration Dashboard

    To enjoy the API and the different Apility.io services it is necessary for the user to register on our platform. Once registered, the user will have access to a 30-day Trial of the service that will allow you to know without any cost the benefits of our solution. If after these 30 days the user does not enter the method of payment, you will enjoy the service for free for an unlimited period of time but with some restrictions.

    By registering on the platform you have access to the administration dashboard. This administration console allows you to manage and configure the different services to tailor them to the needs of each client.

    Authentication

    To authorize with a header parameter, use this code:

    # With shell, you can just pass the correct header with each request
    curl "https://api.apility.net"
      -H "X-Auth-Token: UUID"
    

    To authorize with a query string parameter, use this code:

    # With shell, you can just pass the correct header with each request
    curl "https://api.apility.net/?token=UUID"
    

    Make sure to replace UUID with your API key.

    Apility.io uses API keys to allow access to the API. You need to sign up to get an API Key.

    Apility.io expects for the API Key to be included in all API requests made. It can be included as a header or as a query string parameter.

    X-Auth-Token: UUID

    Simple Model: GET requests and HTTP response codes

    Example: Is IP 1.2.3.4 in any blacklist?

    We will use curl from the command line.

    $ curl -i -X GET api.apility.net/badip/1.2.3.4 -H "X-Auth-Token: UUID"
    

    The response is:

    HTTP/1.1 200 OK
    CONTENT-TYPE: text/plain; charset=utf-8
    CONTENT-LENGTH: 7
    DATE: Tue, 21 Jun 2016 08:52:14 GMT
    SERVER: Python/3.5 aiohttp/0.21.6
    

    The HTTP 200 (OK) code means the IP 1.2.3.4 belongs to any blacklist.

    Example: Is IP 8.8.8.8 in any blacklist?

    We will use curl from the command line.

    $ curl -i -X GET api.apility.net/badip/8.8.8.8 -H "X-Auth-Token: UUID"
    

    The response is:

    HTTP/1.1 404 Not Found
    CONTENT-TYPE: text/plain; charset=utf-8
    CONTENT-LENGTH: 18
    DATE: Sun, 26 Jun 2016 15:41:40 GMT
    SERVER: Python/3.5 aiohttp/0.21.6
    

    The HTTP 404 (Not Found) code means the IP 8.8.8.8 does not belong to any blacklist (8.8.8.8 is a public DNS by Google, which makes a lot of sense to not be in any blacklist of abusers...)

    The easiest way to use the API get advantage of GET requests and responses with standard HTTP codes. In this model, a HTTP 200 (OK) response code means that the value passed in the request belongs to any lists and therefore is a bad resource. If the answer is a HTTP 404 (Not found) code that means it does not belong to any lists and therefore is a clean resource.

    Developers just need to check the status code returned in the response. If code is 200 (OK), then the resource was found in any list and it's a bad resource. If the code is 404 (Not found), the resource was not found in any list.

    Advanced Model: GET requests, JSON and HTTP response codes

    Example: Is domain gmail.com in any blacklist?

    $ curl -H "Accept: application/json" -H "X-Auth-Token: UUID" -X GET https://api.apility.net/baddomain/gmail.com
    

    The response is:

    {  
       "type":"baddomain",
       "response":{  
          "domain":{  
             "mx":[  
                "alt4.gmail-smtp-in.l.google.com",
                "alt2.gmail-smtp-in.l.google.com",
                "gmail-smtp-in.l.google.com",
                "alt1.gmail-smtp-in.l.google.com",
                "alt3.gmail-smtp-in.l.google.com"
             ],
             "ns":[  
                "ns3.google.com.",
                "ns4.google.com.",
                "ns1.google.com.",
                "ns2.google.com."
             ],
             "blacklist_mx":[ ],
             "blacklist_ns":[ ],
             "blacklist":[  
                "FREEMAIL"
             ],
             "score":-1
          },
          "score":-1,
          "source_ip":{  
             "score":0,
             "geo":{},
             "is_quarantined":false,
             "blacklist":[ ]
          },
          "ip":{  
             "score":0,
             "geo":{  
                "country":"US",
                "continent":"NA",
                "hostname":"mad06s25-in-f5.1e100.net.",
                "city":"Mountain View",
                "as":{  
                   "country":"US",
                   "asn":"15169",
                   "name":"GOOGLE - Google Inc."
                },
                "region":"California",
                "postal":"94043",
                "address":"216.58.201.133",
                "longitude":-122.0574,
                "latitude":37.419200000000004
             },
             "is_quarantined":false,
             "blacklist":[ ]
          }
       }
    }
    

    Gmail is in the blackist FREEMAIL. It contains a catalog of Free Email services worldwide. You can remove FREEMAIL from the blacklists from the dashboard if you don't want to restrict access to Free Email services.

    This model follows the approach of the simple model, but allows to know the blacklists the requested resource is. This model still follow that if the response is an HTTP code 200 (OK) means that the value passed in the request is part of the lists and therefore is a bad resource. But this answer returns a set of list names the resource belongs to.

    And if the answer is an HTTP 404 (Not found) code means that the value cannot be found in the lists and therefore is a clean resource.

    To use Advanced Model, the developer needs to add to the header of the requests the application/json response Accept:

    Developers will need to parse and analyze the JSON object returned in their applications.

    JSONP support

    Example: Is email marketing@apility.io in any blacklist?

    $ curl -H "X-Auth-Token: UUID" -X GET "https://api.apility.net/bademail/marketing@apility.io?callback=myfunction"
    

    The response is:

    myfunction(
    {"error":
        { "message": "Resource not found",
          "status": 404
        }
    });
    

    The marketing email from Apility.io is not in any blacklist, and the error comes as a JSON payload inside a function call as JSONP needs.

    Example: Is domain mailinator.com in any blacklist?

    $ curl -H "X-Auth-Token: UUID" -X GET "https://api.apility.net/baddomain/mailinator.com?callback=myfunction"
    

    The response is:

    myfunction(
    {"blacklists": ["IVOLO-DED", "DEA"]}
    );
    

    Mailinator is a very well known Disposible Email Address provider, and the response returns as a JSON payload inside a function call as JSONP needs.

    JSONP (JSON with Padding or JSON-P) is a technique used by web developers to overcome the cross-domain restrictions imposed by browsers' same-origin policy that limits access to resources retrieved from origins other than the one the page was served by. Read more details in the wikipedia

    The developer does not need to add to the header of the requests the application/json response Accept, it will be added implicit when the parameter callback is passed:

    With JSONP requests some client side libraries can't manage HTTP codes properly, so the error responses are returned as JSON payload as follows:

    CORS restrictions

    Cross-Origin Resource Sharing (CORS) is a mechanism that uses additional HTTP headers to let a user agent gain permission to access selected resources from a server on a different origin (domain) than the site currently in use. A user agent makes a cross-origin HTTP request when it requests a resource from a different domain, protocol, or port than the one from which the current document originated.

    Paid plans can configure the allowed referers site to prevent unauthorized use and quota theft. Key restriction lets you specify which web sites, IP addresses, or apps can use this key. You can test this feature during the 30 days trail period.

    IP Address restrictions

    Paid plans can restrict the source IP of the requests to prevent unauthorized use and quota theft. You can test this feature during the 30 days trail period.

    IP Check

    Apility.io tracks multiple abuse blacklists and consolidates them in a single database you can look up with our minimalist API.

    Check if an IP belongs to any abusers' blacklist

    $ curl -i -H "X-Auth-Token: UUID" -X GET "https://api.apility.net/badip/<IP>"
    

    The response can be:

    HTTP/1.1 200 OK
    CONTENT-TYPE: text/plain; charset=utf-8
    CONTENT-LENGTH: 7
    DATE: X
    SERVER: Python/3.5 aiohttp/0.21.6
    

    or

    HTTP/1.1 404 Not Found
    CONTENT-TYPE: text/plain; charset=utf-8
    CONTENT-LENGTH: 18
    DATE: X
    SERVER: Python/3.5 aiohttp/0.21.6
    

    This endpoint returns if the IP belongs to any list with the HTTP status code in the response.

    HTTP Request

    GET https://api.apility.net/badip/<IP>

    Header Parameters

    Parameter Mandatory Description
    X-Auth-Token No API Key of the owner.

    QueryString Parameters

    Parameter Mandatory Description
    token No API Key of the owner.
    callback No Function to invoke when using JSONP model.

    URL Parameters

    Parameter Description
    IP The IP to look up in the system.

    Response

    The response can be a 200 or 404 HTTP code if everything is ok:

    Get all abusers' blacklist an IP belongs to

    $ curl -H "Accept: application/json" -H "X-Auth-Token: UUID" -X GET "https://api.apility.net/badip/<IP>"
    

    The response can be:

    {
        "blacklists": ["STOPFORUMSPAM-180", "STOPFORUMSPAM-30", "STOPFORUMSPAM-7", "STOPFORUMSPAM-365", "STOPFORUMSPAM-90"]
    }
    

    or

    Resource Not found
    

    If a developer wants to know what blacklists contain the IP passed as argument, she needs to pass to curl an extra argument with information about the Content type as application/json:

    HTTP Request

    GET https://api.apility.net/badip/<IP>

    Header Parameters

    Parameter Mandatory Description
    X-Auth-Token No API Key of the owner.
    Accept Yes application/json

    QueryString Parameters

    Parameter Mandatory Description
    token No API Key of the owner.
    callback No Function to invoke when using JSONP model.

    URL Parameters

    Parameter Description
    IP The IP to look up in the system.

    Response

    The status code of the response can be a 200 or 404 HTTP code if everything is ok, but it will also return the following JSON structure if status code is 200:

    Parameter Description
    blacklists Array with a list with the Identifiers of each blacklist.

    Get all abusers' blacklist a set of IP belong to (Bulk request)

    $ curl -H "Accept: application/json" -H "X-Auth-Token: UUID" -X GET "https://api.apility.net/badip_batch/<IP1>,<IP2>...<IPn>"
    

    The response can be:

    {
        "response": [
            {
                "ip": "8.8.8.8",
                "blacklists": []
            },
            {
                "ip": "212.231.122.12",
                "blacklists": []
            },
            {
                "ip": "1.2.3.4",
                "blacklists": ["STOPFORUMSPAM-180", "STOPFORUMSPAM-30", "STOPFORUMSPAM-7", "STOPFORUMSPAM-365", "STOPFORUMSPAM-90"]
            }
        ]
    }
    

    A developer can save time and rate-limit restrictions if she passes a list of comma separated IP in the QueryString. She will get the blacklists for each IP in the response. If the IP is not well formed it will return nothing for that IP, but will perform the lookup for the rest of the valid IP:

    HTTP Request

    GET https://api.apility.net/badip_batch/<IP>

    Header Parameters

    Parameter Mandatory Description
    X-Auth-Token No API Key of the owner.
    Accept No application/json

    QueryString Parameters

    Parameter Mandatory Description
    token No API Key of the owner.
    callback No Function to invoke when using JSONP model.

    URL Parameters

    Parameter Description
    IP1,IP2,...IPn The comma separated list of IP to look up in the system.

    Response

    The status code of the response can be a 200 if everything is ok, but it will also return the following JSON structure:

    Parameter Description
    response Array with a list with the blacklists for each IP.

    Domain Check

    Domain check implements an algorithm that assigns a score to the domain based on several checks done by the system:

    By default if some of these tests success, a -1 score is added to the overall score of the domain. So an overall score of -3 means the chances of being a bad domain are higher than -1.

    Check if a domain scores a negative or neutral score.

    Check a "clean" domain

    $ curl -i -H "X-Auth-Token: UUID" -X GET "https://api.apility.net/baddomain/google.com"
    

    The response:

    HTTP/1.1 404 Not Found
    Server: nginx/1.10.3 (Ubuntu)
    Date: Fri, 24 Nov 2017 13:59:42 GMT
    Content-Type: text/plain; charset=utf-8
    Content-Length: 18
    Connection: keep-alive
    

    Check a "bad" domain

    $ curl -i -H "X-Auth-Token: UUID" -X GET "https://api.apility.net/baddomain/mailinator.com"
    
    HTTP/1.1 200 OK
    Server: nginx/1.10.3 (Ubuntu)
    Date: Fri, 24 Nov 2017 14:00:50 GMT
    Content-Type: text/plain; charset=utf-8
    Content-Length: 7
    Connection: keep-alive
    Strict-Transport-Security: max-age=63072000; includeSubdomains
    X-Frame-Options: DENY
    X-Content-Type-Options: nosniff
    

    This endpoint returns in the HTTP status code of the response if the domain has a neutral or a negative score. A negative score means that the domain has been classified as 'bad' by the algorithm.

    HTTP Request

    GET https://api.apility.net/baddomain/<DOMAIN>

    Header Parameters

    Parameter Mandatory Description
    X-Auth-Token No API Key of the owner.

    QueryString Parameters

    Parameter Mandatory Description
    token No API Key of the owner.
    callback No Function to invoke when using JSONP model.
    quarantine_ip No This IP address will be added to the quarantine blacklist of the user if the domain has a negative score.
    quarantine_ttl No The TTL in seconds to store the IP address passed in 'quarantine_ip'. If not passed, default TTL is 3600.

    URL Parameters

    Parameter Description
    DOMAIN The Domain name to look up in the system.

    Response

    The response can be a 200 or 404 HTTP code if everything is ok:

    Get individual scores of a domain

    Get all information from a "clean" domain

    $ curl -H "Accept: application/json" -H "X-Auth-Token: UUID" -X GET "https://api.apility.net/baddomain/google.com"
    

    The response can be:

    {
       "response":{
          "domain":{
             "score":0,
             "blacklist_ns":[],
             "mx":[
                "alt2.aspmx.l.google.com",
                "alt1.aspmx.l.google.com",
                "aspmx.l.google.com",
                "alt4.aspmx.l.google.com",
                "alt3.aspmx.l.google.com"
             ],
             "blacklist_mx":[],
             "blacklist":[],
             "ns":[
                "ns2.google.com.",
                "ns3.google.com.",
                "ns1.google.com.",
                "ns4.google.com."
             ]
          },
          "score":0,
          "ip":{
             "score":0,
             "is_quarantined":false,
             "address":"74.125.133.102",
             "blacklist":[]
          },
          "source_ip":{
             "score":0,
             "is_quarantined":false,
             "address":"2.137.249.73",
             "blacklist":[]
          }
       },
       "type":"baddomain"
    }
    

    Get all information from a "bad" domain

    $ curl -H "Accept: application/json" -H "X-Auth-Token: UUID" -X GET "https://api.apility.net/baddomain/mailinator.com"
    

    The response can be:

    {
       "response":{
          "domain":{
             "score":-1,
             "blacklist_ns":[
    
             ],
             "mx":[
                "mail2.mailinator.com",
                "mail.mailinator.com"
             ],
             "blacklist_mx":[
    
             ],
             "blacklist":[
                "IVOLO-DED",
                "DEA"
             ],
             "ns":[
                "betty.ns.cloudflare.com.",
                "james.ns.cloudflare.com."
             ]
          },
          "score":-1,
          "ip":{
             "score":0,
             "is_quarantined":false,
             "address":"104.25.198.31",
             "blacklist":[
    
             ]
          },
          "source_ip":{
             "score":0,
             "is_quarantined":false,
             "address":"2.137.249.73",
             "blacklist":[
    
             ]
          }
       },
       "type":"baddomain"
    }
    

    This endpoint returns a full JSON structure with individual details about the score of the different domains and IP analyzed by the algorithm. The request always returns the status code 200 (HTTP OK) no matter if the domain is bad or clean.

    HTTP Request

    GET https://api.apility.net/baddomain/<DOMAIN>

    Header Parameters

    Parameter Mandatory Description
    X-Auth-Token No API Key of the owner.
    Accept Yes application/json

    QueryString Parameters

    Parameter Mandatory Description
    token No API Key of the owner.
    callback No Function to invoke when using JSONP model.
    quarantine_ip No This IP address will be added to the quarantine blacklist of the user if the domain has a negative score.
    quarantine_ttl No The TTL in seconds to store the IP address passed in 'quarantine_ip'. If not passed, default TTL is 3600.

    URL Parameters

    Parameter Description
    DOMAIN The Domain name to look up in the system.

    Response

    The status code of the response is 200 (HTTP OK) if everything was ok, but it will also return the following JSON:

    Parameter Description
    response JSON structure containing the 'Domain' object.
    type String describing the response type: baddomain

    Get all the scores of a set of domains (Bulk request)

    Get all information from a set of domain

    $ curl -H "Accept: application/json" -H "X-Auth-Token: UUID" -X GET "https://api.apility.net/baddomain_batch/google.com,moocher.io,apility.io,mailinator.com"
    

    The response can be:

    {
        "response": [
            {
                "domain": "apility.io",
                "scoring": {
                    "score": 0,
                    "source_ip": {
                        "score": 0,
                        "blacklist": [],
                        "is_quarantined": false,
                        "address": "127.0.0.1"
                    },
                    "domain": {
                        "score": 0,
                        "blacklist_ns": [],
                        "ns": [
                            "alex.ns.cloudflare.com.",
                            "pam.ns.cloudflare.com."
                        ],
                        "mx": [
                            "aspmx.l.google.com",
                            "aspmx2.googlemail.com",
                            "aspmx3.googlemail.com",
                            "alt1.aspmx.l.google.com",
                            "alt2.aspmx.l.google.com"
                        ],
                        "blacklist_mx": [],
                        "blacklist": []
                    },
                    "ip": {
                        "score": 0,
                        "blacklist": [],
                        "is_quarantined": false,
                        "address": "104.31.76.225"
                    }
                }
            },
            {
                "domain": "moocher.io",
                "scoring": {
                    "score": 0,
                    "source_ip": {
                        "score": 0,
                        "blacklist": [],
                        "is_quarantined": false,
                        "address": "127.0.0.1"
                    },
                    "domain": {
                        "score": 0,
                        "blacklist_ns": [],
                        "ns": [
                            "alex.ns.cloudflare.com.",
                            "pam.ns.cloudflare.com."
                        ],
                        "mx": [
                            "aspmx.l.google.com",
                            "alt2.aspmx.l.google.com",
                            "alt4.aspmx.l.google.com",
                            "alt1.aspmx.l.google.com",
                            "alt3.aspmx.l.google.com"
                        ],
                        "blacklist_mx": [],
                        "blacklist": []
                    },
                    "ip": {
                        "score": 0,
                        "blacklist": [],
                        "is_quarantined": false,
                        "address": "104.18.45.187"
                    }
                }
            },
            {
                "domain": "gmail.com",
                "scoring": {
                    "score": -1,
                    "source_ip": {
                        "score": 0,
                        "blacklist": [],
                        "is_quarantined": false,
                        "address": "127.0.0.1"
                    },
                    "domain": {
                        "score": -1,
                        "blacklist_ns": [],
                        "ns": [
                            "ns4.google.com.",
                            "ns1.google.com.",
                            "ns2.google.com.",
                            "ns3.google.com."
                        ],
                        "mx": [
                            "alt3.gmail-smtp-in.l.google.com",
                            "alt4.gmail-smtp-in.l.google.com",
                            "alt2.gmail-smtp-in.l.google.com",
                            "gmail-smtp-in.l.google.com",
                            "alt1.gmail-smtp-in.l.google.com"
                        ],
                        "blacklist_mx": [],
                        "blacklist": [
                            "FREEMAIL"
                        ]
                    },
                    "ip": {
                        "score": 0,
                        "blacklist": [],
                        "is_quarantined": false,
                        "address": "216.58.214.165"
                    }
                }
            },
            {
                "domain": "mailinator.com",
                "scoring": {
                    "score": -1,
                    "source_ip": {
                        "score": 0,
                        "blacklist": [],
                        "is_quarantined": false,
                        "address": "127.0.0.1"
                    },
                    "domain": {
                        "score": -1,
                        "blacklist_ns": [],
                        "ns": [
                            "betty.ns.cloudflare.com.",
                            "james.ns.cloudflare.com."
                        ],
                        "mx": [
                            "mail2.mailinator.com",
                            "mail.mailinator.com"
                        ],
                        "blacklist_mx": [],
                        "blacklist": [
                            "MARTENSON-DED",
                            "DEA",
                            "IVOLO-DED"
                        ]
                    },
                    "ip": {
                        "score": 0,
                        "blacklist": [],
                        "is_quarantined": false,
                        "address": "104.25.198.31"
                    }
                }
            }
        ]
    }
    

    A developer can save time and rate-limit restrictions if she passes a list of comma separated domains in the QueryString. She will get the scoring and full JSON structure for each domain in the response. If the domain is not well formed it will return nothing for that domain, but will perform the lookup for the rest of the valid domains:

    HTTP Request

    GET https://api.apility.net/baddomain_batch/<DOMAIN1>,<DOMAIN2>,...,<DOMAINn>

    Header Parameters

    Parameter Mandatory Description
    X-Auth-Token No API Key of the owner.
    Accept No application/json

    QueryString Parameters

    Parameter Mandatory Description
    token No API Key of the owner.
    callback No Function to invoke when using JSONP model.

    URL Parameters

    Parameter Description
    DOMAIN1,DOMAIN2,...,DOMAINn The list of Domain names to lookup in the system.

    Response

    The status code of the response is 200 (HTTP OK) if everything was ok, but it will also return the following JSON:

    Parameter Description
    response JSON structure containing a list of JSON structures with the domain name and a 'Domain' object.

    Email Check

    Email check implements an algorithm as a superset of the used for the domain analysis that assigns a score to the email based on several checks done by the system:

    By default if some of these tests success, a -1 score is added to the overall score of the email. So an overall score of -3 means the chances of being a bad email are higher than -1.

    Check if an email scores a negative or neutral score.

    Check a "clean" email

    $ curl -i -H "X-Auth-Token: UUID" -X GET "https://api.apility.net/bademail/support@apility.io"
    

    The response:

    HTTP/1.1 404 Not Found
    Server: nginx/1.10.3 (Ubuntu)
    Date: Fri, 24 Nov 2017 15:42:53 GMT
    Content-Type: text/plain; charset=utf-8
    Content-Length: 18
    Connection: keep-alive
    

    Check a "bad" email

    $ curl -i -H "X-Auth-Token: UUID" -X GET "https://api.apility.net/bademail/test@mailinator.com"
    
    HTTP/1.1 200 OK
    Server: nginx/1.10.3 (Ubuntu)
    Date: Fri, 24 Nov 2017 15:43:55 GMT
    Content-Type: application/json; charset=utf-8
    Content-Length: 809
    Connection: keep-alive
    Strict-Transport-Security: max-age=63072000; includeSubdomains
    X-Frame-Options: DENY
    X-Content-Type-Options: nosniff
    

    This endpoint returns in the HTTP status code of the response if the email has a neutral or a negative score. A negative score means that the email has been classified as 'bad' by the algorithm.

    HTTP Request

    GET https://api.apility.net/bademail/<EMAIL>

    Header Parameters

    Parameter Mandatory Description
    X-Auth-Token No API Key of the owner.

    QueryString Parameters

    Parameter Mandatory Description
    token No API Key of the owner.
    callback No Function to invoke when using JSONP model.
    quarantine_ip No This IP address will be added to the quarantine blacklist of the user if the domain has a negative score.
    quarantine_ttl No The TTL in seconds to store the IP address passed in 'quarantine_ip'. If not passed, default TTL is 3600.

    URL Parameters

    Parameter Description
    EMAIL The Email name to look up in the system.

    Response

    The response can be a 200 or 404 HTTP code if everything is ok:

    Get individual scores of an email

    Get all information from a "clean" email

    $ curl -H "Accept: application/json" -H "X-Auth-Token: UUID" -X GET "https://api.apility.net/bademail/ceo@apility.io"
    

    The response can be:

    {
       "response":{
          "score":0,
          "address":{
             "score":0,
             "is_role":false,
             "is_well_formed":true
          },
          "ip":{
             "score":0,
             "is_quarantined":false,
             "address":"52.218.49.2",
             "blacklist":[
    
             ]
          },
          "smtp":{
             "exist_mx":true,
             "score":0,
             "exist_address":false,
             "exist_catchall":false
          },
          "freemail":{
             "score":0,
             "is_freemail":false
          },
          "domain":{
             "score":0,
             "blacklist_ns":[
    
             ],
             "mx":[
                "aspmx.l.google.com",
                "aspmx2.googlemail.com",
                "aspmx3.googlemail.com",
                "alt1.aspmx.l.google.com",
                "alt2.aspmx.l.google.com"
             ],
             "blacklist_mx":[
    
             ],
             "blacklist":[
    
             ],
             "ns":[
                "ns-1395.awsdns-46.org.",
                "ns-1635.awsdns-12.co.uk.",
                "ns-213.awsdns-26.com.",
                "ns-614.awsdns-12.net."
             ]
          },
          "email":{
             "score":0,
             "blacklist":[
    
             ]
          },
          "source_ip":{
             "score":0,
             "is_quarantined":false,
             "address":"2.137.249.73",
             "blacklist":[
    
             ]
          },
          "disposable":{
             "score":0,
             "is_disposable":false
          }
       },
       "type":"bademail"
    }
    

    Get all information from a "bad" email

    $ curl -H "Accept: application/json" -H "X-Auth-Token: UUID" -X GET "https://api.apility.net/bademail/test@mailinator.com"
    

    The response can be:

    {
       "response":{
          "score":-3,
          "address":{
             "score":0,
             "is_role":false,
             "is_well_formed":true
          },
          "ip":{
             "score":0,
             "is_quarantined":false,
             "address":"104.25.199.31",
             "blacklist":[
    
             ]
          },
          "smtp":{
             "exist_mx":true,
             "score":0,
             "exist_address":false,
             "exist_catchall":false
          },
          "freemail":{
             "score":0,
             "is_freemail":false
          },
          "domain":{
             "score":-1,
             "blacklist_ns":[
    
             ],
             "mx":[
                "mail2.mailinator.com",
                "mail.mailinator.com"
             ],
             "blacklist_mx":[
    
             ],
             "blacklist":[
                "IVOLO-DED",
                "DEA"
             ],
             "ns":[
                "betty.ns.cloudflare.com.",
                "james.ns.cloudflare.com."
             ]
          },
          "email":{
             "score":-1,
             "blacklist":[
                "STOPFORUMSPAM-90",
                "STOPFORUMSPAM-180",
                "STOPFORUMSPAM-365"
             ]
          },
          "source_ip":{
             "score":0,
             "is_quarantined":false,
             "address":"2.137.249.73",
             "blacklist":[
    
             ]
          },
          "disposable":{
             "score":-1,
             "is_disposable":true
          }
       },
       "type":"bademail"
    }
    

    This endpoint returns a full JSON structure with individual details about the score of the different domains, IP, SMTP and other parameters analyzed by the algorithm. The request always returns the status code 200 (HTTP OK) no matter if the domain is bad or clean.

    HTTP Request

    GET https://api.apility.net/bademail/<EMAIL>

    Header Parameters

    Parameter Mandatory Description
    X-Auth-Token No API Key of the owner.
    Accept Yes application/json

    QueryString Parameters

    Parameter Mandatory Description
    token No API Key of the owner.
    callback No Function to invoke when using JSONP model.
    quarantine_ip No This IP address will be added to the quarantine blacklist of the user if the domain has a negative score.
    quarantine_ttl No The TTL in seconds to store the IP address passed in 'quarantine_ip'. If not passed, default TTL is 3600.

    URL Parameters

    Parameter Description
    EMAIL The Email name to look up in the system.

    Response

    The status code of the response is 200 (HTTP OK) if everything was ok, but it will also return the following JSON:

    Parameter Description
    response JSON structure containing the 'Email' object.
    type String describing the response type: baddomain

    Get all the scores of a set of emails (Bulk requests)

    Get all information from a set of emails

    $ curl -H "Accept: application/json" -H "X-Auth-Token: UUID" -X GET "https://api.apility.net/bademail_batch/test@moocher.io,test@apility.io,test@mailinator.com"
    

    The response can be:

    {
        "response": [
            {
                "email": "test@moocher.io",
                "scoring": {
                    "score": 0,
                    "smtp": {
                        "score": 0,
                        "exist_address": false,
                        "exist_mx": true,
                        "exist_catchall": false
                    },
                    "domain": {
                        "score": 0,
                        "blacklist_ns": [],
                        "ns": [
                            "alex.ns.cloudflare.com.",
                            "pam.ns.cloudflare.com."
                        ],
                        "mx": [
                            "aspmx.l.google.com",
                            "alt2.aspmx.l.google.com",
                            "alt4.aspmx.l.google.com",
                            "alt1.aspmx.l.google.com",
                            "alt3.aspmx.l.google.com"
                        ],
                        "blacklist_mx": [],
                        "blacklist": []
                    },
                    "freemail": {
                        "score": 0,
                        "is_freemail": false
                    },
                    "ip": {
                        "score": 0,
                        "address": "104.18.44.187",
                        "is_quarantined": false,
                        "blacklist": []
                    },
                    "source_ip": {
                        "score": 0,
                        "address": "127.0.0.1",
                        "is_quarantined": false,
                        "blacklist": []
                    },
                    "disposable": {
                        "score": 0,
                        "is_disposable": false
                    },
                    "email": {
                        "score": 0,
                        "blacklist": []
                    },
                    "address": {
                        "score": 0,
                        "is_role": false,
                        "is_well_formed": true
                    }
                }
            },
            {
                "email": "test@apility.io",
                "scoring": {
                    "score": 0,
                    "smtp": {
                        "score": 0,
                        "exist_address": false,
                        "exist_mx": true,
                        "exist_catchall": false
                    },
                    "domain": {
                        "score": 0,
                        "blacklist_ns": [],
                        "ns": [
                            "alex.ns.cloudflare.com.",
                            "pam.ns.cloudflare.com."
                        ],
                        "mx": [
                            "aspmx.l.google.com",
                            "aspmx2.googlemail.com",
                            "aspmx3.googlemail.com",
                            "alt1.aspmx.l.google.com",
                            "alt2.aspmx.l.google.com"
                        ],
                        "blacklist_mx": [],
                        "blacklist": []
                    },
                    "freemail": {
                        "score": 0,
                        "is_freemail": false
                    },
                    "ip": {
                        "score": 0,
                        "address": "104.31.77.225",
                        "is_quarantined": false,
                        "blacklist": []
                    },
                    "source_ip": {
                        "score": 0,
                        "address": "127.0.0.1",
                        "is_quarantined": false,
                        "blacklist": []
                    },
                    "disposable": {
                        "score": 0,
                        "is_disposable": false
                    },
                    "email": {
                        "score": 0,
                        "blacklist": []
                    },
                    "address": {
                        "score": 0,
                        "is_role": false,
                        "is_well_formed": true
                    }
                }
            },
            {
                "email": "test@mailinator.com",
                "scoring": {
                    "score": -2,
                    "smtp": {
                        "score": 1,
                        "exist_address": true,
                        "exist_mx": true,
                        "exist_catchall": false
                    },
                    "domain": {
                        "score": -1,
                        "blacklist_ns": [],
                        "ns": [
                            "betty.ns.cloudflare.com.",
                            "james.ns.cloudflare.com."
                        ],
                        "mx": [
                            "mail2.mailinator.com",
                            "mail.mailinator.com"
                        ],
                        "blacklist_mx": [],
                        "blacklist": [
                            "MARTENSON-DED",
                            "DEA",
                            "IVOLO-DED"
                        ]
                    },
                    "freemail": {
                        "score": 0,
                        "is_freemail": false
                    },
                    "ip": {
                        "score": 0,
                        "address": "104.25.198.31",
                        "is_quarantined": false,
                        "blacklist": []
                    },
                    "source_ip": {
                        "score": 0,
                        "address": "127.0.0.1",
                        "is_quarantined": false,
                        "blacklist": []
                    },
                    "disposable": {
                        "score": -1,
                        "is_disposable": true
                    },
                    "email": {
                        "score": -1,
                        "blacklist": [
                            "STOPFORUMSPAM-365",
                            "STOPFORUMSPAM-180"
                        ]
                    },
                    "address": {
                        "score": 0,
                        "is_role": false,
                        "is_well_formed": true
                    }
                }
            }
        ]
    }
    

    A developer can save time and rate-limit restrictions if she passes a list of comma separated Emails in the QueryString. She will get the scoring and full JSON structure for each Email in the response. If the Email is not well formed it will return nothing for that email, but will perform the lookup for the rest of the valid emails:

    HTTP Request

    GET https://api.apility.net/bademail_batch/<EMAIL1>,<EMAIL2>,...,<EMAILn>

    Header Parameters

    Parameter Mandatory Description
    X-Auth-Token No API Key of the owner.
    Accept No application/json

    QueryString Parameters

    Parameter Mandatory Description
    token No API Key of the owner.
    callback No Function to invoke when using JSONP model.

    URL Parameters

    Parameter Description
    EMAIL1,EMAIL2,...,EMAILn The list of Emails to lookup in the system.

    Response

    The status code of the response is 200 (HTTP OK) if everything was ok, but it will also return the following JSON:

    Parameter Description
    response JSON structure containing a list of JSON structures with the email address and the 'Email' object.

    Geo IP look up

    The Geo IP service cannot be classified as blacklists as the lists above, but are really helpful to analyze an IP and create a profile of your users. Just like blacklists they can be accessed with our simple API and they are rate limited the same way. So if you get 429 error (Too many requests) please consider upgrading to a paid plan.

    This service returns the geo location of any IP with relevant information like:

    This API request will always return a JSON structure with the information and a 200 HTTP code if the IP can be found in the database. If not, then it will return a 404 HTTP code as usual.

    Get IP geo location.

    Get the geo location data of an IP:

    $ curl -H "X-Auth-Token: UUID" -X GET "https://api.apility.net/geoip/9.9.9.9"
    

    The response can be:

    {
        "ip": {
            "time_zone": "Europe/Paris",
            "city": "",
            "continent_geoname_id": 6255148,
            "region": "",
            "accuracy_radius": 1000,
            "latitude": 48.8582,
            "region_geoname_id": -1,
            "region_names": {},
            "postal": "",
            "longitude": 2.3387000000000002,
            "as": {
                "networks": [
                    "9.9.9.0/24",
                    "149.112.112.0/24",
                    "149.112.149.0/24"
                ],
                "name": "QUAD9-AS-1 - Quad9",
                "asn": "19281",
                "country": "US"
            },
            "address": "9.9.9.9",
            "continent": "EU",
            "country_names": {
                "en": "France",
                "pt-BR": "França",
                "fr": "France",
                "ja": "フランス共和国",
                "de": "Frankreich",
                "zh-CN": "法国",
                "es": "Francia",
                "ru": "Франция"
            },
            "city_names": {},
            "hostname": "",
            "country_geoname_id": 3017382,
            "country": "FR",
            "continent_names": {
                "en": "Europe",
                "pt-BR": "Europa",
                "fr": "Europe",
                "ja": "ヨーロッパ",
                "de": "Europa",
                "zh-CN": "欧洲",
                "es": "Europa",
                "ru": "Европа"
            },
            "city_geoname_id": -1
        }
    }
    

    This endpoint returns a JSON structure with individual details about the geographical location of the IP, and information about the Autonomous System and its networks. The request always returns the status code 200 (HTTP OK) if the IP exists. If the IP is malformed it will return a 400 (HTTP Bad Request) code.

    HTTP Request

    GET https://api.apility.net/geoip/<IP>

    Header Parameters

    Parameter Mandatory Description
    X-Auth-Token No API Key of the owner.
    Accept Yes application/json

    QueryString Parameters

    Parameter Mandatory Description
    token No API Key of the owner.
    callback No Function to invoke when using JSONP model.

    URL Parameters

    Parameter Description
    IP The IP to geo locate in the system.

    Response

    The status code of the response is 200 (HTTP OK) if everything was ok, but it will also return the following JSON:

    Parameter Description
    ip JSON structure containing the 'geoip' object.

    Get geo location of a set of IP (Bulk Request).

    Get the geo location data of a set of IP:

    $ curl -H "X-Auth-Token: UUID" -X GET "https://api.apility.net/geoip_batch212.231.122.12,8.8.8.8,9.9.9.9"
    

    The response can be:

    {
        "response": [
            {
                "ip": "8.8.8.8",
                "geoip": {
                    "time_zone": "",
                    "city": "",
                    "continent_geoname_id": 6255149,
                    "region": "",
                    "accuracy_radius": 1000,
                    "latitude": 37.751,
                    "region_geoname_id": -1,
                    "region_names": {},
                    "postal": "",
                    "longitude": -97.822,
                    "as": {
                        "networks": [
                            "8.8.4.0/24",
                            "8.8.8.0/24",
                            ...
                            "216.252.222.0/24"
                        ],
                        "ip": "8.8.8.8",
                        "name": "GOOGLE - Google LLC",
                        "asn": "15169",
                        "country": "US"
                    },
                    "address": "8.8.8.8",
                    "continent": "NA",
                    "country_names": {
                        "en": "United States",
                        "pt-BR": "Estados Unidos",
                        "fr": "États-Unis",
                        "ja": "アメリカ合衆国",
                        "de": "USA",
                        "zh-CN": "美国",
                        "es": "Estados Unidos",
                        "ru": "США"
                    },
                    "city_names": {},
                    "hostname": "",
                    "country_geoname_id": 6252001,
                    "country": "US",
                    "continent_names": {
                        "en": "North America",
                        "pt-BR": "América do Norte",
                        "fr": "Amérique du Nord",
                        "ja": "北アメリカ",
                        "de": "Nordamerika",
                        "zh-CN": "北美洲",
                        "es": "Norteamérica",
                        "ru": "Северная Америка"
                    },
                    "city_geoname_id": -1
                }
            },
            {
                "ip": "212.231.122.12",
                "geoip": {
                    "time_zone": "",
                    "city": "",
                    "continent_geoname_id": 6255148,
                    "region": "",
                    "accuracy_radius": 500,
                    "latitude": 40.4172,
                    "region_geoname_id": -1,
                    "region_names": {},
                    "postal": "",
                    "longitude": -3.684,
                    "as": {
                        "networks": [
                            "31.222.80.0/20",
                            "46.6.0.0/18",
                            ...
                            "213.195.96.0/19"
                        ],
                        "ip": "212.231.122.12",
                        "name": "AS15704",
                        "asn": "15704",
                        "country": "ES"
                    },
                    "address": "212.231.122.12",
                    "continent": "EU",
                    "country_names": {
                        "en": "Spain",
                        "pt-BR": "Espanha",
                        "fr": "Espagne",
                        "ja": "スペイン",
                        "de": "Spanien",
                        "zh-CN": "西班牙",
                        "es": "España",
                        "ru": "Испания"
                    },
                    "city_names": {},
                    "hostname": "",
                    "country_geoname_id": 2510769,
                    "country": "ES",
                    "continent_names": {
                        "en": "Europe",
                        "pt-BR": "Europa",
                        "fr": "Europe",
                        "ja": "ヨーロッパ",
                        "de": "Europa",
                        "zh-CN": "欧洲",
                        "es": "Europa",
                        "ru": "Европа"
                    },
                    "city_geoname_id": -1
                }
            },
            {
                "ip": "9.9.9.9",
                "geoip": {
                    "time_zone": "Europe/Paris",
                    "city": "",
                    "continent_geoname_id": 6255148,
                    "region": "",
                    "accuracy_radius": 1000,
                    "latitude": 48.8582,
                    "region_geoname_id": -1,
                    "region_names": {},
                    "postal": "",
                    "longitude": 2.3387000000000002,
                    "as": {
                        "networks": [
                            "9.9.9.0/24",
                            "149.112.112.0/24",
                            "149.112.149.0/24"
                        ],
                        "ip": "9.9.9.9",
                        "name": "QUAD9-AS-1 - Quad9",
                        "asn": "19281",
                        "country": "US"
                    },
                    "address": "9.9.9.9",
                    "continent": "EU",
                    "country_names": {
                        "en": "France",
                        "pt-BR": "França",
                        "fr": "France",
                        "ja": "フランス共和国",
                        "de": "Frankreich",
                        "zh-CN": "法国",
                        "es": "Francia",
                        "ru": "Франция"
                    },
                    "city_names": {},
                    "hostname": "",
                    "country_geoname_id": 3017382,
                    "country": "FR",
                    "continent_names": {
                        "en": "Europe",
                        "pt-BR": "Europa",
                        "fr": "Europe",
                        "ja": "ヨーロッパ",
                        "de": "Europa",
                        "zh-CN": "欧洲",
                        "es": "Europa",
                        "ru": "Европа"
                    },
                    "city_geoname_id": -1
                }
            }
        ]
    }
    

    A developer can save time and rate-limit restrictions if she passes a list of comma separated IP in the QueryString. She will get the information inside a JSON structure for each IP in the response. If the IP is not well formed it will return nothing for that IP, but will perform the lookup for the rest of the valid IP addresses:

    HTTP Request

    GET https://api.apility.net/geoip_batch/<IP1>,<IP2>,...,<IPn>

    Header Parameters

    Parameter Mandatory Description
    X-Auth-Token No API Key of the owner.
    Accept No application/json

    QueryString Parameters

    Parameter Mandatory Description
    token No API Key of the owner.
    callback No Function to invoke when using JSONP model.

    URL Parameters

    Parameter Description
    IP1,IP2,...,IPn The list of IP to geo locate in the system.

    Response

    The status code of the response is 200 (HTTP OK) if everything was ok, but it will also return the following JSON:

    Parameter Description
    response JSON structure containing a JSON structure with the IP to geo locate and its 'geoip' object.

    Autonomous System look up

    The Autonomous System look up services cannot be classified as blacklists too, but are really helpful to deep analyze an IP and create a profile of your users. Just like blacklists they can be accessed with our simple API and they are rate limited the same way. So if you get 429 error (Too many requests) please consider upgrading to a paid plan.

    This service returns the Autonomous System information of an IP or ASN:

    This API request will always return a JSON structure with the information and a 200 HTTP code if the IP or AS number can be found in the system. If not, then it will return a 404 HTTP code as usual.

    Get the AS information from an IP.

    Get the AS data of an IP:

    $ curl -H "X-Auth-Token: UUID" -X GET "https://api.apility.net/as/ip/9.9.9.9"
    

    The response can be:

    {
       "as":{
          "networks":"['9.9.9.0/24', '149.112.112.0/24', '149.112.149.0/24']",
          "asn":"19281",
          "name":"QUAD9-AS-1 - Quad9",
          "country":"US"
       }
    }
    

    This endpoint returns a JSON structure with details about the Autonomous System that owns the IP, and information about its networks. The request always returns the status code 200 (HTTP OK) if the IP exists. If the IP is malformed it will return a 400 (HTTP Bad Request) code.

    HTTP Request

    GET https://api.apility.net/as/ip/<IP>

    Header Parameters

    Parameter Mandatory Description
    X-Auth-Token No API Key of the owner.
    Accept Yes application/json

    QueryString Parameters

    Parameter Mandatory Description
    token No API Key of the owner.
    callback No Function to invoke when using JSONP model.

    URL Parameters

    Parameter Description
    IP The IP to look up the AS in the system.

    Response

    The status code of the response is 200 (HTTP OK) if everything was ok, but it will also return the following JSON:

    Parameter Description
    as JSON structure containing the ''as'' object.

    Get the AS information from a set of IP (Bulk Request).

    Get the AS data of a set of IP addresses:

    $ curl -H "X-Auth-Token: UUID" -X GET "https://api.apility.net/as_batch/ip/212.231.122.12,8.8.8.8,9.9.9.9"
    

    The response can be:

    {
        "response": [
            {
                "as": {
                    "country": "ES",
                    "asn": "15704",
                    "networks": [
                        "31.222.80.0/20",
                        "46.6.0.0/18",
                        ...
                        "213.195.96.0/19"
                    ],
                    "name": "AS15704"
                },
                "ip": "212.231.122.12"
            },
            {
                "as": {
                    "country": "US",
                    "asn": "15169",
                    "networks": [
                        "8.8.4.0/24",
                        "8.8.8.0/24",
                        ...
                        "216.252.222.0/24"
                    ],
                    "name": "GOOGLE - Google LLC"
                },
                "ip": "8.8.8.8"
            },
            {
                "as": {
                    "networks": [
                        "9.9.9.0/24",
                        "149.112.112.0/24",
                        "149.112.149.0/24"
                    ],
                    "asn": "19281",
                    "country": "US",
                    "name": "QUAD9-AS-1 - Quad9"
                },
                "ip": "9.9.9.9"
            }
        ]
    }
    

    A developer can save time and rate-limit restrictions if she passes a list of comma separated IP in the QueryString. She will get the information inside a JSON structure for each IP in the response. If the IP is not well formed it will return nothing for that IP, but will perform the lookup for the rest of the valid IP addresses:

    HTTP Request

    GET https://api.apility.net/as_batch/ip/<IP1>,<IP2>,...,<IPn>

    Header Parameters

    Parameter Mandatory Description
    X-Auth-Token No API Key of the owner.
    Accept No application/json

    QueryString Parameters

    Parameter Mandatory Description
    token No API Key of the owner.
    callback No Function to invoke when using JSONP model.

    URL Parameters

    Parameter Description
    IP1,IP2,...,IPn The list of IP addresses to lookup the AS in the system.

    Response

    The status code of the response is 200 (HTTP OK) if everything was ok, but it will also return the following JSON:

    Parameter Description
    response JSON structure containing a JSON structure with the IP adddress and its ''as'' object.

    Get the AS information from its number.

    Get the AS data from its number:

    $ curl -H "X-Auth-Token: UUID" -X GET "https://api.apility.net/as/num/19281"
    

    The response can be:

    {
       "as":{
          "networks":"['9.9.9.0/24', '149.112.112.0/24', '149.112.149.0/24']",
          "asn":"19281",
          "name":"QUAD9-AS-1 - Quad9",
          "country":"US"
       }
    }
    

    This endpoint returns a JSON structure with details about the Autonomous System with the number, and information about its networks. The request always returns the status code 200 (HTTP OK) if the IP exists. If the IP is malformed it will return a 400 (HTTP Bad Request) code.

    HTTP Request

    GET https://api.apility.net/as/num/<NUMBER>

    Header Parameters

    Parameter Mandatory Description
    X-Auth-Token No API Key of the owner.
    Accept Yes application/json

    QueryString Parameters

    Parameter Mandatory Description
    token No API Key of the owner.
    callback No Function to invoke when using JSONP model.

    URL Parameters

    Parameter Description
    NUMBER The Number of the AS to look up in the system.

    Response

    The status code of the response is 200 (HTTP OK) if everything was ok, but it will also return the following JSON:

    Parameter Description
    as JSON structure containing the 'as' object.

    Get the AS information from a set of AS numbers (Bulk Request).

    Get the AS data from a set of AS numbers:

    $ curl -H "X-Auth-Token: UUID" -X GET "https://api.apility.net/as_batch/num/15704,3352,15169"
    

    The response can be:

    {
        "response": [
            {
                "asn": "15704",
                "as": {
                    "country": "ES",
                    "asn": "15704",
                    "networks": [
                        "31.222.80.0/20",
                        "46.6.0.0/18",
                        ...
                        "213.195.96.0/19"
                    ],
                    "name": "AS15704"
                }
            },
            {
                "asn": "3352",
                "as": {
                    "country": "ES",
                    "asn": "3352",
                    "networks": [
                        "2.136.0.0/16",
                        "2.137.0.0/16",
                        ...
                        "217.127.0.0/16"
                    ],
                    "name": "TELEFONICA_DE_ESPANA"
                }
            },
            {
                "asn": "15169",
                "as": {
                    "country": "US",
                    "asn": "15169",
                    "networks": [
                        "8.8.4.0/24",
                        "8.8.8.0/24",
                        ...
                        "216.252.222.0/24"
                    ],
                    "name": "GOOGLE - Google LLC"
                }
            }
        ]
    }
    

    A developer can save time and rate-limit restrictions if she passes a list of comma separated AS numbers in the QueryString. She will get the information inside a JSON structure for each AS number in the response. If the AS Number is not a correct number or the AS does not exist it will return nothing for it, but will perform the lookup for the rest of the valid AS numbers:

    HTTP Request

    GET https://api.apility.net/as_batch/num/<NUM1>,<NUM2>,...,<NUMn>

    Header Parameters

    Parameter Mandatory Description
    X-Auth-Token No API Key of the owner.
    Accept No application/json

    QueryString Parameters

    Parameter Mandatory Description
    token No API Key of the owner.
    callback No Function to invoke when using JSONP model.

    URL Parameters

    Parameter Description
    NUMBER The Number of the AS to look up in the system.

    Response

    The status code of the response is 200 (HTTP OK) if everything was ok, but it will also return the following JSON:

    Parameter Description
    response JSON structure containing a list of JSON structures with the AS number and its 'as' object.

    Quarantined Objects

    Apility.io adds every few weeks new lists from multiple sources with the intention of helping our users to keep away those who want to abuse the services of our clients. However, it may be the case that our customers want to create their own blacklists based on individual parameters or business logic. This is why a new capability has been implemented to create private exclusion lists based on user IP properties. The properties we can control are the following:

    For each type of object it's possible to perform four different actions:

    As part of the attributes of the object, the Time To Live of the object in the black list is the most important. The TTL or Time to Live is the number of seconds the object will be in the black list before expiring and disappearing. Hence, it's possible to temporaly ban an IP address or set of IP addreses based on some attributes: for example ban the IP address coming from a toxic Autonomous System. Due to this time-based ban this kind of blacklists are referred as QUARANTINED objects.

    Finally, to check if the IP belongs to any of these lists it's as simple as using the IP Check services of the API. If the IP matches some of the attributes, then the QUARANTINED blacklist will be shown just like the rest of the public blacklist.

    Add an IP to the private QUARANTINE-IP blacklist

    $ curl -i -H "X-Auth-Token: UUID" -X POST -d'{"ip":<IP>,"ttl":<TTL>}' "https://api.apility.net/quarantine/ip"
    

    If the operation can be performed then the result is:

    HTTP/2 200
    server: nginx/1.10.3 (Ubuntu)
    date: Mon, 29 Jan 2018 17:01:31 GMT
    content-type: text/plain; charset=utf-8
    content-length: 7
    strict-transport-security: max-age=63072000; includeSubdomains
    x-frame-options: DENY
    x-content-type-options: nosniff
    
    200: OK
    

    This endpoint add the IP address passed as argument in the body to the QUARANTINE-IP private blacklist. The TTL must be passed too and it permits two options:

    HTTP Request

    POST https://api.apility.net/quarantine/ip

    Header Parameters

    Parameter Mandatory Description
    X-Auth-Token No API Key of the owner. You can choose to pass the API Key in the header or in the Query String.

    QueryString Parameters

    Parameter Mandatory Description
    token No API Key of the owner. You can choose to pass the API Key in the header or in the Query String.
    callback Yes Function to invoke when using JSONP model.

    JSON body

    The body must have a valid JSON object composed of two parameters

    Parameter Mandatory Description
    ip Yes IP address to add to QUARANTINE-IP blacklist.
    ttl Yes Time to Live in seconds of the IP in the blacklist. Zero for never expiring.

    Response

    The response should be a HTTP/1.1 200 OK if everything is ok and means that the IP has been added succesfully to the QUARANTINE-IP blacklist. Any other error message means that the IP could not be added:

    Add the Country of an IP address to the private QUARANTINE-COUNTRY blacklist

    $ curl -i -H "X-Auth-Token: UUID" -X POST -d'{"country":<COUNTRY_CODE>,"ttl":<TTL>}' "https://api.apility.net/quarantine/country"
    

    If the operation can be performed then the result is:

    HTTP/2 200
    server: nginx/1.10.3 (Ubuntu)
    date: Mon, 29 Jan 2018 17:01:31 GMT
    content-type: text/plain; charset=utf-8
    content-length: 7
    strict-transport-security: max-age=63072000; includeSubdomains
    x-frame-options: DENY
    x-content-type-options: nosniff
    
    200: OK
    

    This endpoint add the country passed as argument in the body to the QUARANTINE-COUNTRY private blacklist. The TTL must be passed too and it permits two options:

    The service will automatically obtain the country of the IP using the Geo location service. If the country is in the QUARANTINE-COUNTRY blacklist, it will be reported in the IP Check services.

    HTTP Request

    POST https://api.apility.net/quarantine/country

    Header Parameters

    Parameter Mandatory Description
    X-Auth-Token No API Key of the owner. You can choose to pass the API Key in the header or in the Query String.

    QueryString Parameters

    Parameter Mandatory Description
    token No API Key of the owner. You can choose to pass the API Key in the header or in the Query String.
    callback Yes Function to invoke when using JSONP model.

    JSON body

    The body must have a valid JSON object composed of two parameters

    Parameter Mandatory Description
    country Yes Country ISO 3166-1 alfa-2 code to add to the QUARANTINE-COUNTRY blacklist.
    ttl Yes Time to Live in seconds of the Country in the blacklist. Zero for never expiring.

    Response

    The response should be a HTTP/1.1 200 OK if everything is ok and means that the Country has been added succesfully to the QUARANTINE-Country blacklist. Any other error message means that the Country could not be added:

    Add the Continent of an IP address to the private QUARANTINE-CONTINENT blacklist

    $ curl -i -H "X-Auth-Token: UUID" -X POST -d'{"continent":<CONTINENT_CODE>,"ttl":<TTL>}' "https://api.apility.net/quarantine/continent"
    

    If the operation can be performed then the result is:

    HTTP/2 200
    server: nginx/1.10.3 (Ubuntu)
    date: Mon, 29 Jan 2018 17:01:31 GMT
    content-type: text/plain; charset=utf-8
    content-length: 7
    strict-transport-security: max-age=63072000; includeSubdomains
    x-frame-options: DENY
    x-content-type-options: nosniff
    
    200: OK
    

    This endpoint add the continent passed as argument in the body to the QUARANTINE-CONTINENT private blacklist. The TTL must be passed too and it permits two options:

    The service will automatically obtain the continent of the IP using the Geo location service. If the continent is in the QUARANTINE-CONTINENT blacklist, it will be reported in the IP Check services.

    HTTP Request

    POST https://api.apility.net/quarantine/continent

    Header Parameters

    Parameter Mandatory Description
    X-Auth-Token No API Key of the owner. You can choose to pass the API Key in the header or in the Query String.

    QueryString Parameters

    Parameter Mandatory Description
    token No API Key of the owner. You can choose to pass the API Key in the header or in the Query String.
    callback Yes Function to invoke when using JSONP model.

    JSON body

    The body must have a valid JSON object composed of two parameters

    Parameter Mandatory Description
    continent Yes Continent codes to add to the QUARANTINE-CONTINENT blacklist.
    ttl Yes Time to Live in seconds of the Continent in the blacklist. Zero for never expiring.

    Response

    The response should be a HTTP/1.1 200 OK if everything is ok and means that the Continent has been added succesfully to the QUARANTINE-CONTINENT blacklist. Any other error message means that the Continent could not be added:

    Add the Autonomous System (AS) that owns the IP address to the private QUARANTINE-AS blacklist

    $ curl -i -H "X-Auth-Token: UUID" -X POST -d'{"asn":<AS_NUMBER>,"ttl":<TTL>}' "https://api.apility.net/quarantine/as"
    

    If the operation can be performed then the result is:

    HTTP/2 200
    server: nginx/1.10.3 (Ubuntu)
    date: Mon, 29 Jan 2018 17:01:31 GMT
    content-type: text/plain; charset=utf-8
    content-length: 7
    strict-transport-security: max-age=63072000; includeSubdomains
    x-frame-options: DENY
    x-content-type-options: nosniff
    
    200: OK
    

    This endpoint adds the Autonomous System Number passed as argument in the body to the QUARANTINE-AS private blacklist. The TTL must be passed too and it permits two options:

    The service will automatically obtain the AS number of the IP using the AS resolution service. If the AS is in the QUARANTINE-AS blacklist, it will be reported in the IP Check services.

    HTTP Request

    POST https://api.apility.net/quarantine/as

    Header Parameters

    Parameter Mandatory Description
    X-Auth-Token No API Key of the owner. You can choose to pass the API Key in the header or in the Query String.

    QueryString Parameters

    Parameter Mandatory Description
    token No API Key of the owner. You can choose to pass the API Key in the header or in the Query String.
    callback Yes Function to invoke when using JSONP model.

    JSON body

    The body must have a valid JSON object composed of two parameters

    Parameter Mandatory Description
    asn Yes Autonomous System Number (ASN) to add to the QUARANTINE-AS blacklist.
    ttl Yes Time to Live in seconds of the AS in the blacklist. Zero for never expiring.

    Response

    The response should be a HTTP/1.1 200 OK if everything is ok and means that the AS has been added succesfully to the QUARANTINE-AS blacklist. Any other error message means that the AS could not be added:

    Check if the IP is in the private QUARANTINE-IP blacklist

    $ curl -i -H "X-Auth-Token: UUID" -X GET "https://api.apility.net/quarantine/ip/<IP>"
    

    If the IP is in the list:

    HTTP/2 200
    server: nginx/1.10.3 (Ubuntu)
    date: Mon, 29 Jan 2018 17:19:39 GMT
    content-type: text/plain; charset=utf-8
    content-length: 7
    strict-transport-security: max-age=63072000; includeSubdomains
    x-frame-options: DENY
    x-content-type-options: nosniff
    
    

    If the IP is NOT the list:

    HTTP/2 404
    server: nginx/1.10.3 (Ubuntu)
    date: Mon, 29 Jan 2018 17:20:26 GMT
    content-type: text/plain; charset=utf-8
    content-length: 14
    
    

    This endpoint check if the IP address passed as argument in the query string is in the QUARANTINE-IP private blacklist. If exists, it returns a HTTP 200 OK, and if not, a HTTP 404 Not Found error. If you want to perform a full test on the IP address including public blacklists you should better use the IP Check API services.

    HTTP Request

    GET https://api.apility.net/quarantine/ip/<IP>

    Header Parameters

    Parameter Mandatory Description
    X-Auth-Token No API Key of the owner. You can choose to pass the API Key in the header or in the Query String.

    QueryString Parameters

    Parameter Mandatory Description
    token No API Key of the owner. You can choose to pass the API Key in the header or in the Query String.
    callback Yes Function to invoke when using JSONP model.
    IP Yes IP address to check if it is in the QUARANTINE-IP

    Response

    The response should be a HTTP/1.1 200 OK if everything is ok and means that the IP is in the QUARANTINE-IP blacklist. A HTTP/1.1 404 Not Found means that the IP address is not in the QUARANTINE-IP blacklist. Any other error message means that the IP could not be parsed:

    Check if the Country is in the private QUARANTINE-COUNTRY blacklist

    $ curl -i -H "X-Auth-Token: UUID" -X GET "https://api.apility.net/quarantine/country/<COUNTRY_CODE>"
    

    If the Country is in the list:

    HTTP/2 200
    server: nginx/1.10.3 (Ubuntu)
    date: Mon, 29 Jan 2018 17:19:39 GMT
    content-type: text/plain; charset=utf-8
    content-length: 7
    strict-transport-security: max-age=63072000; includeSubdomains
    x-frame-options: DENY
    x-content-type-options: nosniff
    
    

    If the Country is NOT the list:

    HTTP/2 404
    server: nginx/1.10.3 (Ubuntu)
    date: Mon, 29 Jan 2018 17:20:26 GMT
    content-type: text/plain; charset=utf-8
    content-length: 14
    
    

    This endpoint checks if the Country code passed as argument in the query string is in the QUARANTINE-COUNTRY private blacklist. If exists, it returns a HTTP 200 OK, and if not, a HTTP 404 Not Found error. If you want to perform a full test on the IP address including public blacklists you should better use the IP Check API services.

    HTTP Request

    GET https://api.apility.net/quarantine/country/<COUNTRY_CODE>

    Header Parameters

    Parameter Mandatory Description
    X-Auth-Token No API Key of the owner. You can choose to pass the API Key in the header or in the Query String.

    QueryString Parameters

    Parameter Mandatory Description
    token No API Key of the owner. You can choose to pass the API Key in the header or in the Query String.
    callback Yes Function to invoke when using JSONP model.
    COUNTRY_CODE Yes Country ISO 3166-1 alfa-2 code to check if it is in the QUARANTINE-COUNTRY list.

    Response

    The response should be a HTTP/1.1 200 OK if everything is ok and means that the Country code is in the QUARANTINE-COUNTRY blacklist. A HTTP/1.1 404 Not Found means that the Conutry code is not in the QUARANTINE-COUNTRY blacklist. Any other error message means that the Country Code could not be parsed:

    Check if the Continent is in the private QUARANTINE-CONTINENT blacklist

    $ curl -i -H "X-Auth-Token: UUID" -X GET "https://api.apility.net/quarantine/continent/<CONTINENT_CODE>"
    

    If the Continent is in the list:

    HTTP/2 200
    server: nginx/1.10.3 (Ubuntu)
    date: Mon, 29 Jan 2018 17:19:39 GMT
    content-type: text/plain; charset=utf-8
    content-length: 7
    strict-transport-security: max-age=63072000; includeSubdomains
    x-frame-options: DENY
    x-content-type-options: nosniff
    
    

    If the Continent is NOT in the list:

    HTTP/2 404
    server: nginx/1.10.3 (Ubuntu)
    date: Mon, 29 Jan 2018 17:20:26 GMT
    content-type: text/plain; charset=utf-8
    content-length: 14
    
    

    This endpoint checks if the Continent code passed as argument in the query string is in the QUARANTINE-CONTINENT private blacklist. If exists, it returns a HTTP 200 OK, and if not, a HTTP 404 Not Found error. If you want to perform a full test on the IP address including public blacklists you should better use the IP Check API services.

    HTTP Request

    GET https://api.apility.net/quarantine/continent/<CONTINENT_CODE>

    Header Parameters

    Parameter Mandatory Description
    X-Auth-Token No API Key of the owner. You can choose to pass the API Key in the header or in the Query String.

    QueryString Parameters

    Parameter Mandatory Description
    token No API Key of the owner. You can choose to pass the API Key in the header or in the Query String.
    callback Yes Function to invoke when using JSONP model.
    CONTINENT_CODE Yes Continent codes to check if it is in the QUARANTINE-CONTINENT list.

    Response

    The response should be a HTTP/1.1 200 OK if everything is ok and means that the Continent code is in the QUARANTINE-CONTINENT blacklist. A HTTP/1.1 404 Not Found means that the Continent code is not in the QUARANTINE-CONTINENT blacklist. Any other error message means that the Continent Code could not be parsed:

    Check if the AS is in the private QUARANTINE-AS blacklist

    $ curl -i -H "X-Auth-Token: UUID" -X GET "https://api.apility.net/quarantine/as/<AS_NUM>"
    

    If the AS is in the list:

    HTTP/2 200
    server: nginx/1.10.3 (Ubuntu)
    date: Mon, 29 Jan 2018 17:19:39 GMT
    content-type: text/plain; charset=utf-8
    content-length: 7
    strict-transport-security: max-age=63072000; includeSubdomains
    x-frame-options: DENY
    x-content-type-options: nosniff
    
    

    If the AS is NOT in the list:

    HTTP/2 404
    server: nginx/1.10.3 (Ubuntu)
    date: Mon, 29 Jan 2018 17:20:26 GMT
    content-type: text/plain; charset=utf-8
    content-length: 14
    
    

    This endpoint checks if the AS Number passed as argument in the query string is in the QUARANTINE-AS private blacklist. If exists, it returns a HTTP 200 OK, and if not, a HTTP 404 Not Found error. If you want to perform a full test on the IP address including public blacklists you should better use the IP Check API services.

    HTTP Request

    GET https://api.apility.net/quarantine/as/<AS_NUM>

    Header Parameters

    Parameter Mandatory Description
    X-Auth-Token No API Key of the owner. You can choose to pass the API Key in the header or in the Query String.

    QueryString Parameters

    Parameter Mandatory Description
    token No API Key of the owner. You can choose to pass the API Key in the header or in the Query String.
    callback Yes Function to invoke when using JSONP model.
    AS_NUM Yes Autonmous System Number (ASN) to check if it is in the QUARANTINE-AS list.

    Response

    The response should be a HTTP/1.1 200 OK if everything is ok and means that the AS is in the QUARANTINE-AS blacklist. A HTTP/1.1 404 Not Found means that the AS is not in the QUARANTINE-AS blacklist. Any other error message means that the AS number could not be parsed:

    Get full list of IP addresses in the private QUARANTINE-IP blacklist

    $ curl -H "X-Auth-Token: UUID" -X GET "https://api.apility.net/quarantine/ip"
    

    The response will always return a JSON object, even when there is no elements in the list:

    {
       "quarantined":[
          {
             "ip":"8.8.4.4",
             "ttl":7185
          },
          {
             "ip":"9.9.9.9",
             "ttl":1717
          },
          {
             "ip":"8.8.8.8",
             "ttl":3571
          }
       ]
    }
    

    This endpoint returns the full list of the IP addresses and the corresponding TTL in the QUARANTINE-IP private blacklist as a JSON object.

    HTTP Request

    GET https://api.apility.net/quarantine/ip

    Header Parameters

    Parameter Mandatory Description
    X-Auth-Token No API Key of the owner. You can choose to pass the API Key in the header or in the Query String.

    QueryString Parameters

    Parameter Mandatory Description
    token No API Key of the owner. You can choose to pass the API Key in the header or in the Query String.
    callback Yes Function to invoke when using JSONP model.

    Response

    The response should be a HTTP/1.1 200 OK if everything is ok. Any other error should be considered a platform problem and you can report it to our suppor team.

    The JSON response is composed of:

    Parameter Description
    quarantined List containing the pair of IP addresses and TTL.

    Get full list of Country codes in the private QUARANTINE-COUNTRY blacklist

    $ curl -H "X-Auth-Token: UUID" -X GET "https://api.apility.net/quarantine/country"
    

    The response will always return a JSON object, even when there is no elements in the list:

    {
       "quarantined":[
          {
             "country":"ES",
             "ttl":7182
          },
          {
             "country":"EE",
             "ttl":7171
          },
          {
             "country":"US",
             "ttl":7195
          }
       ]
    }
    
    

    This endpoint returns the full list of the Country codes and the corresponding TTL in the QUARANTINE-COUNTRY private blacklist as a JSON object.

    HTTP Request

    GET https://api.apility.net/quarantine/country

    Header Parameters

    Parameter Mandatory Description
    X-Auth-Token No API Key of the owner. You can choose to pass the API Key in the header or in the Query String.

    QueryString Parameters

    Parameter Mandatory Description
    token No API Key of the owner. You can choose to pass the API Key in the header or in the Query String.
    callback Yes Function to invoke when using JSONP model.

    Response

    The response should be a HTTP/1.1 200 OK if everything is ok. Any other error should be considered a platform problem and you can report it to our suppor team.

    The JSON response is composed of:

    Parameter Description
    quarantined List containing the pair of Country codes and TTL.

    Get full list of Continent codes in the private QUARANTINE-CONTINENT blacklist

    $ curl -H "X-Auth-Token: UUID" -X GET "https://api.apility.net/quarantine/continent"
    

    The response will always return a JSON object, even when there is no elements in the list:

    {
       "quarantined":[
          {
             "continent":"EU",
             "ttl":7179
          },
          {
             "continent":"AS",
             "ttl":3592
          }
       ]
    }
    
    

    This endpoint returns the full list of the Continent codes and the corresponding TTL in the QUARANTINE-CONTINENT private blacklist as a JSON object.

    HTTP Request

    GET https://api.apility.net/quarantine/continent

    Header Parameters

    Parameter Mandatory Description
    X-Auth-Token No API Key of the owner. You can choose to pass the API Key in the header or in the Query String.

    QueryString Parameters

    Parameter Mandatory Description
    token No API Key of the owner. You can choose to pass the API Key in the header or in the Query String.
    callback Yes Function to invoke when using JSONP model.

    Response

    The response should be a HTTP/1.1 200 OK if everything is ok. Any other error should be considered a platform problem and you can report it to our suppor team.

    The JSON response is composed of:

    Parameter Description
    quarantined List containing the pair of Continent codes and TTL.

    Get full list of AS in the private QUARANTINE-AS blacklist

    $ curl -H "X-Auth-Token: UUID" -X GET "https://api.apility.net/quarantine/as"
    

    The response will always return a JSON object, even when there is no elements in the list:

    {
       "quarantined":[
          {
             "asn":"3352",
             "ttl":3559
          },
          {
             "asn":"15169",
             "ttl":7191
          }
       ]
    }
    

    This endpoint returns the full list of the AS Numbers and the corresponding TTL in the QUARANTINE-AS private blacklist as a JSON object.

    HTTP Request

    GET https://api.apility.net/quarantine/as

    Header Parameters

    Parameter Mandatory Description
    X-Auth-Token No API Key of the owner. You can choose to pass the API Key in the header or in the Query String.

    QueryString Parameters

    Parameter Mandatory Description
    token No API Key of the owner. You can choose to pass the API Key in the header or in the Query String.
    callback Yes Function to invoke when using JSONP model.

    Response

    The response should be a HTTP/1.1 200 OK if everything is ok. Any other error should be considered a platform problem and you can report it to our suppor team.

    The JSON response is composed of:

    Parameter Description
    quarantined List containing the pair of AS Numbers and TTL.

    Delete an IP address if it is in the private QUARANTINE-IP blacklist

    $ curl -i -H "X-Auth-Token: UUID" -X DELETE "https://api.apility.net/quarantine/ip/<IP>"
    

    The response will always be HTTP 200 OK no matter if the IP to delete exists or not:

    HTTP/2 200
    server: nginx/1.10.3 (Ubuntu)
    date: Mon, 29 Jan 2018 17:45:14 GMT
    content-type: text/plain; charset=utf-8
    content-length: 7
    strict-transport-security: max-age=63072000; includeSubdomains
    x-frame-options: DENY
    x-content-type-options: nosniff
    
    

    This endpoint delete the IP address passed as argument in the query string if it exists in the QUARANTINE-IP private blacklist. This API call will delete the IP address no matter if it will expire or not.

    HTTP Request

    DELETE https://api.apility.net/quarantine/ip/<IP>

    Header Parameters

    Parameter Mandatory Description
    X-Auth-Token No API Key of the owner. You can choose to pass the API Key in the header or in the Query String.

    QueryString Parameters

    Parameter Mandatory Description
    token No API Key of the owner. You can choose to pass the API Key in the header or in the Query String.
    callback Yes Function to invoke when using JSONP model.
    IP Yes IP address to remove from the QUARANTINE-IP blacklist

    Response

    The response should be a HTTP/1.1 200 OK if everything is ok and means that the operation was performed succesufully. Any other error should be considered a platform problem and you can report it to our suppor team.

    Delete a Country Code if it is in the private QUARANTINE-COUNTRY blacklist

    $ curl -i -H "X-Auth-Token: UUID" -X DELETE "https://api.apility.net/quarantine/country/<COUNTRY_CODE>"
    

    The response will always be HTTP 200 OK no matter if the Country code to delete exists or not:

    HTTP/2 200
    server: nginx/1.10.3 (Ubuntu)
    date: Mon, 29 Jan 2018 17:45:14 GMT
    content-type: text/plain; charset=utf-8
    content-length: 7
    strict-transport-security: max-age=63072000; includeSubdomains
    x-frame-options: DENY
    x-content-type-options: nosniff
    
    

    This endpoint delete the Country code passed as argument in the query string if it exists in the QUARANTINE-COUNTRY private blacklist. This API call will delete the Country code no matter if it will expire or not.

    HTTP Request

    DELETE https://api.apility.net/quarantine/country/<COUNTRY_CODE>

    Header Parameters

    Parameter Mandatory Description
    X-Auth-Token No API Key of the owner. You can choose to pass the API Key in the header or in the Query String.

    QueryString Parameters

    Parameter Mandatory Description
    token No API Key of the owner. You can choose to pass the API Key in the header or in the Query String.
    callback Yes Function to invoke when using JSONP model.
    COUNTRY_CODE Yes Country Code to remove from the QUARANTINE-COUNTRY blacklist

    Response

    The response should be a HTTP/1.1 200 OK if everything is ok and means that the operation was performed succesufully. Any other error should be considered a platform problem and you can report it to our suppor team.

    Delete a Continent Code if it is in the private QUARANTINE-CONTINENT blacklist

    $ curl -i -H "X-Auth-Token: UUID" -X DELETE "https://api.apility.net/quarantine/continent/<CONTINENT_CODE>"
    

    The response will always be HTTP 200 OK no matter if the Continent code to delete exists or not:

    HTTP/2 200
    server: nginx/1.10.3 (Ubuntu)
    date: Mon, 29 Jan 2018 17:45:14 GMT
    content-type: text/plain; charset=utf-8
    content-length: 7
    strict-transport-security: max-age=63072000; includeSubdomains
    x-frame-options: DENY
    x-content-type-options: nosniff
    
    

    This endpoint delete the Continent code passed as argument in the query string if it exists in the QUARANTINE-CONTINENT private blacklist. This API call will delete the Continent code no matter if it will expire or not.

    HTTP Request

    DELETE https://api.apility.net/quarantine/continent/<CONTINENT_CODE>

    Header Parameters

    Parameter Mandatory Description
    X-Auth-Token No API Key of the owner. You can choose to pass the API Key in the header or in the Query String.

    QueryString Parameters

    Parameter Mandatory Description
    token No API Key of the owner. You can choose to pass the API Key in the header or in the Query String.
    callback Yes Function to invoke when using JSONP model.
    CONTINENT_CODE Yes Continent code to remove from the QUARANTINE-CONTINENT blacklist

    Response

    The response should be a HTTP/1.1 200 OK if everything is ok and means that the operation was performed succesufully. Any other error should be considered a platform problem and you can report it to our suppor team.

    Delete an AS if it is in the private QUARANTINE-AS blacklist

    $ curl -i -H "X-Auth-Token: UUID" -X DELETE "https://api.apility.net/quarantine/AS/<AS_NUM>"
    

    The response will always be HTTP 200 OK no matter if the AS to delete exists or not:

    HTTP/2 200
    server: nginx/1.10.3 (Ubuntu)
    date: Mon, 29 Jan 2018 17:45:14 GMT
    content-type: text/plain; charset=utf-8
    content-length: 7
    strict-transport-security: max-age=63072000; includeSubdomains
    x-frame-options: DENY
    x-content-type-options: nosniff
    
    

    This endpoint delete the AS passed as argument in the query string if it exists in the QUARANTINE-AS private blacklist. This API call will delete the AS no matter if it will expire or not.

    HTTP Request

    DELETE https://api.apility.net/quarantine/as/<AS_NUM>

    Header Parameters

    Parameter Mandatory Description
    X-Auth-Token No API Key of the owner. You can choose to pass the API Key in the header or in the Query String.

    QueryString Parameters

    Parameter Mandatory Description
    token No API Key of the owner. You can choose to pass the API Key in the header or in the Query String.
    callback Yes Function to invoke when using JSONP model.
    AS_NUM Yes AS Number to remove from the QUARANTINE-AS blacklist

    Response

    The response should be a HTTP/1.1 200 OK if everything is ok and means that the operation was performed succesufully. Any other error should be considered a platform problem and you can report it to our suppor team.

    Add an IP address automatically to QUARANTINE-IP blacklist if a domain or an email has a negative score

    Check a "bad" domain and add IP address 8.8.8.8 to QUARANTINE-IP if found malicious

    $ curl -i -H "X-Auth-Token: UUID" -X GET "https://api.apility.net/baddomain/mailinator.com?quarantine_ip=8.8.8.8&quarantine_ttl=86400"
    
    HTTP/1.1 200 OK
    Server: nginx/1.10.3 (Ubuntu)
    Date: Fri, 24 Nov 2017 14:00:50 GMT
    Content-Type: text/plain; charset=utf-8
    Content-Length: 7
    Connection: keep-alive
    Strict-Transport-Security: max-age=63072000; includeSubdomains
    X-Frame-Options: DENY
    X-Content-Type-Options: nosniff
    

    Check a "bad" email and add IP address 8.8.8.8 to QUARANTINE-IP if found malicious

    $ curl -i -H "X-Auth-Token: UUID" -X GET "https://api.apility.net/bademail/test@mailinator.com?quarantine_ip=8.8.8.8&quarantine_ttl=86400"
    
    HTTP/1.1 200 OK
    Server: nginx/1.10.3 (Ubuntu)
    Date: Fri, 24 Nov 2017 14:00:50 GMT
    Content-Type: text/plain; charset=utf-8
    Content-Length: 7
    Connection: keep-alive
    Strict-Transport-Security: max-age=63072000; includeSubdomains
    X-Frame-Options: DENY
    X-Content-Type-Options: nosniff
    

    Sometimes a developer wants the IP address from which the checked domain or email was sent to be stored in the quarantine blacklist to prevent abuse from the same IP address over and over again.

    This can be done by adding the quarantine_ip and quarantine_ttl parameters to the existing API request for domain and existing API request for email. In quarantine_ip you should pass the source IP address of the request, and in quarantine_ttl you can optionally pass the Time to Live in seconds that should remain the IP address in quarantine. If this parameter is not added, the default Time to Live is 3600 seconds.

    Resource History

    Our databases contain several million active records of IP addresses, domains and emails. But this is just the tip of the iceberg because every day we process more than a million transactions on this database. A resource such as an IP address can enter and exit a blocking list on multiple occasions, which added to the fact that it can enter and exit different lists at the same time allows our users to get an idea of the magnitude of the information we handle.

    For those cybersecurity experts who wish to know the historical activity of these resources in our database, we now make available to our users complete access to the history we have available for each one.

    The resources available are:

    Because there may be a large amount of data available, it is possible to restrict queries by providing:

    Calling this API always returns items from the most recent to the oldest, so Unix time always indicates the freshsest transaction. If none of these parameters are provided, the API call will return the history from the current date with a maximum of 10 items.

    Every call made to the API will count as a new HIT in the quota of the user.

    Get IP address history

    $ curl -i -H "X-Auth-Token: UUID" -X GET "https://api.apility.net/metadata/changes/ip/<IP>?timestamp=<TIMESTAMP>&page=<PAGE>&items=<ITEMS>"
    

    No matter if the IP has information in the database, it will always return the changes_ip JSON object. If it has information in the database:

    {
        "changes_ip": [
            {
                "blacklist_change": "FAIL2BAN-ALL,FAIL2BAN-SSH",
                "blacklists": "",
                "timestamp": 1520187309162,
                "command": "rem",
                "ip": "XX.XX.XX.XX"
            },
            {
                "blacklist_change": "FAIL2BAN-ALL",
                "blacklists": "FAIL2BAN-ALL,FAIL2BAN-SSH",
                "timestamp": 1520108359925,
                "command": "add",
                "ip": "XX.XX.XX.XX"
            },
            {
                "blacklist_change": "FAIL2BAN-ALL",
                "blacklists": "FAIL2BAN-SSH",
                "timestamp": 1520104871843,
                "command": "rem",
                "ip": "XX.XX.XX.XX"
            },
            {
                "blacklist_change": "FAIL2BAN-SSH",
                "blacklists": "FAIL2BAN-ALL,FAIL2BAN-SSH",
                "timestamp": 1520072166966,
                "command": "add",
                "ip": "XX.XX.XX.XX"
            },
            {
                "blacklist_change": "FAIL2BAN-SSH",
                "blacklists": "FAIL2BAN-ALL",
                "timestamp": 1520068580059,
                "command": "rem",
                "ip": "XX.XX.XX.XX"
            },
            {
                "blacklist_change": "FAIL2BAN-SSH,FAIL2BAN-ALL",
                "blacklists": "FAIL2BAN-SSH,FAIL2BAN-ALL",
                "timestamp": 1519946120669,
                "command": "add",
                "ip": "XX.XX.XX.XX"
            },
            {
                "blacklist_change": "FAIL2BAN-SSH,FAIL2BAN-ALL",
                "blacklists": "FAIL2BAN-SSH,FAIL2BAN-ALL",
                "timestamp": 1519946118892,
                "command": "add",
                "ip": "XX.XX.XX.XX"
            },
            {
                "blacklist_change": "FAIL2BAN-SSH,FAIL2BAN-ALL",
                "blacklists": "",
                "timestamp": 1519661715742,
                "command": "rem",
                "ip": "XX.XX.XX.XX"
            },
            {
                "blacklist_change": "FAIL2BAN-SSH",
                "blacklists": "FAIL2BAN-SSH,FAIL2BAN-ALL",
                "timestamp": 1519647423138,
                "command": "add",
                "ip": "XX.XX.XX.XX"
            },
            {
                "blacklist_change": "FAIL2BAN-SSH",
                "blacklists": "FAIL2BAN-ALL",
                "timestamp": 1519643865538,
                "command": "rem",
                "ip": "XX.XX.XX.XX"
            }
        ]
    }
    

    If there is no information in the database:

    {
        "changes_ip": []
    }
    

    The changes_ip JSON object contains a list of transaction_ip objects. Each transaction IP object will return:

    HTTP Request

    GET https://api.apility.net/metadata/changes/ip/<IP>

    Header Parameters

    Parameter Mandatory Description
    X-Auth-Token No API Key of the owner. You can choose to pass the API Key in the header or in the Query String.

    QueryString Parameters

    Parameter Mandatory Description
    token No API Key of the owner. You can choose to pass the API Key in the header or in the Query String.
    timestamp No UNIX time in seconds to filter the search in the database. If ignored, then current UNIX time is taken.
    page No Page number to paginate the result. Always start at 1. If ignored, then search for page one.
    items No Number of items per page. Can be in the range of 5 to 200. If ignored, then return 10 items.
    callback Yes Function to invoke when using JSONP model.

    Response

    The response should be a HTTP/1.1 200 OK if everything is ok. Any other error message means something is wrong in the system and you should contact support.

    If everything goes fine then it will also return the following JSON object:

    Parameter Description
    changes_ip JSON object containing a list of JSON 'transaction ip' objects.

    Get Domain history

    $ curl -i -H "X-Auth-Token: UUID" -X GET "https://api.apility.net/metadata/changes/domain/<DOMAIN>?timestamp=<TIMESTAMP>&page=<PAGE>&items=<ITEMS>"
    

    No matter if the Domain has information in the database, it will always return the changes_domain JSON object. If it has information in the database:

    {
        "changes_domain": [
            {
                "blacklist_change": "LISINGE-DED",
                "blacklists": "LISINGE-DED,MARTENSON-DED,IVOLO-DED,DEA",
                "command": "add",
                "domain": "XXX.XXX.XXX",
                "timestamp": 1519836616549
            },
            {
                "blacklist_change": "MARTENSON-DED",
                "blacklists": "MARTENSON-DED,IVOLO-DED,DEA",
                "command": "add",
                "domain": "XXX.XXX.XXX",
                "timestamp": 1519708978688
            },
            {
                "blacklist_change": "IVOLO-DED",
                "blacklists": "IVOLO-DED,DEA",
                "command": "add",
                "domain": "XXX.XXX.XXX",
                "timestamp": 1519708958303
            },
            {
                "blacklist_change": "DEA",
                "blacklists": "DEA",
                "command": "add",
                "domain": "XXX.XXX.XXX",
                "timestamp": 1519707737136
            }
        ]
    }
    

    If there is no information in the database:

    {
        "changes_domain": []
    }
    

    The changes_domain JSON object contains a list of transaction_domain objects. Each transaction Domain object will return:

    HTTP Request

    GET https://api.apility.net/metadata/changes/domain/<DOMAIN>

    Header Parameters

    Parameter Mandatory Description
    X-Auth-Token No API Key of the owner. You can choose to pass the API Key in the header or in the Query String.

    QueryString Parameters

    Parameter Mandatory Description
    token No API Key of the owner. You can choose to pass the API Key in the header or in the Query String.
    timestamp No UNIX time in seconds to filter the search in the database. If ignored, then current UNIX time is taken.
    page No Page number to paginate the result. Always start at 1. If ignored, then search for page one.
    items No Number of items per page. Can be in the range of 5 to 200. If ignored, then return 10 items.
    callback Yes Function to invoke when using JSONP model.

    Response

    The response should be a HTTP/1.1 200 OK if everything is ok. Any other error message means something is wrong in the system and you should contact support.

    If everything goes fine then it will also return the following JSON object:

    Parameter Description
    changes_domain JSON object containing a list of JSON 'transaction domain' objects.

    Get Email history

    $ curl -i -H "X-Auth-Token: UUID" -X GET "https://api.apility.net/metadata/changes/email/<EMAIL>?timestamp=<TIMESTAMP>&page=<PAGE>&items=<ITEMS>"
    

    No matter if the Email has information in the database, it will always return the changes_email JSON object. If it has information in the database:

    {
        "changes_email": [
            {
                "blacklist_change": "STOPFORUMSPAM-365",
                "blacklists": "",
                "command": "rem",
                "email": "XXXXX@XXXXX.COM",
                "timestamp": 1518666525299
            },
            {
                "blacklist_change": "STOPFORUMSPAM-365",
                "blacklists": "STOPFORUMSPAM-365",
                "command": "add",
                "email": "XXXXX@XXXXX.COM",
                "timestamp": 1518461696289
            }
        ]
    }
    

    If there is no information in the database:

    {
        "changes_email": []
    }
    

    The changes_email JSON object contains a list of transaction_email objects. Each transaction Email object will return:

    HTTP Request

    GET https://api.apility.net/metadata/changes/email/<EMAIL>

    Header Parameters

    Parameter Mandatory Description
    X-Auth-Token No API Key of the owner. You can choose to pass the API Key in the header or in the Query String.

    QueryString Parameters

    Parameter Mandatory Description
    token No API Key of the owner. You can choose to pass the API Key in the header or in the Query String.
    timestamp No UNIX time in seconds to filter the search in the database. If ignored, then current UNIX time is taken.
    page No Page number to paginate the result. Always start at 1. If ignored, then search for page one.
    items No Number of items per page. Can be in the range of 5 to 200. If ignored, then return 10 items.
    callback Yes Function to invoke when using JSONP model.

    Response

    The response should be a HTTP/1.1 200 OK if everything is ok. Any other error message means something is wrong in the system and you should contact support.

    If everything goes fine then it will also return the following JSON object:

    Parameter Description
    changes_email JSON object containing a list of JSON 'transaction email' objects.

    WHOIS query

    WHOIS is a query and response protocol that is widely used for querying databases that store the registered users or assignees of an Internet resource, such as a domain name, an IP address block, or an autonomous system, but is also used for a wider range of other information. The protocol stores and delivers database content in a human-readable format. The WHOIS protocol is documented in RFC 3912.

    This endpoint implements a WHOIS query service and returns as much information as possible for a given resource in JSON format.

    The resources currently available are (more in the future):

    The API call will try to return the WHOIS information of the resource cached in our databases. If the cache has expired or the resource is not cached then it will perform a rountrip to the Regional Internet Registry (RIR) to which the resource belongs.

    Every call made to the API will count as a new HIT in the quota of the user.

    Lookup WHOIS IP address

    $ curl -i -H "X-Auth-Token: UUID" -X GET "https://api.apility.net/whois/ip/<IP>"
    

    No matter if the IP address has information in any RIR, it will always return the whois JSON object. If the IP address has information in any RIR:

    {
        "whois": {
            "asn_country_code": "US",
            "objects": {
                "ABUSE5250-ARIN": {
                    "handle": "ABUSE5250-ARIN",
                    "events": [
                        {
                            "action": "last changed",
                            "actor": null,
                            "timestamp": "2017-12-04T10:49:20-05:00"
                        },
                        {
                            "action": "registration",
                            "actor": null,
                            "timestamp": "2015-11-06T15:36:35-05:00"
                        }
                    ],
                    "roles": [
                        "abuse"
                    ],
                    "status": [
                        "validated"
                    ],
                    "contact": {
                        "email": [
                            {
                                "type": null,
                                "value": "network-abuse@google.com"
                            }
                        ],
                        "phone": [
                            {
                                "type": [
                                    "work",
                                    "voice"
                                ],
                                "value": "+1-650-253-0000"
                            }
                        ],
                        "role": null,
                        "name": "Abuse",
                        "address": [
                            {
                                "type": null,
                                "value": "1600 Amphitheatre Parkway\nMountain View\nCA\n94043\nUnited States"
                            }
                        ],
                        "title": null,
                        "kind": "group"
                    },
                    "remarks": [
                        {
                            "links": null,
                            "title": "Registration Comments",
                            "description": "Please note that the recommended way to file abuse complaints are located in the following links.\r\n\r\nTo report abuse and illegal activity: https://www.google.com/intl/en_US/goodtoknow/online-safety/reporting-abuse/ \r\n\r\nFor legal requests: http://support.google.com/legal \r\n\r\nRegards,\r\nThe Google Team"
                        }
                    ],
                    "links": [
                        "https://rdap.arin.net/registry/entity/ABUSE5250-ARIN",
                        "https://whois.arin.net/rest/poc/ABUSE5250-ARIN"
                    ],
                    "events_actor": null,
                    "notices": [
                        {
                            "links": [
                                "https://www.arin.net/whois_tou.html"
                            ],
                            "title": "Terms of Service",
                            "description": "By using the ARIN RDAP/Whois service, you are agreeing to the RDAP/Whois Terms of Use"
                        }
                    ],
                    "raw": null,
                    "entities": null
                },
                "GOGL": {
                    "handle": "GOGL",
                    "events": [
                        {
                            "action": "last changed",
                            "actor": null,
                            "timestamp": "2017-12-21T13:24:44-05:00"
                        },
                        {
                            "action": "registration",
                            "actor": null,
                            "timestamp": "2000-03-30T00:00:00-05:00"
                        }
                    ],
                    "roles": [
                        "registrant"
                    ],
                    "status": null,
                    "contact": {
                        "email": null,
                        "phone": null,
                        "role": null,
                        "name": "Google LLC",
                        "address": [
                            {
                                "type": null,
                                "value": "1600 Amphitheatre Parkway\nMountain View\nCA\n94043\nUnited States"
                            }
                        ],
                        "title": null,
                        "kind": "org"
                    },
                    "remarks": null,
                    "links": [
                        "https://rdap.arin.net/registry/entity/GOGL",
                        "https://whois.arin.net/rest/org/GOGL"
                    ],
                    "events_actor": null,
                    "notices": null,
                    "raw": null,
                    "entities": [
                        "ABUSE5250-ARIN",
                        "ZG39-ARIN"
                    ]
                },
                "ZG39-ARIN": {
                    "handle": "ZG39-ARIN",
                    "events": [
                        {
                            "action": "last changed",
                            "actor": null,
                            "timestamp": "2017-10-17T06:35:04-04:00"
                        },
                        {
                            "action": "registration",
                            "actor": null,
                            "timestamp": "2000-11-30T13:54:08-05:00"
                        }
                    ],
                    "roles": [
                        "administrative",
                        "technical"
                    ],
                    "status": [
                        "validated"
                    ],
                    "contact": {
                        "email": [
                            {
                                "type": null,
                                "value": "arin-contact@google.com"
                            }
                        ],
                        "phone": [
                            {
                                "type": [
                                    "work",
                                    "voice"
                                ],
                                "value": "+1-650-253-0000"
                            }
                        ],
                        "role": null,
                        "name": "Google LLC",
                        "address": [
                            {
                                "type": null,
                                "value": "1600 Amphitheatre Parkway\nMountain View\nCA\n94043\nUnited States"
                            }
                        ],
                        "title": null,
                        "kind": "group"
                    },
                    "remarks": null,
                    "links": [
                        "https://rdap.arin.net/registry/entity/ZG39-ARIN",
                        "https://whois.arin.net/rest/poc/ZG39-ARIN"
                    ],
                    "events_actor": null,
                    "notices": [
                        {
                            "links": [
                                "https://www.arin.net/whois_tou.html"
                            ],
                            "title": "Terms of Service",
                            "description": "By using the ARIN RDAP/Whois service, you are agreeing to the RDAP/Whois Terms of Use"
                        }
                    ],
                    "raw": null,
                    "entities": null
                }
            },
            "asn_cidr": "8.8.8.0/24",
            "nir": null,
            "entities": [
                "GOGL"
            ],
            "network": {
                "handle": "NET-8-8-8-0-1",
                "status": null,
                "type": null,
                "start_address": "8.8.8.0",
                "end_address": "8.8.8.255",
                "remarks": null,
                "events": [
                    {
                        "action": "last changed",
                        "actor": null,
                        "timestamp": "2014-03-14T15:52:05-04:00"
                    },
                    {
                        "action": "registration",
                        "actor": null,
                        "timestamp": "2014-03-14T15:52:05-04:00"
                    }
                ],
                "parent_handle": "NET-8-0-0-0-1",
                "cidr": "8.8.8.0/24",
                "country": null,
                "raw": null,
                "name": "LVLT-GOGL-8-8-8",
                "notices": [
                    {
                        "links": [
                            "https://www.arin.net/whois_tou.html"
                        ],
                        "title": "Terms of Service",
                        "description": "By using the ARIN RDAP/Whois service, you are agreeing to the RDAP/Whois Terms of Use"
                    }
                ],
                "ip_version": "v4",
                "links": [
                    "https://rdap.arin.net/registry/ip/8.8.8.0",
                    "https://whois.arin.net/rest/net/NET-8-8-8-0-1",
                    "https://rdap.arin.net/registry/ip/8.0.0.0/8"
                ]
            },
            "asn_description": "GOOGLE - Google LLC, US",
            "asn_date": "1992-12-01",
            "query": "8.8.8.8",
            "raw": null,
            "asn_registry": "arin",
            "asn": "15169"
        }
    }```
    
    >If there is no information in any RIR:
    
    ```shell
    {
        "whois": []
    }
    

    The whois JSON object contains all the information returned by the RIR about the object. See a full description of the objet whois.

    HTTP Request

    GET https://api.apility.net/whois/ip/<IP>

    Header Parameters

    Parameter Mandatory Description
    X-Auth-Token No API Key of the owner. You can choose to pass the API Key in the header or in the Query String.

    QueryString Parameters

    Parameter Mandatory Description
    token No API Key of the owner. You can choose to pass the API Key in the header or in the Query String.
    callback Yes Function to invoke when using JSONP model.

    Response

    The response should be a HTTP/1.1 200 OK if everything is ok. Any other error message means something went wrong in the system and you should contact support.

    If everything goes fine then it will also return the following JSON object:

    Parameter Description
    whois JSON object containing all the information returned by the RIR 'whois' object.

    Objects

    domain

    The domain object contains the information used in the scoring algorithm.

    Parameter Description
    score Number describing the result of the algorithm. Negative means 'suspicious' or 'bad' domain. Neutral or positivo means it's a 'clean' domain.
    domain JSON structure containing the 'domainname score' object as result of the analysis of the domains.
    ip JSON structure containing the 'ip score' object as result of the analysis of the IP of the domain.
    source_ip JSON structure containing the 'ip score' object as result of the analysis of the IP origin of the request.

    email

    The email object contains the information used in the scoring algorithm.

    Parameter Description
    score Number describing the result of the algorithm. Negative means 'suspicious' or 'bad' domain. Neutral or positive means it's a 'clean' domain.
    domain JSON structure containing the 'domainname score' object as result of the analysis of the domains.
    ip JSON structure containing the 'ip score' object as result of the analysis of the IP of the domain.
    source_ip JSON structure containing the 'ip score' object as result of the analysis of the IP origin of the request.
    address JSON structure containing the 'address score' object as result of the analysis of the email.
    smtp JSON structure containing the 'smtp score' object as result of the analysis of the email service.
    freemail JSON structure containing the 'freemail score' object as result of the analysis of the email provider.
    email JSON structure containing the 'email-blacklist score' object as result of the look up in the email blacklists.
    disposable JSON structure containing the 'disposable score' object as result of the analysis of the email provider.

    geoip

    The geoip object contains the information used in Geolocation of an IP.

    Parameter Description
    longitude Longitude where the IP has been found
    latitude Latitude where the IP has been found
    hostname Name of the host resolved from the IP
    address IPv4 or IPv6 address of the request
    continent 2 letter code of the continent.
    country ISO 3166-1 Country code.
    region Name of the region, by default the english translation in 'region_names'.
    city Name of the city, by default the english translation in 'city_names'.
    postal Postal code or Zip code
    time_zone Time zone of the location
    accuracy_radius The approximate radius in kilometers around the latitude and longitude for the geographical entity. -1 if unknown.
    continent_geoname_id Id of the continent in the geonames.org database. -1 if the continent cannot be geolocated.
    country_geoname_id Id of the country in the geonames.org database. -1 if the country cannot be geolocated.
    region_geoname_id Id of the region in the geonames.org database. -1 if the region cannot be geolocated.
    city_geoname_id Id of the city in the geonames.org database. -1 if the city cannot be geolocated.
    continent_names JSON structure containing the different names of the continent in different languages. Languages are in ISO 639-1. Empty if continent cannot be geolocated.
    country_names JSON structure containing the different names of the country in different languages. Languages are in ISO 639-1. Empty if country cannot be geolocated.
    region_names JSON structure containing the different names of the region in different languages. Languages are in ISO 639-1. Empty if region cannot be geolocated.
    city_names JSON structure containing the different names of the city in different languages. Languages are in ISO 639-1. Empty if city cannot be geolocated.
    as JSON structure containing the 'as' object.

    as

    The AS object contains the information of Autonmous System

    Parameter Description
    asn AS number
    name name of the AS
    country ISO 3166-1 Country code
    networks Array with the lists of networks of the AS

    domainname score

    The domainname score contains the information of testing different subdomains of the main root domain: NS records, MX records and domain blacklists.

    Parameter Description
    score Number describing the result of the algorithm. Negative means 'suspicious' or 'bad' domain. Neutral or positive means it's a 'clean' domain.
    blacklist_ns Array containing the blacklists where the NS domains were found.
    blacklist_mx Array containing the blacklists where the MX domains were found.
    blacklist Array containing the blacklists where the domain was found.
    mx Array with the hosts found in the MX records.
    ns Array with the hosts found in the NS records.

    ip score

    The ip score contains the information of looking up the IP in the blacklists.

    Parameter Description
    score Number describing the result of the algorithm. Negative means 'suspicious' or 'bad' IP. Neutral or positive means it's a 'clean' IP.
    blacklist Array containing the blacklists where the IP was found.
    is_quarantined If the IP has been added by the user to the quarantine lists.
    address IPv4 or IPv6 resolved.

    address score

    The address score contains the information of checking the format of the email.

    Parameter Description
    score Number describing the result of the algorithm. Negative means 'suspicious' or 'bad' email. Neutral or positive means it's a 'clean' email.
    is_role The email has the format of a role-based-address. It's not common to allow registration with role-based-addresses.
    is_well_formed The email is compliant or not with the standards and could cause issues in some systems.

    smtp score

    The smtp score contains the information obtained after testing the remote inbox where the email is hosted.

    Parameter Description
    score Number describing the result of the algorithm. Negative means 'suspicious' or 'bad' email. Neutral or positive means it's a 'clean' email.
    exist_mx The SMTP service is reachable using the hosts in the MX records.
    exist_address The SMTP service recognizes the email address.
    exist_catchall The SMTP service implements a catch-all email feature.

    freemail score

    The freemail score contains the information of looking up the domain in the lists of Free Email Service Providers.

    Parameter Description
    score Number describing the result of the algorithm. Negative means 'suspicious' or 'bad' domain. Neutral or positive means it's a 'clean' domain.
    is_freemail The domain has been found in any Free Email Service Provider list.

    disposable score

    The disposable score contains the information of looking up the domain in the lists of Disposable Email Addresses Providers.

    Parameter Description
    score Number describing the result of the algorithm. Negative means 'suspicious' or 'bad' domain. Neutral or positive means it's a 'clean' domain.
    is_disposable The domain has been found in any Disposable Email Address Providers list.

    email score

    The email score contains the information of looking up the email in the blacklists.

    Parameter Description
    score Number describing the result of the algorithm. Negative means 'suspicious' or 'bad' email. Neutral or positive means it's a 'clean' email.
    blacklist Array containing the blacklists where the email was found.

    transaction ip

    The transaction ip object contains information about what action was performed on the blacklists/blacklists in the database.

    Parameter Description
    timestamp The UNIX time in seconds when the transaction was performed.
    command 'add' or 'rem'. Type of transaction in the database: ADD to the blacklist or REMove of the blacklist.
    ip IP address of the transaction
    blacklist_change Blackist added or removed thanks to the transaction.
    blacklists List of blacklists after the execution of the command and the blacklist change.

    transaction domain

    The transaction domain object contains information about what action was performed on the blacklists in the database.

    Parameter Description
    timestamp The UNIX time in seconds when the transaction was performed.
    command 'add' or 'rem'. Type of transaction in the database: ADD to the blacklist or REMove of the blacklist.
    domain Domain of the transaction
    blacklist_change Blackist added or removed thanks to the transaction.
    blacklists List of blacklists after the execution of the command and the blacklist change.

    transaction email

    The transaction email object contains information about what action was performed on the blacklists in the database.

    Parameter Description
    timestamp The UNIX time in seconds when the transaction was performed.
    command 'add' or 'rem'. Type of transaction in the database: ADD to the blacklist or REMove of the blacklist.
    email Email of the transaction
    blacklist_change Blackist added or removed thanks to the transaction.
    blacklists List of blacklists after the execution of the command and the blacklist change.

    whois

    Contains many nested lists and objects, detailed below.

    Parameter Description
    query The IP address
    asn Globally unique identifier used for routing information exchange with Autonomous Systems.
    asn_cidr Network routing block assigned to an ASN.
    asn_country_code ASN assigned country code in ISO 3166-1 format.
    asn_date ASN allocation date in ISO 8601 format.
    asn_registry ASN assigned regional internet registry.
    asn_description The ASN description
    network The assigned network for an IP address. May be a parent or child network. See Network object.
    entities list of object names referenced by an RIR network. Map these to the objects keys.
    objects The objects (entities) referenced by an RIR network or by other entities (depending on depth parameter). Keys are the object names with values as Object.

    whois network

    The parameters mapped to the network in the objects list within the whois object.

    Parameter Description
    cidr Network routing block an IP address belongs to.
    country Country code registered with the RIR in ISO 3166-1 format.
    end_address The last IP address in a network block.
    events List of events. See Events object.
    handle Unique identifier for a registered object.
    ip_version IP protocol version (v4 or v6) of an IP address.
    links HTTP/HTTPS links provided for an RIR object.
    name The identifier assigned to the network registration for an IP address.
    notices List of notice objects. See Notices object.
    parent_handle Unique identifier for the parent network of a registered network.
    remarks List of remark (notice) dictionaries. See Notices object.
    start_address The first IP address in a network block.
    status List indicating the state of a registered object.
    type The RIR classification of a registered network.

    whois object

    The parameters mapped to the object (entity) in the objects list within the whois.

    Parameter Description
    contact Contact information registered with an RIR object. See Object Contact.
    entities List of object names referenced by an RIR object. Map these to other objects keys.
    events List of event dictionaries. See Events object.
    events_actor List of event (no actor) dictionaries. See Events object.
    handle Unique identifier for a registered object.
    links List of HTTP/HTTPS links provided for an RIR object.
    notices List of notice dictionaries. See Notices object.
    remarks List of remark (notice) dictionaries. See Notices object.
    roles List of roles assigned to a registered object.
    status List indicating the state of a registered object.

    whois object contact

    The contact information registered to an RIR object. This is the contact key contained in Object.

    Parameter Description
    address List of contact postal address dictionaries. Contains key type and value.
    email List of contact email address dictionaries. Contains key type and value.
    kind The contact information kind (individual, group, org).
    name The contact name.
    phone List of contact phone number dictionaries. Contains key type and value.
    role The contact’s role.
    title The contact’s position or job title.

    whois event

    Common to lists of events in the registry.

    Parameter Description
    action The reason for an event.
    timestamp The date an event occured in ISO 8601 format.
    actor The identifier for an event initiator (if any).

    whois notice

    Information contained in notices and remarks.

    Parameter Description
    title The title/header for a notice.
    description The description/body of a notice.
    links list of HTTP/HTTPS links provided for a notice.

    Errors

    Apility.io uses the following error codes:

    Error Code Meaning
    400 Bad Request -- Your request is probably using parameters with bad format. Check the error details.
    401 Unauthorized -- Your API key is wrong.
    403 Forbidden -- Your API key does not have enough permissions to perform the action requested.
    404 Not Found -- If using Simple Model, then it means the resource is not in any blacklist (and this is good).
    405 Method Not Allowed -- All endpoints only allow GET verbs.
    429 Too Many Requests -- You have ran out of quota. Please consider upgrading your plan.
    500 Internal Server Error -- We had a problem with our server. Please report to our suppor team.
    503 Service Unavailable -- We're temporarily offline for maintenance. Please try again later.