Responses

API Responses

Syntax Checker

{
    "checker_type": "SYNTAX",
    "idna_subject": "example.com",
    "params": null,
    "status": "VALID",
    "status_source": "SYNTAX",
    "subject": "example.com",
    "tested_at": "2021-03-09T17:43:24.477977"
}

Availability Checker

{
    "checker_type": "AVAILABILITY",
    "dns_lookup": {
        "NS": [
            "a.iana-servers.net.",
            "b.iana-servers.net."
        ]
    },
    "dns_lookup_record": {
        "dns_name": "example.com.",
        "follow_nameserver_order": true,
        "nameserver": "9.9.9.9",
        "port": 53,
        "preferred_protocol": "UDP",
        "query_record_type": "NS",
        "query_timeout": 5.0,
        "response": [
            "a.iana-servers.net.",
            "b.iana-servers.net."
        ],
        "subject": "example.com",
        "used_protocol": "UDP"
    },
    "domain_syntax": true,
    "expiration_date": null,
    "http_status_code": null,
    "idna_subject": "example.com",
    "ip_syntax": false,
    "ipv4_range_syntax": false,
    "ipv4_syntax": false,
    "ipv6_range_syntax": false,
    "ipv6_syntax": false,
    "netinfo": null,
    "netloc": "example.com",
    "params": {
        "do_syntax_check_first": false,
        "use_dns_lookup": true,
        "use_extra_rules": true,
        "use_http_code_lookup": true,
        "use_netinfo_lookup": true,
        "use_reputation_lookup": false,
        "use_whois_db": true,
        "use_whois_lookup": false,
        "use_collection": false
    },
    "registrar": null,
    "second_level_domain_syntax": true,
    "status": "ACTIVE",
    "status_after_extra_rules": null,
    "status_before_extra_rules": null,
    "status_source": "DNSLOOKUP",
    "status_source_after_extra_rules": null,
    "status_source_before_extra_rules": null,
    "subdomain_syntax": false,
    "subject": "example.com",
    "tested_at": "2021-03-09T17:42:15.771647",
    "url_syntax": false,
    "whois_lookup_record": {
        "expiration_date": null,
        "port": 43,
        "query_timeout": 5.0,
        "record": null,
        "server": null,
        "subject": "example.com",
        "registrar": null
    },
    "whois_record": null
}

Reputation Checker

{
    "checker_type": "REPUTATION",
    "dns_lookup": [
        "93.184.216.34"
    ],
    "dns_lookup_record": {
        "dns_name": "example.com.",
        "follow_nameserver_order": true,
        "nameserver": "9.9.9.9",
        "port": 53,
        "preferred_protocol": "UDP",
        "query_record_type": "A",
        "query_timeout": 5.0,
        "response": [
            "93.184.216.34"
        ],
        "subject": "example.com",
        "used_protocol": "UDP"
    },
    "domain_syntax": true,
    "idna_subject": "example.com",
    "ip_syntax": false,
    "ipv4_range_syntax": false,
    "ipv4_syntax": false,
    "ipv6_range_syntax": false,
    "ipv6_syntax": false,
    "params": {
        "do_syntax_check_first": false,
        "use_collection": false
    },
    "second_level_domain_syntax": true,
    "status": "SANE",
    "status_source": "REPUTATION",
    "subdomain_syntax": false,
    "subject": "example.com",
    "tested_at": "2021-03-09T17:44:02.908452",
    "url_syntax": false
}

API Responses (explained)

In this page, we intend to explain the most useful parts of the API responses.

checker_type

The checker type. It describes the checker which was used to provide the given response.

It should be one of the following:

  • SYNTAX
  • AVAILABILITY
  • REPUTATION

idna_subject

The IDNA formatted subject. It is the subject that is internally exposed the all supported testing methods.

You should consider this as the subject and consider the subject key as a placeholder of what was given by you.

params

The parameters. It describes the parameter applied to the checker. In most case, if you are using the Python API, you should be able to control most of them through the class constructor or their property setters with the same name.

Syntax Checker

As of now, there is no known parameters.

Availability Checker

With the availability checker, the following is provided.

{
    "do_syntax_check_first": false,
    "use_dns_lookup": true,
    "use_extra_rules": true,
    "use_http_code_lookup": true,
    "use_netinfo_lookup": true,
    "use_reputation_lookup": false,
    "use_whois_db": true,
    "use_whois_lookup": false,
    "use_collection": false
}
do_syntax_check_first

This parameter lets the checker know that it has to do a syntax check before starting an extensive test. Meaning that the status strongly depends on the caught syntax.

use_dns_lookup

This parameter lets the checker know that it is allowed to perform some DNS lookup to determine the status of the given subject.

use_extra_rules

This parameter lets the checker know that it is allowed to check against our own sets of SPECIAL rules in order to escalate or deescalate the status of the given subject.

use_http_code_lookup

This parameter lets the checker know that it is allowed to gather and use the HTTP status code of the given subject to determine its status.

use_netinfo_lookup

This parameter lets the checker know that it is allowed to perform a network information lookup to determine the status of the given subject.

use_reputation_lookup

This parameter lets the checker know that is allowed to perform a reputation lookup to determine the status of the given subject.

use_whois_db

This parameter lets the checker know that it is allowed to look at the WHOIS local WHOIS database before even trying to perform a WHOIS lookup to determine the status of the given subject.

Warning

If the use_whois_lookup parameter is deactivated, this parameter is ignored.

use_whois_lookup

This parameter lets the checker know that is it allowed to perform a WHOIS lookup to determine the status of the given subject.

use_collection

This parameter lets the checker know that it is allowed to perform a lookup into the collection API before starting an extensive local test.

Reputation Checker

With the availability checker, the following is provided.

{
    "do_syntax_check_first": false,
    "use_collection": false
}
do_syntax_check_first

This parameter lets the checker know that it has to do a syntax check before starting an extensive test. Meaning that the status strongly depends on the caught syntax.

use_collection

This parameter lets the checker know that it is allowed to perform a lookup into the collection API before starting an extensive local test.

status

The status. It describes the final status gathered by the checker.

Syntax Checker

With the syntax checker, it may be one of the following:

  • VALID
  • INVALID

Availability Checker

With the availability checker, it may be one of the following:

  • ACTIVE
  • INACTIVE
  • INVALID

Reputation Checker

With the reputation checker, it may be one of the following:

  • SANE
  • MALICIOUS

registrar

The registrar. It describes the registrar of the given subject as described in its WHOIS record.

Syntax Checker

Non-existent.

Availability Checker

Provides the - found - registrar. Otherwise, null is provided.

Reputation Checker

Non-existent.

status_after_extra_rules

The status after our extra rules lookup. It describes the status after the lookup against our own sets of rules.

If no rules were matched, null is provided.

Warning

Beware, this is only provided by the availability checker.

status_before_extra_rules

The status before our extra rules lookup. It describes the status before the lookup against our own sets of rules. In other words, it is the status provided by our standard status lookup strategy.

If no rules were matched, null is provided.

Warning

Beware, this is only provided by the availability checker.

status_source

The status source. It describes the test method that led to the given status.

It should be one of the following:

  • SYNTAX
  • WHOIS
  • DNSLOOKUP
  • NETINFO
  • HTTP CODE
  • SPECIAL (extra rules)
  • COLLECTION

status_source_after_extra_rules

The status source after our extra rules lookup. It describes the status source after the lookup against our own sets of rules.

It should be SPECIAL.

If no rules were matched, null is provided.

Warning

Beware, this is only provided by the availability checker.

status_source_before_extra_rules

The status source before our extra rules lookup. It describes the status source before the lookup against our own sets of rules.

In other words, it is the status source provided by our standard status lookup strategy.

It should be one of the following:

  • SYNTAX
  • WHOIS
  • DNSLOOKUP
  • NETINFO
  • HTTP CODE
  • COLLECTION

If no rules were matched, null is provided.

Warning

Beware, this is only provided by the availability checker.

subject

The subject. It describes the subject that was given by you.

tested_at

The test date. It may not be useful to everyone, but it describes the date and time of the generation of the given output.

dns_lookup

The DNS lookup summary. It describes the summary of the DNS Lookup that was performed.

Syntax Checker

Non-existent.

Availability Checker

With the availability checker, the following format (or null) is provided:

{
    "QUERY TYPE": [
        "string",
        "string"
    ]
}

Where QUERY TYPE is one of the following:

  • NS
  • A
  • AAAA
  • CNAME
  • DNAME

Reputation Checker

With the reputation checker, the following format (or null) is provided:

[
    "string",
    "string"
]

It is just a simple list of IPs that we check against. When the given subject is an IPv4, null is provided.

dns_lookup_record

The DNS lookup record. It describes the latest performed DNS lookup record.

Syntax Checker

Non-existent.

Availability and Reputation Checker

With the availability or reputation checker, the following is provided.

{
    "dns_name": "example.com.",
    "follow_nameserver_order": true,
    "nameserver": "9.9.9.9",
    "port": 53,
    "preferred_protocol": "UDP",
    "query_record_type": "NS",
    "query_timeout": 5.0,
    "response": [
        "a.iana-servers.net.",
        "b.iana-servers.net."
    ],
    "subject": "example.com",
    "used_protocol": "UDP"
}
dns_name

The DNS name. It describes the DNS name that was queried.

follow_nameserver_order

It describes if we followed the nameserver order.

nameserver

The nameserver. It describes the nameserver that was queried last.

port

The port. It describes the port that was used to communicate with the nameserver.

query_record_type

The query record type. It describes the record type that was queried last.

query_timeout

The query timeout. It describes the query timeout that was used to perform the query.

response

The response. It describes a list of domains or IPs given by the nameserver as response.

subject

The subject. It describes the subject that was given to the query tool.

used_protocol

The used protocol. It describes the used protocol.

It should be one of the following:

  • UDP (default)
  • TCP
  • HTTPS
  • TLS

domain_syntax

The domain syntax. It describes through a boolean the state of the given subject.

In other words: true is provided when the given subject is a 2nd level domain or a subdomain.

Warning

This key may give you a null if nothing was performed (yet).

Warning

Beware, this is only provided by the availability and reputation checkers.

expiration_date

The expiration date. It describes the expiration date of the given subject as extracted from the WHOIS record.

If none is found, null will be provided.

Warning

Beware, this is only provided by the availability checker.

http_status_code

The HTTP status code. It describes the HTTP status code which was discovered.

If none is found, null or 0 will be provided.

Warning

Beware, this is only provided by the availability checker.

ip_syntax

The IP syntax. It describes through a boolean the state of the given subject.

In other words: true is provided when the given subject is an IPv4 or an IPv6 (range excluded).

Warning

This key may give you a null if nothing was performed (yet).

Warning

Beware, this is only provided by the availability and reputation checkers.

ipv4_range_syntax

The IPv4 range syntax. It describes through a boolean the state of the given subject.

In other words: true is provided when the given subject is an IPv4 range.

Warning

This key may give you a null if nothing was performed (yet).

Warning

Beware, this is only provided by the availability and reputation checkers.

ipv4_syntax

The IPv4 syntax. It describes through a boolean the state of the given subject.

In other words: true is provided when the given subject is an IPv4 (range excluded).

Warning

This key may give you a null if nothing was performed (yet).

Warning

Beware, this is only provided by the availability and reputation checkers.

ipv6_range_syntax

The IPv6 range syntax. It describes through a boolean the state of the given subject.

In other words: true is provided when the given subject is an IPv6 range.

Warning

This key may give you a null if nothing was performed (yet).

Warning

Beware, this is only provided by the availability and reputation checkers.

ipv6_syntax

The IPv6 syntax. It describes through a boolean the state of the given subject.

In other words: true is provided when the given subject is an IPv6 (range excluded).

Warning

This key may give you a null if nothing was performed (yet).

Warning

Beware, this is only provided by the availability and reputation checkers.

second_level_domain_syntax

The 2nd level domain syntax. It describes through a boolean the state of the given subject.

In other words: true is provided when the given subject is a 2nd level domain.

Warning

This key may give you a null if nothing was performed (yet).

Warning

Beware, this is only provided by the availability and reputation checkers.

subdomain_syntax

The subdomain syntax. It describes through a boolean the state of the given subject.

In other words: true is provided when the given subject is a subdomain.

Warning

This key may give you a null if nothing was performed (yet).

Warning

Beware, this is only provided by the availability and reputation checkers.

url_syntax

The subdomain syntax. It describes through a boolean the state of the given subject.

In other words: true is provided when the given subject is a URL.

Warning

This key may give you a null if nothing was performed (yet).

Warning

Beware, this is only provided by the availability and reputation checkers.

netinfo

The network information summary. It describes the summary of the network information lookup.

Syntax Checker

Non-existent.

Availability Checker

With the availability checker, the following format (or null) is provided:

[
    "string",
    "string"
]

It is just a simple list of IPs or domains that were found. Otherwise, null will be supplied.

Reputation Checker

Non-existent.

netloc

The network location. It describe the network location of the tested subject. This can be useful when working with URLs. When working with URLs the value of netloc will be in the domain:port formet if the port is explicitly given and domain otherwise.

whois_lookup_record

The WHOIS lookup record. It describes the latest performed WHOIS lookup record.

Syntax Checker

Non-existent.

Availability Checker

With the availability checker, the following is provided.

{
    "expiration_date": null,
    "port": 43,
    "query_timeout": 5.0,
    "record": null,
    "server": null,
    "subject": "example.com"
}
expiration_date

The expiration date. It describes the extracted expiration date.

It should be a string if the format 09-oct-1970 or null otherwise.

port

The port. It describes the port used to communicate with the WHOIS server.

query_timeout

The query timeout. It describes the query timeout that was applied during the query.

record

The WHOIS record. It describes the record or response of the WHOIS server.

subject

The subject. It describes the subject which was queried.

Reputation Checker

Non-existent.

whois_lookup

The WHOIS record. It describes the WHOIS record as given by the (root) WHOIS server.

Warning

Beware, this is only provided by the availability checker.

CLI Responses

From the CLI, there is a lot less information available to the end-user. This patch intend to shortly preset each column of the CLI stdout outputs.

Subject

The subject. It describes the given or decoded subject after conversion to IDNA.

Status

The status. It describes the official status of the tested subject.

Source

The status source. It describes the method that let to the given status.

Expiration Date

The expiration date. It describes the expiration date extracted from the WHOIS record - if found. Otherwise, Unknown is supplied.

HTTP Code

The HTTP status code. It describes the HTTP status code - if found. Otherwise, Unknown is supplied.

Checker

The checker. It describes the checker used to gather the status.