> 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/postback-event-api-setup-guide.md).

# Postback Event API Setup Guide

Addressable’s Events API is a modern **server-to-server postback**: your backend reports key funnel events (page\_views, signups, wallet connects, purchases, etc.) so they can be attributed to campaigns and used for optimization.

## <mark style="background-color:yellow;">Choose Setup Path</mark>

#### **Path A (Recommended):** Addressable Pixel + Postback API

* Use this if you can install the Addressable Pixel on your site.
* This is the recommended setup for campaign attribution and is the easiest to maintain.

#### **Path B (No Pixel At All):** Postback API only

* Only use this if you **do not have** a pixel set up on your Addressable account.
* Some organizations have compliance policies that restrict tracking pixels.
* If you have a true “no pixel” policy, follow the S2S-only setup.

> **Important**: Only use Path B if the Pixel is not installed at all and cannot be installed.&#x20;

***

## <mark style="background-color:yellow;">Path A (Recommended):</mark>

If you’re using both the Pixel and the Events API, follow this path.

**Process Overview**

1. Install the Addressable Pixel (Page View is automatic)
2. Capture the browser id `___adrsbl_nonce` and store it with your user record
3. Send Events API postbacks with `properties.user_id = ___adrsbl_nonce` for attribution

### Step-by-Step

#### <mark style="background-color:yellow;">**— Step 1 —**</mark>

**Install the Addressable Pixel**

First you must install the Pixel (via GTM or JS) on your website or platform, using [this guide](https://addressable.gitbook.io/knowledge-base/integrations/addressable-pixel). Once installed, the Pixel manages sessions and user IDs on-site.

#### <mark style="background-color:yellow;">**— Step 2 —**</mark>

**Capture Addressable's ID for Users**

The Addressable Pixel creates a browser-side identifier stored in local storage:

* Key: `___adrsbl_nonce`

Read it on page load (or early in the session):

```js
const adrsblNonce = window.localStorage.getItem("___adrsbl_nonce");
```

> Debug: If `adrsblNonce` is `null`, confirm the Pixel is loading and firing on that page.

#### <mark style="background-color:yellow;">**— Step 3 —**</mark>

**Store the nonce with your user record (backend)**

When you know who the user is (login, signup, wallet connect, etc.), persist:

* your internal identifier (user id / wallet / etc.)
* the latest `adrsblNonce` you saw for them

**Example flow:** (frontend → backend)

```js
await fetch("/api/identify-addressable", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    userId: "<your-internal-user-id-or-wallet>",
    addressableUserId: adrsblNonce
  })
});
```

#### <mark style="background-color:yellow;">**— Step 4 —**</mark>

**Send postbacks via the Events API (Server-to-Server)**

#### A. Endpoint + parameters

* Endpoint: `https://tag.adrsbl.io/events/prod_standard_stage/p.png`
* Query params:
  * `is_conversion=true|false`
  * `data` = base64-wrapped JSON payload

{% hint style="info" %}
NOTE: Requests must be **URL-encoded**.
{% endhint %}

#### B. Required attribution field (Pixel + API join)

In your `data` JSON, include:

```json
"properties": [
  { "name": "user_id", "value": "<___adrsbl_nonce value>" }
]
```

This “join key” allows Addressable to attribute server-side events to the same user sessions the Pixel observed. ([Addressable](https://addressable.gitbook.io/knowledge-base/apis/events-api-server-to-server/attribution-with-addressable-pixel-recommended))

#### C. Required headers

Include these headers:

* `Content-Type: application/json` (mandatory) ([Addressable](https://addressable.gitbook.io/knowledge-base/apis/events-api-server-to-server))
* `X-Forwarded-For: <user original IP>` (mandatory) ([Addressable](https://addressable.gitbook.io/knowledge-base/apis/events-api-server-to-server))
* `Accept-Language` / `User-Agent` (optional but recommended: pass the user’s original values) ([Addressable](https://addressable.gitbook.io/knowledge-base/apis/events-api-server-to-server))

#### D. Use the Events API Example – Recommended

The Events API docs include a ready-to-use code example showing the correct encoding and request format.\
The only “Pixel + API” requirement is that your `properties` includes `user_id` with the stored nonce value.

#### <mark style="background-color:yellow;">**— Step 5 —**</mark>

**While this is optional, it is recommended. Include revenue parameters for ROAS and deduplication.**

{% hint style="info" %}
When possible send the revenue events over the Pixel, if that's not possible, this will help you set it up using an API event call.
{% endhint %}

If you want ROAS + deduplication support, include revenue-related parameters such as:

* `transaction_amount_usd`
* `transaction_unique_id`&#x20;

Next Step: [Follow the guide by scroll down to Revenue Reporting](#revenue-reporting).

***

## <mark style="background-color:yellow;">Path B (No Pixel At All):</mark>

This is for organizations with a true “no pixel” policy.

**Process Overview**

1. Generate/choose a persistent unique user identifier (`user_id`)
2. Send a server-side `page_view` event that includes UTMs and `ViewID`
3. Send funnel + conversion events using the same `user_id`
4. (Optional) Include revenue parameters for ROAS + deduplication

**Overview Callout**

In this setup, **you** must provide what the Pixel would normally provide:

* a persistent `user_id`
* a `page_view` (site visit) event
* tracking parameters (UTMs + `ViewID`) so Addressable can attribute post-click and post-view

### Step-by-Step

#### <mark style="background-color:yellow;">**— Step 1 —**</mark>

**Use a persistent unique user id**

Each user must have a unique identifier that persists for at least \~30 days so Addressable can correlate multiple events to the same user.

**Examples:**

* internal user id
* wallet address
* anonymous user id stored in your system

> In Path B, `user_id` is **your** identifier. (In Path A, `user_id` is reserved for the nonce join.)

#### <mark style="background-color:yellow;">**— Step 2 —**</mark>

**Send `page_view` via S2S and include tracking parameters**

{% hint style="danger" %}
Without the Pixel, it is this **`page_view`** server-side event that **enables attribution** calculations.
{% endhint %}

#### Post-click attribution (UTMs)

When a user clicks an ad, UTMs like `utm_campaign`, `utm_source`, `utm_medium`, `utm_content`, and `clickID` should be captured from the page URL and reported with the `page_view` event. ([Addressable](https://addressable.gitbook.io/knowledge-base/apis/events-api-server-to-server/attribution-without-the-addressable-pixel))

#### Post-view attribution (ViewID)

When a user views (but doesn’t click) an ad, a unique `ViewID` is provided. When the user later visits/acts, include:

* `user_id`
* the original `ViewID` ([Addressable](https://addressable.gitbook.io/knowledge-base/apis/events-api-server-to-server/attribution-without-the-addressable-pixel))

#### Where do these go in the Events API payload?

The Events API provides a `properties` array for key/value parameters. ([Addressable](https://addressable.gitbook.io/knowledge-base/apis/events-api-server-to-server))\
In “no pixel” mode, include your tracking params in `properties` (examples):

```json
"properties": [
  { "name": "user_id", "value": "<your persistent user id>" },
  { "name": "utm_campaign", "value": "<value>" },
  { "name": "utm_source", "value": "<value>" },
  { "name": "utm_medium", "value": "<value>" },
  { "name": "utm_content", "value": "<value>" },
  { "name": "clickID", "value": "<value>" },
  { "name": "ViewID", "value": "<value>" }
]
```

> You don’t need every field every time — but whatever tracking params exist for that session should be included on the `page_view`. ([Addressable](https://addressable.gitbook.io/knowledge-base/apis/events-api-server-to-server/attribution-without-the-addressable-pixel))

#### <mark style="background-color:yellow;">**— Step 3 —**</mark>

**Send funnel events + conversions via S2S**

Report funnel events via the S2S API (examples include): `page_view`, `button_click`, `sign_up`, `wallet_connect`, `conversion`.

Use:

* `is_conversion=true` for conversion events
* `is_conversion=false` for everything else

{% hint style="warning" %}
Always include the same persistent `user_id` so events chain together.
{% endhint %}

#### <mark style="background-color:yellow;">**— Step 4 —**</mark>

**While this is optional, it is recommended. Include revenue parameters for ROAS and deduplication**

If you want ROAS + deduplication support, include revenue-related parameters such as:

* `transaction_amount_usd`
* `transaction_unique_id`&#x20;

Next Step: [Follow the guide by scroll down to Revenue Reporting](#revenue-reporting).

***

## <mark style="background-color:yellow;">Revenue Reporting</mark>

Enabling Revenue Reporting unlocks ROI tracking, user-level revenue, ROAS for campaigns, and more in your Addressable dashboard. Revenue reporting applies to **both Path A and Path B**. Regardless of your setup, include revenue properties on any conversion event where a financial transaction occurs.

{% hint style="info" %}
Revenue events are usually sent as conversions. Therefore it's generally recommended to set `is_conversion=true` on any event that includes revenue properties.
{% endhint %}

#### Supported Transaction Types

Revenue must be reported using **one of the four transaction types** below. Choose the one that matches your transaction model — USD is recommended for most use cases.

<table data-card-size="large" data-view="cards" data-full-width="true"><thead><tr><th>Transaction Type</th><th>Example Use Case</th><th>Required Properties</th><th>Code Example</th></tr></thead><tbody><tr><td><strong>USD</strong> (Recommended)</td><td><ul><li>Payments</li><li>Trading</li></ul></td><td><ul><li>Unique Transaction Identifier</li><li>Transaction Amount</li></ul></td><td><pre class="language-json" data-line-numbers data-expandable="true"><code class="lang-json">"properties": [
    { "name": "transaction_id", "value": "VAC123D432" },
    { "name": "transaction_amount", "value": 50 }
]
</code></pre></td></tr><tr><td><strong>Foreign Currency Exchange</strong></td><td><ul><li>Converting EUR to USD</li></ul></td><td><ul><li>Unique Transaction Identifier</li><li>Transaction Amount</li><li>USD Exchange Rate (at time of transaction)</li></ul></td><td><pre class="language-json" data-line-numbers data-expandable="true"><code class="lang-json">"properties": [
    { "name": "transaction_id", "value": "VAC123D432" },
    { "name": "transaction_amount", "value": 150 },
    { "name": "exchange_rate", "value": "0.870132" }
]
</code></pre></td></tr><tr><td><strong>Native Token</strong></td><td><ul><li>Value transfer between wallets</li><li>Staking</li></ul></td><td><ul><li>Unique Transaction Identifier</li><li>Transaction Amount</li><li>Network/Chain ID</li></ul></td><td><pre class="language-json" data-line-numbers data-expandable="true"><code class="lang-json">"properties": [
    { "name": "transaction_id", "value": "VAC123D432" },
    { "name": "transaction_amount", "value": 150 },
    { "name": "network_id", "value": "8453" }
]
</code></pre></td></tr><tr><td><strong>Contract Token</strong></td><td><ul><li>Stablecoin payments</li><li>DeFi interactions</li></ul></td><td><ul><li>Unique Transaction Identifier</li><li>Transaction Amount</li><li>Network/Chain ID</li><li>Token Contract Address</li></ul></td><td><pre class="language-json" data-line-numbers data-expandable="true"><code class="lang-json">"properties": [
    { "name": "transaction_id", "value": "VAC123D432" },
    { "name": "transaction_amount", "value": 100 },
    { "name": "network_id", "value": "8453" },
    { "name": "token_address", "value": "0x0000000000000000000000000000000000000000" }
]
</code></pre></td></tr></tbody></table>

These properties are included in the data JSON payload alongside your other event fields — no separate request needed.

{% hint style="warning" %}
After setting up revenue tracking, contact your Addressable Customer Service representative to ensure your revenue events are properly configured on our end.
{% endhint %}

***

## Troubleshooting

#### Events are received, but attribution is missing

* **Path A:** confirm `properties` includes `{ "name":"user_id", "value":"<___adrsbl_nonce>" }` exactly.
* **Path B:** confirm your `page_view` includes `user_id` + UTMs and/or `ViewID` when present.

#### You’re not sure which path you’re on

* If the Pixel is installed and you can read `___adrsbl_nonce`, you’re on **Path A**.
* If Pixel cannot be installed due to policy, you’re on **Path B**.


---

# 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/postback-event-api-setup-guide.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.