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.

Visit type

{
    "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": "Visit is always allowed.",
    "captcha_status": null,
    "created": 1578018203208
}

Attributes

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!
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.
country_codestring

Country code for visitor IP address.

country_namestring

Country name for visitor IP address.

creatednumber

Timestamp of object creation in milliseconds.

domainstring

Domain name extracted from URL of visit.

idstring

Unique identifier for object.

ipstring

IP address of visitor.

pagestring

Page extracted from URL of visit.

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.

reasonstring

Message explaining authorization result. Only available for authorized visits.

tagsarray

List of tags for visitor IP address.

typestring

String representing object type.

always value: "visit"
user_agentstring

User agent string of visitor.

user_idnumber

User ID of visitor.

Create and authorize visit

POST/gatekeeper/visits/authorization

Parameters

ipstring(required)

IP address of request.

urlstring(required)

URL of request.

user_agentstring(optional)

User agent of request.

user_idnumber(optional)

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.

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/

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

statusstring(required)

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.

Example

Request

curl "https://api.nettoolkit.com/v1/gatekeeper/visits/:visit_id/captcha" \
-H "X-NTK-KEY: $YOUR_KEY_HERE" \
-d status=SOLVED

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

GET/gatekeeper/visits/count-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.

Parameters

ipstring(required)

IP address of visitor.

policy_idstring(required)

ID of policy.

Example

Request

curl "https://api.nettoolkit.com/v1/gatekeeper/visits/count-for-policy?ip=1.2.3.4&policy_id=798526cc-cdc1-4966-a20f-197dc73e4ae0" \
-H "X-NTK-KEY: $YOUR_KEY_HERE"

Response

{
    "code": 1000,
    "results": [
        {
            "count": 12
        }
    ]
}