Integrate USP Using API

who is this for developers who want complete control over the user selected perks experience and prefer to build a fully custom ui using the api outcome implement usp via the momentperks api by managing offer retrieval, session ids, user selections, and tracking without relying on the sdk overview if you want full control over how offers are displayed, selected, and submitted within your app or website, you can build a fully custom integration using the usp apis this approach lets you design your own user interface while using our backend for session management, offer selection, and tracking prerequisites you have an active momentperks integration using the api integration steps step 1 retrieve offers using the momentperks api user selected perks (usp) is built on top of the momentperks api to enable usp, your integration must call the api to retrieve eligible offers for a given user each request to the momentperks api must include a pub user id in the request body a unique, non pii identifier representing the end user used to associate offer sessions and selections with a specific user must remain consistent across user sessions and devices can be the same value as adpx fp, if available you can generate the pub user id using any method that ensures uniqueness (e g , a uuid stored in localstorage or server side user id) example api response a successful response will return a session id in the body the session id is a unique identifier for the user's active offer session it must be stored and reused for any subsequent offer selection, unselection, or session state operations it is tied directly to the pub user id you provided { "data" { "session id" "abc123456789", // other parameters } } step 2 build your ui with the offer data returned from the momentperks api, you can build a fully customized user selected perks (usp) interface tailored to your brand and user experience the ui should allow users to view available offers including titles, descriptions, images, and reward values select or deselect individual offers bulk select or unselect all offers at once for convenience this interface acts as the primary point of interaction for users to curate their perks before checkout or a major app flow to help users understand the value of selecting offers, we recommend adding a short introduction above the offer unit for example 💡 choose the perks you’re interested in before completing your purchase you’ll earn rewards by engaging with these personalized offers step 3 handle user interactions once the offer selection ui is in place, you need to track and communicate user interactions, such as selecting or unselecting offers, by calling the appropriate momentperks endpoints all usp api endpoints use the following base url https //api momentscience com select offer api use this endpoint when a user selects an individual offer to indicate interest this must be called for each individual offer selection as part of the user selected perks (usp) flow http method post url https //api momentscience com/sdk/v4/usp/{{session id}}/{{campaign id}}/select json https //api momentscience com/sdk/v4/usp/{{session id}}/{{campaign id}}/select json select offer api post https //api momentscience com/sdk/v4/usp/{{session id}}/{{campaign id}}/select json replace {{session id}} with the session id returned by the momentperks api {{campaign id}} with the id of the selected offer's campaign headers header value required authorization bearer {{api key}} yes content type application/json yes request body field type required description pub user id string yes unique, non pii identifier for the end user must be consistent across sessions example curl request example curl request curl x post \\ "https //api adspostx com/sdk/v4/usp/{{session id}}/{{campaign id}}/select json" \\ h "content type application/json" \\ h "authorization bearer {{api key}}" \\ d '{ "pub user id" "your pub user id" }' success response { "status" "success", "data" { "session id" "abc123456789", "campaign id" 849 } } response fields field type description session id string the current session id tied to the user campaign id number the campaign id of the offer that was selected unselect offer api use this endpoint when a user unselects a previously selected offer this must be called for each individual offer unselection as part of the user selected perks (usp) flow endpoint http method post url https //api momentscience com/sdk/v4/usp/{{session id}}/{{campaign id}}/unselect json https //api momentscience com/sdk/v4/usp/{{session id}}/{{campaign id}}/unselect json post https //api momentscience com/sdk/v4/usp/{{session id}}/{{campaign id}}/unselect json replace {{session id}} with the session id returned by the momentperks api {{campaign id}} with the id of the offer's campaign that the user is unselecting headers header value required authorization bearer {{api key}} yes content type application/json yes request body field type required description pub user id string yes unique, non pii identifier for the end user must be consistent across sessions example curl request curl x post \\ "https //api adspostx com/sdk/v4/usp/{{session id}}/{{campaign id}}/unselect json" \\ h "content type application/json" \\ h "authorization bearer {{api key}}" \\ d '{ "pub user id" "your pub user id" }' success response { "status" "success", "data" { "session id" "abc123456789", "campaign id" 849 } } response fields field type description session id string the current session id tied to the user campaign id number the campaign id of the offer that was unselected bulk select offers api use this endpoint when a user selects multiple offers at once this is commonly used when implementing a "select all" interaction in the user selected perks (usp) flow http method post url https //api momentscience com/sdk/v4/usp/{{session id}}/select json https //api momentscience com/sdk/v4/usp/{{session id}}/select json post https //api momentscience com/sdk/v4/usp/{{session id}}/select json replace {{session id}} with the session id returned by the momentperks api headers header value required authorization bearer {{api key}} yes content type application/json yes request body example request body { "pub user id" "your pub user id", "campaign ids" \[849, 850, 851] } field type required description pub user id string yes unique, non pii identifier for the end user must match previously used id campaign ids array yes array of campaign ids the user selected example curl request curl x post \\ "https //api momentscience com/sdk/v4/usp/{{session id}}/select json" \\ h "content type application/json" \\ h "authorization bearer {{api key}}" \\ d '{ "pub user id" "user 123456", "campaign ids" \[849, 850, 851] }' response fields field type description session id string the session id used in the request selected campaign ids array list of campaign ids that were successfully selected bulk unselect offers api use this endpoint when a user unselects multiple offers at once (e g , "unselect all") within the usp flow endpoint http method post url https //api momentscience com/sdk/v4/usp/{{session id}}/unselect json https //api momentscience com/sdk/v4/usp/{{session id}}/unselect json post https //api momentscience com/sdk/v4/usp/{{session id}}/unselect json replace {{session id}} with the session id returned by the momentperks api headers header value required authorization bearer {{api key}} yes content type application/json yes request body { "pub user id" "your pub user id", "campaign ids" \[849, 850, 851] } field type required description pub user id string yes unique, non pii identifier for the end user must match previously used id campaign ids array yes array of campaign ids the user unselected example curl request example request curl x post \\ "https //api momentscience com/sdk/v4/usp/{{session id}}/unselect json" \\ h "content type application/json" \\ h "authorization bearer {{api key}}" \\ d '{ "pub user id" "user 123456", "campaign ids" \[849, 850, 851] }' success response { "status" "success", "data" { "session id" "abc123456789", "unselected campaign ids" \[849, 850, 851] } } success response field type description session id string the session id used in the request unselected campaign ids array list of campaign ids that were successfully unselected step 5 retrieve current session state use this endpoint to fetch the current state of a usp session, including active session metadata available campaigns in the session currently selected campaign ids this is useful for resuming sessions, pre selecting previously chosen offers, or syncing ui state across devices use cases scenario why to call this endpoint resume session on app relaunch show previously selected offers and campaign list after a user returns sync across devices restore selection state if the user switches from mobile to desktop prepopulate selection ui populate your offer selection ui with current selection from backend qa / debugging inspect current session state and selections for debugging or qa get session state endpoint use this endpoint to fetch session details, selected offers, and metadata http method get url https //api momentscience com/sdk/v4/usp/session/{{session id}} json?pub user id={{pub user id}} https //api momentscience com/sdk/v4/usp/session/{{session id}} json?pub user id={{pub user id}} get https //api momentscience com/sdk/v4/usp/session/{{session id}} json?pub user id={{pub user id}} replace {{session id}} with the active session id {{pub user id}} with the unique user id from your system headers header value required authorization bearer {{api key}} yes example curl request example curl request curl x get \\ "https //api momentscience com/sdk/v4/usp/session/{{session id}} json?pub user id={{pub user id}}" \\ h "authorization bearer {{api key}}" example response (truncated) { "status" "success", "data" { "session" { "session id" "d48734cd9d465f3285c8e38c917de44b7b6729d8", "pub user id" "momentscience usp demo", "user id" 3507, "device" "desktop", "os" "windows", "browser" "chrome", "campaigns" \[ { "campaign id" 2955, "title" "get $15 cash back on today's purchase", "cta yes" "claim your $15", "cta no" "no, thanks", "image" "https //adpx b cdn net/campaigns/1693/f5642bf0266822795a9f4d1827d977ce png", "advertiser name" "shipments free" }, { "campaign id" 2966, "title" "enter to win a $500 ebay gift card!", "cta yes" "claim now!", "cta no" "no, thanks", "image" "https //adpx b cdn net/campaigns/2966/b88b7ce4e1086282c85e461e51f37f64 jpg", "advertiser name" "ebay" }, { "campaign id" 3404, "title" "your dream hawaiian get away is just a click away!", "cta yes" "yes please", "cta no" "no thanks", "image" "https //adpx b cdn net/campaigns/3404/1b24eaff41cfeebf04338544e7fe5372 png", "advertiser name" "hawaiian airlines" } ], "selected" \[2955, 2966, 3404], "sequence" \[2955, 3404, 2966], "sdk payload" { "country" "us", "dev" true } } } } key response fields field type description session id string unique session identifier pub user id string your platform's user id campaigns\[] array campaigns in the session campaign id int unique id for each campaign title , cta yes , cta no string text for ui display image string primary image url selected\[] array ids of currently selected campaigns sequence\[] array campaign display order sdk payload dev boolean indicates sandbox vs production mode device , os , browser string basic user agent fingerprinting location city/country string detected geo location from ip you can use the selected\[] array to mark offers as already selected in your ui enable a "bulk unselect" button if selected length > 0 enable a "bulk select all" using the ids in campaigns\[] campaign id step 6 complete the session once your user has reviewed and selected their desired offers, and completed their primary action (such as checkout or form submission), you must notify momentscience that the usp (user selectable perks) session is complete complete session api http method post url https //api adspostx com/sdk/v4/usp/session/{session id} json https //api adspostx com/sdk/v4/usp/session/{session id} json post https //api adspostx com/sdk/v4/usp/session/{session id} json replace {session id} with the active session id received during initialization payload parameters parameter type required description pub user id string yes your internal user id (should match session init) example request curl x post "https //api adspostx com/sdk/v4/usp/session/d48734cd9d465f3285c8e38c917de44b7b6729d8 json" \\ h "authorization bearer b9a31935 a222 4bdd bfc6 a63e6bb01e39" \\ h "content type application/json" \\ d '{ "pub user id" "momentscience usp demo" }' example response { "status" "success", "data" { "session" { "user id" 3507, "sdk payload" { "pub user id" "momentscience usp demo", "country" "us", "dev" true, " location" { "country" "eg", "state" "alx", "city" "alexandria", "zipcode" null } }, "session id" "d48734cd9d465f3285c8e38c917de44b7b6729d8", "user agent" "mozilla/5 0 (windows nt 10 0; win64; x64) applewebkit/537 36 (khtml, like gecko) chrome/138 0 0 0 safari/537 36", "pub user id" "momentscience usp demo", "tags" \[], "settings" {}, "source" "native\ api", "device" "desktop", "os" "windows", "browser" "chrome", "fingerprint" "momentscience usp demo", "is embedded" false, "is mou" false, "is offerwall" false, "parent session id" null, "sequence" \[ 2955, 3404, 2966 ], "is from cache" true }, "selected" \[ { "id" 5651, "campaign id" 2955, "title" "get $15 cash back on today's purchase", "description" "get free shipping rebates on online purchases just for trying shipments free claim your $15 cash back now!", "click url" "https //adspostx com", "image" "https //adpx b cdn net/campaigns/1693/f5642bf0266822795a9f4d1827d977ce png", "mini text" "", "terms and conditions" "", "pixel" "https //adspostx com/p png", "cta yes" "claim your $15", "cta no" "no, thanks", "useraction cta" null, "useraction url" null, "adv pixel url" "", "beacons" { "close" "https //adspostx com/event/record/close?oid=5651\&cid=2955\&pid=3507\&sess id=d48734cd9d465f3285c8e38c917de44b7b6729d8\&fp=momentscience usp demo", "no thanks click" "https //adspostx com/event/record/no thanks click?oid=5651\&cid=2955\&pid=3507\&sess id=d48734cd9d465f3285c8e38c917de44b7b6729d8\&fp=momentscience usp demo" }, "creatives" \[ { "id" 4215, "url" "https //adpx b cdn net/campaigns/1693/f5642bf0266822795a9f4d1827d977ce png", "height" 300, "width" 400, "type" "png", "creative type" "", "is primary" true, "aspect ratio" 1 33, "user id" 0 }, { "id" 4966, "url" "https //adpx b cdn net/campaigns/2955/2aefbd58fa4e2ac40eebdd076e873ba2 png", "height" 280, "width" 1000, "type" "png", "creative type" "hero image", "is primary" false, "aspect ratio" 3 57, "user id" 0 }, { "id" 4967, "url" "https //adpx b cdn net/campaigns/2955/0a64c7f84074b181a4b6631ac2db2195 png", "height" 150, "width" 150, "type" "png", "creative type" "icon image", "is primary" false, "aspect ratio" 1, "user id" 0 } ], "offerwall enabled" true, "perkswallet enabled" true, "short description" "get free shipping rebates on online purchases just for trying shipments free claim your $15 cash back now!", "short headline" "get $15 cash back on today's purchase", "advertiser name" "shipments free", "is loyaltyboost" false, "loyaltyboost requirements" "", "save for later url" "https //api perkswallet com/pwaas/save json?o id=5651\&c id=2955\&p id=3507\&sess id=d48734cd9d465f3285c8e38c917de44b7b6729d8\&pub user id=momentscience usp demo", "tags" \[ "delivery", "rewards" ], "offer description" "", "campaign" { "campaign images" \[ { "id" 4215, "url" "https //adpx b cdn net/campaigns/1693/f5642bf0266822795a9f4d1827d977ce png", "height" 300, "width" 400, "type" "png", "creative type" "", "is primary" true, "aspect ratio" 1 33, "user id" 0 }, { "id" 4966, "url" "https //adpx b cdn net/campaigns/2955/2aefbd58fa4e2ac40eebdd076e873ba2 png", "height" 280, "width" 1000, "type" "png", "creative type" "hero image", "is primary" false, "aspect ratio" 3 57, "user id" 0 }, { "id" 4967, "url" "https //adpx b cdn net/campaigns/2955/0a64c7f84074b181a4b6631ac2db2195 png", "height" 150, "width" 150, "type" "png", "creative type" "icon image", "is primary" false, "aspect ratio" 1, "user id" 0 } ], "offer description" "", "is product" false } }, { "id" 6075, "campaign id" 3404, "title" "your dream hawaiian get away is just a click away!", "description" "need to get away? hawaiian airlines offers 150 daily flights within the hawaiian islands, and non stop flights between hawai'i and major us cities more than any other airline book now and save!", "click url" "https //adspostx com", "image" "https //adpx b cdn net/campaigns/3404/1b24eaff41cfeebf04338544e7fe5372 png", "mini text" "", "terms and conditions" "", "pixel" "https //adspostx com/p png", "cta yes" "yes please", "cta no" "no thanks", "useraction cta" null, "useraction url" null, "adv pixel url" "", "beacons" { "close" "https //adspostx com/event/record/close?oid=6075\&cid=3404\&pid=3507\&sess id=d48734cd9d465f3285c8e38c917de44b7b6729d8\&fp=momentscience usp demo", "no thanks click" "https //adspostx com/event/record/no thanks click?oid=6075\&cid=3404\&pid=3507\&sess id=d48734cd9d465f3285c8e38c917de44b7b6729d8\&fp=momentscience usp demo" }, "creatives" \[ { "id" 6078, "url" "https //adpx b cdn net/campaigns/3404/1b24eaff41cfeebf04338544e7fe5372 png", "height" 300, "width" 300, "type" "png", "creative type" "offer image", "is primary" true, "aspect ratio" 1, "user id" 0 } ], "offerwall enabled" true, "perkswallet enabled" false, "short description" "hawaiian airlines offers 150 daily flights within the hawaiian islands, and non stop flights between hawai'i and the us book now and save!", "short headline" "your dream hawaiian get away is just a click away!", "advertiser name" "hawaiian airlines", "is loyaltyboost" false, "loyaltyboost requirements" "", "save for later url" "https //api perkswallet com/pwaas/save json?o id=6075\&c id=3404\&p id=3507\&sess id=d48734cd9d465f3285c8e38c917de44b7b6729d8\&pub user id=momentscience usp demo", "tags" \[], "offer description" "", "campaign" { "campaign images" \[ { "id" 6078, "url" "https //adpx b cdn net/campaigns/3404/1b24eaff41cfeebf04338544e7fe5372 png", "height" 300, "width" 300, "type" "png", "creative type" "offer image", "is primary" true, "aspect ratio" 1, "user id" 0 } ], "offer description" "", "is product" false } }, { "id" 5662, "campaign id" 2966, "title" "enter to win a $500 ebay gift card!", "description" "take a quick survey for a chance to win a $500 ebay gift card your opinion counts!", "click url" "https //adspostx com", "image" "https //adpx b cdn net/campaigns/2966/b88b7ce4e1086282c85e461e51f37f64 jpg", "mini text" "", "terms and conditions" "", "pixel" "https //adspostx com/p png", "cta yes" "claim now!", "cta no" "no, thanks", "useraction cta" null, "useraction url" null, "adv pixel url" "", "beacons" { "close" "https //adspostx com/event/record/close?oid=5662\&cid=2966\&pid=3507\&sess id=d48734cd9d465f3285c8e38c917de44b7b6729d8\&fp=momentscience usp demo", "no thanks click" "https //adspostx com/event/record/no thanks click?oid=5662\&cid=2966\&pid=3507\&sess id=d48734cd9d465f3285c8e38c917de44b7b6729d8\&fp=momentscience usp demo" }, "creatives" \[ { "id" 4410, "url" "https //adpx b cdn net/campaigns/2966/b88b7ce4e1086282c85e461e51f37f64 jpg", "height" 400, "width" 400, "type" "jpg", "creative type" "", "is primary" true, "aspect ratio" 1, "user id" 0 }, { "id" 5425, "url" "https //adpx b cdn net/campaigns/2966/b1fec4ae049fc904c3bc28dcff5b4f46 png", "height" 150, "width" 150, "type" "png", "creative type" "icon image", "is primary" false, "aspect ratio" 1, "user id" 0 }, { "id" 5609, "url" "https //adpx b cdn net/campaigns/2966/3f9e43b0952e5696669a13fa94f1af11 png", "height" 448, "width" 1600, "type" "png", "creative type" "hero image", "is primary" false, "aspect ratio" 3 57, "user id" 0 } ], "offerwall enabled" true, "perkswallet enabled" true, "short description" "take a quick survey for a chance to win a $500 ebay gift card your opinion counts!", "short headline" "enter to win a $500 ebay gift card!", "advertiser name" "ebay", "is loyaltyboost" false, "loyaltyboost requirements" "", "save for later url" "https //api perkswallet com/pwaas/save json?o id=5662\&c id=2966\&p id=3507\&sess id=d48734cd9d465f3285c8e38c917de44b7b6729d8\&pub user id=momentscience usp demo", "tags" \[], "offer description" "", "campaign" { "campaign images" \[ { "id" 4410, "url" "https //adpx b cdn net/campaigns/2966/b88b7ce4e1086282c85e461e51f37f64 jpg", "height" 400, "width" 400, "type" "jpg", "creative type" "", "is primary" true, "aspect ratio" 1, "user id" 0 }, { "id" 5425, "url" "https //adpx b cdn net/campaigns/2966/b1fec4ae049fc904c3bc28dcff5b4f46 png", "height" 150, "width" 150, "type" "png", "creative type" "icon image", "is primary" false, "aspect ratio" 1, "user id" 0 }, { "id" 5609, "url" "https //adpx b cdn net/campaigns/2966/3f9e43b0952e5696669a13fa94f1af11 png", "height" 448, "width" 1600, "type" "png", "creative type" "hero image", "is primary" false, "aspect ratio" 3 57, "user id" 0 } ], "offer description" "", "is product" false } } ] } } always complete the session after the user’s final decision to ensure selected offers are saved you can inspect the selected array in the response to confirm which offers were logged ensure you’re using the same pub user id used in the session initialization step 📢 if you're running into any issues while going through the integration process, feel free to contact us at help\@momentscience com mailto\ help\@momentscience com