Visits

Intro

Visits are the data used to drive Gatekeeper. Typically, visits are synonymous with web page requests. That is, each time a user loads a page, a visit for that request is recorded. The visit object contains information about the request, such who the visitor is and what they are attempting to do.

Additionally, a visit can be authorized, whereupon Gatekeeper will make a recommendation on how to handle the request. Visit authorization is a core feature of Gatekeeper. See the visit authorization documentation for more information on how visits are authorized.

Visits object

Sample object

{
    "type": "visit",
    "id": "798526cc-cdc1-4966-a20f-197dc73e4ae0",
    "ip": "1.2.3.4",
    "domain": "www.nettoolkit.com",
    "page": "/gatekeeper/visits",
    "user_id": null,
    "user_agent": "Mozilla/5.0 (compatible; Googlebot/2.1; +http://www.google.com/bot.html)",
    "identifies_as_bot": true,
    "country_code": "US",
    "country_name": "United States",
    "tags": [
        "data center"
    ],
    "policy_id": "798526cc-cdc1-4966-a20f-197dc73e4ae0",
    "policy_name": "whitelisted",
    "authorization": "ALLOWED",
    "captcha_status": null,
    "created": 1578018203208
}

Attributes

typestring

String representing object type.

always value: "visit"
idstring

Unique identifier for object.

ipstring

IP address of visitor.

domainstring

Domain name extracted from URL of visit.

pagestring

Page extracted from URL of visit.

user_idnumber

User ID of visitor.

user_agentstring

User agent string of visitor.

identifies_as_botboolean

Whether visitor self-identified as a bot in user agent.

country_codestring

Country code for visitor IP address.

country_namestring

Country name for visitor IP address.

tagsarray

List of tags for visitor IP address.

policy_idstring

ID of policy used to handle visit. Only available for authorized visits.

policy_namestring

Name of policy used to handle visit. Only available for authorized visits.

authorizationstring

Recommendation on how to handle request based on your rule chain. Only available for authorized visits.

Options:
  • "ALLOWED": Visitor is allowed access.
  • "DENIED": Visitor is denied access.
  • "CAPTCHA": Visitor must complete CAPTCHA for access.
reasonstring

Message explaining authorization result. Only available for authorized visits.

captcha_statusstring

Status of CAPTCHA associated with visit. Only available for authorized visits with "CAPTCHA" authorization.

Options:
  • "UNSOLVED": No solution has been submitted.
  • "SOLVED": CAPTCHA was solved by user.
  • "FAILED": CAPTCHA was failed by user.
creatednumber

Timestamp of object creation in milliseconds.

Endpoints

Create and authorize visit

POST/gatekeeper/visits/authorization

Parameters

ip(required)string

IP address of request.

url(required)string

URL of request.

user_idnumber

User ID of visitor. Missing user IDs will be treated as 0 for visitor checking.

user_agentstring

User agent of request.

Examples

Example Request
curl -s -H "X-NTK-KEY: $your_key_here" -d "ip=1.2.3.4" -d "url=https://www.example.com/" \
"https://api.nettoolkit.com/v1/gatekeeper/visits/authorization"
Example Response
{
    "code": 1000,
    "results": [
        {
            "type": "visit",
            "id": "8a6f7a35-3104-4ebc-8d17-eaba29ed445e",
            "ip": "1.2.3.4",
            "domain": "www.example.com",
            "page": "/",
            "user_agent": "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/66.0.3359.181 Safari/537.36",
            "identifies_as_bot": false,
            "country_code": "US",
            "country_name": "United States",
            "tags": [
                "data center and ISP"
            ],
            "policy_id": "441fc477-8dd1-495d-9164-078885a4b294",
            "policy_name": "verification required",
            "authorization": "CAPTCHA",
            "captcha_status": "UNSOLVED",
            "created": 1578018203208
        }
    ]
}

Update visit CAPTCHA status

PUT/gatekeeper/visits/:visit_id/captcha

Parameters

status(required)string

Status of CAPTCHA attempt.

Options:
  • "SOLVED": Indicates user submitted the correct solution to the CAPTCHA.
  • "FAILED": Indicates user submitted an incorrect solution to the CAPTCHA.

Examples

Example Request
curl -s -H "X-NTK-KEY: $your_key_here" -d "status=SOLVED" \
"https://api.nettoolkit.com/v1/gatekeeper/visits/:visit_id/captcha"
Example Response
{
    "code": 1000,
    "results": [
        {
            "type": "visit",
            "id": "8a6f7a35-3104-4ebc-8d17-eaba29ed445e",
            "ip": "1.2.3.4",
            "domain": "www.example.com",
            "page": "/",
            "user_agent": "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/66.0.3359.181 Safari/537.36",
            "identifies_as_bot": false,
            "country_code": "US",
            "country_name": "United States",
            "tags": [
                "data center and ISP"
            ],
            "policy_id": "441fc477-8dd1-495d-9164-078885a4b294",
            "policy_name": "verification required",
            "authorization": "CAPTCHA",
            "captcha_status": "SOLVED",
            "created": 1578018203208
        }
    ]
}