Postman Guide

This guide helps developers quickly test and integrate the In-Chat Recommendations API using Postman.

---

1) Create a Postman Request

Request Name

In-Chat Recs - Fetch Ads

Method

POST

Production Endpoint

https://mv.outbrain.com/Multivac/api/in-chat-recs

---

2) Configure Query Parameters

In Postman, go to the Params tab and add the following:

Key	Required	Example Value	Notes
key	✅ Yes	YOUR_KEY	Your unique API Key
contentUrl	✅ Yes	test.com	URL-encoded host page
widgetJSId	✅ Yes	APP_12	Provided by Teads
cors	✅ Yes	true	Must be true
testMode	❌ No	true	Use for development testing

Final request URL example:

https://mv.outbrain.com/Multivac/api/in-chat-recs?key=YOUR_KEY&contentUrl=test.com&widgetJSId=APP_12&cors=true&testMode=true

---

3) Configure Headers

Go to the Headers tab:

Header	Value
Content-Type	application/json

---

4) Configure JSON Body (Contextual Signals)

Go to Body → raw → JSON and paste:

{
  "keywords": ["investing", "savings", "personal finance"],
  "iabCategories": ["IAB13"]
}

Notes:

• keywords should reflect the real-time chat context
• iabCategories should contain IAB taxonomy categories (example: "IAB13")

---

5) Send the Request

Click Send.

If successful, the response will contain:

• documents[] → the recommended ad cards
• tracking.reportServed → impression pixel endpoint

---

6) Understand the Response

Key Fields Per Ad (documents[])

Field	Description	How to Use
url	Destination link	Wrap the title/image
thumbnail_url	Creative image URL	Display as ad image
content	Headline/title	Main ad text
source_display_name	Advertiser name	Show “Sponsored by …”
target_domain	Advertiser domain	Display for transparency
pos	Ad position index	Critical for reporting
cta	Call-to-action label (optional)	Button label

Tracking Object

The tracking object contains the reportServed URL. This is the endpoint used to notify Teads that an ad was actually seen by the user.

---

7) Reporting Impressions (Pixel Firing)

To ensure monetization, fire the reportServed pixel as soon as the ads are rendered.

Where to Find the Pixel

In the response:

"tracking": {
  "reportServed": "https://mcdp-nldc1.outbrain.com/writePartialStats?token=..."
}

How to Construct the Final Pixel URL

Append the positions (pos) of all displayed ads using:

&pos=X-Y

Example

If you render ads at positions 0 and 2:

https://mcdp-nldc1.outbrain.com/writePartialStats?token=...&pos=0-2

Recommended Client-side Method

Fire it as a GET request or use:

• navigator.sendBeacon(pixelUrl)

---

8) Testing Pixel Reporting in Postman

You can validate impression reporting directly in Postman:

Create a new request

Name: Report Served Pixel

Method

GET

URL Example

https://mcdp-nldc1.outbrain.com/writePartialStats?token=...&pos=0-2

Click Send.

If the request returns a successful HTTP status (commonly 200), the pixel was fired correctly.

---

9) Example Integration Flow

1. User sends chat message
2. Extract contextual intent → keywords / IAB category
3. Call the API (POST /in-chat-recs)
4. Render some of the returned ad cards
5. Fire the impression pixel (tracking.reportServed + &pos=...)

---

10) JavaScript Example (End-to-End)

async function getAds() {
  const url =
    "https://mv.outbrain.com/Multivac/api/in-chat-recs" +
    "?contentUrl=example.com&widgetJSId=APP_12&key=YOUR_KEY&cors=true";

  const response = await fetch(url, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      keywords: ["finance"],
      iabCategories: ["IAB13"]
    })
  });

  const data = await response.json();

  // Render the first ad headline
  const ad = data.documents[0];
  console.log(`Displaying Ad: ${ad.content} by ${ad.source_display_name}`);

  // Report that the first ad was served
  if (data.tracking?.reportServed) {
    const pixel = `${data.tracking.reportServed}&pos=${ad.pos}`;
    navigator.sendBeacon(pixel);
  }
}

---

Postman Collection Tip (Recommended)

Create Postman variables:

Variable	Example
baseUrl	https://mv.outbrain.com/Multivac/api/in-chat-recs
apiKey	YOUR_KEY
widgetJSId	APP_12
contentUrl	test.com

Then build the URL like:

{{baseUrl}}?key={{apiKey}}&contentUrl={{contentUrl}}&widgetJSId={{widgetJSId}}&cors=true&testMode=true