MomentPerks API

overview the momentperks api offers a flexible, programmatic interface for integrating momentscience offers into your application or website it is compatible with any environment capable of making http requests and returns structured json responses for easy integration use cases display personalized offers at checkout to increase average order value present special deals during user idle time to boost engagement show targeted promotions after specific user actions (e g , article completion) monetize natural breaks in user experience with relevant offers integration architecture proxy connect (recommended) in this approach, your application or website communicates with your own proxy server the proxy server then securely forwards requests and responses to and from the momentperks api this architecture allows you to add custom business logic, logging, or caching at the proxy layer secure api credentials and control outbound traffic maintain better observability of requests direct connect in a direct integration, your app or website makes requests directly to the momentperks api to retrieve and render offers this method is simple to implement suitable for rapid prototyping or low risk environments however, it may expose api keys and is less suitable for production use without additional security measures try it out try our moments 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 must include a valid 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 offers endpoint method post url https //api adspostx com/native/v2/offers json https //api adspostx com/native/v2/offers json request header header required description content type yes must be application/json accept no set to application/json for explicit json responses query parameters parameter type required description api key string yes your api key with "ads/offers permission learn more loyaltyboost string no controls inclusion of loyaltyboost offers 0 exclude all loyaltyboost offers 1 include if available 2 show only loyaltyboost offers creative string no set to 1 to return only offers with at least one creative (image) campaignid string no filter to return offers from a specific campaign only one campaign can be specified per request body parameters parameter type required description placement string yes an attribute that represents the specific page, section, or location where the offer unit was triggered (e g , checkout page , article end ) this parameter enables enhanced reporting, analytics, and traffic segmentation pub user id string required if using 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 ua string recommended the user agent of the end user required for proper targeting if proxying requests via a server call, be sure to pass through the user agent of the end user ip string recommended end user's ip address for geo targeting adpx fp string recommended a unique alphanumeric user identifier enables frequency capping and opt out handling should be persistent and anonymous dev string no set to 1 to return test offers ignores geo restrictions and disables tracking use for development and testing only \[custom] string no custom key value attributes for passing additional metadata in the request payload these attributes are included in conversion reports and can be used for advanced segmentation, analytics, or tracking purposes you can include multiple custom attributes each must be a valid key value pair within the json body the adpx fp parameter is strongly recommended for all integrations it is a persistent, anonymous user identifier that enables per user frequency capping prevents re serving offers after opt out improves overall offer targeting and performance this value should be a consistent, non pii, alphanumeric string generated for each user request example curl request example curl request post \\ \ url 'https //api adspostx com/native/v2/offers 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 )", // recommended end user user agent string for targeting "ip" "203 0 113 45", // recommended ip address of the end user for geo and device targeting "adpx fp" "1234abcd 5678 efgh 9101 ijklmnopqrst", // strongly recommended unique, persistent, non pii user fingerprint "pub user id" "1234abcd 5678 efgh 9101 ijklmnopqrst", // required for pwaas unique, anonymous user id consistent across sessions "creative" "1", // optional set to '1' to return offers with at least one creative "loyaltyboost" "1", // optional '1' to include loyaltyboost offers, '2' for loyaltyboost only "dev" "1" // optional '1' to return test offers (no tracking, ignores geo) }' javascript request example const fetch = require('node fetch'); // use native fetch in modern environments const url = 'https //api adspostx com/native/v2/offers json?api key=replace with your api key'; const headers = { 'content type' 'application/json' }; const body = { placement 'checkout confirmation page', // required ua navigator useragent, // recommended (use real user agent if proxying) ip '203 0 113 45', // recommended (if known) adpx fp '1234abcd 5678 efgh 9101 ijklmnopqrst', // strongly recommended pub user id '1234abcd 5678 efgh 9101 ijklmnopqrst', // required for pwaas creative '1', // optional loyaltyboost '1', // optional dev '1' // optional (test mode) }; fetch(url, { method 'post', headers, body json stringify(body) }) then(res => res json()) then(data => console log('offers ', data)) catch(err => console error('error fetching offers ', err)); kotlin request example import okhttp3 import org json jsonobject import java io ioexception val client = okhttpclient() val json = jsonobject() apply { put("placement", "checkout confirmation page") put("ua", "mozilla/5 0 (linux; android 11 )") put("ip", "203 0 113 45") put("adpx fp", "1234abcd 5678 efgh 9101 ijklmnopqrst") put("pub user id", "1234abcd 5678 efgh 9101 ijklmnopqrst") put("creative", "1") put("loyaltyboost", "1") put("dev", "1") } val body = requestbody create(mediatype parse("application/json"), json tostring()) val request = request builder() url("https //api adspostx com/native/v2/offers json?api key=replace with your api key") post(body) addheader("content type", "application/json") build() client newcall(request) enqueue(object callback { override fun onfailure(call call, e ioexception) { println("error ${e message}") } override fun onresponse(call call, response response) { response body()? string()? let { println("offers $it") } } }) swift request example import foundation let url = url(string "https //api adspostx com/native/v2/offers json?api key=replace with your api key")! var request = urlrequest(url url) request httpmethod = "post" request setvalue("application/json", forhttpheaderfield "content type") let body \[string any] = \[ "placement" "checkout confirmation page", "ua" "mozilla/5 0 (iphone; cpu iphone os 15 0 like mac os x)", "ip" "203 0 113 45", "adpx fp" "1234abcd 5678 efgh 9101 ijklmnopqrst", "pub user id" "1234abcd 5678 efgh 9101 ijklmnopqrst", "creative" "1", "loyaltyboost" "1", "dev" "1" ] request httpbody = try? jsonserialization data(withjsonobject body) let task = urlsession shared datatask(with request) { data, response, error in guard let data = data, error == nil else { print("error ", error ?? "unknown error") return } if let json = try? jsonserialization jsonobject(with data) { print("offers ", json) } } task resume() api response a successful response from the momentperks api returns a data object containing one or more offers each offer object includes all the metadata required to render and track a momentscience offer within your application field type description session id string unique identifier for the current user session offers array array of offer objects (see detailed structure below) count integer total number of offers returned in this response privacy url string url to momentscience's privacy policy for user transparency styles object visual styling definitions for rendering offers in ui settings object display configuration for controlling offer presentation you can easily manage how many offers are returned in the response from your dashboard navigate to the configuration page locate the "number of offers" setting set your desired number of offers to be returned click "save configuration" to apply the changes sample response { "data" { "session id" "abc123 def456 ghi789", "offers" \[ { "id" 12345, "campaign id" 67890, "advertiser name" "premium sports store", "title" "get 25% off athletic wear + free shipping", "description" "save on top brand athletic wear, running shoes, and gym equipment free shipping on orders over $50 ", "short headline" "25% off athletic wear", "short description" "save on top brands + free shipping over $50", "mini text" "excludes sale items valid through 12/31/2024 ", "click url" "https //offers momentscience com/click/abc123", "cta yes" "shop now", "cta no" "no thanks", "image" "https //cdn momentscience com/creatives/sports banner jpg", "qr code img" "data\ image/png;base64,ivborw0kggoaaaansuheugaa ", "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 }, { "id" 1002, "url" "https //cdn momentscience com/creatives/sports banner jpg", "height" 200, "width" 800, "type" "jpg", "is primary" false, "aspect ratio" 4 0 } ], "terms and conditions" "\<p>\<strong>offer valid through december 31, 2024 \</strong>\</p>\<ul>\<li>cannot be combined with other offers\</li>\<li>excludes sale items\</li>\<li>free shipping on orders $50+\</li>\</ul>", "pixel" "https //tracking momentscience com/impression/abc123", "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" }, "offerwall enabled" true, "perkswallet enabled" true, "save for later url" "https //api momentscience com/wallet/save", "offerwall url" "https //offers momentscience com/wall/user123", "is loyaltyboost" true, "loyaltyboost requirements" "complete purchase to earn 500 bonus points" "tags" \["security", "vpn", "privacy"], } ], "count" 1, "privacy url" "https //momentscience com/privacy", "styles" { "primary color" "#007bff", "background color" "#ffffff", "text color" "#333333" // more styles parameters }, "settings" { "max display time" 30, "auto close" false // more settings parameters } } } offer object properties each offer in the offers array contains the following properties identification & metadata field type description offers\[] id integer unique id of the offer offers\[] campaign id integer id of the campaign the offer belongs to offers\[] advertiser name string name of the advertiser providing the offer use for transparency or display if required offer text content field type description offers\[] title string primary headline for desktop or wide displays max 90 characters ideal 40 characters offers\[] description string full offer description for desktop or wide displays max 220 characters ideal 140 characters offers\[] mini text string legal disclaimers or subtext avoid unless necessary max 160 characters offers\[] short headline string compact headline for mobile or narrow displays max 60 characters ideal 40 characters offers\[] short description string compact description for mobile or narrow displays max 140 characters ideal 140 characters use title and description for desktop/tablet layouts use short headline and short description for mobile/compact layouts reserve mini text for essential legal disclaimers only call to action elements field type description offers\[] click url url the url to open when the user accepts the offer must be implemented in your integration (required) offers\[] cta yes string suggested label for the primary (positive) call to action button max 25 characters ideal 20 characters offers\[] cta no string suggested label for the secondary (negative) call to action button max 25 characters ideal 20 characters images & creatives assets field type description offers\[] image url primary image representing the offer offers\[] qr code img string base64 encoded png or jpeg of qr code that represents click url use in cross device or offline contexts format png/jpeg dimensions 228×228 px color black on white offers\[] creatives array array of additional creative image objects for dynamic rendering creatives object structure parameter type description offers\[] creatives\[] id integer unique identifier for this creative asset offers\[] creatives\[] url url direct url to the image asset offers\[] creatives\[] height double image height in pixels offers\[] creatives\[] width double image width in pixels offers\[] creatives\[] type string image format, e g , png , jpg offers\[] creatives\[] is primary boolean indicates if the image is the primary creative offers\[] creatives\[] aspect ratio double aspect ratio (width ÷ height) 1 = square <1 = portrait >1 = landscape terms & conditions field type description offers\[] terms and conditions string (html) required to implemnt 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 (terms and conditions) , , , , , , , , , , , , , , , , 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 url required to implelent 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\[] adv pixel url url optional advertiser impression tracker fire in addition to primary pixel offers\[] beacons object additional event beacons interaction beacons parameter type description offers\[] beacons close url fire when the offer container is dismissed or the user scrolls past all offers offers\[] beacons no thanks click url fire when the user clicks the negative cta button recommended feature flags parameter type description offers\[] offerwall enabled boolean indicates if perkswall navigation ui is enabled for this offer offers\[] perkswallet enabled boolean boolean value to indicate if the perkswallet feature that enables user to save offers into their accounts is enabled or not offers\[] save for later url url 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\[] offerwall url url the url that the user will be redirected to when clicking on the "more offers" button that takes him to the perkswall page loyaltyboost attributes parameter type description offers\[] is loyaltyboost boolean indicates if the offer qualifies for loyaltyboost incentives offers\[] loyaltyboost requirements string describes actions the user must take to receive loyaltyboost rewards max 160 characters parsing the response and displaying offers once you receive a successful response from the momentperks endpoint, you can begin rendering offers using the structured data provided in the response each offer object contains all the necessary fragments (text, images, tracking urls, etc ) to generate and present an interactive, trackable offer unit in your app or website display sequence and tracking flow to ensure accurate performance tracking and seamless offer display, implement the following flow render the first offer using its content fragments ( title , description , image , click url , etc ) fire the impression beacon url ( pixel ) as soon as the first offer is visibly displayed to the user a successful get request to this url is required for momentscience to register the impression handle user interaction if the user clicks the positive cta, redirect them to the click url if the user clicks the negative cta, fire the no thanks click url from the beacons object render the next offer in sequence, and again display its visual and text content fire its corresponding pixel beacon for impression tracking continue this process until all offers are exhausted or the user exits the offer flow why impression beacons matter accurate impression tracking via the pixel url is critical because it enables momentscience to measure key performance metrics such as click through rate (ctr) effective cpm (ecpm) conversion rate optimize offer relevance and ranking based on real time engagement data maintain accurate billing and reporting data for both advertisers and publishers implementing event beacons beyond impression tracking, momentperks also supports tracking additional user interactions through the beacons object in each offer beacon name description no thanks click fire this url when the user taps the negative cta ("no thanks", "not now") close fire this url when the user dismisses the offer container or ends the flow these urls should be triggered with simple get requests at the appropriate moments beacons help measure user intent and drop off behavior on the fly image resizing to optimize for different screen sizes and resolutions, you can dynamically resize image assets using query parameters ?width=xxx resize width to xxx pixels ?height=yyy resize height to yyy pixels ?aspect ratio=x\ y override aspect ratio example https //cdn momentscience com/creative jpg?width=300 these transformations are handled server side and ensure that images remain responsive across devices integration checklist we recommend you go through our implementation checklist docid\ nzqqzpx9czbn mzqypdxr to ensure that you have not missed any integration steps this will help you gain the full advantage of the features provided by momentscience if you're encountering problems rendering offers, triggering beacons, or receiving data, reach out to help\@momentscience com