--- title: Perkswall API slug: perkswall-api icon: {"apiMethod":"POST"} docTags: createdAt: 2025-07-26T11:24:13.942Z --- :::hint{type="info"} **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 ![](https://api.archbee.com/api/optimize/ELjiwjWcrv0a1IejQFFAF/HjkGBHY3PpIik2p8qva-V_image.png "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. ![](https://api.archbee.com/api/optimize/ELjiwjWcrv0a1IejQFFAF/bsfujvKY2ftsBr4PWgwHx_image.png "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. :::Iframe{iframeHeight="0" code=""} ::: ## 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** 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 and Managing Your API Key](docId\:T1D2Y6EmUG0LH0T_Bi6Ao). ::: # 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` | | `` | 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"` | :::hint{type="success"} **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 ```javascript 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 ```javascript { "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": "

Offer valid for online purchases only. 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.

", "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 ](https://en.wikipedia.org/wiki/Base64)PNG image of a QR Code that encodes the value of the campaign’s `click_url`. The string is returned in [Data URI](https://developer.mozilla.org/en-US/docs/Web/URI/Reference/Schemes/data) format, beginning with `data:image/png;base64,` or`data: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 ``, ``, `

`, `