Integrate USP Using API

31 min

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_idin 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_idusing 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_idis 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_idyou 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

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

{
  "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

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.

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"
  }'

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

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

{
  "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

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

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

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

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}}

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

{
  "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

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)

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"
}'

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