DirectPerks API

12 min

Who is this for: Partners who need programmatic access to their available offers catalog to display specific offers on websites, apps, or in email campaigns.

Outcome: Retrieve a JSON feed of all active, provisioned offers-including creatives and tracking links-for real-time display and status checks.

Introduction

The DirectPerks API (also known as 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 DirectPerks 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 DirectPerks 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.

Try It Out

Try our DirectPerks API live now and experience the response in real time! Test it below to see how it works and explore the data it returns.

Fetching Offers Using DirectPerks API

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

Request Example

curl --request GET \
  --url 'https://api.adspostx.com/native/v3/catalog.json?api_key=REPLACE_WITH_YOUR_API_KEY&countries=REPLACE_WITH_COUNTRY_CODES&os=REPLACE_WITH_OS&platforms=REPLACE_WITH_PLATFORMS&browsers=REPLACE_WITH_BROWSERS&offer_id=REPLACE_WITH_OFFER_ID' \
  --header 'Content-Type: application/json'

The Response Body

After a successful request to the DirectPerks 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

{
    "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 DirectPerks 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 DirectPerks 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.

When utilizing the DirectPerks 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]