Perkswall API

overview the momentscience perkswall api facilitates the integration of a curated "perks gallery" into your application or website through restful calls this api is designed to give you access to perkswall enabled offers, enabling a highly customizable and branded perkswall experience by utilizing the perkswall api , you can fetch all available offers configured for your account these offers can then be used to construct a dynamic and engaging perkswall that aligns with your brand’s identity and enhances user interaction pre requisites to use the perkswall api, you must first have the perkswall feature activated for your account contact your account manager to request activation once the perkswall feature is enabled, obtain your api key from your momentscience dashboard the api key is required to authenticate all requests made to the perkswall api apis documentation try it out try our perkswall api live now and experience the response in real time! test it below to see how it works and explore the data it returns fetch perkswall offers method post base url https //api adspostx com/native/v4/perkswall json header parameters parameter type description content type required required s tring specifies the media type of the request must be set to application/json query parameters parameter description type example api key required required your api key apis documentation docid\ kt3kx09z 7oovjynx fdj required permission ads/offers string 4bbdefc2 b130 424d 8170 54bdcb98e64e loyaltyboost optional include loyaltyboost offers in the response 0 = do not include loyaltyboost offers 1 = include loyaltyboost offers 2 = return only loyaltyboost offers string 0 / 1 / 2 creative optional returns offers with at least one creative (image) if set to 1 0 false 1 true string 0 / 1 body parameters parameter description type example placement required required an attribute that represents the specific page, section, or location where the offer unit was triggered this parameter enables enhanced reporting, analytics, and traffic segmentation s tring checkout confirmation page ua recommended recommended the user agent string of the end user, required for proper targeting if proxying requests via a server, ensure the user agent of the end user is passed through string mozilla/5 0 (linux; android 10; k) applewebkit/537 36 (khtml, like gecko) chrome/120 0 6099 43 mobile safari/537 36 ip recommended recommended the ip address of the end user for targeting purposes string adpx fp recommended recommended a unique identifier for the end user this is not required, but highly recommended for accurate tracking more information is provided below string 1234abcd 5678 efgh 9101 ijklmnopqrst dev optional enables a test response when set to 1, the sandbox environment is activated, allowing for testing without recording any activity in production in this mode, geo restrictions are ignored, and all offers are returned in the response, providing a comprehensive testing experience set to 1 to enable test mode string 0 | 1 subid optional an id used to identify specific usages of the fetch perkswall offers api string mobile android app post transaction pub user id required when integrating with perkswallet as a service (pwaas) or user selected perks required when integrating with perkswallet as a service (pwaas) or user selected perks a unique, non pii identifier for the end user this value links offers to individual users and must remain consistent across sessions and devices you may use the same value as adpx fp , if available do not use personally identifiable information (pii), such as email addresses or phone numbers you can generate this identifier using any method, as long as it guarantees uniqueness per user string 1234abcd 5678 efgh 9101 ijklmnopqrst \<string> optional custom key value payload attributes you can add any number of custom attributes for additional details these attributes are included in conversion reports and can be tracked in relation to impressions and clicks string membershipid "a45gre987343pkd" the adpx fp attribute is a special parameter used in the body of the fetch give you offers calls to enhance offer performance it should be populated with a unique alphanumeric string that identifies the end user momentscience leverages the adpx fp value for frequency capping —ensuring that offers are displayed to users within predefined limits additionally, it prevents offers from being shown again once a user has opted out of a specific offer, ensuring a more personalized and seamless experience request example curl request post \\ \ url 'https //api adspostx com/native/v4/perkswall json?api key=replace with your api key' \\ \ header 'content type application/json' \\ \ data '{ "placement" "replace with placement", "ua" "replace with user agent", "ip" "replace with user ip address", "adpx fp" "replace with user fingerprint id", "pub user id" "replace with unique user id", "creative" "replace with 0 or 1", "loyaltyboost" "replace with 0 1 or 2", "membershipid" "replace with membership id", "subid" "replace with subid" }' response information upon a successful response from the fetch perkswall offers api, the body will include a data object containing an array of offer objects these objects provide all the necessary details to construct the offers for your perkswall below are the relevant attributes within the offer objects sample response response example { "data" { "offers" \[ { "id" 5597, "campaign id" 2901, "title" "grab $750 shein gift card!", "description" "unlock your fashion dreams take our survey for a shot at a $750 shein gift card act now!", "click url" "https //momentscience com", "image" "https //adpx b cdn net/campaigns/1576/8945fa8e15b39d84f01e3de98705e8cd png", "mini text" "", "terms and conditions" "", "pixel" "https //momentscience com/p png", "cta yes" "claim shein gift card!", "cta no" "no, thanks", "useraction cta" null, "useraction url" null, "adv pixel url" "", "beacons" { "close" "https //momentscience com/event/record/close?oid=5597\&cid=2901\&pid=3507\&sub id1=mobile android app post transaction\&sess id=56cc71bd45ee20eacfb8641bbe2e9b6bbded0421\&fp=uniqueuser123", "no thanks click" "https //momentscience com/event/record/no thanks click?oid=5597\&cid=2901\&pid=3507\&sub id1=mobile android app post transaction\&sess id=56cc71bd45ee20eacfb8641bbe2e9b6bbded0421\&fp=uniqueuser123" }, "creatives" \[ { "id" 4094, "url" "https //adpx b cdn net/campaigns/1576/8945fa8e15b39d84f01e3de98705e8cd png", "height" 224, "width" 225, "type" "png", "is primary" true, "aspect ratio" 1, "creative type" null }, { "id" 4853, "url" "https //adpx b cdn net/campaigns/2901/a03729bcc3bc015c851f11fdc0fe3c54 png", "height" 150, "width" 150, "type" "png", "is primary" false, "aspect ratio" 1, "creative type" "icon image" }, ], "offerwall enabled" true, "perkswallet enabled" true, "short description" "take a survey for a shot at claiming a $750 shein gift card don't miss out!", "short headline" "grab $750 shein gift card!", "advertiser name" "shein", "is loyaltyboost" false, "loyaltyboost requirements" "", "offerwall url" "https //get perkswall com/offerwall?accountid=96c6df58ad0e017b\&themeid=disabled\&session id=56cc71bd45ee20eacfb8641bbe2e9b6bbded0421\&c id=2901\&perkswall version=", "qr code img" "data\ image/png;base64,ivborw0kggoaaaansuheugaaaiqaaacec ", "save for later url" "https //api perkswallet com/pwaas/save json?o id=5738\&c id=3042\&p id=3065\&sess id=b779feeec95272cae3cc3c8fb0f0f1aeff20c12d\&pub user id=pktw2", "tags" \[ "gift cards", "fashion", "shopping" ] }, { "id" 5113, "campaign id" 2408, "title" "30 day free trial with stamps com!", "description" "say goodbye to post office lines! print postage in seconds with stamps com sign up now for $5 in free postage ", "click url" "https //momentscience com", "image" "https //adpx b cdn net/campaigns/2408/0d64e6ab19905bf5244dee202ac4b625 jpg", "mini text" "", "terms and conditions" "", "pixel" "https //momentscience com/p png", "cta yes" "sign up now!", "cta no" "no, thanks", "useraction cta" null, "useraction url" null, "adv pixel url" "", "beacons" { "close" "https //momentscience com/event/record/close?oid=5113\&cid=2408\&pid=3507\&sub id1=mobile android app post transaction\&sess id=56cc71bd45ee20eacfb8641bbe2e9b6bbded0421\&fp=uniqueuser123", "no thanks click" "https //momentscience com/event/record/no thanks click?oid=5113\&cid=2408\&pid=3507\&sub id1=mobile android app post transaction\&sess id=56cc71bd45ee20eacfb8641bbe2e9b6bbded0421\&fp=uniqueuser123" }, "creatives" \[ { "id" 2838, "url" "https //adpx b cdn net/campaigns/1841/f2c0654e58c8cf51faa6c5dff6b53ab1 png", "height" 1001, "width" 1001, "type" "png", "is primary" false, "aspect ratio" 1, "creative type" null }, { "id" 5162, "url" "https //adpx b cdn net/campaigns/2408/18e46a9de59850f4600cfe40caf75033 jpg", "height" 150, "width" 150, "type" "jpg", "is primary" false, "aspect ratio" 1, "creative type" "icon image" }, { "id" 5163, "url" "https //adpx b cdn net/campaigns/2408/0d64e6ab19905bf5244dee202ac4b625 jpg", "height" 120, "width" 120, "type" "jpg", "is primary" true, "aspect ratio" 1, "creative type" "offer image" }, { "id" 5645, "url" "https //adpx b cdn net/campaigns/2408/14ed0ad44c9ba34d6a60669d3df4d8a1 png", "height" 448, "width" 1600, "type" "png", "is primary" false, "aspect ratio" 3 57, "creative type" "hero image" } ], "offerwall enabled" true, "perkswallet enabled" false, "short description" "say goodbye to post office lines! print postage in seconds with stamps com sign up now for $5 in free postage ", "short headline" "30 day free trial with stamps com!", "advertiser name" "stamps com", "is loyaltyboost" false, "loyaltyboost requirements" "", "offerwall url" "https //get perkswall com/offerwall?accountid=96c6df58ad0e017b\&themeid=disabled\&session id=56cc71bd45ee20eacfb8641bbe2e9b6bbded0421\&c id=2901\&perkswall version=""qr code img" "data\ image/png;base64,ivborw0kggoaaaansuheugaaaiqaaacec ""save for later url" "https //api perkswallet com/pwaas/save json?o id=5738\&c id=3042\&p id=3065\&sess id=b779feeec95272cae3cc3c8fb0f0f1aeff20c12d\&pub user id=pktw2", "tags" \[ "tickets", "audio and speakers", "cell phones and accessories", "technology" ] }, { "id" 5665, "campaign id" 2969, "title" "enter to win a walmart gift card!", "description" "take a quick survey for a chance to win a walmart gift card your opinion counts!", "click url" "https //momentscience com", "image" "https //adpx b cdn net/campaigns/2969/670afd03cb8c4323fc57d2875586b4b8 jpg", "mini text" "", "terms and conditions" null, "pixel" "https //momentscience com/p png", "cta yes" "claim now!", "cta no" "no, thanks", "useraction cta" null, "useraction url" null, "adv pixel url" "", "beacons" { "close" "https //momentscience com/event/record/close?oid=5665\&cid=2969\&pid=3507\&sub id1=mobile android app post transaction\&sess id=56cc71bd45ee20eacfb8641bbe2e9b6bbded0421\&fp=uniqueuser123", "no thanks click" "https //momentscience com/event/record/no thanks click?oid=5665\&cid=2969\&pid=3507\&sub id1=mobile android app post transaction\&sess id=56cc71bd45ee20eacfb8641bbe2e9b6bbded0421\&fp=uniqueuser123" }, "creatives" \[ { "id" 4239, "url" "https //adpx b cdn net/campaigns/2969/670afd03cb8c4323fc57d2875586b4b8 jpg", "height" 272, "width" 452, "type" "jpg", "is primary" true, "aspect ratio" 1 66, "creative type" null } ], "offerwall enabled" true, "perkswallet enabled" false, "short description" "take a quick survey for a chance to win a walmart gift card your opinion counts!", "short headline" "enter to win a walmart gift card!", "advertiser name" "walmart", "is loyaltyboost" false, "loyaltyboost requirements" "", "save for later url" "https //api perkswallet com/pwaas/save json?o id=5738\&c id=3042\&p id=3065\&sess id=b779feeec95272cae3cc3c8fb0f0f1aeff20c12d\&pub user id=pktw2", "offerwall url" "https //get perkswall com/offerwall?accountid=96c6df58ad0e017b\&themeid=disabled\&session id=56cc71bd45ee20eacfb8641bbe2e9b6bbded0421\&c id=2969\&perkswall version=", "tags" \[ "gift cards", "shopping", "retail" ] } // more offers ], "settings" { "custom head" null, "before body tag" null, "before head tag" null, "offerwall header text" "you unlocked more exclusive offers", "offerwall logo url" "", "perkswallet cta" "save for later", "perkswallet show cta" false, "auto show" true, "show header" true, "show intermediate" "interstitial", "offer count" 12, "show logo" true, "show image" true, "suppress links" false, "tile count" 3, "show shadow" false, "featured overlay color" "#000000", "show dots" true, "show icons" false, "featured offer" false, "featured offer list" \[], "perkswall version" 20000, "page title" "perkswall", "show offer tiles" true, "featured offers auto slide" false, "enable perkswallet" true, "logo url" "https //adpx b cdn net/publishers/3507 png", "fav icon logo" "fav icon 3507 png" }, "count" 56, "styles" { "header" { "style" "light", "color" "#ffffff", "image" null }, "body" { "background" "#ffffff" }, "popup" { "background" "#ffffff", "bordercolor" "#eaecf0", "backgroundhover" "#ffffff", "borderthickness" 1, "tileradius" 16, "shadow" "0px 1px 2px 0px rgba(16, 24, 40, 0 05)" }, "offertext" { "textcolor" "#101828", "font" "inter", "tiletextalignment" "left", "fontsizetitle" 16, "fontsizedescription" 12, "buttonradius" 8, "buttonyes" { "background" "#155eef12", "hover" "#155eef2b", "stroke" "#1c64f2", "color" "#155eef", "fontsizecta" 16 }, "buttonperkswallet" { "color" "#101828", "hover" "#f44336", "fontsizeperkswallet" 12 } }, "settings" { "custom head" null, "before body tag" null, "before head tag" null, "offerwall header text" "you unlocked more exclusive offers", "offerwall logo url" "", "perkswallet cta" "save for later", "perkswallet show cta" false, "auto show" true, "show header" true, "show intermediate" "interstitial", "offer count" 12, "show logo" true, "show image" true, "suppress links" false, "tile count" 3, "show shadow" false, "featured overlay color" "#000000", "show dots" true, "show icons" false, "featured offer" false, "featured offer list" \[], "perkswall version" 20000, "page title" "perkswall", "show offer tiles" true, "featured offers auto slide" false, "enable perkswallet" true, "logo url" "https //adpx b cdn net/publishers/3507 png", "fav icon logo" "fav icon 3507 png" }, "data" { "displayname" "standard theme", "id" 413, "is default" true, "slug" "standard theme", "user id" 3507, "created at" "2024 12 21t20 04 50 643z" } } } } response parameters offers (array of offer objects) an array of objects containing the details for each available offer each offer object contains the following attributes offer attributes offers\[] id integer the unique identifier for the offer offers\[] title string recommended to implemen recommended to implemen t for larger formats t for larger formats the title of the offer is typically used to construct the headline maximum length 90 characters ideal length 40 characters offers\[] advertiser name string the name of the advertiser offering the offer offers\[] description string recommended to implemen recommended to implemen t for larger formats t for larger formats a brief description of the offer maximum length 220 characters ideal length 140 characters offers\[] save for later url string required to implement when integrating with perkswallet required to implement when integrating with perkswallet the url your system should use to save the offer to the user's wallet when they click the save for later button when pub user id is present in the request save for later url contains a valid post endpoint trigger this url when the user clicks save for later when pub user id is not present in the request this field is null skip rendering or disabling the save for later action offers\[] tags array\<string> recommended for filtering, categorization, and ui personalization recommended for filtering, categorization, and ui personalization a list of category tags assigned to the offer each offer can belong to multiple categories these tags help organize offers into logical groups, power filtering experiences, and enable more relevant recommendations offers can have multiple tags to reflect different verticals (e g , "technology", "financial", "video games and consoles") if an offer does not include any tags, it should be treated as part of a default category such as "all" in the ui offers\[] qr code img string a base64 encoded png image of a qr code that encodes the value of the campaign’s click url the string is returned in data uri format, beginning with data\ image/png;base64, or data\ image/jpeg;base64, use this image to provide a quick, scannable link to claim the offer , especially in cross device or offline scenarios qr code guidelines format png or jpeg color scheme black foreground on white background (no gradients or color inversions) dimensions 228x228 pixels offers\[] click url string required to implement required to implement the url the offer directs to when clicked offers\[] image string recommended to implement recommended to implement the url of the primary image for the offer offers\[] mini text string recommended to implement recommended to implement a shorter description for the offer, useful for disclaimers maximum length 160 characters ideal usage avoid unless absolutely necessary offers\[] terms and conditions string recommended to implement recommended to implement offers\[] terms and conditions string required to implement required to implement contains the offer’s terms and conditions in html format, which should be rendered as raw html to preserve styling and structure if this field is not present or empty, assume no specific terms apply to the offer expected html tags the html content may include the following tags expected html tags , , , , , , , , , , , , , , , , good implementation practices do not display full terms by default within the initial view of the offer provide a clear, user friendly way to access the terms using one of the following ui mechanisms expanding or accordion style reveal flip card interaction modal or lightbox popup tooltip on hover link to a separate detail view offers\[] pixel string required to implement required to implement the impression beacon url to be fired when the offer is displayed to the user for impression tracking a successful get call to the pixel url is required to successfully record delivery on the momentscience dashboard offers\[] cta yes string recommended to implement recommended to implement suggested copy for the positive cta button to accept the offer maximum length 25 characters ideal length 20 characters offers\[] cta no string suggested copy for the negative cta button to reject the offer maximum length 25 characters ideal length 20 characters offers\[] adv pixel url string required to implement if available required to implement if available advertiser may provide their own impression tracking url, fire this along with the pixel impression beacon url a successful get call to adv pixel url is required offers\[] beacons object it contains urls for various actions related to the offer a successful get request to these urls is required to record certain activities attribute type description offers\[] beacons close recommended to implement recommended to implement if perkswall offers are presented in a dismissable container if perkswall offers are presented in a dismissable container string url fired when the offer container is closed or when the user has browsed through all offers, for reporting purposes a successful get call to beacons close is required if implemented offers\[] beacons no thanks click r r ecommended to implement ecommended to implement if a negative cta is implemented for each offer on the perkswall if a negative cta is implemented for each offer on the perkswall string url fired when the negative cta is clicked (e g , rejecting the offer) for reporting purposes a successful get call to beacons no thanks clicks is required if implemented offers\[] creatives array of creative objects contains additional creative images that can be used to construct the offers unit each creative object contains the following attributes attribute type description offers\[] creatives\[] id integer unique identifier for each creative offers\[] creatives\[] url string url of the creative image offers\[] creatives\[] height double height of the creative image in pixels offers\[] creatives\[] width double width of the creative image in pixels offers\[] creatives\[] type string the file type of the creative image (e g , jpeg, png) offers\[] creatives\[] is primary boolean indicates if the creative is the primary image for the offer offers\[] creatives\[] aspect ratio integer the aspect ratio of the image, which defines the relationship between its width and height 1 = square image < 1 = portrait orientation > 1 = landscape orientation offers\[] creatives\[] creative type string the type of creative being used can be one of the following options icon image hero image offer image offers\[] advertiser name string the name of the advertiser providing the offer offers\[] short description string recommended to implemen recommended to implemen t for smaller formats t for smaller formats 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 ideal length 140 characters offers\[] short headline string recommended to implemen recommended to implemen t for smaller formats t for smaller formats 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 ideal length 40 characters offers\[] is loyaltyboost boolean indicates if an offer is eligible to be used in an incentive 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 settings object the settings object allows for customization of the perkswall’s appearance and behavior however, for integration purposes, the only essential attribute to focus on is settings object settings featured offer list array a list of offer ids (from offers\[] id ) that are designated as featured the offers\[] id values are used here to specify which offers should be marked as featured within the perkswall display count integer number of offers returned from the call parsing the response and displaying offers when you receive a successful response from the fetch perkswall offers api , follow these steps to construct and display offers using the provided data for more information about how to make the most of the api response, please refer to the perkswall anatomy docid\ ogduiw3chofegmftb3vxz response handling and offer construction extract offer data parse the response to retrieve the offers array, which contains the necessary attributes for constructing each offer generate offers use the following attributes from each offer object to display the offer title offer headline (recommended for larger formats) if a shorter version is available, use short headline for smaller formats advertiser name name of the advertiser description detailed offer description (max length 220 characters) if a shorter version is available, use short description for smaller formats click url destination url when the user interacts with the offer image primary image for visual representation pixel impression beacon url for tracking implement impression tracking for each displayed offer make a get request to the pixel url this ensures the momentscience dashboard logs the impression and tracks performance metrics such as click through rate (ctr) effective cost per thousand impressions (ecpm) display offers sequentially render the first offer and trigger its pixel url proceed to display subsequent offers in sequence, ensuring each impression is tracked using creatives each offer includes a creatives attribute that contains an array of images leverage this data as follows primary creative identify the primary creative using the is primary boolean attribute use this by default if no other creative is specified creatives types we support multiple creatives types, offer image displays an image relevant to the offer, size based on design requirements hero image represents the offer in the perkswall featured section, with only one hero image allowed (1000 × 280 px, ±10% size variation) this image can also be used to populate larger "interstitial" offer modals or similar bigger units if implemented icon image represents the offer's icon or brand logo, with only one icon image allowed (250 × 250 px, ±10% size variation) creative selection choose creatives that best suit your platform (e g , desktop, mobile) consider aspect ratios 1 square < 1 portrait > 1 landscape image transformations optimize images for different devices using query parameters width=xxx adjust the width height=xxx adjust the height aspect ratio=x\ y specify the aspect ratio integration checklist to ensure a smooth integration confirm implementation of all required attributes ( title , click url , pixel , etc ) verify that all beacon urls ( pixel , close , no thanks click , etc ) are functional test creative transformations and rendering on various devices for a complete list of integration steps, refer to the moments and perkswall api implementation checklist 📢 if you're running into any issues while going through the integration process, feel free to contact us at help\@momentscience com