APIs Documentation

Moments API

16min

The Moments API allows publishers to easily integrate Offers within their app or website using any language that supports the ability to make RESTful calls. 
Quickstart
The typical flow to generate and serve Offers is as follows:
﻿Obtain your API Key﻿﻿
Make a Fetch Offers API call to MomentScience to retrieve Offers 
Parse the response and display Offers in the desired fashion
Ensure that beacon URLs fire on sequence and Offer impression loads.
﻿
<iframe style="border:none" width="800" height="450" src="https://whimsical.com/embed/DDn5gm6ic6xqWZotWET6fo"></iframe>
<iframe style="border:none" width="800" height="450" src="https://whimsical.com/embed/DDn5gm6ic6xqWZotWET6fo"></iframe>
﻿
Fetch Offers
Method: POST
Base URL: https://api.adspostx.com/native/v2/offers.json
Header Parameters
Parameter
Description
Type
Example
Content-Type
required﻿
Should be application/json
string
application/json
Query Parameters
Parameter
Description
Type
Example
api_key
required﻿
Your API Key. 
Obtain your API Key﻿
Required Permission: Ads/Offers
string
4bbdefc2-b130-424d-8170-54bdcb98e64e
loyaltyboost
optional
Include LoyaltyBoost offers in response; 
Values: 
0 = None
1 = True
2 = Only
string 
0|1|2
creative
optional
Returns Offers with at least one creative (image) if set to true. 
string
0|1
Body Parameters
Parameter
Description
Type
Example
ua
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. 
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﻿
IP address of the end user to be passed through. Used for targeting. 
string
﻿
adpx_fp
recommended﻿
A unique identifier for the end user; Not required but highly recommended.  More information can be found below.
string
﻿
dev
optional
Returns a test response. Ignores geo restrictions. No activity is recorded. 
string
0|1
<string>
optional
Custom Key-Value payload attributes. You can add any number of custom key-value payload attributes to the payload that you want to use to add additional details. 

All payload attributes are passed back on conversion reports and can be reported on in relation to impression and clicks. 
string
membershipID: "A45GRE987343PKD"
The adpx_fp attribute in the body of the Fetch Offers call is a special parameter that aids in overall Offer performance.  It should be populated with a unique end-user identifier as an alpha-numeric string.

MomentScience uses the adpx_fp value to frequency cap Offers on a unique user basis as well as exclude Offers from showing again when a user opts-out for a certain Offer. 
Note that the number of Offers is controlled by the Configuration Settings in your publisher dashboard.  Log into your dashboard, click on Settings -> Configuration from the side menu and then select the number of Offers you would like to have returned.
The Response Body
Upon a successful response from the Fetch Offers API request, the body of the reponse will include a data object that contains an array of objects that can be used to construct your Offers. 
Sample Response
Response Example
{
    "data": {
        "offers": [
            {
                "id": 4359,
                "campaign_id": 2282,
                "title": "You Unlocked MomentScience For 90 Days - Free!",
                "description": "MomentScience lets you capture revenue across your user's moments. Delight your users with relevant Offers at the right time. Get 3 months free!",
                "click_url": "https://trk.pubtailer.com/sdk/offer-click?o_id=4359&c_id=1649&p_id=1854&sess_id=51267da82f8e1a6c2900c5c051c1648a63f8410e",
                "image": "https://adpx.b-cdn.net/campaigns/1649/62a98d93af4e12a3dbbcf247172fadce.png",
                "mini_text": "Enjoy MomentScience Free Trail",
                "pixel": "https://trk.pubtailer.com/sdk/v2/impression/p.png?o_id=4359&c_id=1649&p_id=1854&sess_id=51267da82f8e1a6c2900c5c051c1648a63f8410e&cbuster=%7BCBUSTER%7D",
                "cta_yes": "Try out MomentScience!",
                "cta_no": "No, Thanks",
                "useraction_cta": "",
                "useraction_url": "",
                "adv_pixel_url": "",
                "beacons": {
                    "close": "https://trk.pubtailer.com/event/record/close?oid=4359&cid=1649&pid=1854&sess_id=51267da82f8e1a6c2900c5c051c1648a63f8410e",
                    "no_thanks_click": "https://trk.pubtailer.com/event/record/no_thanks_click?oid=4359&cid=1649&pid=1854&sess_id=51267da82f8e1a6c2900c5c051c1648a63f8410e"
                },
                "creatives": [
                    {
                        "id": 1436,
                        "url": "https://adpx.b-cdn.net/campaigns/1649/62a98d93af4e12a3dbbcf247172fadce.png",
                        "height": 1530,
                        "width": 1530,
                        "type": "png",
                        "is_primary": true,
                        "aspect_ratio": 1
                    }
                ],
                "offerwall_enabled": true,
                "perkswallet_enabled": false,
                "short_description": "Capture revenue across your user's moments. Get 3 months free!",
                "short_headline": "3 Free Months of MomentScience!",
                "advertiser_name": "MomentScience",
                "is_loyaltyboost": false,
                "loyaltyboost_requirements": "",
                "loyaltyboost_requirements": "",
                "offerwall_url": "https://get.perkswall.com/offerwall?accountId=fbe15a0c6f803ef4&offer_count=3&auto_show=1&show_logo=1&show_header=1&show_shadow=0&show_image=1&font_family=Open+Sans&session_id=95868dc0306887060b991e555c8f5057a6b619b0&c_id=2282"
            },
            {
                "id": 4586,
                "campaign_id": 2396,
                "title": "You Unlocked MomentScience For 90 Days - Free!",
                "description": "MomentScience lets you capture revenue across your user's moments. Delight your users with relevant Offers at the right time. Get 3 months free!",
                "click_url": "https://trk.pubtailer.com/sdk/offer-click?o_id=4586&c_id=1879&p_id=1854&sess_id=51267da82f8e1a6c2900c5c051c1648a63f8410e",
                "image": "https://adpx.b-cdn.net/campaigns/1879/d93fbd2662b784b655d430c9ce3789e4.png",
                "mini_text": "",
                "pixel": "https://trk.pubtailer.com/sdk/v2/impression/p.png?o_id=4586&c_id=1879&p_id=1854&sess_id=51267da82f8e1a6c2900c5c051c1648a63f8410e&cbuster=%7BCBUSTER%7D",
                "cta_yes": "Earn 150 Points",
                "cta_no": "No, Thanks",
                "useraction_cta": "",
                "useraction_url": "",
                "adv_pixel_url": "",
                "beacons": {
                    "close": "https://trk.pubtailer.com/event/record/close?oid=4586&cid=1879&pid=1854&sess_id=51267da82f8e1a6c2900c5c051c1648a63f8410e",
                    "no_thanks_click": "https://trk.pubtailer.com/event/record/no_thanks_click?oid=4586&cid=1879&pid=1854&sess_id=51267da82f8e1a6c2900c5c051c1648a63f8410e"
                },
                "creatives": [
                    {
                        "id": 1769,
                        "url": "https://adpx.b-cdn.net/campaigns/1879/d93fbd2662b784b655d430c9ce3789e4.png",
                        "height": 1530,
                        "width": 1530,
                        "type": "png",
                        "is_primary": true,
                        "aspect_ratio": 1
                    }
                ],
                "offerwall_enabled": true,
                "perkswallet_enabled": false,
                "short_description": "Capture revenue across your user's moments. Get 3 months free!",
                "short_headline": "3 Free Months of MomentScience!",
                "advertiser_name": "MomentScience",
                "is_loyaltyboost": true,
                "loyaltyboost_requirements": "User must finish integrating MomentScience to qualify. You must click “Allow” if tracking permission is requested within the app.""offerwall_url": "https://get.perkswall.com/offerwall?accountId=fbe15a0c6f803ef4&offer_count=3&auto_show=1&show_logo=1&show_header=1&show_shadow=0&show_image=1&font_family=Open+Sans&session_id=95868dc0306887060b991e555c8f5057a6b619b0&c_id=2396"
            }
        ],
        "count": 3,
        "privacy_url": "https://www.momentscience.com/privacy-policy"
    }
}
{
    "data": {
        "offers": [
            {
                "id": 4359,
                "campaign_id": 2282,
                "title": "You Unlocked MomentScience For 90 Days - Free!",
                "description": "MomentScience lets you capture revenue across your user's moments. Delight your users with relevant Offers at the right time. Get 3 months free!",
                "click_url": "https://trk.pubtailer.com/sdk/offer-click?o_id=4359&c_id=1649&p_id=1854&sess_id=51267da82f8e1a6c2900c5c051c1648a63f8410e",
                "image": "https://adpx.b-cdn.net/campaigns/1649/62a98d93af4e12a3dbbcf247172fadce.png",
                "mini_text": "Enjoy MomentScience Free Trail",
                "pixel": "https://trk.pubtailer.com/sdk/v2/impression/p.png?o_id=4359&c_id=1649&p_id=1854&sess_id=51267da82f8e1a6c2900c5c051c1648a63f8410e&cbuster=%7BCBUSTER%7D",
                "cta_yes": "Try out MomentScience!",
                "cta_no": "No, Thanks",
                "useraction_cta": "",
                "useraction_url": "",
                "adv_pixel_url": "",
                "beacons": {
                    "close": "https://trk.pubtailer.com/event/record/close?oid=4359&cid=1649&pid=1854&sess_id=51267da82f8e1a6c2900c5c051c1648a63f8410e",
                    "no_thanks_click": "https://trk.pubtailer.com/event/record/no_thanks_click?oid=4359&cid=1649&pid=1854&sess_id=51267da82f8e1a6c2900c5c051c1648a63f8410e"
                },
                "creatives": [
                    {
                        "id": 1436,
                        "url": "https://adpx.b-cdn.net/campaigns/1649/62a98d93af4e12a3dbbcf247172fadce.png",
                        "height": 1530,
                        "width": 1530,
                        "type": "png",
                        "is_primary": true,
                        "aspect_ratio": 1
                    }
                ],
                "offerwall_enabled": true,
                "perkswallet_enabled": false,
                "short_description": "Capture revenue across your user's moments. Get 3 months free!",
                "short_headline": "3 Free Months of MomentScience!",
                "advertiser_name": "MomentScience",
                "is_loyaltyboost": false,
                "loyaltyboost_requirements": "",
                "loyaltyboost_requirements": "",
                "offerwall_url": "https://get.perkswall.com/offerwall?accountId=fbe15a0c6f803ef4&offer_count=3&auto_show=1&show_logo=1&show_header=1&show_shadow=0&show_image=1&font_family=Open+Sans&session_id=95868dc0306887060b991e555c8f5057a6b619b0&c_id=2282"
            },
            {
                "id": 4586,
                "campaign_id": 2396,
                "title": "You Unlocked MomentScience For 90 Days - Free!",
                "description": "MomentScience lets you capture revenue across your user's moments. Delight your users with relevant Offers at the right time. Get 3 months free!",
                "click_url": "https://trk.pubtailer.com/sdk/offer-click?o_id=4586&c_id=1879&p_id=1854&sess_id=51267da82f8e1a6c2900c5c051c1648a63f8410e",
                "image": "https://adpx.b-cdn.net/campaigns/1879/d93fbd2662b784b655d430c9ce3789e4.png",
                "mini_text": "",
                "pixel": "https://trk.pubtailer.com/sdk/v2/impression/p.png?o_id=4586&c_id=1879&p_id=1854&sess_id=51267da82f8e1a6c2900c5c051c1648a63f8410e&cbuster=%7BCBUSTER%7D",
                "cta_yes": "Earn 150 Points",
                "cta_no": "No, Thanks",
                "useraction_cta": "",
                "useraction_url": "",
                "adv_pixel_url": "",
                "beacons": {
                    "close": "https://trk.pubtailer.com/event/record/close?oid=4586&cid=1879&pid=1854&sess_id=51267da82f8e1a6c2900c5c051c1648a63f8410e",
                    "no_thanks_click": "https://trk.pubtailer.com/event/record/no_thanks_click?oid=4586&cid=1879&pid=1854&sess_id=51267da82f8e1a6c2900c5c051c1648a63f8410e"
                },
                "creatives": [
                    {
                        "id": 1769,
                        "url": "https://adpx.b-cdn.net/campaigns/1879/d93fbd2662b784b655d430c9ce3789e4.png",
                        "height": 1530,
                        "width": 1530,
                        "type": "png",
                        "is_primary": true,
                        "aspect_ratio": 1
                    }
                ],
                "offerwall_enabled": true,
                "perkswallet_enabled": false,
                "short_description": "Capture revenue across your user's moments. Get 3 months free!",
                "short_headline": "3 Free Months of MomentScience!",
                "advertiser_name": "MomentScience",
                "is_loyaltyboost": true,
                "loyaltyboost_requirements": "User must finish integrating MomentScience to qualify. You must click “Allow” if tracking permission is requested within the app.""offerwall_url": "https://get.perkswall.com/offerwall?accountId=fbe15a0c6f803ef4&offer_count=3&auto_show=1&show_logo=1&show_header=1&show_shadow=0&show_image=1&font_family=Open+Sans&session_id=95868dc0306887060b991e555c8f5057a6b619b0&c_id=2396"
            }
        ],
        "count": 3,
        "privacy_url": "https://www.momentscience.com/privacy-policy"
    }
}
﻿
Response Parameters
Upon making an API call, the following attributes are returned in the response to construct your Offers with.
﻿
offers array of offer objects
Contains the copy, creatives, and resources to construct each Offer. Each offer object has the following attributes:
offers[].id int
The unique ID that represents the Offer.
﻿
offers[].campaign_id int
The unique ID of the campaign that this Offer belongs to.
﻿
offers[].title string
recommended to implemen﻿t for larger formats﻿
The title of the Offer. To be used to construct the headline of the Offer. 
Maximum length: 90 characters.
﻿
offers[].advertiser_name string
The name of the advertiser offering the Offer.
﻿
offers[].description string
recommended to implemen﻿t for larger formats﻿
The description of the Offer.
Maximum length: 220 characters.
﻿
offers[].click_url URL
required to implement﻿
URL the Offer should direct to when the user clicks on the positive CTA button.
﻿
offers[].image URL
recommended to implement﻿
URL for the Offer's primary image.
﻿
offers[].mini_text string 
recommended to implement﻿
Additional sub-description for the Offer. Used for disclaimers. 
Maximum length: 160 characters.
﻿
offers[].pixel URL
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 implementing a postitive CTA button for the User to accept the Offer. 
Maximum length: 25 characters.
﻿
offers[].cta_no string 
recommended to implement﻿
Suggested copy for implementing a negative CTA button for the User to reject an Offer. 
Maximum length: 25 characters.
﻿
offers[].adv_pixel_url URL 
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
Contains beacon URLs for a variety of actions. The beacons object contains the following attributes:
Attribute
Type
Description
offers[].beacons.close 
URL
To be fired when closer closes the Offer container or when the user has browsed through all available Offers. For reporting purposes. A successful GET call to beacons.close is required if implemented. 

recommended to implement if Offers are presented in a dismissable container﻿
offers[].beacons.no_thanks_click
URL
To  be fired when user clicks the Negative CTA element. For reporting purposes. A successful GET call to beacons.no_thanks_clicks is required if implemented. 

recommended to implement if a negative CTA is 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
Int
Unique ID of the creative.
offers[].creatives[].url
URL 
URL location for the creative.
offers[].creatives[].height
double
Height of the image in pixels.
offers[].creatives[].width
double
Width of the image in pixels.
offers[].creatives[].type
string
File type of the image. 
offers[].creatives[].is_primary
boolean
Indicates whether the image is primary or not.
offers[].creatives[].aspect_ratio

number
The aspect ratio of the image.
a value of 1 = square image
a value < 1 signifies generally portrait
a value > 1 signifies generally landscape
﻿
offers[].offerwall_enabled boolean
Boolean value to indicate whether the Offer has an Offerwall feature enabled or not.
﻿
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[].offerwall_url URL
The url that the user will be redirected to when clicking on the "More Offers" button that takes him to the Offerwall page.
﻿
offers[].short_description string 
recommended to implemen﻿t 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 implemen﻿t 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.
﻿
count integer
Number of Offers returned from the call. 
﻿
privacy_url URL
recommended to implement﻿
URL to MomentScience's current end-user privacy policy page. 
﻿
Parsing the Response and Displaying Offers
Upon a successful response from the Fetch Offer's API request, generate Offers using the Offer fragments provided for each returned Offer.
Remember to implement impression tracking using the pixel attribute for each displayed Offer. A successful GET call to the Pixel URL is required to successfully record delivery on the MomentScience Dashboard.
This allows MomentScience to: 
Accurately calculate and present performance statistics such as click-through rate (CTR), eCPM and other metrics.
Use performance data to optimize Offer delivery on future traffic.
Generate and display first Offer using the fragments of the Offer returned in the response.
Implement the Impression Beacon URL (pixel) for the first Offer
If user engages with the negative call-to-action, implement the Negative CTA Beacon URL (no_thanks_click) 
Render the second Offer (and implement the Impression Beacon URL for this Offer)
Continue through the sequence based on user engagement
Using Creatives
When retrieving Offer, we provide a creatives attribute with each returned Offer, which lists creatives available for use in your Offers. 
Included with each creative is an is_primary boolean attribute. You can use any of the creatives available depending on the platform you are rendering or default to the primary creative if you are unsure.
The Moments API also supports on-the-fly image transformations: by simply adding the query parameter "width=XXX" into the image url (replace XXX with a suitable integer value for width, depending on the device resolution). The query parameters "height=XXX" or "?aspect_ratio=X:Y" are also available as on-the-fly image processing directives on images.
We also provide an aspect_ratio attribute for each creative which can be helpful in selecting an image for the Offer.  
An aspect_ratio with:
a value of 1 = square image
a value < 1 signifies generally portrait
a value > 1 signifies generally landscape
Implementing Event Beacons
In addition to tracking impressions, the Offers response also provides a beacons object, containing the tracking URLs for events no_thanks_click (to be fired when user clicks the Negative CTA element) and close (to be fired when user closes the Offer container or when the user has browsed through all the available Offers).
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 running into any issues while going through the integration process, feel free to contact us at [email protected] 

Parameter	Description	Type	Example
Content-Type required	Should be application/json	string	application/json

Parameter	Description	Type	Example
api_key required	Your API Key. Obtain your API Key Required Permission: Ads/Offers	string	4bbdefc2-b130-424d-8170-54bdcb98e64e
loyaltyboost optional	Include LoyaltyBoost offers in response; Values: 0 = None 1 = True 2 = Only	string	0\|1\|2
creative optional	Returns Offers with at least one creative (image) if set to true.	string	0\|1

Parameter	Description	Type	Example
ua 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.	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	IP address of the end user to be passed through. Used for targeting.	string
adpx_fp recommended	A unique identifier for the end user; Not required but highly recommended. More information can be found below.	string
dev optional	Returns a test response. Ignores geo restrictions. No activity is recorded.	string	0\|1
<string> optional	Custom Key-Value payload attributes. You can add any number of custom key-value payload attributes to the payload that you want to use to add additional details. All payload attributes are passed back on conversion reports and can be reported on in relation to impression and clicks.	string	membershipID: "A45GRE987343PKD"

Attribute	Type	Description
offers[].beacons.close	URL	To be fired when closer closes the Offer container or when the user has browsed through all available Offers. For reporting purposes. A successful GET call to beacons.close is required if implemented. recommended to implement if Offers are presented in a dismissable container
offers[].beacons.no_thanks_click	URL	To be fired when user clicks the Negative CTA element. For reporting purposes. A successful GET call to beacons.no_thanks_clicks is required if implemented. recommended to implement if a negative CTA is implemented

Attribute	Type	Description
offers[].creatives[].id	Int	Unique ID of the creative.
offers[].creatives[].url	URL	URL location for the creative.
offers[].creatives[].height	double	Height of the image in pixels.
offers[].creatives[].width	double	Width of the image in pixels.
offers[].creatives[].type	string	File type of the image.
offers[].creatives[].is_primary	boolean	Indicates whether the image is primary or not.
offers[].creatives[].aspect_ratio	number	The aspect ratio of the image. a value of 1 = square image a value < 1 signifies generally portrait a value > 1 signifies generally landscape

Updated 12 Nov 2024

Did this page help you?

APIs Documentation

Perkswall API

Moments API

Quickstart

Fetch Offers

Header Parameters

Query Parameters

Body Parameters

The Response Body

Sample Response

Response Parameters

offer Attributes

Parsing the Response and Displaying Offers

Using Creatives

Implementing Event Beacons

Integration Checklist