Perkswall API

22 min

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 https //app momentscience com navigate to https //app momentscience com/account/profile settings generate a new api key with the "ads/offers" permission for more details, see docid\ t1d2y6emug0lh0t bi6ao fetch perkswall offers method post base url https //api adspostx com/native/v4/perkswall json header parameters true 224,224,226 unhandled content type unhandled content type unhandled content type unhandled content type unhandled content type unhandled content type unhandled content type unhandled content type unhandled content type query parameters true 131,94 28458498023716,88 03014711041467,360 6852679093482left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type body parameters true 119,63,92,100left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type 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 true 81,50,231left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type offers (array of offer objects) identification & metadata true 166,51,233left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type text content true 221,83 49333333333334,369 50666666666666left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type call to action elements true 104,50,236left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type images & creative assets true 112,50,232left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type creatives array the offers\[] creatives array contains detailed information about available images true 158,65,219left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type categorization true 164,141 86666666666665,368 1333333333333left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type terms & conditions true 224,71,379left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type 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 true 205,85 45777777777778,383 5422222222222left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type beacons object the offers\[] beacons object contains additional tracking endpoints true 224,59,391left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type perkswallet & loyalty features true 224,91,359left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type 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 true 224,160,290left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type 📢 if you're running into any issues while going through the integration process, feel free to contact us at mailto\ help\@momentscience com