--- title: DirectPerks API slug: directperks-api icon: {"apiMethod":"GET"} docTags: createdAt: 2024-05-29T21:15:13.987Z --- :::hint{type="info"} **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 1. Contact your account manager to enable access to the DirectPerks API. 2. [Obtain your API Key:](docId:1p8gELWd4VQzaQy9cFKn6) Before making API calls, ensure you have your API Key on hand. This unique identifier is necessary for authenticating your requests. 3. **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. 4. **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. :::Iframe{iframeHeight="0" code=""} ::: # 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.](docId:1p8gELWd4VQzaQy9cFKn6)
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](https://en.wikipedia.org/wiki/List_of_ISO_3166_country_codes) 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 ```javascript 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 :::CodeblockTabs Response Example ```json { "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: :::ExpandableHeading ### offer 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_urls`ensures 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 [help@momentscience.com](#)