# Audience Event Onboarding

Collect, activate, and measure marketing events with the Event API through
server-side data collection. Linked to a MathTag (aka MediaMath event pixel),
server-side events are processed like events from a MediaMath JavaScript or
image tag but avoid the placement of code on your site or in your app. These
events can be used just like an on-site MathTag, collecting marketing events
for use in targeting, optimization, segmentation & lookalike modeling, and
measurement.

We offer two options for collecting marketing events via the Event API:

- Individual event collection, recommended for server-side tag manager
integrations and any real-time marketing event collection
- Batch event collection, recommended for CDPs, DMPs, visitation measurement,
and other offline conversion event collection in bulk


### Server Events vs Client (Browser) Events

On the web, a client refers to a web browser or mobile device—whatever the
consumer is using to navigate the Internet. The server refers to a program or
device that returns web pages to be rendered in a browser or mobile app.
Collecting a marketing event client-side means the action takes place on the
consumer’s browser or device and collecting a marketing event server-side
means the action takes place on a server.

There are different reasons and pros/cons to both options, which is why
MediaMath offers a variety of audience data onboarding solutions. Consider the
questions below when deciding whether the Event API is right for you:

- Is site latency a concern?
- Is the activity you want to distribute to the MediaMath platform happening
offline or offsite?
- How important is real-time activation & optimization?
- What percentage of your site visitors employ ad blockers?
- Do you have engineering resources to support server-side event collection?


## Getting Started

As part of the provisioning process, you will receive the following from
MediaMath:

For individual, real-time server-side event collection:

- **MathTag** (aka MediaMath event pixel) **ID** (_this may be provided by a
mutual client, created in the MediaMath platform, &/or created with the
MediaMath API)


For batch, server-side event collection:

- **Batch event API key** (note: this key is separate from the Client ID &
Secret used to authenticate with other MediaMath APIs)
- **Mapping ID** (1 per MathTag ID)
- **MathTag** (aka MediaMath event pixel) **ID** (_this may be provided by a
mutual client, created in the MediaMath platform, &/or created with the
MediaMath API)


### Data Partners: What to Expect During the Setup Process

All data partners distributing data to MediaMath need a MediaMath vendor
account. The vendor account organizes your data for use in our systems and,
for certain data providers, will be referenced for reporting & financial
purposes.

There are several steps prior to onboarding data with MediaMath:

1. **Choose the integration method(s) best suited for your needs.** Depending
on the marketing data you have, one or more audience data onboarding solutions
from MediaMath may meet your needs. This set of server-side event collection
solutions are best suited for using audience data for retargeting,
optimization, 1P segmentation & modeling, and attribution in the MediaMath
platform.
2. **Engage with the partnerships team.** They will help you establish a
vendor account and, in some cases, determine the structure of a commercial
agreement (i.e. for 3rd party data providers). Prior to reaching out to the
partnerships team, familiarize yourself with the
[MediaMath Audience Data Policy](http://www.mediamath.com/legal/terms/audiencedata_policy).
3. **Verify Batch Event API access and deliver a Batch Event payload.** With
confirmation of successful event delivery, access to deliver data on behalf of
MediaMath customer accounts will be granted.
4. **Determine the appropriate attribute fields**: MediaMath will provide you
with our Event API Mapping Template along with a complete list of attributes
we support. Use the template to determine the appropriate "From" fields - what
the attribute fields are named in the partner's system, and determine the
appropriate "To" fields - the attribute fields used by MediaMath, and which
the "From" fields will be mapped to. Once you fill out the mapping template
with the appropriate Advertiser Name, Advertiser ID and mapping attributes,
submit a request to [support@mediamath.com](mailto:support@mediamath.com) for a new API key (if you already
do not have one) and a new mapping ID.


Example:

**From** | **To**         | **Data Type**

sku      | product_id     | String

order_id | order_id       | String

price    | product_price  | String

### Clients: What to Expect During the Setup Process

All MediaMath clients may distribute their 1P data to MediaMath for their use
as part of a standard services agreement.

If you wish to monetize your data assets, you will follow the steps above as a
data partner so that financial reporting can take place.

## Common Parameters

The following parameters are used across both real-time and batch event collection methods.

| Parameter | Required/Optional | Data Type | Description |
|  --- | --- | --- | --- |
| mt_id | Required | integer | MathTag (event pixel) ID |
| mt_adid | Required | integer | Advertiser ID |
| mt_uuid | Required | string | UUID for the event. Accepted values: MediaMath 3P cookie IDs, mobile advertising IDs, Connected TV device IDs. Format: standard GUID (128-bit hexadecimal: 8-4-4-4-12). Only standard GUID format UUIDs are accepted. New UUID formats and types are being added regularly. If you have a specific ID format you'd like to use, please contact your MediaMath representative to check compatibility. |
| mt_ts | Optional | 10-digit epoch (seconds) | UNIX timestamp. Overwrites transaction timestamp. **Note**: Setting a historical timestamp will subject the event record to MediaMath event processing rules and may impact data processing downstream. |
| mt_ip | Recommended | string | IPv4 address where the event occurred. When specified, mt_uuid becomes optional. When mt_uuid is not provided, a random UUID will be generated internally. This generated ID will not be used for retargeting and attribution. Format: Valid public IPv4 address (e.g., "203.0.113.1"). Do not use private IP ranges (10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16) or loopback addresses (127.0.0.0/8) as these have little usefulness for retargetting or attribution. |


### Event API Limits

The Event API has rate limiting in place. If you have concerns about the
limits outlined below, please contact the data partnerships team to discuss
your needs.

For individual, real-time server-side event collection:

- 1k QPS


For batch, server-side event collection (rate limited by API key):

- 10 QPS
- Up to 5 concurrent requests
- 50k total requests per day, per Batch event API key


## Real-time Server-Side Event Collection

### Confirm Required Parameters

**Pixel ID** (mt_id) is a required parameter and an integer. If a MathTag is
already set-up on your website, you can use the same Pixel ID for your browser
and server-side events. For format and acceptance details, see the
[mt_id](#mt_id) entry in the Common Parameters section.

**Advertiser ID** (mt_adid) is a required parameter and an integer. If you're
a data partner, ask your client to locate their advertiser ID in the Admin
section of the MediaMath platform or to reach out to their account team for
assistance. For format and acceptance details, see the [mt_adid](#mt_adid)
entry in the Common Parameters section.

**UUID** (mt_uuid) is a required parameter and a string. Accepted values
include MediaMath 3P cookie IDs, obtained via syncing, mobile advertising IDs,
and Connected TV device IDs. For format, acceptance details, and usage notes,
see the [UUID (mt_uuid)](#mt_uuid) entry in the Common Parameters
section.

**Source** (source) is a required parameter and a string. You'll append
&source=s2s to every record produced, which enables tracking and monitoring
of the data collected.

### Generate Pixel ID

If you don’t already have a Pixel ID, it can be created in the MediaMath
platform, &/or created with the MediaMath API. If you’re a data partner, ask
your client to provide a pixel ID in the Audiences section of the MediaMath
platform or to reach out to their account team for assistance.

### Test Individual Event Distribution

**Requests**
To send events, POST a request to pixel-s2s.mathtag.com from this path:


```json
https://pixel-s2s.mathtag.com/event/img?mt_id=(pixel_id)&mt_adid=(advertiser_id)&mt_uuid=(browser or device ID)&source=s2s
```

### Verify Event Distribution

After you send events, confirm they have been received in the MediaMath
platform. Note, if you are a data partner working on behalf of a mutual
client, ask the client or MediaMath support to confirm loads & uniques for the
pixel ID(s).

### Set-up & Distribute Event Parameters

Once you have verified event distribution, review the website or app and the
list of recommended parameters below to determine if any additional metadata
should be distributed to MediaMath. For marketing use cases that include 1P
segmentation & modeling or attribution, selecting relevant recommended
parameters will support activation in the MediaMath platform.

## Batch Server-Side Event Collection

### Confirm Required Parameters

**Version** is a required parameter and an integer. Set this to 4.0.

**Type** is a required parameter and a string.

**Mapping ID** (mapping_ID) is a required parameter and a string. This will be
provided by the MediaMath team during initial set-up. As there is a 1:1
relationship between Mapping ID and MathTag (aka MediaMath event pixel) ID,
subsequent mapping IDs may be required.

**Advertiser ID** (advertiser_ID) is a required parameter and an integer. If
you're a data partner, ask your client to locate their advertiser ID in the
Admin section of the MediaMath platform or to reach out to their account team
for assistance.

**Advertiser ID Usage**: The advertiser ID can be specified at the top level
or overridden per-event using the `mt_adid` attribute within the `attributes`
array.

- **Top-level advertiser_id**: Use when all events in your request belong to
the same advertiser. This is the default advertiser for all events in the
request.
- **mt_adid attribute**: Use when sending events for multiple advertisers in a
single batch request. Specify `mt_adid` within each events' attributes array
to override the top-level value for that specific event.


**Attributes** is required and an Array of Objects. Each object is a
dictionary of attributes and their values. Required parameters for each event
(`mt_id`, `mt_adid`, `mt_uuid`) must be included within the attributes array.

**Pixel ID** (mt_id) is a required parameter and an integer. If you've already
set up a MathTag for your website, we recommend that you use the same Pixel ID
for your browser and server events. For format and acceptance details, see the
[mt_id](#mt_id) entry in the Common Parameters section.

**UUID** (mt_uuid) is a required parameter and a string. Accepted values
include MediaMath 3P cookie IDs, obtained via syncing, mobile advertising IDs,
and Connected TV device IDs. For format, acceptance details, and usage notes,
see the [UUID (mt_uuid)](#mt_uuid) entry in the Common Parameters section.

### Generate Pixel ID

If you don’t already have a Pixel ID, it can be created in the MediaMath
platform, &/or created with the MediaMath API. If you’re a data partner, ask
your client to provide a pixel ID in the Audiences section of the MediaMath
platform or to reach out to their account team for assistance.

### Test Batch Event Distribution

**Requests**
The batch endpoint supports individual and batch event distribution (up to 100
events per request) to MediaMath. To send events, POST a request to
`https://ingest-default.prod.octane.mediamath.com/v1/event(s)`

*Individual event request
Use: `https://ingest-default.prod.octane.mediamath.com/v1/event`*


```json
{  
    "version": 4.0,  
    "type": "event",  
    "mapping_id": "[YOUR_MAPPING_ID]",  
    "advertiser_id": [YOUR_ADVERTISER_ID],  
    "attributes": [ 
        { 
            "mt_id": "[YOUR_PIXEL_ID]",
            "mt_adid": "[YOUR_ADVERTISER_ID]",
            "mt_uuid": "[DEVICE_UUID]",
            "[YOUR_KEY]": "[YOUR_VALUE]" 
        } 
    ] 
}
```

*Batch event request
Use: `https://ingest-default.prod.octane.mediamath.com/v1/events`*


```json
{ 
    "events": [ 
        { 
            "version": 4.0,  
            "type": "event",  
            "mapping_id": "[YOUR_MAPPING_ID]",  
            "advertiser_id": [YOUR_ADVERTISER_ID],  
            "attributes": [ 
                { 
                    "mt_id": "[YOUR_PIXEL_ID]",
                    "mt_adid": "[YOUR_ADVERTISER_ID]",
                    "mt_uuid": "[DEVICE_UUID]",
                    "[YOUR_KEY]": "[YOUR_VALUE]" 
                } 
            ] 
        }, 
        { 
            "version": 4.0,  
            "type": "event",  
            "mapping_id": "[YOUR_MAPPING_ID]",  
            "advertiser_id": [YOUR_ADVERTISER_ID],  
            "attributes": [ 
                { 
                    "mt_id": "[YOUR_PIXEL_ID]",
                    "mt_adid": "[YOUR_ADVERTISER_ID]",
                    "mt_uuid": "[DEVICE_UUID]",
                    "[YOUR_KEY]": "[YOUR_VALUE]" 
                } 
            ] 
        }, 
        { 
            "version": 4.0,  
            "type": "event",  
            "mapping_id": "[YOUR_MAPPING_ID]",  
            "advertiser_id": [YOUR_ADVERTISER_ID],  
            "attributes": [ 
                { 
                    "mt_id": "[YOUR_PIXEL_ID]",
                    "mt_adid": "[YOUR_ADVERTISER_ID]",
                    "mt_uuid": "[DEVICE_UUID]",
                    "[YOUR_KEY]": "[YOUR_VALUE]" 
                } 
            ] 
        } 
    ]      
}
```

### Review Responses

| Code | Message | Description |
|  --- | --- | --- |
| 200 | Ok | Event(s) received |
| 400 | Invalid request body | Request missing required fields |
| 400 | Mapping not found | Mapping ID does not exist |
| 403 | Forbidden | Missing or invalid x-api-key |
| 415 | Unsupported media type | Content-Type is not application/json |
| 429 | Too many requests | Rate limit exceeded |


## Recommended Parameters

We support 200+ optional marketing event attributes, including up to 40 custom
attributes per MediaMath event pixel. An attribute is a key and the
information you transmit to MediaMath is the value paired with it.

- If an attribute is not relevant for a given marketing event record, leave
the value blank (e.g. &page-name=).
- Do not include a currency symbol when passing revenue; use the currency
attribute to declare currency.
- Only include salted & hashed values when passing email addresses or customer
IDs; **never** include personally identifiable information (PII).


### Recommended parameters for conversions

| Attribute | Parameter | Data Type | Example use case |
|  --- | --- | --- | --- |
| Revenue | v1 | numeric | Representing the total value of the transaction, revenue value is used to inform MediaMath Platform attribution (for ROAS / ROI goals) and can be used to build 1P audience segments based on transaction size |
| Currency | v2 | string | Representing the currency in which the transaction was recorded, currency value is important for brand's that operate in more than one currency type |


Additional parameters may be useful, but for most conversion attribution use
cases we recommend providing revenue captured from the conversion activity.
Revenue attribution is used to inform the MediaMath Brain which attribute to
use for revenue when optimizing towards ROI. If your site or app supports
multiple currencies, provide that value as well. MediaMath supports either
fixed or dynamic currency, if your site or app supports multiple currencies.

### Recommended parameters for retailers

| Attribute | Parameter | Data Type | Example use case |
|  --- | --- | --- | --- |
| Order ID | order_id | string | Representing a consumer's order in your system, this value can be useful for [log level data](/apis/log-level-data-service) analytics, like customer classification and sales insights |
| Revenue | v1 | numeric | Representing the total value of the transaction, revenue value is used to inform MediaMath Platform attribution (for ROAS / ROI goals) and can be used to build 1P audience segments based on transaction size |
| Currency | v2 | string | Representing the currency in which the transactions was recorded, currency value is important for brands' that operate in more than one currency type |
| Product ID | product_id | string | Representing a SKU, this value uniquely identifies the products you sell. The value can be used to build 1P audience segments for remarketing and cross-selling purposes |
| Product Name | product_name | string | Representing the name of the product, this value can be used to build 1P audience segments for product level marketing efforts |
| Product Category | product_category | string | Representing a higher-level grouping of products, this value can be used to build 1P audience segments for product level marketing efforts |


### Recommended parameters for B2B

| Attribute | Parameter | Data Type | Example use case |
|  --- | --- | --- | --- |
| Client Status | client_status | string | Representing your classification of your customers (e.g. new, existing, preferred, etc.), this value can be used to build 1P audience segments for loyalty marketing efforts |
| Hashed Customer ID | mt_excl | string | Representing your customer's unique identifier, salted and hashed with SHA256. **Never** include personally identifiable information (PII). Use either mt_excl (customer ID) or mt_exem (email) but not both, aligned with privacy by design principles to minimize personal data shared. |
| Hashed Email Address | mt_exem | string | Representing your customer's email address, salted and hashed with SHA256. **Never** include personally identifiable information (PII). Use either mt_excl (customer ID) or mt_exem (email) but not both, aligned with privacy by design principles to minimize personal data shared. |
| Page Name | page_name | string | Representing the page the consumer visited, this value can be used to build 1P audience segments based on content consumption over a period of time |


*Note*: if you're considering passing your customer's IDs or email addresses, we recommend only passing one of the hashed values. This aligns with the approach of privacy by design to minimize the amount of personal data shared. If you opt to only pass one hashed value, the unused attribute's parameter can be omitted or passed without a value (e.g. mt_excl=). All hashed values should be salted & hashed with SHA256. **Never** include personally identifiable information (PII).