Website logo
Dashboard
⌘K
🚀Integration Guide Overview
JS SDK (for Websites)
Presentation Options
Google Tag Manager (GTM)
Google Ad Manager (GAM)
Mobile SDK
iOS SDK
Android SDK
React Native SDK
Flutter SDK
Using macros
Passing payload values
Shopify
API
Native Ads API
Reporting API
Settings API
Errors
Postbacks
LoyaltyBoost (Rewarded Campaigns)
Perkswall
Frequently Asked Questions
Adding AdsPostX to your page
Offerwall
Docs powered by Archbee
API

Native Ads API

he AdsPostX Native Ads API is a powerful platform that 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:

  1. Obtain your API Key
  2. Make a Fetch Ads API call to AdsPostX to retrieve Offers (see below for information)
  3. Parse the response and display Offers in the desired fashion
  4. Ensure that beacon URLs fire on sequence and Offer impression loads.

Once you generate an API Key in Step 1 above, try the Native Ads API by visiting our Native Ads API Tester.



<iframe style="border:none" width="800" height="450" src="https://whimsical.com/embed/DDn5gm6ic6xqWZotWET6fo"></iframe>


Fetch Offers

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.

Returns Offers from AdsPostX
POST
Params
Query Parameters
creative
optional
Boolean
Returns campaigns with at least one creative (image) if set to true. Otherwise, returns campaigns with or without images.
include_products
optional
String
Include product Offers in response; Values: true, false, only Passing only instructs AdsPostX to only retrieve Product Offers.
included_rewarded
optional
String
Include rewarded campaigns in response; Values: true, false, only Passing only instructs AdsPostX to only retrieve rewarded campaigns.
accountID
optional
String
You can optionally pass in your account's SDK ID (or account ID) instead of using an API Key for Authorization.
Header Parameters
Content_Type
required
String
application/json
Authorization
optional
String
Bearer your_api_key Required Permission: Ads Delivery
User-Agent
required
String
The user-agent of the end-user; if proxying requests via a server call, be sure to pass through the User-Agent of the end-user
Body Parameters
email
optional
String
firstname
optional
String
lastname
optional
String
confirmationref
optional
String
zipcode
optional
String
subid
optional
String
Pass a unique identifier for the sequence of Offers returned.
paymenttype
optional
String
ccbin
optional
String
country
optional
String
language
optional
String
dev
optional
Boolean
Return a test response. No activity is recorded to the ADPX Dashboard.
adpx_fp
optional
String
A unique identifier for the end user; Not required but highly recommended. More information can be found below


The adpx_fp attribute in the body of the Fetch Offers and Fetch Perkswall Offers calls 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. AdsPostX 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.

Fetch Perkswall Offers

Perkswall Offers returns all Perkswall enabled Offers available to the publisher. These Offers can be used by the publisher to construct their Perkswall in a branded experience. In order to use this endpoint, contact your account manager to enable Perkswall features.

Returns Perkswall Offers from AdsPostX
POST
Params
Query Parameters
creative
optional
Boolean
Returns campaigns with at least one creative (image) if set to true. Otherwise, returns campaigns with or without images.
include_products
optional
String
Include product Offers in response; Values: true, false, only Passing only instructs AdsPostX to only retrieve Product Offers.
included_rewarded
optional
String
Include rewarded campaigns in response; Values: true, false, only Passing only instructs AdsPostX to only retrieve rewarded campaigns.
accountID
optional
String
You can optionally pass in your account's SDK ID (or account ID) instead of using an API Key for Authorization.
Header Parameters
Content_Type
required
String
application/json
Authorization
optional
String
Bearer your_api_key Required Permission: Ads Delivery
User-Agent
required
String
The user-agent of the end-user; if proxying requests via a server call, be sure to pass through the User-Agent of the end-user
Body Parameters
email
optional
String
firstname
optional
String
lastname
optional
String
confirmationref
optional
String
zipcode
optional
String
subid
optional
String
Pass a unique identifier for the sequence of Offers returned.
paymenttype
optional
String
ccbin
optional
String
country
optional
String
language
optional
String
dev
optional
Boolean
Return a test response. No activity is recorded to the ADPX Dashboard.
adpx_fp
optional
String
A unique identifier for the end user; Not required but highly recommended. More information can be found below


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. The following attributes are the relevant attributes to construct your Offers with.

Attributes



offers array of objects

Contains the copy, creatives, and resources to construct each Offer.

offers child attributes



offers[].title string

The title of the ad. To be used to construct the headline of the Offer. Expect maximum characters of 60.



offers[].advertiser_name string

The name of the advertiser offering the Offer.



offers[].description string

The description of the Offer. Expect maximum characters of 120.



offers[].click_url URL

URL the Offer should direct to.



offers[].image URL

URL for the Offer's main image.



offers[].mini_text string

Additional sub description for the Offer. Usually used for disclaimers.



offers[].pixel URL

The Impression Beacon URL to be fired when the Offer is displayed to the user for impression tracking.



offers[].cta_yes string

Suggested copy for implementing a postitive CTA button for the User to accept the Offer.



offers.cta_no string

Suggested copy for implementing a negative CTA button for the User to reject an Offer.



offers[].adv_pixel_url URL

Advertiser may provide their own impression tracking URL, fire this along with the pixel Impression Beacon URL.



offers[].beacons object

Contains tracking URLs for a variety of actions.

beacons object



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.

offers[].beacons.no_thanks_click URL

To be fired when user clicks the Negative CTA element. For reporting purposes.



offers[].creatives array of objects

Contains additional creatives that can be used to construct the Offers unit.

creatives object



offers[].creatives[].url URL

URL location for the creative.

offers[].creatives[].height integer

The height of the creative in pixels.

offers[].creatives[].width integer

The width of the creative in pixels.

offers[].creatives[].type string

The format type of the creative.

offers[].creatives[].is_primary boolean

Boolean to indicate if the creative is the primary creative to be used.

offers[].creatives[].aspect_ratio float

  • a value of 1 = square image
  • a value < 1 signifies generally portrait
  • a value > 1 signifies generally landscape


offers[].short_description string

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. Expect maximum characters of 60.



offers[].short_headline string

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. Expect maximum characters of 30.



count integer

Number of Offers returned from the call.



privacy_url URL

URL to AdsPostX'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 AdsPostX Dashboard.

This allows AdsPostX to:

  • Accurately calculate and present performance statistics such as click-through rate (CTR), eCPM and other metrics.
  • Use performance data to optimize ad delivery on future traffic.
  1. Generate and display first Offer using the fragments of the Offer returned in the response
  2. Implement the Impression Beacon URL for the first Offer
  3. If user engages with the negative call-to-action, render the second Offer (and implement the Impression Beacon URL for this Offer)
  4. 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 Native Ads 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).

PREVIOUS
API
NEXT
Anatomy of an Offer
Docs powered by Archbee