Outbrain Content API 2.0

This document explains how to use Outbrain’s Content Endpoint API for client-to-server and server-to-server integrations. It is imperative to adhere to these instructions. Deviation from this guide can result in lost revenue.

Contact your Outbrain Account Manager if you have any questions about the requirements described in this document.

Testing & Outbrain Verification

Before launch, your app will be required to direct requests to a test server for Outbrain verification. Send testMode=true in the Outbrain request URL to prevent clicks and impressions from having any impact on our system while testing and developing.

A test page or finalized build must be sent to Outbrain QA a minimum of 5 business days before your anticipated release date. We may request changes which will require additional development resources and could delay your release.

Outbrain reserves the right to remove our recommendations or restrict the widget from generating Outbrain revenue if required changes are not incorporated prior to release. Contact your Account Manager for submission instructions.

New Partner Requirements

Review all Outbrain compliance requirements and flag any concerns/exceptions with your Partner Manager and Sales Engineer immediately.

Making an Ad Request

Client-to-Server Request

Platform	Status	Description
Regular web	Must be enabled	See XMLHttpRequest.withCredentials and fetch with credentials:include
Mobile apps	Must be disabled	Device's Advertising ID will be sent as a request parameter

Request Parameters

Base URL: 'https://mv.outbrain.com'

Endpoint: '/Multivac/api/platforms'

Name	Requirement	Description	Example
'contentUrl'	Required for web	The URI-encoded clean permalink (stripped of parameters) to identify the currently displayed content.	https://www.currentSite.com/articleName
'bundleUrl'	Required for apps	The URI-encoded store URL of the App.	`http://itunes.apple.com/<country>/app/<app-name>/id<app-ID>` `https://play.google.com/store/apps/details?id=<package_name>`
'portalUrl'	Required for native environments	Send if contentUrl & bundleUrl do not apply. A URL representing the context where the ad placement is presented to users. Does not need to be a reachable/crawlable URL.	http://www.chatPortal.com
'widgetJSId'	Required	The ID of the widget, used for reporting by placement. Your Outbrain Account Manager will provide this. Each Widget_ID has a fixed number of recommendations and image size.	APP_1
'key'	Required	Unique API key, provided by Outbrain.	DEMOP1MN24J3E1MGLQ92067LH
'api_user_id'	Required for native apps. Must be unique user session identifier	Web: do not send - we will rely on user cookies instead. Desktop apps: send a unique user ID that identifies the user during the application session. Mobile apps: It is mandatory to pass the Google or Apple Advertising ID.	38400000-8cf0-11bd-b23e-10b96e40000d
'lang'	Required for apps & native environments	The 2-letter language code (ISO-639-1-alpha-2). Must be added if bundleUrl or portalUrl is sent.	en
'idx'	Required	The current position of the widget relative to other widgets on the page: The first unit on page will have idx=0 while the second unit will have idx=1 and so on. For pages/views with only one widget installed, use idx=0 for each request.	0
't'	Optional	This token (the 't' value) is returned from the server on every request as a 'request.t' object and should be used in any consecutive request on the same page. The first request on the page should have 'idx=0' and no 't' value, while the second request on the same page should use 'idx=1' and send the 't' value returned by the first request.	ZjZkN2Q0NmRiZGRlNGRmMmNiNDVkZTlkMGU1OWFmNDQ=
'pubImpId'	Only if instructed by SE, Required for Native2Image	8-32 character string unique impression identifier - will be used as key for storing the relevant click redirect on Outbrain server side	string1234568
'pubPvId'	Only if instructed by SE, Optional	8-32 character string unique pageview id. Instead of using the 't' token in API response, a single pageview can be defined by passing a unique id. Consecutive requests can be made using the same 'pubPvId' to declare the same pageview, however, 'idx' must start from 0 and incremented for different placements.	string12345
'maxNumAds'	Only if instructed by SE, Optional	Number of ads to fetch. Typically, a static number of ads is configured for each Outbrain placement (widgetJSId). Please use it only if you require a variable number of ads on each request.	5
'maxNumOrganicRecs'	Only if instructed by SE, Optional	Number of Organic recommendations to fetch. Typically, a static number of Organic recommendations is configured for each Outbrain placement (widgetJSId). Please use it only if you require a variable number of Organic recommendations on each request.	5
'psub'	Only if instructed by SE, Optional	String value for additional section-level reporting breakdowns. Allowed characters: alphanumeric and underscore '_'. Requires permission from your Sales Engineer or Partner Manager.	minus1
'app_id'	Only if instructed by SE, Required for App Native Environment	The App's unique identifier iOS: Bundle ID, Android: Application ID/Package Name	com.king.candycrushsaga
'cors'	Required	Set to true. Send simple requests without unapproved headers which will trigger "preflighted requests".	true
'format'	Required	String value for the response format	JSON: vjnc VAST for Native2Video: vast Image for Native2Image: image
'adblck'	Optional, required for partners sending adblock traffic	Boolean value to indicate if the request is coming from an adblocker environment.	true
'testMode'	Optional	Set to true to prevent any clicks and impressions from impacting the Outbrain system while testing and developing. This parameter must be removed before releasing to production.	true
'cnsntv2'	Optional	Base64-encoded consent string, as defined by the IAB for TCF v2.0. If this is not received it is assumed no consent is given. Please do not send cnsntv2 together with the deprecated parameter "cnsnt".	CO4SiGQO4SiGQAGABBENAzCgAP_AAG...(omitted)...Q4C8yoAEAHwA.YAAAAAAAAAAA
'ccpa'	Optional	4-character consent string, as defined by the IAB. See U.S. Privacy String. Send 1 character each for Specification Version, Explicit Notice, Opt-Out Sale, and LSPA.	1YNN
'api_consent'	Only if instructed by SE, Optional	0/1 value of user's consent for personalisation. Alternative consent signal when your environment has own consent management system instead of IAB compliant TCF v2.0. Please do not send api_consent together with 'cnsntv2'.	0:Opt-out or Not decided 1: Opt-in Consent
'extid'	Optional	String value with maximum of 110 characters for use with the Engage Variant Reporting API. A maximum of 100K IDs/hour are supported. Contact your Partner Manager for API access.	tagID12345
'extid2'	Optional	String value with maximum of 110 characters. A secondary id for Engage Variant Reporting API as same as the 'extid'	tagID67890
'news'	Only if instructed by SE, Required for OB News	Pre-defined value of a single OB News category. Supported categories varies by country which is specified by either geo location of the user or 'newsFrom' parameter.	Either of: latest sports tech business entertainment lifestyle
'newsFrom'	Only if instructed by SE, Optional for OB News	The 2-letter country code of news source location. Supported countries are limited. Please use it only if you need to strictly specify the news source location.	Country: US

Server-to-Server Request

HTTP Request Headers

The server side integration must forward user's device and geolocation via HTTP request headers. In case when it's not available, e.g. Proxied traffic, the 'ob_ua' and 'location' parameters can accept generic information. However, the limited support for these information may significantly affect the performance. Please consult with your Sales Engineer if your platform cannot support these headers.

Name	Description	Example
'User-Agent'	The user’s UserAgent	Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/77.0.3865.90 Safari/537.36
'X-Forwarded-For'	The user’s IP address	233.54.67.45

Request Parameters

Base URL: 'https://mv.outbrain.com'

Endpoint: '/Multivac/api/platforms'

Parameter Name	Requirement	Description	Example
'contentUrl'	Required for web	The URI-encoded clean permalink (stripped of parameters) to identify the currently displayed content.	https://www.currentSite.com/
'bundleUrl'	Required for apps	The URI-encoded store URL of the App.	`http://itunes.apple.com/<country>/app/<app-name>/id<app-ID>` `https://play.google.com/store/apps/details?id=<package_name>`
'portalUrl'	Required for native environments	Send if contentUrl & bundleUrl do not apply. A URL representing the context where the ad placement is presented to users. Does not need to be a reachable/crawlable URL.	http://www.chatPortal.com
'widgetJSId'	Required	The ID of the widget, used for reporting by placement. Your Outbrain Account Manager will provide this. Each Widget_ID has a fixed number of recommendations and image size.	APP_1
'key'	Required	Unique API key, provided by Outbrain.	DEMOP1MN24J3E1MGLQ92067LH
'api_user_id'	Required	Desktop apps: send a unique user ID that identifies the user during the application session. Mobile apps: It is mandatory to pass the Google or Apple Advertising ID.	38400000-8cf0-11bd-b23e-10b96e40000d
'lang'	Required for apps & native environments	The 2-letter language code (ISO-639-1-alpha-2). Must be added if bundleUrl or portalUrl is sent.	en
'ob_ua'	Only if instructed by SE, Optional	Pre-defined value of generic user agents only if actual UA cannot be forwarded in HTTP headers.	Desktop devices: ob_desktop Mobile devices: ob_mobile Tablet devices: ob_tablet Unknown devices: ob_unknown_user_agent
'location'	Only if instructed by SE, Optional	The 2-letter country code of the user’s location only if actual IP address cannot be forwarded in HTTP headers.	Country: US State: US>NY DMA: US>NY>501 Zipcode: use a separate parameter 'zip=user’s zipcode'
'idx'	Required	The current position of the widget relative to other widgets on the page: The first unit on page will have idx=0 while the second unit will have idx=1 and so on. For pages/views with only one widget installed, use idx=0 for each request.	0
't'	Optional	This token (the 't' value) is returned from the server on every request as a 'request.t' object and should be used in any consecutive request on the same page. The first request on the page should have 'idx=0' and no 't' value, while the second request on the same page should use 'idx=1' and send the 't' value returned by the first request.	ZjZkN2Q0NmRiZGRlNGRmMmNiNDVkZTlkMGU1OWFmNDQ=
'pubImpId'	Only if instructed by SE, Required for Native2Image	8-32 character string unique impression identifier - will be used as key for storing the relevant click redirect on Outbrain server side	string1234568
'pubPvId'	Only if instructed by SE, Optional	8-32 character string unique pageview id. Instead of using the 't' token in API response, a single pageview can be defined by passing a unique id. Consecutive requests can be made using the same 'pubPvId' to declare the same pageview, however, 'idx' must start from 0 and incremented for different placements.	string12345
'maxNumAds'	Only if instructed by SE, Optional	Number of ads to fetch. Typically, a static number of ads is configured for each Outbrain placement (widgetJSId). Please use it only if you require a variable number of ads on each request.	5
'maxNumOrganicRecs'	Only if instructed by SE, Optional	Number of Organic recommendations to fetch. Typically, a static number of Organic recommendations is configured for each Outbrain placement (widgetJSId). Please use it only if you require a variable number of Organic recommendations on each request.	5
'psub'	Only if instructed by SE, Optional	String value for additional section-level reporting breakdowns. Allowed characters: alphanumeric and underscore '_'. Requires permission from your Sales Engineer or Partner Manager.	minus1
'app_id'	Only if instructed by SE, Required for App Native Environment	The App's unique identifier iOS: Bundle ID, Android: Application ID/Package Name	com.king.candycrushsaga
'format'	Required	String value for the response format	JSON: vjnc VAST for Native2Video: vast Image for Native2Image: image
'secured'	Optional	For HTTPS support, add secured=true to the request.	true
'adblck'	Optional, required for partners sending adblock traffic	Boolean value to indicate if the request is coming from an adblocker environment.	true
'testMode'	Optional	Set to true to prevent any clicks and impressions from impacting the Outbrain system while testing and developing. This parameter must be removed before releasing to production.	true
'cnsntv2'	Optional	Base64-encoded consent string, as defined by the IAB for TCF v2.0. If this is not received it is assumed no consent is given. Please do not send cnsntv2 together with the deprecated parameter "cnsnt".	CO4SiGQO4SiGQAGABBENAzCgAP_AAG...(omitted)...A4gDcAHoAReAkQBQ4C8yoAEAHwA.YAAAAAAAAAAA
'ccpa'	Optional	4-character consent string, as defined by the IAB. See U.S. Privacy String. Send 1 character each for Specification Version, Explicit Notice, Opt-Out Sale, and LSPA.	1YNN
'api_consent'	Only if instructed by SE, Optional	0/1 value of user's consent for personalisation. Alternative consent signal when your environment has own consent management system instead of IAB compliant TCF v2.0. Please do not send api_consent together with 'cnsntv2'.	0:Opt-out or Not decided 1: Opt-in Consent
'extid'	Optional	String value with maximum of 110 characters for use with the Engage Variant Reporting API. A maximum of 100K IDs/hour are supported. Contact your Partner Manager for API access.	tagID12345
'extid2'	Optional	String value with maximum of 110 characters. A secondary id for Engage Variant Reporting API as same as the 'extid'	tagID67890
'news'	Only if instructed by SE, Required for OB News	Pre-defined value of a single OB News category. Supported categories varies by country which is specified by either geo location of the user or 'newsFrom' parameter.	Either of: latest sports tech business entertainment lifestyle
'newsFrom'	Only if instructed by SE, Optional for OB News	The 2-letter country code of news source location. Supported countries are limited. Please use it only if you need to strictly specify the news source location.	Country: US

Handling Ad Response

After the request is made, Outbrain returns the recommendations in a specified format. If you are installing the Outbrain service on multiple containers on the same page, please ask your Account Manager for additional widget IDs (e.g. APP_2, APP_3) for use in each distinct container.

JSON format

Outbrain Response

Each response returns multiple recommendations intended to be displayed together in the same container. Jump to Test Content API to see an example. The recommendations are available in the doc array within the documents property at the root of the response.

Response Field	Requirement	Description
'documents'	-	A wrapper for the recommendations array with the total number of recommendations
'doc'	-	An array of returned recommendations objects
'doc.content'	Required	The title of the recommendation
'doc.url'	Required	The redirect URL of Outbrain. This URL must be used to navigate the user to the outbrain paid recommendation when a user is clicking on paid a recommendation, and can be used for organic recommendations.
'doc.orig_url'	Optional for Organic	The original URL of the recommendation. This should not be used to navigate the user to paid recommendations, and can only be used for organic recommendations.
'doc.source_display_name'	Required for Ads	The advertiser name. Be sure to use this 'source_display_name' and not 'source_name'.
'doc.pc_id'	-	Returns if the recommendation is a paid link
'doc.author'	Optional for Organic	The author of the recommended article. For paid recommendations this field will usually be blank.
'doc.desc'	Optional	The Description of the recommendation.
'doc.thumbnail'	-	Object that contains thumbnail information, if configured to send thumbnails
'doc.thumbnail.url'	Required	The URL of the thumbnail
'doc.thumbnail.width'	-	The width of the thumbnail
'doc.thumbnail.height'	-	The height of the thumbnail
'doc.isVideo'	-	Indicate if the doc is a video recommendation
'doc.predictedRpm'	-	The estimated RPM of each ad. It's not a guaranteed RPM. Ask your Sales Engineer to enable.

Events & Pixels

The JSON response includes a set of postback URLs that must be triggered on specific events.

If you are unable to support these actions, notify your Partner Manager.

Response Field	Requirement	Description
'viewability_actions.reportServed'	Required	This event is used to report Outbrain PVs/impressions. Trigger this URL when the Outbrain response is received and rendered on the user’s device. Note: This postback expires after 3 minutes.
'viewability_actions.reportViewed'	(Deprecated) Please support the Listing level tracker 'doc.on-viewed' instead	~~Trigger this URL when the Outbrain recommendation is viewed by the user. Viewed: The top 1px of the widget is visible in the browser window for a continuous 1 second.~~

Listing-Level Trackers

Note: Limited support for pixels may lead to restricted activity

Response Field	Requirement	Description
'doc.pixels'	Required	Image pixels are required to support Advertiser/Marketer activity tracking. Maximum 5 of pixels in the Outbrain response must be fired preferably from the client side. Please contact Outbrain Account Strategist if your implementation needs to fire them on the server side.
'doc.jsTrackers'	Optional	JavaScript tracking pixels are required to support Advertiser/Marketer activity tracking, verification and authentication services. All pixels in the Outbrain response must be executed from the client side. Please contact Outbrain Account Strategist if your implementation can support them.
'doc.on-viewed'	Required	Trigger this URL when the Outbrain recommendation is viewed by the user. Viewed: 50% of the Listing Ad unit is visible in the viewport for a continuous 1 second.
'doc.clickTrackers'	Optional	A list of pixel URLs to be fired when the user clicks on the recommendation.

VAST format

Outbrain Response

After the request is made, Outbrain returns the recommendations in a VAST 3.0 format.

Events & Pixels

Compliant to VAST 3.0 specifications, all 'TrackingEvents.Event' URL must be fired on certain type of event occurs in the video player.

Image format

Outbrain Response

After the request is made, Outbrain returns the image data with HTTP 302 redirect. Each response returns a single recommendations.

Events & Pixels

No events pixels are required to be handled at the moment.

Handling Clicks

Registering a user click is critical for tracking performance and algorithmic optimization. All clicks are registered through the Outbrain redirect, even in the case of a user right clicking to open a link in a new tab.

JSON format(Click)

Paid recommendations

When a user clicks on a paid recommendation, it must direct them to the 'doc.url' of that recommendation without any additional redirect URL or UX disturbance. Paid recommendation URLs start with http://paid.outbrain.com/network/redir. This registers a click in Outbrain reporting.

Organic recommendations

Option 1: Using 'doc.url' When a user clicks on an organic recommendation, direct the user to the 'doc.url' of that recommendation. Organic recommendations URLs “http://traffic.outbrain.com/network/redir”.

Option 2: Using 'doc.orig_url' + 'doc.url' When a user clicks on an organic recommendation, direct the user to the 'doc.orig_url' of that recommendation and report the click by sending a separate request to the 'doc.url' in parallel.

VAST format(Click)

Paid and Organic recommendations

Compliant to VAST 3.0 specifications, 'VideoClicks.ClickThrough' URL must open in a new tab when user clicks on any given player area except video controls.

Image format(Click)

Paid recommendations

When a user clicks a paid recommendation, direct them to the URL corresponds to the pubImpId of the Ad fetch request. The URL format is 'https://paid.outbrain.com/network/redir2?key=[key]&pubImpId=[pubImpId]'. This registers a click in Outbrain reporting.

Organic recommendations

Organic recommendations are not supported at the moment.

Browser Requirements

Desktop apps: Recommendations must be opened in a standard web browser.

Mobile apps: Recommendations must be opened in either:

Safari/SFViewController
Chrome/Chrome Custom Tabs

Opt-Out

Users must have the ability to opt out of Outbrain’s user tracking. Possible exceptions:

Application with universal opt-out
Notifications which users can block in browser settings
Partner Terms of Service includes link to Outbrain privacy policy (Only accepted on Web client side integration and requires Partner Manager Permission)

Please reach out to you Partner Manager if you think one of the above exceptions apply to your activity.

To support Outbrain opt-out:

Add the AdChoices Icon and make it a clickable link pointing to Outbrain Privacy Policy URL as stated below.

AdChoices Icon

'https://widgets.outbrain.com/images/widgetIcons/achoice.svg'

Privacy Policy URL

Use Case: Web - Client-to-Server

'https://www.outbrain.com/what-is/'

Use Case: Web - Server-to-Server

The user’s unique identifier must be passed in the uid parameter. This is the same value specified in api_user_id: 'https://www.outbrain.com/what-is/?uid=UNIQUE_USER_ID'

Use Case: Desktop apps

The user’s unique identifier must be passed in the uid parameter. This is the same value specified in api_user_id: 'https://www.outbrain.com/what-is/?uid=UNIQUE_USER_ID'

Use Case: Mobile apps

The user’s unique identifier must be passed in the uid parameter. This is the same value specified in api_user_id: 'https://www.outbrain.com/what-is/?uid=UNIQUE_USER_ID' In compliance with Google and Apple guidelines, if the user opted out of ad tracking/personalisation, pass api_user_id=null in the Outbrain request URL.

Test Content API for Web [`/Multivac/api/platforms?contentUrl={contentUrl}&widgetJSId={widgetJSId}&key={key}&idx={idx}&format={format}&testMode={testMode}`]