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.

Proxy Connect Flow

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.

Direct Connect Flow

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

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

Request Header

Header	Required	Description
Content-Type	Yes	Must be application/json
Accept	No	Set to application/jsonfor 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 1to 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_fpparameter 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 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).
}'

API Response

A successful response from the MomentPerks API returns a dataobject 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.

<a>, <href>, <strong>, <small>, <p>, <ul>, <ol>, <li>, <b>, <i>, <span>, <s>, <sub>, <sup>, <table>, <tr>, <u>

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_idis present in the request: save_for_later_urlcontains a valid POSTendpoint. 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 offerobject 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.

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 Moments API integration checklist 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 [email protected].