Visitor Groups

Intro

A visitor group is a set of classifications used to identify users visiting your application. Available visitor classifications include IP address/range, organization, tag, location, and user ID. For more information, see the visitor types documentation.

A visitor is a valid member of its visitor type. For example, "1.2.3.4" is a valid IP visitor, but not a valid organization visitor.

Visitor groups are used by policies to determine if a visit triggers that policy. One visitor group can be used by multiple policies.

Visitor group type

{
    "type": "visitor_group",
    "id": "71ba3946-bdb8-45f4-9118-9fc3d5790bb3",
    "name": "whitelisted IPs",
    "visitor_type": "IP",
    "visitors": [
        {
            "type": "visitor",
            "visitor_group_id": "71ba3946-bdb8-45f4-9118-9fc3d5790bb3",
            "value": "1.2.3.4",
            "created": 1578018203208,
            "creator_type": "USER",
            "creator_id": "05063cca-dede-485d-be3c-c7899b9d737c"
        }
    ],
    "visitors_pagination": {
        "has_more": false,
        "url": "/v1/gatekeeper/visitor-groups/71ba3946-bdb8-45f4-9118-9fc3d5790bb3/visitors"
    },
    "operator": null,
    "created": 1578018203208,
    "is_default": false
}

Attributes

creatednumber

Timestamp of object creation in milliseconds.

idstring

Unique identifier for object.

is_defaultboolean

Whether the object is a system default. System defaults cannot be modified.

namestring

Unique display name for object.

operatorstring

The operator for advanced handling of user IDs. Only available for user ID type visitor groups.

Options:
  • "in": Match user IDs in this set.
  • "between": Match user IDs between two value. Range is checked inclusively (id >= lower bounds, id <= upper bounds).
  • "less": Match user IDs less than this value. Number is checked exclusively (id > number).
  • "greater": Match user IDs greater than this value. Number is checked exclusively (id > number).
typestring

String representing object type.

always value: "visitor_group"
visitor_typestring

String representing how visitors are matched for this group.

Options:
  • "IP": Match visitors with this IP address or in this IP range.
  • "ORGANIZATION": Match visitors from this organization.
  • "TAG": Match visitors with this tag.
  • "COUNTRY": Match visitors from this country.
  • "USER_ID": Match visitors in this user ID set.
  • "DEFAULT": Match all visitors (used by default visitor group).
visitorsarray of Visitor

List of visitors associated with this object. Limited to 20 results.

List visitor groups

GET/gatekeeper/visitor-groups

Gets a list of visitor groups. Results are ordered by creation time, from newest to oldest.

Example

Request

curl "https://api.nettoolkit.com/v1/gatekeeper/visitor-groups" \
-H "X-NTK-KEY: $YOUR_KEY_HERE"

Response

{
    "code": 1000,
    "results": [
        {
            "type": "visitor_group",
            "id": "bb175a71-13c9-438f-ab2a-dfb3aca2b7a4",
            "name": "North America",
            "visitor_type": "COUNTRY",
            "visitors": [
                {
                    "type": "visitor",
                    "visitor_group_id": "bb175a71-13c9-438f-ab2a-dfb3aca2b7a4",
                    "value": "United States",
                    "created": 1578018203208
                }
            ],
            "visitors_pagination": {
                "has_more": false,
                "url": "/v1/gatekeeper/visitor-groups/bb175a71-13c9-438f-ab2a-dfb3aca2b7a4/visitors"
            },
            "created": 1578018203208,
            "is_default": false
        }
    ]
}

List visitors in visitor group

GET/gatekeeper/visitor-groups/:visitor_group_id/visitors

Gets a list of visitors in a visitor group. Results are ordered by visitor value alphabetically.

Parameters

limitnumber(optional)
default value: 20

Limit the number of objects returned.

value_afterstring(optional)

Only return objects after this value alphabetically. This parameter can be used for pagination.

Example

Request

curl "https://api.nettoolkit.com/v1/gatekeeper/visitor-groups/bb175a71-13c9-438f-ab2a-dfb3aca2b7a4/visitors" \
-H "X-NTK-KEY: $YOUR_KEY_HERE"

Response

{
    "code": 1000,
    "results": [
        {
            "type": "visitor",
            "visitor_group_id": "bb175a71-13c9-438f-ab2a-dfb3aca2b7a4",
            "value": "Canada",
            "created": 1578018203208
        }
    ],
    "pagination": {
        "has_more": false,
        "url": "/v1/gatekeeper/visitor-groups/bb175a71-13c9-438f-ab2a-dfb3aca2b7a4/visitors"
    }
}

Add visitor to visitor group

POST/gatekeeper/visitor-groups/:visitor_group_id/visitors

Adds a visitor to a visitor group. If the visitor is already present, the request succeeds without making any changes.

Parameters

visitorstring(required)

Value of visitor to add. Value must be a valid member of visitor group type.

Example

Request

curl "https://api.nettoolkit.com/v1/gatekeeper/visitor-groups/bb175a71-13c9-438f-ab2a-dfb3aca2b7a4/visitors" \
-H "X-NTK-KEY: $YOUR_KEY_HERE" \
-d visitor=Canada

Response

{
    "code": 1000,
    "results": [
        {
            "type": "visitor",
            "visitor_group_id": "bb175a71-13c9-438f-ab2a-dfb3aca2b7a4",
            "value": "Canada",
            "created": 1578018203208
        }
    ]
}

Remove visitor from visitor group

DELETE/gatekeeper/visitor-groups/:visitor_group_id/visitors

Removes a visitor from a visitor group. If the visitor is not present in this visitor group, the request succeeds without making any changes.

Parameters

visitorstring(required)

Value of visitor to add. Value must be a valid member of visitor group type.

Example

Request

curl "https://api.nettoolkit.com/v1/gatekeeper/visitor-groups/bb175a71-13c9-438f-ab2a-dfb3aca2b7a4/visitors?visitor=Canada" \
-H "X-NTK-KEY: $YOUR_KEY_HERE"

Response

{
    "code": 1000,
    "results": [
        {
            "type": "visitor",
            "visitor_group_id": "bb175a71-13c9-438f-ab2a-dfb3aca2b7a4",
            "value": "Canada",
            "created": 1578018203208
        }
    ]
}

Other types

Visitor

{
    "type": "visitor",
    "visitor_group_id": "71ba3946-bdb8-45f4-9118-9fc3d5790bb3",
    "value": "1.2.3.4",
    "created": 1578018203208,
    "creator_type": "USER",
    "creator_id": "05063cca-dede-485d-be3c-c7899b9d737c"
}

Attributes

creatednumber

Timestamp of object creation in milliseconds.

typestring

String representing object type.

always value: "visitor"
valuestring

Value for object. The value should be a valid member of its visitor type.

Valid visitors by type:

  • IP: a valid IP address or range. IP addresses should be in IPv4 dot notation. For example, "1.2.3.4" or "99.200.55.3". IP ranges should be in CIDR notation. For example, "1.2.3.0/24" represents all IP addresses between 1.2.3.0 and 1.2.3.255.
  • ORGANIZATION: a recognized organization name. Organization names are derived from regional Internet registry data, and provided as is. For example, "Google, LLC".
  • TAG: a recognized tag value. For example, "data center" or "ISP".
  • COUNTRY: a recognized country name. Country names are provided by Java's Locale class. For example, "United States".
  • USER_ID: a positive 8-byte number in string format. For example, "99" is valid, "-22" is not. When authorizing visits, anonymous visitors will be treated as if they have user ID "0".
visitor_group_idstring

ID of visitor group that owns this object.