--- title: MomentPerks API slug: momentperks-api icon: {"apiMethod":"POST"} docTags: createdAt: 2025-08-01T16:49:26.739Z --- :::hint{type="info"} **Who is this for:** Developers integrating MomentPerks into websites, apps, or any environment capable of making HTTP requests who need full programmatic control. **Outcome:** Fetch personalized offer data in JSON and render it in a custom UI using either a proxy connect or direct connect architecture. ::: # 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 :::hint{type="success"} Before integrating with the MomentPerks API, we recommend reviewing our [Offer Anatomy](docId\:EASoK60fMEjlmkIjEOmMr) documentation to understand the structure of offers and how to effectively use response elements to create compelling offer displays. ::: ## 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. ![](https://api.archbee.com/api/optimize/ELjiwjWcrv0a1IejQFFAF/1MIXIm5-lRakNbi9ja3Ps_image.png "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. ![](https://api.archbee.com/api/optimize/ELjiwjWcrv0a1IejQFFAF/qph_PaZFYZ5kSS9MgEJWl_image.png "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. :::Iframe{iframeHeight="0" code=""} ::: ## 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** 1. Log in to the [MomentScience Dashboard](https://app.momentscience.com) 2. Navigate to [Profile Settings > API Keys](https://app.momentscience.com/account/profile-settings) 3. Generate a new API key with the **"Ads/Offers" **permission :::hint{type="success"} For more details, see: [Getting Your API Key](docId\:CD0hKzWhbqxqwKYfO_cZG) ::: # 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.
* Learn more about [Getting Your API Key](docId\:CD0hKzWhbqxqwKYfO_cZG) | | `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. | :::hint{type="info"} 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 :::CodeblockTabs cURL Request Example ```javascript 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 ```javascript 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 ```kotlin 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 ```swift 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 | :::hint{type="success"} You can easily manage how many offers are returned in the response from your dashboard. 1. Navigate to the[ Configuration page.](https://app.momentscience.com/account/settings/behavior) 2. Locate the "Number of Offers" setting. 3. Set your desired number of offers to be returned. 4. Click "Save Configuration" to apply the changes. ::: ### Sample Response ```javascript { "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": "

Offer valid through December 31, 2024.

", "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 (HTML) | Full offer description for desktop or wide displays. Contains HTML markup and should be rendered as HTML to preserve formatting and structure.
**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 (HTML) | Compact description for mobile or narrow displays. Contains HTML markup and should be rendered as HTML to preserve formatting and structure.
**Max:** 140 characters
**Ideal:** 140 characters | :::hint{type="success"} - 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. - Render `description` and `short_description` as HTML to preserve text formatting. ::: **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. | :::CodeblockTabs Expected HTML Tags (terms\_and\_conditions) ```html , , , ,

,

    ,
      ,
    1. , , , , , , , , , ``` ::: :::hint{type="info"} 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: 1. Render the first offer using its content fragments (`title`, `description`, `image`, `click_url`, etc.). 2. 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. 3. 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. 4. Render the next offer in sequence, and again: - Display its visual and text content. - Fire its corresponding `pixel `beacon for impression tracking. 5. 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. :::CodeblockTabs Example ```javascript https://cdn.momentscience.com/creative.jpg?width=300 ``` ::: These transformations are handled server-side and ensure that images remain responsive across devices. # Next Steps ## Integration Checklist Review our [MomentPerks Integration Checklist](docId\:X6WKO1QqSk1o53zhCku_Z) to ensure you've covered all necessary steps. This helps you make the most of the features offered by MomentScience and avoid common integration issues. ### Offer Anatomy Explore our [Offer Anatomy](docId\:EASoK60fMEjlmkIjEOmMr) guide to understand how MomentPerks API responses are structured and how to use them to build effective and engaging offer units. *** If you're encountering problems rendering offers, triggering beacons, or receiving data, reach out to [help@momentscience.com](mailto\:help@momentscience.com).