Pages

Learn how to make a Visitor API request to retrieve a visitor's current affinity groups:

For more information about affinity groups, see Feature: Affinity group.

If you want to retrieve a visitor's affinity profile, see Visitor API reference (affinity profiles).

Requests

URL

The URL for Visitor API requests is https://<platform_instance>/visitorApi, where <platform_instance> is the domain name of your Frosmo Platform instance.

To get the URL for your Frosmo Platform instance:

  1. In the Frosmo Control Panel, select Utilities > Frosmo APIs.

  2. In the Visitor API section, copy the URL.

    URL for Visitor API requests

Authentication

The Visitor API does not require authentication.

Methods

The Visitor API supports the GET HTTP method for retrieving a visitor's current affinity groups.

Syntax

To retrieve a visitor's current affinity groups, make the following GET request:

GET https://<platform_instance>/visitorApi?method=affinityGroups&
    origin=<site_origin>&
    cookieId=<local_frosmo_id>

Parameters

Table: Query parameters for Visitor API requests (affinity groups)

ParameterDescriptionTypeRoleExample
method

Request type.

Use the value affinityGroups.

StringRequired
method=affinityGroups
origin

Site origin.

To find out your site's origin, see Getting your site origin.

StringRequired
origin=shop_company_com
cookieIdLocal Frosmo ID of the visitor whose affinity groups you want to retrieve.StringRequired
cookieId=dsr77t.kstzihlx

Request examples

Example: Retrieve a visitor's current affinity groups 
GET https://inpref.com/visitorApi?method=affinityGroups&
    origin=shop_company_com&
    cookieId=dsr77t.kstzihlx

Responses

Success

On a success, the Visitor API returns the requested affinity groups in a JSON object. The response status code is 200.

The response object contains a single property: groups. The property is an array that lists the IDs of the affinity groups to which the visitor belongs. The affinity group IDs are prefixed with affgp_.

Example: Response with three affinity groups
{
  "groups": [
    "affgp_1096",
    "affgp_1097",
    "affgp_1098"
  ]
}

Error

On an error, the Visitor API returns the response status code 400 or 404 and an error message.

Table: Visitor API error messages

Error messageDescriptionSolution
affinity is not enabled for origin '<origin>'
The Affinity add-on is not enabled for the site, meaning the Frosmo Platform does not track affinities for visitors of the site.Have Frosmo enable the Affinity add-on for the site. Contact Frosmo support.
affinity groups are not enabled for origin '<origin>'
The Affinity Group add-on is not enabled for the site, meaning the Frosmo Platform does not track affinity groups for visitors of the site.Have Frosmo enable the Affinity Group add-on for the site. Contact Frosmo support.
parameter 'method' missing
The method query parameter is missing from the request URL.Provide the method query parameter.
parameter 'method' contains an empty value
The value of the method query parameter is missing.Provide a non-empty value for the method query parameter.
invalid method '<parameter_value>'
The value of the method query parameter, <parameter_value>, is invalid.Provide affinityGroups as the value of the method query parameter.
parameter 'origin' missing
The origin query parameter is missing from the request URL.Provide the origin query parameter.
parameter 'origin' contains an empty value
The value of the origin query parameter is missing.Provide a non-empty value for the origin query parameter.
invalid origin parameter '<parameter_value>'
The value of the origin query parameter, <parameter_value>, is invalid.

Provide a valid site origin as the value of the origin query parameter.

To find out your site's origin, see Getting your site origin.

parameter 'cookieId' missing
The cookieId query parameter is missing from the request URL.Provide the cookieId query parameter.
parameter 'cookieId' contains an empty value
The value of the cookieId query parameter is missing.Provide a non-empty value for the cookieId query parameter.
parameter 'cookieId' has invalid format
The value of the cookieId query parameter has an invalid format.

Provide a value that conforms to the following rules:

  • The length of the value is 1-24 characters.
  • The value contains only the following ASCII characters (in any combination):
    • Letters: A to Z (upper case) and a to z (lower case)
    • Numbers: 0 to 9
    • Special characters: . (period), _ (underscore), + (plus sign), - (hyphen)
user not found
The value of the cookieId query parameter does not match a visitor who belongs to any affinity groups. Either the visitor does not exist or the platform has yet to add the visitor to an affinity group.Provide a local Frosmo ID that matches a visitor who belongs to at least one affinity group as the value of the cookieId query parameter.