> For the complete documentation index, see [llms.txt](https://addressable.gitbook.io/knowledge-base/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://addressable.gitbook.io/knowledge-base/event-tracking/addressable-event-api/events-api-reference.md).

# Events API - Reference

In complex use cases, where the user journey includes 3rd party platforms/applications (e.g. Telegram chatbot, Mobile Sandboxed WebApp, Discord, Telegram games), the best way to report on user engagement and conversion events is directly from your server to your Addressable account using a secure API. 

## Request Structure

The Addressable API has a request structured with the following fields:

* An endpoint url: <https://tag.adrsbl.io/events/prod_standard_stage/p.png>
* Three parameters:
  1. `is_conversion`\
     Use `is_conversion=true`, When you wish to designate an event as a conversion event for it to be recognized as such across all counters that track attributed conversions in our product. \
     Use `is_conversion=false` for all other events.\ <mark style="color:red;">**Note:**</mark>**&#x20;You can have multiple conversion events with this attribute set to true**

  2. `data`\
     `data` is a base64-wrapped JSON parameter that contains event metadata according to the table below.

<table data-full-width="true"><thead><tr><th width="246">Parameter Name</th><th>Is Mandatory</th><th width="132.8">Type</th><th width="349">Value</th><th>Usage</th></tr></thead><tbody><tr><td><code>tid</code></td><td><strong>Mandatory</strong></td><td>String</td><td>Addressable pixel ID which can be found under 'Settings' in your Addressable account.</td><td>For associating events with your tenant</td></tr><tr><td><code>page_url</code></td><td><strong>Mandatory</strong></td><td>String</td><td>The page URL that generated the event can also be represented simply as a string.</td><td>For tracking users as they move between different pages of your website / funnel.</td></tr><tr><td><code>event_name</code></td><td><strong>Mandatory</strong></td><td>String</td><td>The name of the event as you’d like it to be displayed on our platform</td><td>For identifying user events that lead to actions</td></tr><tr><td><code>timestamp</code></td><td><strong>Mandatory</strong></td><td>Int</td><td>Timestamp of the event in UTC</td><td>Ability to filter by time</td></tr><tr><td><code>timezone_name</code></td><td><strong>Mandatory</strong></td><td>String</td><td>User reported timezone for time offset calculation.<br>E.g America/New_York</td><td>Ability to filter by the user's time</td></tr><tr><td><code>timezone_offset</code></td><td><strong>Mandatory</strong></td><td>Int</td><td>The number of seconds in which the user timezone is offset from UTC time.</td><td>Ability to filter by the user's time</td></tr><tr><td><code>referrer</code></td><td>Optional</td><td>String</td><td>The page URL which referred to the page that generated the event. It may be an empty string.</td><td>For makreting channel drilldown, to understand where the traffic is coming from</td></tr><tr><td><code>address</code></td><td>Optional</td><td>String</td><td>The wallet address of the tracked user if known to you on the page where the event was triggered.</td><td>A wallet address is one of the identifiers used to track user events within your system. Addressable also enriches wallets with on-chain data, offering a comprehensive view of your users.</td></tr><tr><td><code>chain_id</code></td><td>Optional</td><td>String</td><td>If the blockchain ID is known to you on the page where the event was triggered, please specify it here.<br>For example, for the Ethereum chain, send "0x1".</td><td>Ability to filter by blockchain and track user actions on various blockchains</td></tr><tr><td><code>extension_provider</code></td><td>Optional</td><td>String</td><td>Name of wallet provider if known to you when the event is triggered.<br>E.g “MetaMask”.</td><td>The ability to filter by wallet provider is available on our interface.</td></tr><tr><td><code>properties</code></td><td>Optional</td><td>List of Jsons</td><td>See below for instructions on how to utilize the properties field.</td><td></td></tr></tbody></table>

Based on the table above, a request could be formulated in the following manner:

<details>

<summary>Typical Request Example</summary>

<https://tag.adrsbl.io/events/prod\\_standard\\_stage/p.png?is\\_conversion=false\\&data=eyJ0aWQiOiAiPHlvdXIgdGlkIGdvZXMgaGVyZT4iLCAiZXZlbnRfbmFtZSI6ICJleGFtcGxlX2V2ZW50IiwgInBhZ2VfdXJsIjogInRlbGVncmFtIiwgInJlZmVycmVyIjogImh0dHBzOi8vdC5tZSIsICJ0aW1lc3RhbXAiOiAxNzIzMzQ0NjQ4LCAidGltZXpvbmVfbmFtZSI6ICJBbWVyaWNhL05ld19Zb3JrIiwgInRpbWV6b25lX29mZnNldCI6IDI0MCwgImV4dGVuc2lvbl9wcm92aWRlciI6Ik1ldGFNYXNrIiwgImFkZHJlc3MiOiAiMHgwMDBjRDI3RjEwZEZGQUM3MzIwMTI1OEVBQTM5MjVjMDQ1MjA1MUEwIiwgImNoYWluX2lkIjogIjB4YTRiMSIsICJleHRlbnNpb25fcHJvdmlkZXIiOiAiTWV0YU1hc2siLCAicHJvcGVydGllcyI6IFt7Im5hbWUiOiAidXNlcl9pZCIsICJ2YWx1ZSI6ICJ1dWlkLXZhbHVlLWdvZXMtaGVyZSJ9LCB7Im5hbWUiOiAicGFyYW0yIiwgInZhbHVlIjogInZhbHVlMiJ9LCB7Im5hbWUiOiAicGFyYW0zX25vX3ZhbHVlIn1dfQ%3D%3D>

</details>

{% hint style="info" %}
Requests sent to our servers must be URL-encoded. Refer to [how URL encoding works](https://www.urlencoder.io/learn/) for more detailed information.
{% endhint %}

{% hint style="info" %}
Include`"Content-Type": "application/json"` header in the request when sending it.
{% endhint %}

3. Request Headers\
   Please use the following headers to pass user information to our servers. Refer to the table below:

<table data-full-width="true"><thead><tr><th>Header</th><th>Is Mandatory</th><th>Value</th><th>Usage</th></tr></thead><tbody><tr><td>Content-Type</td><td><strong>Mandatory</strong></td><td>application/json</td><td>For proper functioning of server-to-server API</td></tr><tr><td>Accept-Language</td><td>Optional</td><td>Use the original user's Accept-Language header and not your server's header</td><td>For drilldown and filtering based on user attributes: i.e languages</td></tr><tr><td>User-Agent</td><td>Optional</td><td>Use the original user's User-Agent header and not your server's header</td><td>For drilldown and filtering on user's OS type, Browser Type, Platform etc.</td></tr><tr><td>X-Forwarded-For</td><td><strong>Mandatory</strong></td><td>User original IP address</td><td>extract country information for each session. In compliance with GDPR and SOC2 regulations, IP addresses are retained for no more than one week. Country data, once extracted, is stored per user_id for your breakdown use.</td></tr><tr><td>X-Requested-With</td><td>Optional</td><td>User mobile referrer app</td><td>For drilldown and filtering - identification of the user orgin app before landed on your app (mobile referrer)</td></tr></tbody></table>

## **Event Properties**

In the context of utilizing the Addressable Pixel, our software manages the definition of user sessions and user IDs.\
Conversely, the responsibility for managing S2S events lies with you.

To improve your comprehension of user behavior, make use of the `properties` field to record key/value parameters that aid in understanding user behavior. This field comprises a list of JSON objects, where each key/value pair represents a specific property and its corresponding value.\
Refer to the example below for guidance on accurate properties reporting:

{% code lineNumbers="true" %}

```json
"properties": [{"name": "customer", "value": "mycustomer"},
               {"name": "username", "value": "Billy Bob"},
               {"name": "free_plan"}]
```

{% endcode %}

In the example provided, three parameters were established. The first two parameters consist of both a name and a value, while the third parameter only includes a name.

## **Proper Attribution**

These events will be reported independently&#x20;

## **Code Example**

Please refer to the following Python code snippet demonstrating how to generate a request to our servers:

{% code overflow="wrap" lineNumbers="true" fullWidth="true" %}

```python
import json
import base64
import requests

data = json.dumps({"tid": "<your tid goes here>",
                   "event_name": "example_event",
                   "page_url": "https://app.example.com/test-tomer?a=1&b=2&c=3",
                   "referrer": "https://app.example.com/",
                   "timestamp": 1730538892,
                   "timezone_name": "America/New_York",
                   "timezone_offset": 240,
                   "extension_provider":"MetaMask",
                   "address": "0x000cD27F10dFFAC73201258EAA3925c0452051A0",
                   "chain_id": "0xa4b1",
                   "properties": [{"name": "user_id", "value": "uuid-value-goes-here"},
                                  {"name": "param2", "value": "value2"},
                                  {"name": "param3_no_value"}]}

params = {"data": base64.b64encode(data.encode())}

headers = {
    "Content-Type": "application/json",
    "Accept-Language": "en-US,en;q=0.9",
    "User-Agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/130.0.0.0 Safari/537.36",
    "X-Forwarded-For": “1.1.1.1”,
    "X-Requested-With": "io.metamask"}

url = 'https://tag.adrsbl.io/events/prod_standard_stage/p.png?is_conversion=false'
res = requests.get(url, params=params, headers=headers)
```

{% endcode %}

&#x20;For technical assistance and troubleshooting, contact us at <support@addressable.io>&#x20;

&#x20;

\ <br>


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://addressable.gitbook.io/knowledge-base/event-tracking/addressable-event-api/events-api-reference.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.