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)",
    "country_code": "US",
    "country_name": "United States",
    "tags": [
        "data center"
    ],
    "policy_id": "798526cc-cdc1-4966-a20f-197dc73e4ae0",
    "policy_name": "whitelisted",
    "authorization": "allow",
    "reason": "Visitis is always 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.

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:
  • "allow": Visitor is allowed access.
  • "deny": Visitor is denied access.
  • "captcha": Visitor must complete CAPTCHA for access.
  • "$YOUR_CUSTOM_AUTHORIZATION": You decide what your custom authorization means!
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. Use 0 to denote an anonymous visitor. If this parameter is omitted, 0 will be used for the purposes of for visitor checking.

user_agentstring

User agent of request.

Examples

Example Request
curl "https://api.nettoolkit.com/v1/gatekeeper/visits/authorization" \
-H "X-NTK-KEY: $YOUR_KEY_HERE" \
-d ip=1.2.3.4 \
-d url=https://www.example.com/
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",
            "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",
            "reason": "Please verify that you're a human.",
            "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 "https://api.nettoolkit.com/v1/gatekeeper/visits/:visit_id/captcha" \
-H "X-NTK-KEY: $YOUR_KEY_HERE" \
-d status=SOLVED
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",
            "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",
            "reason": "Please verify that you're a human.",
            "created": 1578018203208
        }
    ]
}

Count visits for policy

This endpoint can be used to determine how many visits an IP address has accrued within the context of a certain policy. For example, if you are operating a site that offers five free articles within a thirty-day window, then you can query this endpoint to determine how many articles have been visited within that time frame.

GET/gatekeeper/visits/count/for-policy

Parameters

ip(required)string

IP address of visitor.

policy_id(required)string

ID of policy.

Examples

Example Request
curl "https://api.nettoolkit.com/v1/gatekeeper/visits/count/for-policy" \
-H "X-NTK-KEY: $YOUR_KEY_HERE" \
-d ip=1.2.3.4 \
-d policy_id=798526cc-cdc1-4966-a20f-197dc73e4ae0
Example Response
{
    "code": 1000,
    "results": [
        {
            "count": 12
        }
    ]
}