Perkswall API

overview the momentscience perkswall api provides a flexible, programmatic interface for integrating a curated “perks gallery” into your app or site it works from any environment that can make http requests and returns json for easy rendering and tracking use cases create a dedicated "rewards hub" where subscribers browse exclusive perks and special offers display relevant perks on order confirmation pages that complement customers' purchases embed a curated perks gallery during app loading screens or natural transition points elevate your loyalty program with personalized third party perks based on member status integration architecture proxy connect (recommended) your client talks to your proxy; your proxy calls the perkswall api this lets you keep api keys server‑side and control outbound traffic add business logic, logging, or caching improve observability and rate limiting direct connect your client calls the perkswall api directly this is simple for prototypes or low‑risk environments, but may expose api keys add protections if used in production 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 authentication all requests require an api key with the “ads/offers” permission this key authorizes your application to retrieve and serve momentscience offers securely obtaining an api key log in to the momentscience dashboard https //app momentscience com navigate to profile settings > api keys generate a new api key with the "ads/offers" permission for more details, see getting and managing your api key fetch perkswall offers method post base url https //api adspostx com/native/v4/perkswall json header parameters parameter required description content type yes specifies the media type of the request must be set to application/json accept no optionally set to application/json query parameters parameter type required description api key string yes your api key with "ads/offers" permission must be generated from the momentscience dashboard loyaltyboost string no controls inclusion of loyaltyboost eligible offers in results • 0 exclude all loyaltyboost offers • 1 include both standard and loyaltyboost offers (default) • 2 return only loyaltyboost offers creative string no filter offers by creative availability • 0 return all matching offers regardless of creative availability (default) • 1 only return offers with at least one creative asset body parameters parameter type required description placement string yes identifies where the offer unit appears in your application or website used for segmentation, reporting, and offer targeting example checkout confirmation page ua string recommended end user's complete user agent string when implementing via proxy architecture, ensure you forward the actual client ua rather than your server's ua for accurate device targeting example mozilla/5 0 (linux; android 10; k) applewebkit/537 36 (khtml, like gecko) chrome/120 0 6099 43 mobile safari/537 36 ip string recommended end user's ip address for geographic and demographic targeting used to deliver location relevant offers example 203 0 113 45 adpx fp string recommended persistent, anonymous identifier for frequency capping, offer rotation, and honoring opt out preferences should be consistent across sessions for the same user but doesn't need to identify the user specifically use uuid format if possible example 1234abcd 5678 efgh 9101 ijklmnopqrst pub user id string required for pwaas/user selected perks non pii persistent identifier unique to each user must remain consistent across sessions and devices used for personalization and offer saving functionality can match adpx fp if preferred do not use personally identifiable information such as email addresses or phone numbers example 1234abcd 5678 efgh 9101 ijklmnopqrst dev string no set to 1 to receive test offers that ignore geographic restrictions and suppress production tracking events use only in development environments example 1 subid string no free form identifier to track specific implementations, variants, or traffic sources included in reporting and analytics example mobile android app post transaction \<custom> string no any additional key value pairs included in the request will be captured for reporting and segmentation these are passed through to conversion events for attribution examples include source , campaign id , or user segment example membershipid "a45gre987343pkd" notes on adpx fp should be a uuid or other consistent alphanumeric identifier contains no pii (personally identifiable information) critical for frequency capping (preventing the same user from seeing the same offers repeatedly) persists opt out preferences across sessions store in local storage, cookies, or your user database 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" "checkout confirmation page", // required identifier for where the offer is shown (e g , page, screen) "ua" "mozilla/5 0 (linux; android 10; k) applewebkit/537 36 (khtml, like gecko) chrome/120 0 6099 43 mobile safari/537 36", // recommended end user's browser/device information for targeting "ip" "203 0 113 45", // recommended end user's ip address for geographic targeting "adpx fp" "1234abcd 5678 efgh 9101 ijklmnopqrst", // recommended persistent anonymous identifier for frequency capping "pub user id" "1234abcd 5678 efgh 9101 ijklmnopqrst", // required for pwaas non pii user identifier for personalization "subid" "mobile android app post transaction" // optional custom identifier for tracking implementation variants }' api response on success, the response contains a data object with an array of offers and related metadata sample response { "data" { "session id" "sess 12345abcde67890", "offers" \[ { "id" 5576, "campaign id" 2880, "title" "get 25% off athletic wear + free shipping", "description" "save on top brand athletic wear with this exclusive discount orders over $50 qualify for free shipping to anywhere in the continental us ", "click url" "https //offers momentscience com/click/abc123", "image" "https //cdn momentscience com/creatives/sports banner jpg", "mini text" "excludes sale items valid through 12/31/2025 ", "terms and conditions" "\<p>\<strong>offer valid for online purchases only \</strong> discount applies to regular priced items cannot be combined with other promotions free shipping valid on orders over $50 shipped to the continental us expires 12/31/2025 \</p>", "pixel" "https //tracking momentscience com/impression/abc123", "cta yes" "shop now", "cta no" "no thanks", "useraction cta" null, "useraction url" null, "adv pixel url" "https //advertiser com/track?id=xyz789", "beacons" { "close" "https //tracking momentscience com/close/abc123", "no thanks click" "https //tracking momentscience com/decline/abc123" }, "creatives" \[ { "id" 1001, "url" "https //cdn momentscience com/creatives/sports square jpg", "height" 400, "width" 400, "type" "jpg", "is primary" true, "aspect ratio" 1 0, "creative type" "offer image" }, { "id" 1002, "url" "https //cdn momentscience com/creatives/sports banner jpg", "height" 200, "width" 800, "type" "jpg", "is primary" false, "aspect ratio" 4 0, "creative type" "hero image" } ], "offerwall enabled" true, "perkswallet enabled" true, "short description" "save on top brands + free shipping over $50", "short headline" "25% off athletic wear", "advertiser name" "premium sports store", "is loyaltyboost" true, "loyaltyboost requirements" "complete purchase to earn 500 bonus points", "save for later url" "https //api momentscience com/wallet/save", "tags" \["fitness", "apparel", "sports"], "campaign" { "campaign images" \[ { "id" 1001, "url" "https //cdn momentscience com/creatives/sports square jpg", "height" 400, "width" 400, "type" "jpg", "creative type" "offer image", "is primary" true, "aspect ratio" 1 0, "user id" 0 }, { "id" 1002, "url" "https //cdn momentscience com/creatives/sports banner jpg", "height" 200, "width" 800, "type" "jpg", "creative type" "hero image", "is primary" false, "aspect ratio" 4 0, "user id" 0 } ], }, "offerwall url" "https //get perkswall com/offerwall?accountid=abc123\&themeid=documentation example\&session id=sess 12345abcde67890", "qr code img" "data\ image/png;base64,ivborw0kggqbj5onktxatymx7wwtc8rlwuevhrxhovrxfow1rrmjyona3741jupa61rhtza1zysta55wgtd87dwuuzhrxxnw1rrmoe11jupa61rhtza1/w/ejw+ivrqs2eaaaaasuvork5cyii=" } ], "settings" { "featured offer list" \[582, 723, 1154, 1693, 1576, 1863] }, "count" 1 } } top‑level fields field type description data offers array list of offer objects containing all offer information data settings object display preferences and configuration options; may include featured offer list (array of offer ids), header text, display controls, and layout settings data styles object visual styling configuration for the perks interface including colors, fonts, spacing, and component specific settings data session id string unique identifier for the current browsing session count integer number of offers returned offers (array of offer objects) identification & metadata field type description offers\[] id integer unique identifier for the offer always included in response offers\[] campaign id integer identifier for the advertising campaign always included in response offers\[] advertiser name string name of the merchant or advertiser always included in response offers\[] perkswallet enabled boolean whether this offer can be saved to perkswallet optional field offers\[] offerwall url string direct link to this offer in an perkswall optional field text content field type description offers\[] title string recommended to implement for large formats desktop/wide headline for the offer (maximum 90 characters; ideally 40 characters) used in full width layouts and primary views example "get 25% off athletic wear + free shipping" offers\[] description string recommended for large formats desktop/wide description providing offer details (maximum 220 characters; ideally 140 characters) contains fuller explanation of the offer value example "save on top brand athletic wear with this exclusive discount orders over $50 qualify for free shipping to anywhere in the continental us " offers\[] short headline string recommended to implement for mobile formats compact headline optimized for mobile devices and card layouts (maximum 60 characters; ideally 40 characters) used when display space is limited example "25% off athletic wear" offers\[] short description string recommended for mobile formats condensed description for mobile screens and space constrained layouts (maximum 140 characters) provides essential offer details in limited space example "save on top brands + free shipping over $50" offers\[] mini text string a short disclaimer or fine print text for the offer common uses include exclusions, legal requirements, or time sensitive details displayed in smaller font beneath the main offer content (maximum 140 characters) example excludes sale items valid through 12/31/2025 use only when essential to clarify terms without cluttering the main offer description call to action elements field type description offers\[] click url string required to implement destination url opened when user accepts the offer contains tracking parameters for attribution and conversion tracking users are directed here after clicking the primary action button offers\[] cta yes string recommended to implement text label for the primary action button (maximum 25 characters; ideally under 20) examples "shop now", "get offer", "claim deal" sets user expectations for the action and significantly impacts conversion rates offers\[] cta no string optional for implementation text label for the dismissal button (maximum 25 characters; ideally under 20) examples "no thanks", "not now", "skip" provides users with a clear way to decline the offer while still triggering the appropriate tracking beacon images & creative assets field type description offers\[] image string primary image url for the offer use for simplified implementations when you don't need multiple creative formats for responsive designs with multiple aspect ratios, use the creatives array instead 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 format png or jpeg color scheme black foreground on white background (no gradients or color inversions) dimensions 228x228 pixels creatives array the offers\[] creatives array contains detailed information about available images field type description offers\[] creatives\[] id integer unique identifier for the creative asset offers\[] creatives\[] url string url to the image asset offers\[] creatives\[] height number height in pixels offers\[] creatives\[] width number width in pixels offers\[] creatives\[] type string file format (jpg, png, etc ) offers\[] creatives\[] is primary boolean whether this is the primary image offers\[] creatives\[] aspect ratio number 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 representsthe offer's icon or brand logo, with only one icon image allowed (250 × 250 px, ±10% size variation) 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 offer image displays an image relevant to the offer, size based on design requirements categorization field type description offers\[] tags array of strings 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 terms & conditions field type description offers\[] terms and conditions string required to implement html content containing legal terms and conditions for the offer must be rendered as raw html in your interface supports common html tags including \<a> , \<strong> , \<p> , \<ul> , \<ol> , \<li> , etc always display or make accessible to users before they claim offers to ensure legal compliance expected terms & conditions html tags , , , , , , , , , , , , , , , , 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 tracking & analytics field type description offers\[] pixel string required to implement the impression beacon url for tracking when the offer is visibly displayed to the user this url must be requested exactly once per impression, only when the offer is actually visible in the viewport how to use fire via an image request or fetch call a successful get request to this url is required for the impression to be recorded in the momentscience dashboard offers\[] adv pixel url string optional advertiser specific impression tracking url when present, it must be fired at the same time as the primary offers\[] pixel url this will allow advertisers to track impressions in their own analytics systems how to use trigger via an image request or fetch call simultaneously with the primary pixel a successful get request to this url is required for the impression to be counted beacons object the offers\[] beacons object contains additional tracking endpoints field type description offers\[] beacons close string optional url to fire when the user dismisses the offer container, reaches the end of browsing session, or navigates away for reporting purposes a successful get call to beacons close is required if implemented offers\[] beacons no thanks click string optional url to fire specifically when the user clicks the negative cta button (defined by cta no ) provides valuable data on explicit offer rejections versus passive dismissals for reporting purposes a successful get call to beacons no thanks clicks is required if implemented perkswallet & loyalty features field type description offers\[] save for later url string 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\[] is loyaltyboost boolean optional flag indicating whether the offer is eligible for additional loyalty program benefits or point incentives when true , the offer can provide bonus loyalty points or rewards when claimed loyaltyboost requirements string optional text explaining what the user needs to do to earn the loyalty rewards (approximately 160 characters maximum) only present when is loyaltyboost is true should be prominently displayed alongside the offer to communicate the additional value proposition settings object the settings object provides display preferences and configuration options for the presentation of offers it controls which offers should be featured, how they should be organized, and what ui elements should be displayed the only essential attribute to focus on is field type description settings featured offer list array of integers ids of offers that should be given priority placement or special visual treatment in your ui