APIs Documentation

Perkswall API

16min

Overview

The MomentScience Perkswall API facilitates the integration of a curated "perks gallery" into your application or website through RESTful calls. This API is designed to provide you with access to Perkswall-enabled offers, enabling a highly customizable and branded Perkswall experience.

By utilizing the Perkswall API, you can fetch all available offers configured for your account. These offers can then be used to construct a dynamic and engaging Perkswall that aligns with your brand’s identity and enhances user interaction.

Pre-requisites 

  1. To use the Perkswall API, you must first have the Perkswall feature activated for your account. Contact your account manager to request activation.
  2. Once the Perkswall feature is enabled, obtain your API key from your MomentScience dashboard. The API key is required to authenticate all requests made to the Perkswall API. Learn more about how to obtain your API key.

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.



Fetch Perkswall Offers

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

Header Parameters

Parameter

Type

Description

Content-Type Required

String

Specifies the media type of the request. Must be set to application/json

Query Parameters

Parameter

Description

Type

Example

api_key Required

Your API Key. Learn how to obtain your key from the dashboard.

  • Required Permission: Ads/Offers

String

4bbdefc2-b130-424d-8170-54bdcb98e64e

loyaltyboost Optional

Include LoyaltyBoost offers in the response.

  • 0= Do not include LoyaltyBoost Offers.
  • 1= Include LoyaltyBoost Offers.
  • 2= Return only LoyaltyBoost Offers.

String

0/ 1/ 2

creative Optional

Returns offers with at least one creative (image) if set to 1.

  • 0: False
  • 1: True

String

0/ 1

Body Parameters

Parameter

Description

Type

Example

ua Recommended

The User-Agent string of the end-user, required for proper targeting. If proxying requests via a server, ensure the User-Agent of the end-user is passed through.

String

Mozilla/5.0 (Linux; Android 10; K) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.6099.43 Mobile Safari/537.36

ip Recommended

The IP address of the end user for targeting purposes.

String



adpx_fp Recommended

A unique identifier for the end user. This is not required, but highly recommended for accurate tracking. More information is provided below.

String

1234abcd-5678-efgh-9101-ijklmnopqrst

dev Optional

Enables a test response. When set to 1, the sandbox environment is activated, allowing for testing without recording any activity in production. In this mode, geo-restrictions are ignored, and all Offers are returned in the response, providing a comprehensive testing experience.

  • Set to 1 to enable test mode.

String

0|1

subid Optional

An ID used to identify specific usages of the Fetch Perkswall Offers API.

String

mobile_android_app_post_transaction

<string> Optional

Custom key-value payload attributes. You can add any number of custom attributes for additional details. These attributes are included in conversion reports and can be tracked in relation to impressions and clicks.

String

membershipID: "A45GRE987343PKD"

The adpx_fp attribute is a special parameter used in the body of the Fetch Perkswall Offers calls to enhance Offer performance. It should be populated with a unique alphanumeric string that identifies the end-user.

MomentScience leverages the adpx_fp value for frequency capping—ensuring that Offers are displayed to users within predefined limits. Additionally, it prevents Offers from being shown again once a user has opted out of a specific Offer, ensuring a more personalized and seamless experience.

Response Information

Upon a successful response from the Fetch Perkswall Offers API, the body will include a dataobject containing an array of Offer objects. These objects provide all the necessary details to construct the Offers for your Perkswall. Below are the relevant attributes within the Offer objects.

Response Example

Response Parameters

offers(Array of Offer Objects)

An array of objects containing the details for each available Offer. Each Offer object contains the following attributes:



offers[].id Integer 

The unique identifier for the Offer.



offers[].title String Recommended to implement for larger formats

The title of the Offer is typically used to construct the headline.

  • Maximum Length: 90 characters


offers[].advertiser_name String

The name of the advertiser offering the Offer.



offers[].description string Recommended to implement for larger formats

A brief description of the Offer

  • Maximum length: 220 characters.


offers[].click_url String Required to implement

The URL the Offer directs to when clicked.



offers[].image String Recommended to implement

The URL of the primary image for the Offer.



offers[].mini_text String Recommended to implement

A shorter description for the Offer, useful for disclaimers

  • Maximum length: 160 characters.


offers[].pixel String Required to implement

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[].cta_yes string Recommended to implement

Suggested copy for the positive CTA button to accept the Offer.

  • Maximum length: 25 characters.


offers[].cta_no string

Suggested copy for the negative CTA button to reject the Offer.

  • Maximum length: 25 characters.


offers[].adv_pixel_url String Required to implement if available

Advertiser may provide their own impression tracking URL, fire this along with the pixel Impression Beacon URL. A successful GET call to adv_pixel_url is required.



offers[].beacons object

It contains URLs for various actions related to the Offer. A successful GET request to these URLs is required to record certain activities.

Attribute

Type

Description

offers[].beacons.close Recommended to implement if Perkswall Offers are presented in a dismissable container.

String

URL fired when the Offer container is closed or when the user has browsed through all Offers,

  • For reporting purposes. A successful GET call to beacons.close is required if implemented.

offers[].beacons.no_thanks_click

Recommended to implement if a negative CTA is implemented for each Offer on the Perkswall. 

String

URL fired when the negative CTA is clicked (e.g., rejecting the Offer).

  • For reporting purposes. A successful GET call to beacons.no_thanks_clicks is required if implemented.


offers[].creatives array of creative objects

Contains additional creative images that can be used to construct the Offers unit. Each creative object contains the following attributes:

Attribute

Type

Description

offers[].creatives[].id

Integer

Unique identifier for each creative.

offers[].creatives[].url

String

URL of the creative image.

offers[].creatives[].height

Double

Height of the creative image in pixels.

offers[].creatives[].width

Double

Width of the creative image in pixels.

offers[].creatives[].type

String

The file type of the creative image (e.g., JPEG, PNG).

offers[].creatives[].is_primary

Boolean

Indicates if the creative is the primary image for the Offer.

offers[].creatives[].aspect_ratio

Integer

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
  • hero_image
  • offer_image


offers[].advertiser_name String

The name of the advertiser providing the Offer.



offers[].short_description String Recommended to implement for smaller formats

Alternative shorter text to use for the Offer's description if the context of the Offer is in a smaller format, like on mobile, or if you're implementing the Offer in a smaller element.

  • Maximum length: 140 characters.


offers[].short_headline String Recommended to implement for smaller formats

Alternative shorter text to use for the Offer's headline if the context of the Offer is in a smaller format like on mobile or if you're implementing the Offer in a smaller element.

  • Maximum length: 60 characters.


offers[].is_loyaltyboost Boolean

Indicates if an Offer is eligible to be used in an incentive manner.



offers[].loyaltyboost_requirements String

Specifies the requirements for a LoyaltyBoost Offer. It outlines the actions for which rewards will be granted to users. These requirements define the criteria that the user must meet to qualify for rewards associated with the LoyaltyBoost Offer.

  • Maximum length: 160 characters.


settings Object

The settings object allows for customization of the Perkswall’s appearance and behavior. However, for integration purposes, the only essential attribute to focus on is:

settings.featured_offer_list Array

A list of Offer IDs (from offers[].id) that are designated as featured. The offers[].id values are used here to specify which Offers should be marked as featured within the Perkswall display.



count Integer

Number of Offers returned from the call.



Parsing the Response and Displaying Offers

When you receive a successful response from the Fetch Perkswall Offers API, follow these steps to construct and display offers using the provided data.

For more information about how to make the most of the API response, please refer to the Perkswall Anatomy documentation.

Response Handling and Offer Construction

  1. Extract Offer Data Parse the response to retrieve the offers array, which contains the necessary attributes for constructing each offer.
  2. Generate Offers Use the following attributes from each offer object to display the offer:
    • title: Offer headline (recommended for larger formats). If a shorter version is available, use short_headlinefor smaller formats.
    • advertiser_name: Name of the advertiser.
    • description: Detailed offer description (max length: 220 characters). If a shorter version is available, use short_descriptionfor smaller formats.
    • click_url: Destination URL when the user interacts with the offer.
    • image: Primary image for visual representation.
    • pixel: Impression beacon URL for tracking.
  3. Implement Impression Tracking For each displayed offer:
    • Make a GET request to the pixelURL.
    • This ensures the MomentScience Dashboard logs the impression and tracks performance metrics such as:
      • Click-Through Rate (CTR)
      • Effective Cost Per Thousand Impressions (eCPM)
  4. Display Offers Sequentially
    • Render the first offer and trigger its pixel URL.
    • Proceed to display subsequent offers in sequence, ensuring each impression is tracked.

Using Creatives

Each offer includes a creativesattribute that contains an array of images. Leverage this data as follows:

  1. Primary Creative Identify the primary creative using the is_primaryboolean attribute. Use this by default if no other creative is specified.
  2. Creatives Types: we support multiple creatives types,
    1. offer_image: Displays an image relevant to the offer, size based on design requirements.
    2. 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.
    3. icon_image: Represents the offer's icon or brand logo, with only one icon image allowed (250 × 250 px, ±10% size variation).
  3. Creative Selection Choose creatives that best suit your platform (e.g., desktop, mobile). Consider aspect ratios:
    • 1: Square
    • < 1: Portrait
    • > 1: Landscape
  4. Image Transformations Optimize images for different devices using query parameters:
    • width=XXX: Adjust the width.
    • height=XXX: Adjust the height.
    • aspect_ratio=X:Y: Specify the aspect ratio.

Integration Checklist

To ensure a smooth integration:

  1. Confirm implementation of all required attributes (title, click_url, pixel, etc.).
  2. Verify that all beacon URLs (pixel, close, no_thanks_click, etc.) are functional.
  3. Test creative transformations and rendering on various devices.

For a complete list of integration steps, refer to the Perkswall API Integration Checklist.



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

Updated 13 Jan 2025
Did this page help you?
PREVIOUS
Offer Anatomy
NEXT
Offer Catalog API
Docs powered by Archbee