Perkswall API

22 min

Who is this for: Developers building a fully custom Perkswall integration in an app or website using programmatic API calls.

Outcome: Fetch curated offer data from the Perkswall API and render a branded, interactive perks gallery using either a proxy or direct connect architecture.

Overview

The MomentScience Perkswall API provides a flexible, programmatic interface for integrating a curated “perks gallery” into your app or site. It works from any environment that can make HTTP requests and returns JSON for easy rendering and tracking.

Use Cases

Create a dedicated "Rewards Hub" where subscribers browse exclusive perks and special offers

Display relevant perks on order confirmation pages that complement customers' purchases

Embed a curated perks gallery during app loading screens or natural transition points

Elevate your loyalty program with personalized third-party perks based on member status

Integration Architecture

Proxy Connect (Recommended)

Your client talks to your proxy; your proxy calls the Perkswall API. This lets you:

Keep API keys server‑side and control outbound traffic

Add business logic, logging, or caching

Improve observability and rate limiting

Proxy Connect Flow

Direct Connect

Your client calls the Perkswall API directly. This is simple for prototypes or low‑risk environments, but may expose API keys. Add protections if used in production.

Direct Connect Flow

Try It Out

Try our Perkswall 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 require an 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 Perkswall Offers

Method: POST Base URL: https://api.adspostx.com/native/v4/perkswall.json

Header Parameters

Parameter	Required	Description
Content-Type	Yes	Specifies the media type of the request. Must be set to application/json
Accept	No	Optionally set to application/json

Query Parameters

Parameter	Type	Required	Description
api_key	String	Yes	Your API key with "Ads/Offers" permission. Must be generated from the MomentScience Dashboard.
loyaltyboost	String	No	Controls inclusion of LoyaltyBoost-eligible offers in results: • 0: Exclude all LoyaltyBoost offers • 1: Include both standard and LoyaltyBoost offers (default) • 2: Return only LoyaltyBoost offers
creative	String	No	Filter offers by creative availability: • 0: Return all matching offers regardless of creative availability (default) • 1: Only return offers with at least one creative asset

Body Parameters

Parameter	Type	Required	Description
placement	String	Yes	Identifies where the offer unit appears in your application or website. Used for segmentation, reporting, and offer targeting. Example: checkout_confirmation_page
ua	String	Recommended	End-user's complete User-Agent string. When implementing via proxy architecture, ensure you forward the actual client UA rather than your server's UA for accurate device targeting. Example: Mozilla/5.0 (Linux; Android 10; K) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.6099.43 Mobile Safari/537.36
ip	String	Recommended	End-user's IP address for geographic and demographic targeting. Used to deliver location-relevant offers. Example: 203.0.113.45
adpx_fp	String	Recommended	Persistent, anonymous identifier for frequency capping, offer rotation, and honoring opt-out preferences. Should be consistent across sessions for the same user but doesn't need to identify the user specifically. Use UUID format if possible. Example: 1234abcd-5678-efgh-9101-ijklmnopqrst
pub_user_id	String	Required for PWaaS/User Selected Perks	Non-PII persistent identifier unique to each user. Must remain consistent across sessions and devices. Used for personalization and offer saving functionality. Can match adpx_fp if preferred. Do not use personally identifiable information such as email addresses or phone numbers. Example: 1234abcd-5678-efgh-9101-ijklmnopqrst
dev	String	No	Set to 1 to receive test offers that ignore geographic restrictions and suppress production tracking events. Use only in development environments. Example: 1
subid	String	No	Free-form identifier to track specific implementations, variants, or traffic sources. Included in reporting and analytics. Example: mobile_android_app_post_transaction
<custom>	String	No	Any additional key-value pairs included in the request will be captured for reporting and segmentation. These are passed through to conversion events for attribution. Examples include source, campaign_id, or user_segment. Example: membershipID: "A45GRE987343PKD"

Notes on adpx_fp:

Should be a UUID or other consistent alphanumeric identifier

Contains no PII (Personally Identifiable Information)

Critical for frequency capping (preventing the same user from seeing the same offers repeatedly)

Persists opt-out preferences across sessions

Store in local storage, cookies, or your user database

Request Example

curl --request POST \
    --url 'https://api.adspostx.com/native/v4/perkswall.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; K) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.6099.43 Mobile Safari/537.36", // Recommended. End-user's browser/device information for targeting.
        "ip": "203.0.113.45", // Recommended. End-user's IP address for geographic targeting.
        "adpx_fp": "1234abcd-5678-efgh-9101-ijklmnopqrst", // Recommended. Persistent anonymous identifier for frequency capping.
        "pub_user_id": "1234abcd-5678-efgh-9101-ijklmnopqrst", // Required for PWaaS. Non-PII user identifier for personalization.
        "subid": "mobile_android_app_post_transaction" // Optional. Custom identifier for tracking implementation variants.
    }'

API Response

On success, the response contains a data object with an array of offers and related metadata.

Sample Response

{
  "data": {
    "session_id": "sess_12345abcde67890",
    "offers": [
      {
        "id": 5576,
        "campaign_id": 2880,
        "title": "Get 25% off athletic wear + free shipping",
        "description": "Save on top-brand athletic wear with this exclusive discount. Orders over $50 qualify for free shipping to anywhere in the continental US.",
        "click_url": "https://offers.momentscience.com/click/abc123",
        "image": "https://cdn.momentscience.com/creatives/sports-banner.jpg",
        "mini_text": "Excludes sale items. Valid through 12/31/2025.",
        "terms_and_conditions": "<p><strong>Offer valid for online purchases only.</strong> Discount applies to regular-priced items. Cannot be combined with other promotions. Free shipping valid on orders over $50 shipped to the continental US. Expires 12/31/2025.</p>",
        "pixel": "https://tracking.momentscience.com/impression/abc123",
        "cta_yes": "Shop Now",
        "cta_no": "No Thanks",
        "useraction_cta": null,
        "useraction_url": null,
        "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"
        },
        "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,
            "creative_type": "offer_image"
          },
          {
            "id": 1002,
            "url": "https://cdn.momentscience.com/creatives/sports-banner.jpg",
            "height": 200,
            "width": 800,
            "type": "jpg",
            "is_primary": false,
            "aspect_ratio": 4.0,
            "creative_type": "hero_image"
          }
        ],
        "offerwall_enabled": true,
        "perkswallet_enabled": true,
        "short_description": "Save on top brands + free shipping over $50",
        "short_headline": "25% off athletic wear",
        "advertiser_name": "Premium Sports Store",
        "is_loyaltyboost": true,
        "loyaltyboost_requirements": "Complete purchase to earn 500 bonus points",
        "save_for_later_url": "https://api.momentscience.com/wallet/save",
        "tags": ["fitness", "apparel", "sports"],
        "campaign": {
          "campaign_images": [
            {
              "id": 1001,
              "url": "https://cdn.momentscience.com/creatives/sports-square.jpg",
              "height": 400,
              "width": 400,
              "type": "jpg",
              "creative_type": "offer_image",
              "is_primary": true,
              "aspect_ratio": 1.0,
              "user_id": 0
            },
            {
              "id": 1002,
              "url": "https://cdn.momentscience.com/creatives/sports-banner.jpg",
              "height": 200,
              "width": 800,
              "type": "jpg",
              "creative_type": "hero_image",
              "is_primary": false,
              "aspect_ratio": 4.0,
              "user_id": 0
            }
          ],
        },
        "offerwall_url": "https://get.perkswall.com/offerwall?accountId=abc123&themeId=Documentation-Example&session_id=sess_12345abcde67890",
        "qr_code_img": "data:image/png;base64,iVBORw0KGgqbJ5onKTxaTymx7WWtc8rLWueVhrXhOVrXfOw1rrmJyona3741jUPa61rHtZa1zysta55WGtd87DWuuZhrXXNw1rrmoe11jUPa61rHtZa1/w/EjW+ivrQS2EAAAAASUVORK5CYII="
      }
    ],
    "settings": {
      "featured_offer_list": [582, 723, 1154, 1693, 1576, 1863]
    },
    "count": 1
  }
}

Top‑Level Fields

Field	Type	Description
data.offers	Array	List of offer objects containing all offer information
data.settings	Object	Display preferences and configuration options; may include featured_offer_list (array of offer IDs), header text, display controls, and layout settings
data.styles	Object	Visual styling configuration for the perks interface including colors, fonts, spacing, and component-specific settings
data.session_id	String	Unique identifier for the current browsing session
count	Integer	Number of offers returned

offers(Array of Offer Objects)

Identification & Metadata

Field	Type	Description
offers[].id	Integer	Unique identifier for the offer. Always included in response.
offers[].campaign_id	Integer	Identifier for the advertising campaign. Always included in response.
offers[].advertiser_name	String	Name of the merchant or advertiser. Always included in response.
offers[].perkswallet_enabled	Boolean	Whether this offer can be saved to PerksWallet. Optional field.
offers[].offerwall_url	String	Direct link to this offer in an Perkswall. Optional field.

Text Content

Field	Type	Description
offers[].title	String	Recommended to implement for large formats. Desktop/wide headline for the offer (maximum 90 characters; ideally 40 characters). Used in full-width layouts and primary views. Example: "Get 25% off athletic wear + free shipping"
offers[].description	String	Recommended for large formats. Desktop/wide description providing offer details (maximum 220 characters; ideally 140 characters). Contains fuller explanation of the offer value. Example: "Save on top-brand athletic wear with this exclusive discount. Orders over $50 qualify for free shipping to anywhere in the continental US."
offers[].short_headline	String	Recommended to implement for mobile formats. Compact headline optimized for mobile devices and card layouts (maximum 60 characters; ideally 40 characters). Used when display space is limited. Example: "25% off athletic wear"
offers[].short_description	String	Recommended for mobile formats. Condensed description for mobile screens and space-constrained layouts (maximum 140 characters). Provides essential offer details in limited space. Example: "Save on top brands + free shipping over $50"
offers[].mini_text	String	A short disclaimer or fine-print text for the offer. Common uses include exclusions, legal requirements, or time-sensitive details. Displayed in smaller font beneath the main offer content (maximum 140 characters). Example: Excludes sale items. Valid through 12/31/2025. Use only when essential to clarify terms without cluttering the main offer description.

Call-to-Action Elements

Field	Type	Description
offers[].click_url	String	Required to implement. Destination URL opened when user accepts the offer. Contains tracking parameters for attribution and conversion tracking. Users are directed here after clicking the primary action button.
offers[].cta_yes	String	Recommended to implement. Text label for the primary action button (maximum 25 characters; ideally under 20). Examples: "Shop Now", "Get Offer", "Claim Deal". Sets user expectations for the action and significantly impacts conversion rates.
offers[].cta_no	String	Optional for implementation. Text label for the dismissal button (maximum 25 characters; ideally under 20). Examples: "No Thanks", "Not Now", "Skip". Provides users with a clear way to decline the offer while still triggering the appropriate tracking beacon.

Images & Creative Assets

Field	Type	Description
offers[].image	String	Primary image URL for the offer. Use for simplified implementations when you don't need multiple creative formats. For responsive designs with multiple aspect ratios, use the creatives array instead.
offers[].qr_code_img	String	A Base64-encoded PNG image of a QR Code that encodes the value of the campaign’s click_url. The string is returned in Data URI format, beginning with data:image/png;base64, ordata:image/jpeg;base64,. Use this image to provide a quick, scannable link to claim the Offer , especially in cross-device or offline scenarios. Format: PNG or JPEG Color Scheme: Black foreground on white background (no gradients or color inversions) Dimensions: 228x228 pixels

Creatives Array

The offers[].creatives array contains detailed information about available images:

Field	Type	Description
offers[].creatives[].id	Integer	Unique identifier for the creative asset
offers[].creatives[].url	String	URL to the image asset
offers[].creatives[].height	Number	Height in pixels
offers[].creatives[].width	Number	Width in pixels
offers[].creatives[].type	String	File format (jpg, png, etc.)
offers[].creatives[].is_primary	Boolean	Whether this is the primary image
offers[].creatives[].aspect_ratio	Number	The aspect ratio of the image, which defines the relationship between its width and height. 1 = Square image < 1 = Portrait orientation > 1 = Landscape orientation
offers[].creatives[].creative_type	String	The type of creative being used can be one of the following options icon_image : Representsthe offer's icon or brand logo, with only one icon image allowed (250 × 250 px, ±10% size variation). hero_image: Represents the offer in the Perkswall Featured Section, with only one hero image allowed (1000 × 280 px, ±10% size variation). This image can also be used to populate larger "interstitial" offer modals or similar bigger units if implemented. offer_image: Displays an image relevant to the offer, size based on design requirements.

Categorization

Field	Type	Description
offers[].tags	Array of strings	A list of category tags assigned to the offer. Each offer can belong to multiple categories. These tags help organize offers into logical groups, power filtering experiences, and enable more relevant recommendations. Offers can have multiple tags to reflect different verticals (e.g., "technology", "financial", "video-games-and-consoles"). If an offer does not include any tags, it should be treated as part of a default category such as "All" in the UI.

Terms & Conditions

Field	Type	Description
offers[].terms_and_conditions	String	Required to implement. HTML content containing legal terms and conditions for the offer. Must be rendered as raw HTML in your interface. Supports common HTML tags including <a>, <strong>, <p>, <ul>, <ol>, <li>, etc. Always display or make accessible to users before they claim offers to ensure legal compliance.

<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	String	Required to implement. The Impression Beacon URL for tracking when the offer is visibly displayed to the user. This URL must be requested exactly once per impression, only when the offer is actually visible in the viewport. How to use: Fire via an image request or fetchcall. A successful GET request to this URL is required for the impression to be recorded in the MomentScience Dashboard.
offers[].adv_pixel_url	String	Optional advertiser-specific impression tracking URL. When present, it must be fired at the same time as the primary offers[].pixel URL. This will allow advertisers to track impressions in their own analytics systems. How to use: Trigger via an image request or fetchcall simultaneously with the primary pixel. A successful GETrequest to this URL is required for the impression to be counted.

Beacons Object

The offers[].beacons object contains additional tracking endpoints:

Field	Type	Description
offers[].beacons.close	String	Optional URL to fire when the user dismisses the offer container, reaches the end of browsing session, or navigates away. For reporting purposes. A successful GET call to beacons.close is required if implemented.
offers[].beacons.no_thanks_click	String	Optional URL to fire specifically when the user clicks the negative CTA button (defined by cta_no). Provides valuable data on explicit offer rejections versus passive dismissals. For reporting purposes. A successful GET call to beacons.no_thanks_clicks is required if implemented.

PerksWallet & Loyalty Features

Field	Type	Description
offers[].save_for_later_url	String	Required to implement when integrating with PerksWallet. 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[].is_loyaltyboost	Boolean	Optional flag indicating whether the offer is eligible for additional loyalty program benefits or point incentives. When true, the offer can provide bonus loyalty points or rewards when claimed.
loyaltyboost_requirements	String	Optional text explaining what the user needs to do to earn the loyalty rewards (approximately 160 characters maximum). Only present when is_loyaltyboost is true. Should be prominently displayed alongside the offer to communicate the additional value proposition.

settings Object

The settings object provides display preferences and configuration options for the presentation of offers. It controls which offers should be featured, how they should be organized, and what UI elements should be displayed. the only essential attribute to focus on is:

Field	Type	Description
settings.featured_offer_list	array of integers	IDs of offers that should be given priority placement or special visual treatment in your UI.

📢 If you're running into any issues while going through the integration process, feel free to contact us at [email protected]