Visitor API reference (affinity groups)

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. Log in to the Frosmo Control Panel, and select your site.

2. In the header, click your username, and select API Access.

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

   

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

Query parameters for Visitor API requests (affinity groups)

Parameter	Description	Type	Role	Example
method	Request type. Use the value affinityGroups.	String	Required	method=affinityGroups
origin	Site origin. To find out your site's origin, see Getting your site origin.	String	Required	origin=shop_company_com
cookieId	Frosmo ID of the visitor whose affinity groups you want to retrieve. To get the ID, see Getting a visitor's Frosmo ID. info If the login ID is passed, then this will be used instead of the Frosmo ID.	String	Required	cookieId=dsr77t.kstzihlx
loginId	Login ID of the visitor whose affinity groups you want to retrieve. The ID allows the platform to get the visitor's affinity groups across multiple browsers. note For the login ID to work on a site, login support must be enabled for the site. To enable the feature, if it's not already enabled, contact Frosmo support.	String	Optional	loginId=3364259119087832

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 the following root properties:

• groups: An array that lists the IDs of the affinity groups to which the visitor belongs. The affinity group IDs are prefixed with affgp_.

• user: Object containing visitor information e.g. the visitor's decile or whether the visitor is in the comparison group.

Example: Response with three affinity groups

{
  "groups": [
    "affgp_1096",
    "affgp_1097",
    "affgp_1098"
  ],
  "user": {
    "cookieId": "dsr77t.kstzihlx",
    "loginId": "",
    "decile": 8,
    "isInComparisonGroup": false,
    "source": "cookieId"
  }
}

Error

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

Visitor API error messages (affinity groups)

Error message	Description	Solution
affinity is not enabled for origin '<origin>'	The affinity feature is not enabled for the site, meaning the Frosmo Platform does not track affinities for visitors of the site.	Have Frosmo enable the affinity feature for the site. Contact Frosmo support.
affinity groups are not enabled for origin '<origin>'	The affinity group feature 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 feature 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' or `loginId` missing	The cookieId or loginId query parameter is missing from the request URL.	Provide the cookieId or loginId query parameter.
parameter 'cookieId' contains an empty value parameter 'loginId' contains an empty value	The value of the cookieId or loginId query parameter is missing.	Provide a non-empty value for the cookieId or loginId 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 Frosmo ID that matches a visitor who belongs to at least one affinity group as the value of the cookieId query parameter.