> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pureclarity.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 1. Server-side

# Server-side

Unlike the client-side method, requests to PureClarity are made on the server, rather than the client's browser. This requires the PureClarity API to be called directly from your server-side code. Choose the appropriate endpoint based on where your store was created.

## API Base URL

**EU Region:** `https://api-eu-w-1.pureclarity.net/api/serverside`

**US Region:** `https://api-us-e-1.pureclarity.net/api/serverside`

## Endpoint

### POST /api/serverside

Send tracking data and request personalised content

## Request Schema

<ParamField path="appId" type="string" required>
  Your store views unique access key. This can be found in the PureClarity Admin console

  **Example:** `testAppId`
</ParamField>

<ParamField path="secretKey" type="string" required>
  The secret key provided for all store view level calls. This can be found in the PureClarity Admin console. Remember never to disclose your SecretKey

  **Example:** `testSecretKey`
</ParamField>

<ParamField path="currentUrl" type="string" required>
  The page url that the user is currently on.

  **Example:** `http://www.yoursite.com/shop/product/abc123`
</ParamField>

<ParamField path="userAgent" type="string" required>
  The users browser User Agent string, in all request headers sent by their browser.

  **Example:** `Mozilla/5.0 (compatible; Googlebot/2.1; +http://www.google.com/bot.html)`
</ParamField>

<ParamField path="ip" type="string" required>
  The users IP address

  **Example:** `208.67.222.222`
</ParamField>

<ParamField path="visitorId" type="string">
  The user's unique PureClarity Visitor ID. This is stored as a browser cookie and set by PureClarity. Discussed in the Cookies documentation

  **Example:** `testVisitorId`
</ParamField>

<ParamField path="sessionId" type="string">
  The user's unique PureClarity Session ID, that represents their current visit. This is set by PureClarity and is stored as a browser cookie. Discussed in the Cookies documentation

  **Example:** `testSessionId`
</ParamField>

<ParamField path="referer" type="string">
  The referer value from the users browser header. This is the page that the user has come from, not this current page

  **Example:** `http://www.yoursite.com/shop/`
</ParamField>

<ParamField path="currency" type="string">
  Set's the currency of the products to be returned. The value should be a valid ISO currency code. If not present the default currency configured in PureClarity will be used. Only products that have been sent to PureClarity with this currency price will be returned

  **Example:** `USD`
</ParamField>

<ParamField path="events" type="array">
  An array of tracking event objects

  Each event object contains:

  * **name** (string, required): The identifier of the track event (e.g., `product_view`)
  * **data** (object): The contextual data that accompanies the tracking event. Format determined by the event type (e.g., `{"id": "abc123"}`)
</ParamField>

## Response Schema

<ParamField path="visitorId" type="string">
  The user's unique PureClarity visitor ID. This should be set as the `pc_v_<access_key>` cookie in the users browser. The expiry of the `pc_v_<access_key>` cookie should be set to unlimited

  **Example:** `testVisitorId`
</ParamField>

<ParamField path="sessionId" type="string">
  The user's unique PureClarity session ID for the current visit. This should be set as the `pc_sessid_<access_key>` cookie in the users browser. The expiry of the `pc_sessid_<access_key>` cookie should be set to 5 minutes

  **Example:** `testSessionId`
</ParamField>

<ParamField path="errors" type="array">
  Contains each error that occurred should there be any issues

  Array of string error messages
</ParamField>

<ParamField path="zones" type="object">
  An object that contains the result for each zone on the requested page. Each key property name, with an object that represents the zone content data

  **Example:** `{"HP01": {"type": "staticimage"}}`
</ParamField>

## Example Request

```json theme={null}
{
  "appId": "testAppId",
  "secretKey": "testSecretKey",
  "currentUrl": "http://www.yoursite.com/shop/product/abc123",
  "userAgent": "Mozilla/5.0 (compatible; Googlebot/2.1; +http://www.google.com/bot.html)",
  "ip": "208.67.222.222",
  "visitorId": "testVisitorId",
  "sessionId": "testSessionId",
  "referer": "http://www.yoursite.com/shop/",
  "currency": "USD",
  "events": [
    {
      "name": "page_view",
      "data": {
        "page_type": "product"
      }
    },
    {
      "name": "product_view",
      "data": {
        "id": "abc123"
      }
    }
  ]
}
```

## Example Response

```json theme={null}
{
  "visitorId": "testVisitorId",
  "sessionId": "testSessionId",
  "errors": [],
  "zones": {
    "HP01": {
      "type": "staticimage",
      "content": {
        "imageUrl": "https://example.com/banner.jpg",
        "linkUrl": "https://example.com/promotion"
      }
    },
    "PDP01": {
      "type": "recommender",
      "products": [
        {
          "id": "prod123",
          "title": "Related Product",
          "price": 29.99
        }
      ]
    }
  }
}
```

## Usage

Use the server-side endpoint, and pass the appropriate [tracking events](/integrations/custom/api-reference/event-tracking/overview) based on what page the user is currently on.

If you detect the user has updated their basket, send the [set\_basket](/integrations/custom/api-reference/event-tracking/set_basket) event. If the user is on a product page, send the [product\_view](/integrations/custom/api-reference/event-tracking/product_view) event. If the user has logged in, send the [customer\_details](/integrations/custom/api-reference/event-tracking/customer_details) event.

You can send multiple events in each request.

Ensure you always send the [page\_view](/integrations/custom/api-reference/event-tracking/page_view) tracking event, and set the `page_type` context. This ensures that the response from PureClarity will contain information about the personalised content to show.

<Note>
  Please read our [Implementation Methods](/integrations/custom/api-reference/getting-started/implementation-methods---client-vs-server) guide to determine whether to use client-side or server-side for your site.
</Note>

<Warning> We recommend you use our client-side implementation unless they have a specific requirement for using our server-side API.</Warning>