APIs Documentation

Offer Catalog API

10min

Introduction
The Offer Catalog API enables publishers to access Offers allocated to their accounts programmatically. It provides a convenient way to retrieve a JSON feed of all the Offers currently provisioned to their account that are only active and running, including their creatives, tracking links, and other metadata. 
This allows publishers to stay up-to-date with their available Offers and perform real-time status checks before displaying Offers to their users.
Quickstart
Contact your account manager to enable access to the Offer Catalog API.
﻿Obtain your API Key:﻿ Before making API calls, ensure you have your API Key on hand. This unique identifier is necessary for authenticating your requests.
Make an Offer Catalog API call: Utilize the Offer Catalog endpoint to retrieve Offers. This call will return a JSON response containing details about all available Offers or a single Offer.
Parse the response and display Offers: Once you receive the API response, parse it to extract relevant information such as Offer titles, descriptions, images, and tracking links. Then, format and display these Offers to suit your requirements.
Fetch Offer Catalog 
Method: GET
Base URL:  https://api.adspostx.com/native/v3/catalog.json
Header Parameters
Parameter
Description
Type
Example
Content-Type  
required﻿
Should be application/json
string
 application/json
Query Parameters
Parameter
Description
Type
Example
api_key
required﻿
Your API Key. Obtain your API Key.﻿
Required Permission: Ads/Offers

string
4bbdefc2-b130-424d-8170-54bdcb98e64e
offer_id
optional
If provided, the response will only return data related to that specific Offer.
string
1651
countries
optional
Specify ISO 3166-1 alpha-2 country code(s) to fetch Offers related to specific countries. Use a 2-character country code (e.g., US)
You can add multiple values and separate them with commas. (e.g., US, IN, EG)
string
US
or
US,IN,EG
os
optional
Specify the targeted operating systems for Offers, Supported values include windows, macos, android, and ios.
You can add multiple values and separate them with commas.  (e.g., ios, android)
string
ios
or
ios,android
platforms
optional 
Specify the targeted platforms for Offers, Supported values include desktop, phone, and tablet.
You can add multiple values and separate them with commas.  (e.g., tablet, phone)
string
desktop
or
tablet,phone
browsers
optional
Specify the targeted web browsers for Offers, Supported values include edge, chrome, firefox, safari, and opera. 
You can add multiple values and separate them with commas. (e.g., chrome, firefox)
string
chrome
or
chrome,firefox
﻿
The Response Body
After a successful request to the Offer Catalog API, the response body will include an offers object. This object contains an array of individual offer objects, each representing a unique Offer associated with your API key.
Additionally, when a specific offer_id is provided, the response will only include details of that Offer.
Sample Response
Response Example
{
    "offers": [
        {
            "id": 1651,
            "status": "active",
            "title": "Free Initial Consultation!",
            "description": "MomentScience lets you capture revenue across your user's moments. Delight your users with relevant Offers at the right time. Start now with a free consultation.",
            "short_headline": "Free Initial Consultation!",
            "short_description": "Capture revenue across your user's moments. Start now with a free consultation.",
            "mini_text": "",
            "cta": "Try out MomentScience!",
            "image": "https://adpx.b-cdn.net/campaigns/1651/63549ce925dd7372a0da4e35dfe3eeb0.png",
            "creatives": [
                {
                    "id": 1438,
                    "url": "https://adpx.b-cdn.net/campaigns/1651/63549ce925dd7372a0da4e35dfe3eeb0.png",
                    "height": 1530,
                    "width": 1531,
                    "type": "png",
                    "is_primary": true,
                    "aspect_ratio": 1
                }
            ],
            "payout": 5,  //only available if working with MomentScience in an Affilicate Network capacity.
            "is_loyaltyboost": false,
            "loyaltyboost_requirements": "",
            "click_url": "https://trk.pubtailer.com/sdk/offer-click?o_id=4361&c_id=1651&p_id=1854",
            "targeting": {
                "platforms": [],
                "os": [],
                "browsers": []
            }
        }
    ]
}
{
    "offers": [
        {
            "id": 1651,
            "status": "active",
            "title": "Free Initial Consultation!",
            "description": "MomentScience lets you capture revenue across your user's moments. Delight your users with relevant Offers at the right time. Start now with a free consultation.",
            "short_headline": "Free Initial Consultation!",
            "short_description": "Capture revenue across your user's moments. Start now with a free consultation.",
            "mini_text": "",
            "cta": "Try out MomentScience!",
            "image": "https://adpx.b-cdn.net/campaigns/1651/63549ce925dd7372a0da4e35dfe3eeb0.png",
            "creatives": [
                {
                    "id": 1438,
                    "url": "https://adpx.b-cdn.net/campaigns/1651/63549ce925dd7372a0da4e35dfe3eeb0.png",
                    "height": 1530,
                    "width": 1531,
                    "type": "png",
                    "is_primary": true,
                    "aspect_ratio": 1
                }
            ],
            "payout": 5,  //only available if working with MomentScience in an Affilicate Network capacity.
            "is_loyaltyboost": false,
            "loyaltyboost_requirements": "",
            "click_url": "https://trk.pubtailer.com/sdk/offer-click?o_id=4361&c_id=1651&p_id=1854",
            "targeting": {
                "platforms": [],
                "os": [],
                "browsers": []
            }
        }
    ]
}
﻿
Response Parameters
Upon making an API call, the following attributes are returned in the response.
offers array of offer objects
Each object represents the details of an Offer, including its associated creatives. Each offer object has the following attributes:



﻿
offers[].id  integer
Unique identifier for the Offer.
﻿
offers[].status string
Current status of the Offer. Expected values: "active". Paused Offers are not returned in the API response. 
﻿
offers[].title string
The title or headline of the Offer. 
Maximum length: 90 characters.
﻿
offers[].description string
Detailed description of the Offer. 
Maximum length: 220 characters.
﻿
offers[].short_headline string
Alternative shorter text to use for the Offer's headline if the context of the Offer is in a smaller format like on mobile or if you're implementing the Offer in a smaller element. 
Maximum length: 60 characters.
﻿
offers[].short_description	string
Alternative shorter text to use for the Offer's description if the context of the Offer is in a smaller format like on mobile or if you're implementing the Offer in a smaller element. 
Maximum length: 140 characters
﻿
offers[].mini_text string
Additional sub description for the Offer. Used for disclaimers. 
Maximum length: 160 characters.
﻿
offers[].cta string 
 Call-to-action text prompts users to take action. 
Maximum length: 25 characters.
﻿
offers[].image URL
URL for the Offer's primary image.
﻿
offers[].creatives array of creative objects
Contains details of different creative images associated with the Offer.

Each creative object contains the following attributes:	
Attribute
Type
Description
offers[].creatives[].id 
integer
Unique identifier for the creative image.
offers[].creatives[].url
URL
URL to the creative image.
offers[].creatives[].height
double
Height of the image in pixels.
offers[].creatives[].width
double
Width of the image in pixels.
offers[].creatives[].type
string
File type of the image. 
offers[].creatives[].is_primary
boolean
Indicates whether the image is primary or not.
offers[].creatives[].aspect_ratio
number
The aspect ratio of the image.
a value of 1 = square image
a value < 1 signifies generally portrait
a value > 1 signifies generally landscape
﻿
offers[].payout  number
Publisher payout, in USD, when the User converts. Is only available if the Publisher is working with MomentScience in an Affiliate Network relationship capacity. Contact your account manager for more information.
﻿
offers[].is_loyaltyboost  boolean
Indicates if the Offer is a LoyaltyBoost Offer and can be used in an incentivized manner.
﻿
offers[].loyaltyboost_requirements string 
Specifies the requirements for a LoyaltyBoost Offer. It outlines the actions for which rewards will be granted to users. These requirements define the criteria that the user must meet to qualify for rewards associated with the LoyaltyBoost Offer.
Maximum length: 160 characters.
﻿
offers[].click_url URL
URL that the Offer should direct to. 
﻿
offers[].targeting object
Targeting parameters for the Offer. Publishers must respect these targeting parameters when dispalying Offers to their end user to avoid showing Offers not valid to the Users. The targeting object contains the following attributes:
Attributes
Type
Description
offers[].targeting.platforms
array of strings
An array of targeted platforms 
Possible Values:  phone, desktop, tablet. If empty, then Offer is valid on all platforms.
offers[].targeting.os
array of strings
An array of targeted operating systems Possible Values: macos, windows, ios, android. If empty, then Offer is valid on all operating systems.
offers[].targeting.browsers
array of strings
An array of targeted browsers.
Possible Values: safari, chrome, mozilla, opera, edge). If empty, then Offer is valid on all browsers.
﻿
Using Creatives
When retrieving Offers, we provide a creatives attribute with each returned Offer, which lists creatives available for use in your Offers. 
Included with each creative is an is_primary boolean attribute. You can use any of the creatives available depending on the platform you are rendering or default to the primary creative if you are unsure.
The Catalog API also supports on-the-fly image transformations: by simply adding the query parameter "width=XXX" into the image url (replace XXX with a suitable integer value for width, depending on the device resolution). The query parameters "height=XXX" or "?aspect_ratio=X:Y" are also available as on-the-fly image processing directives on images.
We also provide an aspect_ratio attribute for each creative which can be helpful in selecting an image for the Offer.  
An aspect_ratio with:
a value of 1 = square image
a value < 1 signifies generally portrait
a value > 1 signifies generally landscape
Notes
The returned click_url value(s) in the Offer Catalog response can be updated to include payload values, similar to Direct Offer links. This allows for additional information to be passed along with the URL. ( Learn more﻿ about using payload values in click_urls.)
When utilizing the Offer Catalog API to return LoyaltyBoost Offers that reward users for engagement, implementing payloads becomes crucial. By including user identifiers in the payload, you ensure that rewards are issued to the correct user upon completion of actions.
Implementing payloads in click_urlsensures that necessary user information is transmitted and returned accurately. This enhances the functionality of LoyaltyBoost offers and helps correctly attribute rewards to users based on their engagement.
﻿
📢 If you're running into any issues while going through the integration process, feel free to contact us at [email protected] 

Parameter	Description	Type	Example
Content-Type required	Should be application/json	string	application/json

Parameter	Description	Type	Example
api_key required	Your API Key. Obtain your API Key. Required Permission: Ads/Offers	string	4bbdefc2-b130-424d-8170-54bdcb98e64e
offer_id optional	If provided, the response will only return data related to that specific Offer.	string	1651
countries optional	Specify ISO 3166-1 alpha-2 country code(s) to fetch Offers related to specific countries. Use a 2-character country code (e.g., US) You can add multiple values and separate them with commas. (e.g., US, IN, EG)	string	US or US,IN,EG
os optional	Specify the targeted operating systems for Offers, Supported values include windows, macos, android, and ios. You can add multiple values and separate them with commas. (e.g., ios, android)	string	ios or ios,android
platforms optional	Specify the targeted platforms for Offers, Supported values include desktop, phone, and tablet. You can add multiple values and separate them with commas. (e.g., tablet, phone)	string	desktop or tablet,phone
browsers optional	Specify the targeted web browsers for Offers, Supported values include edge, chrome, firefox, safari, and opera. You can add multiple values and separate them with commas. (e.g., chrome, firefox)	string	chrome or chrome,firefox

Attribute	Type	Description
offers[].creatives[].id	integer	Unique identifier for the creative image.
offers[].creatives[].url	URL	URL to the creative image.
offers[].creatives[].height	double	Height of the image in pixels.
offers[].creatives[].width	double	Width of the image in pixels.
offers[].creatives[].type	string	File type of the image.
offers[].creatives[].is_primary	boolean	Indicates whether the image is primary or not.
offers[].creatives[].aspect_ratio	number	The aspect ratio of the image. a value of 1 = square image a value < 1 signifies generally portrait a value > 1 signifies generally landscape

Attributes	Type	Description
offers[].targeting.platforms	array of strings	An array of targeted platforms Possible Values: phone, desktop, tablet. If empty, then Offer is valid on all platforms.
offers[].targeting.os	array of strings	An array of targeted operating systems Possible Values: macos, windows, ios, android. If empty, then Offer is valid on all operating systems.
offers[].targeting.browsers	array of strings	An array of targeted browsers. Possible Values: safari, chrome, mozilla, opera, edge). If empty, then Offer is valid on all browsers.

Updated 21 Sep 2024

Did this page help you?

Perkswall API

Reporting API

Offer Catalog API

Introduction

Quickstart

Fetch Offer Catalog

Header Parameters

Query Parameters

The Response Body

Sample Response

Response Parameters

offer Attributes

Using Creatives

Notes