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:
- In the Frosmo Control Panel, select Utilities > Frosmo APIs.
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
Table: Query parameters for Visitor API requests (affinity groups)
Parameter | Description | Type | Role | Example |
---|---|---|---|---|
method | Request type. Use the value | 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 | Local Frosmo ID of the visitor whose affinity groups you want to retrieve. | String | Required | cookieId=dsr77t.kstzihlx |
Request examples
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_
.
{ "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 message | Description | Solution |
---|---|---|
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 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:
|
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. |