Get Offers

Offer Wall API Parameters

API parameters pubID, adwallID, and api_key can be found via the "API Details" link next to your profile at Your Offer Wall Profiles.

If you would like us to notify you whenever an offer is completed (lead generated), set up a server postback.

Get Offers

Retrieves offers for the Offer Wall user. Automatic geographic, language, device, and OS targeting will be performed based on the User-Agent and IP address from the request (can be overridden by using a custom User-Agent header (or the user-agent parameter) and the ip parameter).

Response 204 when no offers are available for the given parameters.

Response 400 when required parameter not provided.

Response 404 when adwallID doesn't exist for the pubID specified.

GET:

http://adscendmedia.com/adwall/api/publisher/{pubId}/profile/{adwallId}/offers.json?subid1={subid1}&subid2={subid2}&subid3={subid3}&subid4={subid4}&limit={10}&offset={40}&sort_order={asc}&sort_by={popularity}&category_id={category_id}&featured_only={1}&gender={m}&age_range_id={2}&device={device}&device_lat={true}&ip={ip}

Parameters   Description Type
pubId Required Your publisher ID Number
adwallId Required Your Offer Wall profile ID Number
subid1 Required Your user's primary unique identifier. Maximum length of 60. String
subid2 Optional Used for click and lead tracking. Maximum length of 60. String
subid3 Optional Used for click and lead tracking. Maximum length of 60. String
subid4 Optional Used for click and lead tracking. Maximum length of 60. String
limit Optional Used for pagination. All are shown by default. Example: 10 Number
offset Optional Used for pagination. Example: 40 Default: 0 Number
sort_order Optional Possible values are asc and desc. Example: asc Default: desc String
sort_by Optional Possible values are popularity, trending, payout, and credit_delay. Example: popularity Default: popularity String
category_id Optional Filter offers by category. Possible values are 17 = Free, 18 = Mobile Apps, 19 = Videos, 20 = Surveys, 21 = Shopping, 22 = Free Trials, 23 = Downloads, 24= Sign-Ups, 25 = Mobile Subscriptions, and 26 = Co-Registrations. Ex: category_id[]=17&category_id[]=20 Array
featured_only Optional Filter offers by featured. Example: 1 Default: 0 Number
gender Optional Possible values are m and f. Example: m String
age_range_id Optional Possible values are 1 = 18-35, 2 = 35-45, 3 = 45-55, 4 = 55-65, and 5 = 65+. Example: 2 Number
device Optional User's device ID, e.g. Apple IDFA or Android Advertising ID.
Used for click and lead tracking. Maximum length of 60.		 String
device_lat Optional User's device preference to limit advertising tracking. 
Example: true Default: Boolean
user-agent Optional Simulates the user's User-Agent header. Used to display offers available to the user based on their browser & device type.  Required when making the call server-side String
ip Optional Simulates IP address of user. Used to display offers available in the resolved country and to exclude offers already completed by the IP.  Required when making the call server-side String
privacy_opt_out Optional Send 1 or true when the user has opted out of the sale or sharing of their personal information, for example in your own consent platform. See Privacy opt-out. Any other value is ignored. Example: 1 String
gpp Optional The user's IAB Global Privacy Platform (GPP) string, as your consent management platform (CMP) provides it. An opt-out in any US section of the string is an opt-out. See Privacy opt-out. Example: DBABL~CVVVkkkkkpFY.YA String
gpp_sid Optional The GPP section IDs that apply to this request, comma separated, as your CMP provides them. When sent, only those sections of gpp are read for opt-outs; its TCF section is read either way. Example: 7 String
gdpr Optional 1 when GDPR applies to the user, 0 when it does not, as your CMP provides it. When you do not send gdpr, we decide from the user's IP: the EEA and the UK. See EEA and UK consent. Example: 1 String
gdpr_consent Optional The user's IAB TCF v2 consent string, as your CMP provides it. A TCF section inside gpp is read as well. See EEA and UK consent. Example: CQraFkAQr3wAAAOADAENC1FgALAAAAAAAAYgF5wAgAAgLzAAAAAA.YAAAAAAAAAAA String

Privacy opt-out

When a user has opted out of the sale or sharing of their personal information, tell us on the request, and we will stop offers that pass that user's own data on to third parties from being shown to them. These are market research offers and surveys, and offers that use the user's device ID, device fingerprint or survey profile ID. The user's survey profile is no longer sent to survey providers either.

Any one of these signals is an opt-out:

  • GPP string. If you use a consent management platform (CMP), pass the user's GPP string in gpp, and the applicable section IDs in gpp_sid. These are the standard IAB parameter names, so your CMP or ad stack may already fill them. We read the US National section and the US state sections (section IDs 7 to 27): SaleOptOut, SharingOptOut or TargetedAdvertisingOptOut set to 1 (opted out), or the GPC subsection set, is an opt-out. Other sections, and a string that cannot be read, are ignored.
  • Explicit parameter. If you have no CMP, send privacy_opt_out=1 (or true). Use it, or gpp, when you make the call from your server, because a server call carries your server's headers, not the user's.
  • Global Privacy Control. A request that carries the Sec-GPC: 1 header is treated in the same way. A browser sends it by itself when the user has switched it on, so it reaches us when the Offer Wall is loaded directly in the user's browser or web view.
  • The opt-out is recorded for your pubId and the subid1 of that user and stays in place. Later requests for the same subid1 are handled as opted out even when they no longer carry the parameter, so you do not need to send it on every call, although sending it does no harm.
  • Offers that only pass a click ID and your subid1 on are not affected, so the user can still earn from them.

For users in the European Economic Area and the United Kingdom, pass the user's IAB TCF v2 consent string in gdpr_consent (or as the TCF section of gpp), and gdpr=1. These are the standard IAB parameter names, so your CMP or ad stack may already fill them. When you do not send gdpr, we treat a user whose IP is in the EEA or the UK as in scope; gdpr=0 tells us GDPR does not apply. The TCF section of gpp is read whether or not gpp_sid lists it; when you send both gdpr_consent and gpp, gdpr_consent takes precedence.

Adscend is not a vendor on the IAB Global Vendor List, so we read the user's purpose consents. When the string denies consent to purpose 1 (store and/or access information on a device), 3 (create a personalised advertising profile) or 4 (use that profile to select advertising), the Offer Wall is shown without the offers that pass the user's own data on, with the same offers left out as for a user who opted out: no market research offers and surveys, and no offers that use the user's device ID, device fingerprint or survey profile ID. The rest of the Offer Wall is shown as usual. The user's survey profile is not sent to survey providers either. When the string records that purpose 1 was not disclosed to the user (purpose one treatment), only purposes 3 and 4 are checked. A request without a consent string, or with a consent string we cannot read, is not restricted. Unlike an opt-out, consent is not stored: each request is judged by the string it carries, so send gdpr_consent (or gpp) on every call. A later request with a string that grants consent is not restricted. We keep a record of the consent state we received.

These parameters are read by this API, by the Offer Wall loaded in an iframe or web view, and by the Market Research surveys API. For the Offer Wall in an iframe or web view, append them to the Offer Wall URL; they are passed on to the wall's offer and survey requests. The native Android and iOS SDKs do not pass them yet.

Response 200

Content-Type: application/json

{
  "offers": [
    {
      "offer_id": 1,
      "name": "GoFreeCredit 3-in-1",
      "description": "Know your credit score",
      "requirements": "Submit your email address.", // null = no requirements
      "credit_delay": "0",                          // string; "0" = instant, "2" = number of days, "2-4" = day range, "7" = weekly, "14" = bi-weekly
      "image_url": "http://lorempixel.com/125/125/",
      "click_url": "http://www.example.com",
      "payout": 1.50,
      "currency_count": 380,
      "featured_global": 1,                         // integer; Adscend Media featured
      "featured_profile": 0,                        // integer; Publisher featured for Offer Wall profile
      "epc": 1.54,                                  // 99 = still calculating
      "conversion_rate": "0.484",                   // string; null = still calculating
      "category_id": [18, 22, 23],
      "creative_id": 123,
      "creative_filename": "123-456.gif",
      "mobile_app": {                               // Is set only if offer is a mobile app and is available in its app store.
        "store_id": "com.facebook.katana",          // Unique identifier of the app in its respective app store.
        "platform": 1                               // 1 = Android, 2 = iOS
      },
      "target_system": 30,                          // ignore (used internally)
      "matches_target_system_detected": true,        // ignore (used internally)
      "events": [{                                   // offer events: Array
                    "event_id":1,
                    "event_name":"Install"},
                    {
                      "event_id":1,
                      "event_name":"Open"
                  }]
    }
  ]
}

Continue to Get User Transactions >