DirectPerks API

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 apis documentation docid 1p8gelwd4vqzaqy9cfkn6 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 required should be application/json string application/json query parameters parameter description type example api key required required your api key apis documentation 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 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 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" \[] } } ] } 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 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 ( passing payload values docid\ ymwqhfk a rt0lfya0etj about using payload values in click urls ) 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