Getting Started

This guide helps developers connect a chatbot or web client to Teads’ AI Chatbot SDK and Partner APIs. It distills the integration steps, parameters, and best practices you need to go live quickly and safely.

What you’ll implement

Fire measurement events from your chatbot/SDK.

Fetch publisher (organic) content.

Fetch marketer (paid) content.

(Optional) Render a single paid unit widget on mobile layouts.

Track viewability and click events correctly.

Prerequisites

API keys and widget IDs provisioned by Teads/Partner:
- {YOUR_MEASUREMENT_API_KEY}, {YOUR_MEASUREMENT_WIDGET_ID}
- {YOUR_CONTENT_API_KEY}, {YOUR_ORGANIC_WIDGET_ID}, {YOUR_PAID_WIDGET_ID}
- {YOUR_INSTALLATION_KEY} (for the optional paid widget)
Ability to make HTTPS GET requests from your app/server.
Your page’s canonical URL, URI-encoded and without query params: {ENCODED_CONTENT_URL}.

Environment tip: Never expose API keys in client code. Prefer a server proxy to sign or forward requests.

Endpoints & Formats

Base URL (Production): https://mv.outbrain.com
Base path: /Multivac/api/platforms
Method: HTTP GET with query parameters
Auth: API Key
Responses: JSON (use format=vjnc)

Common Query Parameters

Required for all flows unless noted:

contentUrl — URI-encoded canonical URL of the current page (no query params or fragments).
key — API key provisioned by Teads/Partner.
widgetJSId — Widget identifier provisioned per flow.
idx — Index of the slot/request. Use 0 for single-slot.
format — Response format. Use vjnc.
cors — Must be true.

Optional:

testMode — Set to true for development/QA. Use this in all non‑production tests.

Quick Start (5 Steps)

Prepare the canonical URL of the current page and URI-encode it → {ENCODED_CONTENT_URL}.
Pick the flow you need (Measurement / Publisher content / Marketer content).
Construct the GET URL with the required common parameters + flow‑specific parameters.
Send the request over HTTPS. Handle JSON (vjnc) responses where applicable.
Fire required events within timing/viewability rules (see Event Firing below).

Flow 1 — Measurement API

Purpose: fire measurement-only events from the Teads SDK. You do not need to process the response.

Trigger: send one request per event with an extid describing the event.
- Examples: unit_load, unit_view, unit_click, chatbot_load.
Required params: contentUrl, extid, idx=0, format=vjnc, cors=true, key, widgetJSId
Optional: testMode=true

Example (replace placeholders)

https://mv.outbrain.com/Multivac/api/platforms
  ?contentUrl={ENCODED_CONTENT_URL}
  &key={YOUR_MEASUREMENT_API_KEY}
  &widgetJSId={YOUR_MEASUREMENT_WIDGET_ID}
  &idx=0
  &format=vjnc
  &cors=true
  &extid=unit_load
  &testMode=true

Notes

Ignore the response body for Measurement flow.
Fire promptly; ensure time‑sensitive events occur within 3 minutes of render.

cURL snippet

curl -G "https://mv.outbrain.com/Multivac/api/platforms"   --data-urlencode "contentUrl={ENCODED_CONTENT_URL}"   --data-urlencode "key={YOUR_MEASUREMENT_API_KEY}"   --data-urlencode "widgetJSId={YOUR_MEASUREMENT_WIDGET_ID}"   --data-urlencode "idx=0"   --data-urlencode "format=vjnc"   --data-urlencode "cors=true"   --data-urlencode "extid=unit_load"   --data-urlencode "testMode=true"

JavaScript (fetch)

const params = new URLSearchParams({
  contentUrl: "{ENCODED_CONTENT_URL}",
  key: "{YOUR_MEASUREMENT_API_KEY}",
  widgetJSId: "{YOUR_MEASUREMENT_WIDGET_ID}",
  idx: "0",
  format: "vjnc",
  cors: "true",
  extid: "unit_load",
  testMode: "true"
});

fetch(`https://mv.outbrain.com/Multivac/api/platforms?${params.toString()}`, {
  method: "GET",
  mode: "cors",
  credentials: "omit"
});

Flow 2 — Publisher Content API (Organic)

Purpose: fetch organic recommendations.

Required params: contentUrl, idx, news, newsFrom=US, format=vjnc, cors=true, key, widgetJSId
Supported categories: vary by country and are determined by user geolocation or the newsFrom parameter.
Optional: testMode=true

Example (replace placeholders)

https://mv.outbrain.com/Multivac/api/platforms
  ?contentUrl={ENCODED_CONTENT_URL}
  &key={YOUR_CONTENT_API_KEY}
  &widgetJSId={YOUR_ORGANIC_WIDGET_ID}
  &idx=0
  &format=vjnc
  &cors=true
  &news=latest
  &newsFrom=US
  &testMode=true

cURL snippet

curl -G "https://mv.outbrain.com/Multivac/api/platforms"   --data-urlencode "contentUrl={ENCODED_CONTENT_URL}"   --data-urlencode "key={YOUR_CONTENT_API_KEY}"   --data-urlencode "widgetJSId={YOUR_ORGANIC_WIDGET_ID}"   --data-urlencode "idx=0"   --data-urlencode "format=vjnc"   --data-urlencode "cors=true"   --data-urlencode "news=latest"   --data-urlencode "newsFrom=US"   --data-urlencode "testMode=true"

JavaScript (fetch)

const params = new URLSearchParams({
  contentUrl: "{ENCODED_CONTENT_URL}",
  key: "{YOUR_CONTENT_API_KEY}",
  widgetJSId: "{YOUR_ORGANIC_WIDGET_ID}",
  idx: "0",
  format: "vjnc",
  cors: "true",
  news: "latest",
  newsFrom: "US",
  testMode: "true"
});

const res = await fetch(`https://mv.outbrain.com/Multivac/api/platforms?${params}`, {
  method: "GET",
  mode: "cors",
  credentials: "omit"
});
const data = await res.json(); // vjnc schema

Flow 3 — Marketer Content API (Paid)

Purpose: fetch paid recommendations.

Required params: contentUrl, idx, format=vjnc, cors=true, key, widgetJSId
Optional: testMode=true

Example (replace placeholders)

https://mv.outbrain.com/Multivac/api/platforms
  ?contentUrl={ENCODED_CONTENT_URL}
  &key={YOUR_CONTENT_API_KEY}
  &widgetJSId={YOUR_PAID_WIDGET_ID}
  &idx=0
  &format=vjnc
  &cors=true
  &testMode=true

cURL snippet

curl -G "https://mv.outbrain.com/Multivac/api/platforms"   --data-urlencode "contentUrl={ENCODED_CONTENT_URL}"   --data-urlencode "key={YOUR_CONTENT_API_KEY}"   --data-urlencode "widgetJSId={YOUR_PAID_WIDGET_ID}"   --data-urlencode "idx=0"   --data-urlencode "format=vjnc"   --data-urlencode "cors=true"   --data-urlencode "testMode=true"

JavaScript (fetch)

const params = new URLSearchParams({
  contentUrl: "{ENCODED_CONTENT_URL}",
  key: "{YOUR_CONTENT_API_KEY}",
  widgetJSId: "{YOUR_PAID_WIDGET_ID}",
  idx: "0",
  format: "vjnc",
  cors: "true",
  testMode: "true"
});

const res = await fetch(`https://mv.outbrain.com/Multivac/api/platforms?${params}`, {
  method: "GET",
  mode: "cors",
  credentials: "omit"
});
const data = await res.json();

Use on mobile layouts; renders a single paid unit. Container width is responsive.

Set data-ob-contentUrl to the canonical page URL.
Ensure HTTPS.

<div class="OUTBRAIN"
     data-ob-contentUrl="{PAGE_URL}"
     data-widget-id="MB_1"
     data-ob-installation-key="{YOUR_INSTALLATION_KEY}"></div>

<script type="text/javascript" async src="https://widgets.outbrain.com/outbrain.js"></script>

Implementation reference: https://developer.outbrain.com/using-js-widget-in-web-mediation/

Event Firing & Tracking

Widget‑level (required)

reportServed

Fire as soon as the unit is rendered on the user’s device.
Fire once per response.
Must execute within 3 minutes of render.

Listing‑level

doc.on-viewed (required): trigger when ≥50% of a listing is in viewport continuously for 1s.
doc.pixels (required): fire up to 5 image pixels client‑side per listing.
- If server‑side pixels are necessary, coordinate with your Teads account team.
doc.jsTrackers (optional): execute JS trackers client‑side only.
doc.clickTrackers (optional): fire all listed pixel URLs on user click.

Click Handling

Paid recommendations

Navigate to doc.url exactly as provided (often starts with http://paid.outbrain.com/network/redir or equivalent).
Do not append additional redirects or modify the URL.
This ensures click registration in Partner reporting.

Organic recommendations

Option 1 (simple): navigate directly to doc.url (e.g., http://traffic.outbrain.com/network/redir).
Option 2 (split): navigate user to doc.orig_url while sending a parallel request to doc.url to register the click.

Testing & Verification Checklist

Use testMode=true in all development/QA requests.
Validate:
- contentUrl is canonical and URI‑encoded (no query params/fragments).
- Response parsing aligns with vjnc format.
- Events fire under the correct timing and viewability conditions.
Expect possible feedback from Teads. Unresolved items can delay or restrict monetization.

Best Practices

Parameters

contentUrl must be canonical and URI‑encoded; strip query parameters and fragments.
Provide stable widgetJSId per placement; keep idx consistent for single‑slot (0).

Security

HTTPS only for all requests and assets.
Never expose API keys in public client code. Prefer a secure server proxy.

Performance

Batch conservatively; avoid unnecessary refreshes.
Ensure trackers execute asynchronously to prevent UI jank.

Provisioning & Configuration

Measurement API: use your dedicated measurement key and measurement widget ID.
Organic/Paid APIs: use the content API key. Provision distinct widget IDs for organic and paid placements.

Placeholders for implementation

{YOUR_MEASUREMENT_API_KEY}
{YOUR_CONTENT_API_KEY}
{YOUR_MEASUREMENT_WIDGET_ID}
{YOUR_ORGANIC_WIDGET_ID}
{YOUR_PAID_WIDGET_ID}
{YOUR_INSTALLATION_KEY}
{ENCODED_CONTENT_URL} — URI‑encoded canonical page URL.

Troubleshooting

4xx errors: confirm keys, widgetJSId, required params, and contentUrl encoding.
Empty responses: check format=vjnc, idx, flow‑specific params, and testMode usage.
Clicks not registering: verify you navigate to doc.url unchanged; ensure click trackers fire.
Viewability undercounted: re-check the 50% / 1s rule and event timing within 3 minutes.

Support

For endpoint access, provisioning, and validation, contact your Teads account team.

Getting Started

Prerequisites​

Endpoints & Formats​

Common Query Parameters​

Quick Start (5 Steps)​

Flow 1 — Measurement API​

Example (replace placeholders)​

cURL snippet​

JavaScript (fetch)​

Flow 2 — Publisher Content API (Organic)​

Example (replace placeholders)​

cURL snippet​

JavaScript (fetch)​

Flow 3 — Marketer Content API (Paid)​

Example (replace placeholders)​

cURL snippet​

JavaScript (fetch)​

(Optional) Paid Unit Widget — Client‑Side​

Event Firing & Tracking​

Widget‑level (required)​

Listing‑level​

Click Handling​

Paid recommendations​

Organic recommendations​

Testing & Verification Checklist​

Best Practices​

Provisioning & Configuration​

Troubleshooting​

Support​

Prerequisites

Endpoints & Formats

Common Query Parameters

Quick Start (5 Steps)

Flow 1 — Measurement API

Example (replace placeholders)

cURL snippet

JavaScript (fetch)

Flow 2 — Publisher Content API (Organic)

Example (replace placeholders)

cURL snippet

JavaScript (fetch)

Flow 3 — Marketer Content API (Paid)

Example (replace placeholders)

cURL snippet

JavaScript (fetch)

(Optional) Paid Unit Widget — Client‑Side

Event Firing & Tracking

Widget‑level (required)

Listing‑level

Click Handling

Paid recommendations

Organic recommendations

Testing & Verification Checklist

Best Practices

Provisioning & Configuration

Troubleshooting

Support