# Events API

> Current Froomle documentation · [View canonical page](https://docs.froomle.com/froomle-doc-main/v2/api_reference/events/events_api.html)

Events are at the heart of Froomle. They represent the actions the user takes on your website, which fuel our machine learning models. Use the [Event Model and Tracking Contract](https://docs.froomle.com/froomle-doc-main/v2/guide/topics/tracking-events.html) to decide which events to send. For implementation, use [Frontend SDK event tracking](https://docs.froomle.com/froomle-doc-main/v2/js_lib/jslib.html#EventTracking) or [Manual Event Integration](https://docs.froomle.com/froomle-doc-main/v2/guide/manual-integration/events.html).

To stream these events to the Froomle platform you use your personal HTTP API at subdomain.froomle.com. This URL is followed by /api/_environment_/events. The Froomle support team will decide on the values of _subdomain_ and _environment_ with you at kick-off of the project.

> **NOTE:**
> 
> Events API calls are unauthenticated. Do not send an OAuth `Authorization` header with event requests.

<a id="_back_end_integration"></a>

## Back-end integration

When integrating Froomle into a back-end service, it is recommended to send events to the endpoint in batches. Implementing this is especially applicable during peaks of high traffic and will speed up the response time. The recommended amount of time between two batches is 500 milliseconds. Delays up to 1 second are acceptable. Delays up to 5 seconds have a potential negative influence on the quality of recommendations. Delays >1 minute have a guaranteed negative effect on the quality of recommendations.

<a id="_front_end_integration"></a>

## Front-end integration

When integrating Froomle into a front-end service, the events have to be sent as they occur. For events that occur in rapid succession or at the same time (e.g. multiple impression events), it is still recommended to send events in a single request to the endpoint.

<a id="_image_based_get_integration"></a>

## Image-based GET integration

For channels such as email, Froomle can configure selected event types to accept fields as `GET` query parameters. A valid request records the event and redirects to a small PNG, allowing the endpoint to be used as an image-based tracking pixel. Availability and required fields depend on your environment configuration.

For the customer-facing setup, HTML example, privacy guidance, and measurement limitations, see [Track message opens with an image request](https://docs.froomle.com/froomle-doc-main/v2/guide/manual-integration/events.html#ManualTrackingPixel).

<a id="_specification"></a>

## Specification

<a id="_events_api_events_post_event"></a>

### Log an event of any form to the Froomle Event API.

```
POST /{environment}/events
```

<a id="_parameters"></a>

#### Parameters

| Type | Name | Description | Schema |
| --- | --- | --- | --- |
| **Path** | **environment**<br>_required_ | The environment for which this event is sent. | string |
| **Body** | **body**<br>_required_ |  | [body](https://docs.froomle.com/froomle-doc-main/v2/api_reference/events/events_api.html#_events_api_events_post_event_body) |

**body**

| Name | Schema |
| --- | --- |
| **events**<br>_required_ | < [Event](https://docs.froomle.com/froomle-doc-main/v2/api_reference/events/events_api.html#_event) > array |

<a id="_responses"></a>

#### Responses

| HTTP Code | Description | Schema |
| --- | --- | --- |
| **200** | Event was accepted and will be processed. | No Content |
| **400** | The event body was not in the right format or was missing mandatory information. | No Content |
| **400** | "Events contain errors: …​…​. See exact response for details. Typical examples include channel/page\_type/list\_name with an invalid value or missing mandatory fields." | No Content |
| **415** | The event body is not of type json. | No Content |
| **500** | Something went wrong while processing. | No Content |

<a id="_consumes"></a>

#### Consumes

-   `application/json`
    

<a id="_curl_example"></a>

### cURL Example

```console
$ curl --location --request POST 'https://{subdomain}.froomle.com/api/{environment}/events' \
--header 'Content-Type: application/json' \
--data-raw '{
  "events": [
    {
        //send whenever a user visits an item detail page (regardless of a Froomle module being shown)
        "event_type": "detail_pageview",
        "page_type": "article_detail",
        "device_id" : "the_device_id-123",
        "user_id" : "the_user_id-123",
        "action_item" : "the_action_item_id",
        "action_item_type": "article",
        "channel" : "www-desktop",
        "site_context" : "example.com",
        "subscription_level" : "SUBSCRIPTION",
        "page_url": "https://example.com/articles/the-current-article",
        "referrer_url": "https://www.google.com/",
        "referrer_type": "external",
        "referrer_origin": "https://www.google.com",
        "referrer_domain": "www.google.com"
    },
    {
        //send whenever a user gets a recommendation in view
        "event_type": "impression",
        "page_type": "home",
        "device_id" : "the_device_id-123",
        "user_id" : "the_user_id-123",
        //data from the recommendation
        "list_name" : "The list name",
        "action_item" : "the_action_item_id-123",
        "action_item_type" : "article",
        "request_id": "6461",
        "channel": "mobile-app",
        "site_context": "specific.example.com",
        "subscription_level": "REGISTERED",
        "user_group": "froomle"
    },
    {
        //send whenever a user clicks on a recommendation (Froomle or baseline)
        "event_type": "click_on_recommendation",
        "page_type": "home",
        "device_id" : "the_device_id-123",
        "user_id" : "the_user_id-123",
        //data from the recommendation
        "list_name" : "The list name",
        "action_item" : "the_action_item_id-123",
        "action_item_type" : "article",
        "request_id": "6461",
        "channel": "mobile-app",
        "site_context": "specific.example.com",
        "subscription_level": "REGISTERED",
        "user_group": "froomle"
    },
    {
        //send whenever a user visits a page other than an item detail page (regardless of a Froomle module being shown)
        "event_type": "page_visit",
        "page_type": "home",
        "device_id" : "the_device_id-123",
        "user_id" : "the_user_id-123",
        "channel" : "www-desktop",
        "site_context" : "example.com",
        "subscription_level" : "NONE",
        "page_url": "https://example.com/",
        "referrer_type": "direct"
    },
    {
        //send when a user purchases an item
        "event_type": "purchase",
        "device_id" : "the_device_id-123",
        "user_id" : "the_user_id-123",
        "action_item": "the_action_item_id-123",
        "action_item_type": "product",
        "amount": 10,
        "original_price": 29.99,
        "purchased_price": 9.99,
        "channel": "www-mobile",
        "site_context": "specific.example.com",
        "subscription_level": "SUBSCRIPTION"
    }
  ]
}'
```

<a id="_definitions"></a>

## Definitions

<a id="_event"></a>

### Event

For all supported event types, see [Event Model and Tracking Contract](https://docs.froomle.com/froomle-doc-main/v2/guide/topics/tracking-events.html).

_Polymorphism_ : Composition

| Name | Description | Schema |
| --- | --- | --- |
| **device\_id**<br>_required_ | Unique identifier of the current user’s session, usually stored in a cookie. Use the value `"no-consent"` for users that wish to remain anonymous. | string |
| **site\_context**<br>_optional_ | Customer-defined site, subdomain, edition, or similar analytics context for dashboard segmentation, for example `example.com` or `specific.example.com`. | string |
| **subscription\_level**<br>_optional_ | Current visitor subscription or entitlement state for the event. Accepted values: `NONE`, `REGISTERED`, `TRIAL`, `SUBSCRIPTION`. This is independent of item `access_type` and event `subscription_type`. | string |
| **utm\_id**, **utm\_source**, **utm\_medium**, **utm\_campaign**, **utm\_source\_platform**, **utm\_term**, **utm\_content**, **utm\_creative\_format**, **utm\_marketing\_tactic**<br>_optional_ | Optional UTM campaign parameters for event analytics. Browser SDK integrations can copy them from the current URL; manual Events API integrations may provide them directly. | string |
| **page\_url**, **referrer\_url**, **referrer\_type**, **referrer\_origin**, **referrer\_domain**<br>_optional_ | Optional browser page/referrer source fields for event analytics. Browser SDK integrations derive them from `window.location.href` with the URL fragment removed and `document.referrer`; manual Events API integrations may provide them directly. `referrer_type` should be `direct`, `internal`, or `external`. `referrer_url` is only as complete as the browser exposes through `document.referrer`. | string |
| **user\_id**<br>_optional_ | User id of the authenticated user | string |
| **event\_type**<br>_optional_ | needs to be exactly `Event` | string |
| **action\_item**<br>_required_ | The item id of the item interacted with | string |
| **action\_item\_type**<br>_required_ | Type of the item interacted with | string |