Conversion API

Integration Guide for Advertisers

Overview

The Paramount Conversion API (CAPI) enables advertisers to send server-side conversion events directly to Paramount. These signals are used for measurement and, in future phases, to power closed-loop ad optimization on Paramount properties. This guide covers everything you need to integrate: authentication, the event schema, validation rules, batching, and privacy requirements.

Contents

Getting Started
Authentication
Sending Events
Event Schema
Privacy Requirements
Batching
Validation Rules
Responses
Sample Requests
Implementation Checklist
Appendix Field Reference

1. Getting Started

1.1 Prerequisites

Before you can send events to the CAPI you need:

An executed partnership agreement with Paramount Ads
A provisioned API key (issued per dataset — see Section 1.2)
A dataset ID (data_set_id) assigned to your integration
Your events formatted as JSON — the CAPI does not accept flat files or XML

1.2 Datasets and API Keys

A dataset (identified by a data_set_id) represents a logical grouping of conversion events — typically one per campaign, product line, or business unit. You may have multiple datasets. Each dataset has its own API key.

Important
API keys are issued only after executed terms are in place. Contact your Paramount Ads representative to request a dataset and key. Keys must be kept confidential and should never be embedded in client-side code.

1.3 Base URL

https://events.paramount.tech/v1

2. Authentication

All requests must include a Bearer token in the Authorization header. The token is your API key, issued by Paramount at dataset setup.

Authorization: <your_api_key>
Content-Type: application/json
Accept: application/json

Key scope

Each API key is scoped to a single data_set_id. If you operate multiple datasets, you will have a separate key for each.

3. Sending Events

3.1 Endpoints

Method	Endpoint	Use
POST	/v1/events	Send a single event
POST	/v1/events/batch	Send up to 1,000 events in a single request — preferred for offline or CRM data
GET	/v1/schema/events	Retrieve the current event schema for reference

3.2 When to Send Events

Send events server-to-server, not from the browser
Send as close to the time of the event as possible
Events older than 30 days will be rejected
Events between 7 and 30 days old are accepted but flagged as late — they will not be eligible for optimization
For offline or CRM data, use the batch endpoint

4. Event Schema

Every event is a JSON object. The top-level fields are described below, followed by the identifiers and privacy objects.

4.1 Top-Level Event Object

{
  "data_set_id":       "string",       // required
  "timestamp":         1746558464,     // required — Unix epoch (integer)
  "event_type":        "purchase",     // required — see Section 4.3
  "custom_event_name": "string",       // required if event_type = "custom"
  "source":            "website",      // context of event origin
  "referer":           "string",       // referring URL
  "page_url":          "string",       // page where event occurred
  "value":             129.99,         // transaction value (float)
  "currency_code":     "USD",          // required if value is sent (ISO 4217)
  "identifiers":       { ... },        // required — see Section 4.2
  "privacy":           { ... },        // see Section 5
  "custom_data":       { ... },        // optional freeform key-value pairs
  "mmt_only":          false,          // true = measurement only, no optimization
  "ext":               {}              // reserved for future use
}

Note on event_id

Paramount generates a unique event_id for every event on our side. You do not need to supply one. Each submission response includes a submission_id you can use to reference the batch or event in follow-up queries.

4.2 Identifiers

At least one identifier is required per event. All identifiers must be hashed — the CAPI does not accept plaintext PII of any kind. Events submitted without at least one valid identifier will be rejected.

Field	Type	Required	Notes
email_sha256	string	If available	Lowercase SHA-256 hash of the email address. Normalize to lowercase before hashing.
ifa	string	If available	Advertising ID for CTV or mobile environments.
ip	string	If available	SHA-256 hashed IPv4 address.
partner_id	string	Optional	Opaque advertiser-provided ID for future crosswalk use. Recommended format: hashed or opaque string, max 512 characters. Do not send raw PII in this field.

Required field logic

The 'if available' fields are optional individually, but at least one of them must be present per event. An event with no identifiers at all will be rejected with a 400 error.

4.3 Event Types

The event_type field must contain one of the standard values listed below, or the value "custom" paired with a custom_event_name.

event_type value	Description
purchase	A completed transaction or purchase
page_view	A page on the advertiser website was viewed.
ad_impression	A user was exposed to an ad impression.
add_to_wishlist	An item was added to a wishlist
add_to_cart	An item was added to a cart for purchase.
viewed_cart	A purchase cart was viewed.
viewed_item	An item or product page was viewed.
begin_checkout	A user has begun a checkout flow.
add_payment_info	A user submitted their payment information in a checkout flow.
remove_from_cart	An item was removed from a cart.
refund	One or more items was refunded to a user.
generate_lead	A lead was generated.
qualify_lead	A user is identified as a qualified lead.
close_convert_lead	A lead has been converted and closed.
disqualify_lead	A lead has become disqualified.
close_unconvert_lead	A user is identified as failing to become a converted lead.
sign_up	A user signed up for an account or offer.
search	A user has performed a search.
unlock_achievement	A user unlocked an achievement.
install	An app install.
customize_product	A user customized a product.
contact	A user contact.
donate	A donation was made.
find_location	A user searches for a location.
schedule	A user schedules an appointment.
start_trial	A user begins a trial.
subscribe	A user subscribes to a product or service.
custom	Any event not covered above. Must be paired with a custom_event_name field.

4.3.1 Additional Event Types

These event types are also considered standard values for the event_type field, but are usually shared as a lower priority by advertisers.

event_type value	Description
add_shipping_info	A user submitted shipping information.
share	A user shared content.
select_content	A user selected content.
select_item	A user selected an item from a list.
select_promotion	A user selected a promotion from a list.
view_item_list	A user viewed a list of items.
view_promotion	A user viewed a promotion.
view_search_results	A user was presented with the results of a search.
spend_virtual_currency	A user spent virtual currency.
earn_virtual_currency	A user earned virtual currency.
working_lead	A user contacted, or was contacted by, a representative.
login	A user logged in to a website or app.
join_group	A user joined a group.
level_up	A user leveled up in a game.
post_score	A user posted a score.
tutorial_begin	A user started an on-boarding process.
tutorial_complete	A user completed an on-boarding process.

4.4 Custom Data

The custom_data object accepts any key-value pairs you want to associate with an event. Common uses include transaction IDs, product identifiers, promotional codes, and search terms. There are no fixed required fields within custom_data for V1 — include what is meaningful for your integration.

"custom_data": {
  "transaction_id": "txn_abc123",
  "product_id":     "SKU-4892",
  "coupon":         ["SAVE10"],
  "search_term":    "running shoes"
}

5. Privacy Requirements

Please read this section carefully — events that fail privacy checks will be rejected and not stored.

5.1 GPP Consent Strings & Other Privacy Preference Signals

The Global Privacy Platform (GPP) provides a standardized way to communicate consumer consent and privacy signals. If your systems have access to a GPP consent string for the user associated with an event, you should include it. Where an alternative signal has been implemented to indicate data eligibility, the parties will determine whether that signal can be supported.

Field	Type	Notes
gpp_string	string	The full GPP consent string for the user. Required in regulated US states if available.
gpp_sid	array	Array of applicable GPP section IDs. Required when gpp_string is provided.
us_privacy_string	string	Legacy US privacy string (IAB CCPA format). Optional, for backwards compatibility.

How consent is handled

If a GPP string is present: Paramount will validate it and honor the signal. An invalid GPP string will cause the event to be rejected.
If no GPP string is present: the event will proceed through standard processing. You are not required to provide a GPP string for every event, but you are responsible for ensuring your data collection practices comply with applicable privacy laws. The absence of a GPP or otherwise agreed upon equivalent signal serves as your confirmation that you have already applied all necessary controls to exclude data that is ineligible for standard processing. You remain responsible for ensuring your data practices comply with applicable laws.

5.2 Your Obligations

By sending events to the Paramount CAPI, you represent that:

You have a lawful basis for processing and sharing the conversion data
You have provided appropriate notice to the individuals whose data is included
You will honor opt-outs and deletion requests in your own systems
You will not send events for individuals who have opted out of data sharing for advertising purposes
You will not send plaintext PII — all identifiers must be hashed as specified in Section 4.2

6. Batching

For offline conversions, CRM data, or any case where you are sending multiple events at once, use the batch endpoint.

6.1 Batch Request Format

POST /v1/events/batch
Authorization: Bearer <your_api_key>
Content-Type: application/json

[
  {
    "data_set_id":   "021686f2-0726-41dc-b304-be721b76c1e5",
    "timestamp":     1774553505,
    "event_type":    "purchase",
    "source":        "website",
    "value":         129.99,
    "currency_code": "AUD",
    "identifiers": {
      "email_sha256": "d2ee19013eb3911e2c5006e3312da331df3504977e545e2098d4df46b0a20993"
    },
    "custom_data": {
      "transaction_id": "txn_001",
      "page_url":       "https://example.com/checkout",
      "coupon":         ["SAVE10"],
      "search_term":    "blue sneakers"
    },
    "mmt_only": false,
    "ext": {}
  },
  {
    /* next event object */
  }
]

6.2 Batch Limits

Limit	Value
Maximum events per request	1,000
Recommended batch size	500 events for optimal performance
Maximum payload size	~5 MB

If you have more than 1,000 events to send, please split them into multiple requests.

7. Validation Rules

The CAPI validates every event before accepting it. Events that fail validation are rejected and not stored. You will receive a descriptive error response indicating which field or rule failed.

7.1 Required Fields

data_set_id — must match a provisioned dataset
timestamp — Unix epoch integer, not a string
event_type — must be a valid IAB type or 'custom'
At least one identifier — from the identifiers object
currency_code — required if value is included

7.2 Rejection Conditions

Condition	What happens	Code
Missing required field	Event is rejected, not stored	400
Invalid event_type value	Event is rejected, not stored	400
No identifiers provided	Event is rejected, not stored	400
Plaintext PII detected in identifier fields	Event is rejected, not stored	400
Event timestamp older than 30 days	Event is rejected, not stored	400
Event timestamp 7–30 days old	Accepted but flagged as late — ineligible for optimization	200
Invalid GPP string (if provided)	Event is rejected, not stored	400
Invalid or missing API key	Request is rejected	403

8. Responses

8.1 Success Response — 200

Returned when an event or batch has been received and accepted for processing.

// Single event
{
  "submission_id": "single.80aace59-9cc5-4611-8946-23e1959fa7f8",
  "received_at":   "2026-04-17T18:22:10Z",
  "status":        "RECEIVED"
}

// Batch
{
  "submission_id": "batch.6baa0ea5-042c-446f-babf-49081080e1fc",
  "received_at":   "2026-04-17T18:22:10Z",
  "status":        "RECEIVED"
}

8.2 Error Response — 400

Returned when an event fails schema or validation checks. The response will include an error code and a human-readable message describing the failure.

{
  "status":     "error",
  "error_code": "MISSING_IDENTIFIER",
  "message":    "At least one hashed identifier is required."
}

8.3 Other Status Codes

Code	Meaning
200	Event(s) accepted
400	Invalid schema, missing fields, or validation failure
403	Authentication failure — invalid or missing API key
500	Internal server error — retry with exponential backoff

Async processing

A 200 response means the event has been received and queued for processing — it does not mean the event has been fully validated and stored. Processing is asynchronous. If you receive a 200 and your event does not appear in reporting, contact your Paramount Ads representative.

9. Sample Requests

9.1 Minimal Valid Event

The smallest event the CAPI will accept — one required identifier, no optional fields.

POST /v1/events
Authorization: Bearer <your_api_key>
Content-Type: application/json

{
  "data_set_id": "your_dataset_id",
  "timestamp":   1746558464,
  "event_type":  "purchase",
  "identifiers": {
    "email_sha256": "b94d27b9934d3e08a52e52d7da7dabfac484efe04294e576ca..."
  }
}

9.2 Full Event with Privacy Signal

A complete event including value, custom data, and a GPP consent string.

POST /v1/events
Authorization: Bearer <your_api_key>
Content-Type: application/json

{
  "data_set_id":   "your_dataset_id",
  "timestamp":     1746558464,
  "event_type":    "purchase",
  "source":        "website",
  "value":         129.99,
  "currency_code": "USD",
  "identifiers": {
    "email_sha256": "b94d27b9934d3e08a52e52d7da7dabfac484efe04294e576ca...",
    "ip":           "5891b5b522d5df086d0ff0b110fbd9d21bb4fc7163af34d0..."
  },
  "privacy": {
    "gpp_string": "DBABMA~...",
    "gpp_sid":    [7]
  },
  "custom_data": {
    "transaction_id": "txn_00123",
    "product_id":     "SKU-4892"
  },
  "mmt_only": false
}

9.3 Batch Request

Sending multiple events in a single request.

POST /v1/events/batch
Authorization: Bearer <your_api_key>
Content-Type: application/json

[
  {
    "data_set_id":   "your_dataset_id",
    "timestamp":     1746558464,
    "event_type":    "purchase",
    "value":         49.99,
    "currency_code": "USD",
    "identifiers":   { "email_sha256": "b94d27b..." },
    "mmt_only":      false
  },
  {
    "data_set_id":   "your_dataset_id",
    "timestamp":     1746558500,
    "event_type":    "sign_up",
    "identifiers":   { "email_sha256": "a3f82c1..." },
    "mmt_only":      false
  }
]

10. Implementation Checklist

Before going live, confirm each of the following:

☐	Item
☐	Executed partnership agreement and DPA in place with Paramount
☐	API key and data_set_id received from Paramount Ads
☐	API key stored securely server-side
☐	All identifier values are hashed (SHA-256, lowercase) before sending
☐	event_type values map to valid event types or use 'custom' with custom_event_name
☐	timestamp is sent as a Unix epoch integer — not a formatted date string
☐	GPP consent strings are passed when available
☐	Retry logic is in place for 500 responses (exponential backoff recommended)
☐	Batch requests are under 1,000 events and ~1 MB

Appendix: Field Reference

Quick reference for all top-level event fields.

Field	Type	Required	Notes
data_set_id	string	Yes	Provided by Paramount at setup
timestamp	integer	Yes	Unix epoch. Events >30 days old are rejected.
event_type	string	Yes	IAB standard type or 'custom'
identifiers	object	Yes	At least one hashed ID required
event_id	string	System generated	Generated by Paramount. Not sent by the advertiser.
custom_event_name	string	Conditional	Required when event_type = 'custom'
value	float	Optional	Transaction value. Requires currency_code if set.
currency_code	string	Conditional	ISO 4217. Required when value is present.
source	string	Optional	Origin context: 'website', 'app', 'offline', 'crm', etc.
privacy	object	Optional	Include GPP string and SID when available
custom_data	object	Optional	Freeform key-value pairs for additional context
mmt_only	boolean	Optional	Set true to restrict this event to measurement use only. Default: false.
referer	string	Optional	Referring URL for the event
page_url	string	Optional	Page or screen where the event occurred