These parameters apply to every request you send to the REST API directly, without a Constructor client library. That covers a backend integration, where your servers call Constructor, and a frontend integration that calls the REST API from browser or app code. If you use a client library or a UI library, see the documentation for that library: Client libraries / SDKs or UI libraries.

The parameters on this page are the same for every endpoint: search, autocomplete, browse, recommendations, and the others. Each endpoint also has its own parameters, such as the search query or the filters. The API Reference documents those for each endpoint. Send the parameters on this page in addition to them.

Two values apply only to a backend integration: X-Forwarded-For and x-cnstrc-token. Each one is marked backend only below. Do not send them from a browser or an app.

When a browser sends a request to Constructor, the request carries the end user's User-Agent and IP address. Constructor uses these values to identify the source of each request, which is required for DDoS protection. In a backend integration, your servers send the requests on behalf of end users. The headers then describe your server, so you must forward the end user's values explicitly.

To power personalization, an anonymous user identifier and a session identifier are stored on the user's device. On a website, the beacon stores them in cookies. In an app, the iOS or Android SDK stores them. Read these values and send them with each request.

HTTP headers

X-Forwarded-For - mandatory, backend only

Contains the IPv4 address of the client that originated the request. The header must contain a single IPv4 address representing the user's browser, not a chain of comma-separated IP addresses. IPv6 addresses are not supported.

x-cnstrc-token - mandatory, backend only

A unique string supplied by Constructor to be transmitted with requests originating from the backend. This value should be treated as sensitive information and never exposed client side.

User-Agent - mandatory

Containing the User-Agent of the origin request from the user's device. This header is used for device identification and analytics.

Web (browser-based) integrations

In a frontend integration, the browser sends this header for you. In a backend integration, forward the User-Agent as-is from the end-user's browser.

Native app integrations

Set the header in the formats below. This applies both when your app calls Constructor and when your server forwards a request for your app. The default value of an HTTP client does not always identify the device.

Native app integrations (iOS)

• Format: [app_name]/[app_version] ([device]; CPU iPhone OS [os_version] like Mac OS X)
• Example: MyApp/3.2.1 (iPhone; CPU iPhone OS 17_6 like Mac OS X)

Alternatively, if your app uses URLSession and has access to the CFNetwork/Darwin version numbers:

• Format: [app_name]/[app_version] CFNetwork/[cfnetwork_version] Darwin/[darwin_version]
• Example: MyApp/3.2.1 CFNetwork/1474 Darwin/23.0.0

Native app integrations (Android)

• Format: [app_name]/[app_version] (Linux; Android [os_version]; [device_model])
• Example: MyApp/3.2.1 (Linux; Android 14; Pixel 8)

Key

• [app_name]/[app_version]: your application name and version (e.g., MyApp/3.2.1)
• [device]: the iOS device type: iPhone, iPad, etc.
• [os_version]: OS version using underscores for iOS (e.g., 17_6) or dots for Android (e.g., 14)
• [device_model]: the Android device model (e.g., Pixel 8, SM-G960U)

Query parameters

i,s - mandatory

In a native app, there are no beacon cookies. Read the values from the mobile SDK instead: clientID and sessionID in the iOS / Swift SDK, getClientId() and getSessionId() in the Android / Kotlin SDK.

ui - mandatory for logged-in users

A unique internal identifier for a logged-in user. Used for cross device personalization.

Note: If the user is not logged in, then omit this parameter.

c

Specification of this parameter is only necessary when a client library is not being utilized.

This parameter identifies the client the request is coming from and it should have the following format: cio-[fe/be]-[platform]-[company name]

Where:

• [fe/be] indicates a frontend or backend integration
• [platform] indicates web or mobile platform
• [company name] indicates the name of the company in lowercase (should correspond with company name in dashboard)

Examples:

• The request is coming from a website - cio-fe-web-farmstand
• The request is coming from a mobile app - cio-fe-mobile-farmstand
• The request is coming from a backend server - cio-be-web-farmstand
• The request is coming from a backend server for a mobile app - cio-be-mobile-farmstand

origin_referrer

The page URL of the originating client side request

_dt

Current UNIX timestamp of request (ex: 1634170420420)

Client libraries

The suite of Constructor client helper libraries simplify the process of sending the parameters listed above. For the JavaScript, iOS, and Android libraries, see the documentation for each library in Client libraries / SDKs. For more detailed instructions on how to send the required backend parameters within each client library, please refer to the relevant GitHub Wiki entry: Node, Java, .NET, Python