How can we help you?

  1. Digital Turbine
  2. DT Offer Wall
  3. Publishers
  4. Integrating via REST API
Follow

feed/v1/offers

Use the feed/v1/offers endpoint to request offers based on user and device information. DT returns all available offers that meet the criteria specified in the request.

Note

To avoid receiving potentially expired offers, make requests as close to real–time as possible.

Request URL

Method GET
API_Host http://api.fyber.com/
Endpoint feed/v1/offers
Headers Connection: Keep Alive
Accept-Encoding: gzip		 
http://api.fyber.com/feed/v1/offers.format?
appid=000&
uid=User1234&
ip=000.000.000.000&
locale=EN&
device_id=phone&
pub0=custom&
timestamp=1732679610&
offer_types="112,103,101"&
phone_version="iPhone12,5"&
apple_idfa=EA7583CD-A667-48BC-B806-42ECB2B48606&
apple_idfa_tracking_enabled=[IDFA ENABLED]&
google_ad_id=bk9384xs-p449-96ds-r132&
google_ad_id_limited_tracking_enabled=[GA ID ENABLED]&
hashkey=8ee872d6999f9e05b033a38824385278139d63b6

 

Sample Request URLs

To request offers in JSON format from an Apple 11 Pro Max for 5 offers for either skill games, downloads, or free offers:

http://api.fyber.com/feed/v1/offers.json?
appid=000&
uid=User1234&
ip=000.000.000.000&
locale=EN&
device_id=phone&
pub0=custom&
timestamp=1732679610&
offer_types="112,109,101"&
phone_version="iPhone12,5"&
apple_idfa=EA7583CD-A667-48BC-B806-42ECB2B48606&
apple_idfa_tracking_enabled=TRUE&
google_ad_id=&
google_ad_id_limited_tracking_enabled=&
limit=5&
hashkey=278bb72d6c899e8ab6e641baddbd77b793c1a150

 

To request offers in JSON format from an Android tablet for gaming offers, survey offers, and rewarded action offers:

http://api.fyber.com/feed/v1/offers.json?
appid=000&
uid=User1234&
ip=000.000.000.000&
locale=EN&
device_id=tablet&
pub0=custom&
timestamp=1732679610&
offer_types="106,110,114"&
phone_version=&
apple_idfa=&
apple_idfa_tracking_enabled=&
google_ad_id=bk9384xs-p449-96ds-r132&
google_ad_id_limited_tracking_enabled=TRUE&
hashkey=4d0734c32bf180ea4e77983b5bd95e2641f43fba

 

If the previous request returned offers on multiple pages, the following sample URL requests offers from the second page:

http://api.fyber.com/feed/v1/offers.json?
appid=000&
uid=User1234&
ip=000.000.000.000&
locale=EN&
device_id=tablet&
pub0=custom&
timestamp=1732679610&
offer_types="106,110,114"&
phone_version=&
apple_idfa=&
apple_idfa_tracking_enabled=&
google_ad_id=bk9384xs-p449-96ds-r132&
google_ad_id_limited_tracking_enabled=TRUE&
page=2&
hashkey=bc081efd7faefa1c8807b7c597c7ccd0842d2e8d

 

Query Parameters

PARAMETER TYPE STATUS DESCRIPTION
format string Required The format in which you want DT to respond with offers. DT currently supports responses in JSON. Specify json

Path Parameters

The following table provides details about the path parameters in the request. 

PARAMETER TYPE STATUS DESCRIPTION
appid string Required Unique identifier for your app in DT Offer Wall.
apple_idfa string Conditional

For iOS devices, the Apple ID for Advertising (IDFA) retrieved from the device. Use the following code to retrieve the IDFA from an iOS device:

[[[ASIdentifierManager sharedManager] advertisingIdentifier] UIDString] forKey:@"apple_idfa"];

This parameter is required for iOS devices.
apple_idfa_
tracking_enabled		 boolean Conditional

For iOS devices, the unique identifier retrieved from the device that shows whether the device user enabled tracking via Apple ID for Advertising (IDFA). Specify one of the following values:
TRUE = user allows tracking for advertising
FALSE = user does not allow tracking for advertising

Use the following code to retrieve this setting from an iOS device:

[[ASIdentifierManager sharedManager] isAdvertisingTrackingEnabled]]

This parameter is required for iOS devices.
device_id string Optional

Type of device. If set, Offer Wall sends offers specifically targeted for the indicated device type. Specify one of the following device types:
tablet = send offers for tablet devices
phone = send offers for phone devices

For example, the following code snippet for an iOS device retrieves the device type and assigns the appropriate string for the request.

UI_USER_INTERFACE_IDIOM() == UIUserInterfaceIdiomPad ? @"tablet" : @"phone" forKey:@"device_id"
gdpr_privacy_consent number Optional Denotes whether the user granted consent in accordance with GDPR. Use the following values:
1 = User gives consent under GDPR
2 = User does not give consent under GDPR
google_ad_id string Conditional

For Android devices, the Google Advertising ID (GAID) retrieved from the device. Use the following code to retrieve the GAID from an Android device:

AdvertisingIdClient.getAdvertisingIdInfo
(context).getId()

This parameter is required for Android devices.
google_ad_id_limited_
tracking_enabled		 string Conditional

For Android devices, the identifier retrieved from the device that shows whether the device user enabled user tracking via Google Advertising ID (GAID). Specify one of the following values:
TRUE = user allows tracking for advertising
FALSE = user does not allow tracking for advertising

Use the following code to retrieve this setting from an Android device:

AdvertisingIdClient.getAdvertisingIdInfo(context). isLimitAdTrackingEnabled()

This parameter is required for Android devices.
hashkey string Required A security hash key which signs the entire request. This security parameter ensures that the request is valid and data has not been altered. For more information about how to calculate the hash key value, see Calculating the Hash Key.
ip string Optional IP address of the device. If included, Offer Wall sends offers targeted to the IP address location. If excluded from the request, Offer Wall sends offers for the IP address of the request.
When testing your REST API implementation, ensure that you test valid external IP addresses, as requests from reserved IP addresses (such as 127.0.0.1, 10.0.0.1, etc.) do not return any offers.
limit string Optional Number of offers (maximum 1000) per page to return in the response. If you leave this field blank, DT returns 30 offers (default) per page. To view all offers that meet the criteria in this request in a single response, set this parameter to 1000.
locale string Required Two-character language code for the preferred language of the device user as retrieved from the device. DT only returns offers where the description and required actions are available for the indicated language. For example, to display offers in English, use EN.
offer_types string Optional

Unique identifier for the offer types you want to receive. Specify one or multiple offer types. To pass multiple offer types, specify the offer type IDs in the following format:
"ID1,ID2,ID3"
For example, to pass free offers, offers for skill games, and offers for downloads, specify "112,101,109".

If you pass multiple offer types, DT returns offers matching any of the specified offer types.

For a complete list of supported offer type IDs, see Offer Type IDs
os_version string Required

Version of the operating system running on the device. Use the following code to retrieve the OS version from an iOS device:

[[UIDevice currentDevice] systemVersion]
page string Conditional

If you are sending an initial request for a list of offers, leave this filed blank. The initial response from DT can contain up to 30 offers. In the response, the pages parameter shows how many pages of offers are available. Each page contains a maximum of 30 offers. You can submit a subsequent request for a specific page of offers. For more information about response parameters, see Successful Response.

If you are sending a subsequent request for additional offers, specify the page number you want to request. When requesting a subsequent page of offers, keep all other request parameters constant, and add the page number you want to retrieve. Specify only one page per subsequent request.
phone_version string Optional The iOS device model as retrieved from the device. If included in the request, DT includes offers targeted or compatible with the indicated device model. Enclose the device version in quotation marks. For example, to filter for offers targeted for the iPhone 11 Pro Max, specify "iPhone12,5".
placement_id string Optional Unique identifier for the Offer Wall placement you want to use for this request.

Note

In order to return offers, this value must match one of your Offer Wall Placement IDs in the DT Console. Otherwise, DT does not return offers.
pub0…pub9 string Optional

Custom parameters to help you reward your user. You can include pub0 through pub9 with each request. DT passes these parameters back to you in the callback once the user completes an offer.
timestamp integer Required

Time, in Unix Timestamp format, at which the device sends the request. This parameter helps uniquely identify the request and ensure that it has not been previously processed. Use the following code to retrieve the time from an iOS device:

[NSString stringWithFormat:@"%lu",(long)[[NSNumber numberWithDouble:[[NSDate date] timeIntervalSince1970]] integerValue]
uid string Required Unique user ID for the device user in your app. This identifies the user so that you can credit the user with virtual currency. The user ID must remain constant so that users are prevented from completing an offer more than once.

Offer Type IDs

Specify any of the following offer type IDs for the offer_types parameter:

OFFER TYPE ID OFFER TYPE DESCRIPTION
Offers that may incur cost to user
112 Free Free offers
103 Sale Shopping offers
Offers that require user action
100 Mobile Mobile subscription offers
101 Download Download offers (from Apple Store)
102 Trial Trial subscription offers
104 Registration Information request offers
105 Registration Registration offers
108 Registration Data Generation offers
110 Surveys Survey offers
111 Dating Dating offers
113 Video Video offers
114 Rewarded Action Rewarded Action offers
Offers for Gaming
106 Games Gaming offers
107 Games Gambling offers
109 Games Skill Game offers

Calculating the Hash Key

A hash key made up of the request parameters and your API Key ensure that DT receives an authentic and untampered request. Upon receipt, DT verifies the hash key to ensure the request is not fraudulent before processing it and sending a response.

To calculate the hash key for a request:

  1. Identify all request parameters (except the hashkey parameter) and their values, and sort each parameter-value pair alphabetically by parameter name. For example, the following parameters may be present in a request:

    • appid=000
    • google_ad_id=a0b0c0d0-a0b0-c0d0-e0f0-a0b0c0d0e0f0
    • google_ad_id_limited_tracking_enabled=true
    • ip=111.22.333.44
    • locale=DE
    • page=2
    • pub0=campaign2
    • timestamp=1585187676
    • uid=player1

Note

If a parameter value must be URL encoded, encode the URL after calculating the hashkey. Do not calculate the hashkey based on URL-encoded parameter values.

  1. Concatenate all request parameter–value pairs with & between each pair. For example:
appid=000&google_ad_id=a0b0c0d0-a0b0-c0d0-e0f0-a0b0c0d0e0f0&google_ad_id_limited_tracking_enabled=true&ip=111.22.333.44&locale=EE&page=2&pub0=campaign2&timestamp=1585187676&uid=player1
  1. Concatenate the resulting string with & and your API Key for the Offer Wall REST API. For example, the following string is the resulting string concatenated with an API Key (a11b22222c3333defgh4ijk55t6d7f88):
appid=000&google_ad_id=a0b0c0d0-a0b0-c0d0-e0f0-a0b0c0d0e0f0&google_ad_id_limited_tracking_enabled=true&ip=111.22.333.44&locale=aa&page=2&pub0=campaign2&timestamp=1585187676&uid=player1&a11b22222c3333defgh4ijk55t6d7f88

For more information about how to obtain your API Key, see Activating the Offer Wall REST API.

  1. Using SHA1, hash the string obtained in the previous step. The following is an example of a hash key:
d4c5a4836b61d34f2af83bc5cbf6aaee41989b57

Important

All letters in the resulting hash key must be in lower case.

  1. Include the resulting hash key as the value of the hashkey parameter in the request. The following is an example of a feed/v1/offers request URL that includes the hash key:
http://api.fyber.com/feed/v1/offers.json?appid=000&google_ad_id=a0b0c0d0-a0b0-c0d0-e0f0-a0b0c0d0e0f0&google_ad_id_limited_tracking_enabled=true&ip=111.22.333.44&locale=aa&page=2&pub0=campaign2&timestamp=1585187676&uid=player1&hashkey=d4c5a4836b61d34f2af83bc5cbf6aaee41989b57

The following code sample shows how to calculate the hashkey in Ruby.

require 'digest/sha1'
                        
                        api_key = 'aa11b22222c3333defgh4ijk55t6d7f88' # your DT API key for the application
                        params = 'appid=000&google_ad_id=a0b0c0d0-a0b0-c0d0-e0f0-a0b0c0d0e0f0&google_ad_id_limited_tracking_enabled=true&ip=111.22.333.44&locale=de&pub0=campaign2&timestamp=1585187676&uid=player1' # request params
                        page = 2
                        
                        params = params.split('&').each_with_object({}) do |item, memo|
                          key, value = item.split('=')
                          memo[key] = value
                        end
                        
                        def to_query(hash)
                          hash.to_a.map { |item| item.join('=') }.join('&')
                        end
                        
                        params.delete('hashkey')
                        params['timestamp'] = Time.now.to_i.to_s
                        params['page'] = page
                        
                        params = params.sort.to_h # sort by key name
                        hashkey = Digest::SHA1.hexdigest("#{to_query(params)}&#{api_key}")
                        
                        url = "http://api.fyber.com/feed/v1/offers.json?#{to_query(params)}&hashkey=#{hashkey}"

Response Structure

All Offer Wall responses include a signed HTTP header along with either a successful or unsuccessful response body.

Signed Response Header

To ensure the integrity of the response, DT adds the following security parameter to the HTTP response header:

X-Sponsorpay-Response-Signature: 96cf9acc1c1d1800ba8aa1e095e3a032ec49bca3

Validating the response signature is optional, and DT strongly recommends processing only validated responses in order to safeguard your app from tampering.

To validate the response signature:

  1. Concatenate the full response body with your API key for the Offer Wall REST API. For more information about obtaining your API key, see Activating the Offer Wall REST API.
  1. Using SHA1, hash the resulting string from the previous step.
  1. Compare the resulting hash with the hash key DT sent in the response header (X-Sponsorpay-Response-Signature).

Successful Response

The following are examples of a successful (200 OK) JSON response from the feed/v1/offers endpoint:


  {
  "code": "OK",
  "message": "OK",
  "count": 1,
  "pages": 1,
  "information": {
    "app_name": "My Fun Game",
    "appid": 000,
    "placement_id": "",
    "virtual_currency_sale_enabled": false,
    "country": " US",
    "language": " EN",
    "support_url": "http://iframe.fyber.com/mobile/AA/000/my_offers"
  },
  "offers": [
    {
      "title": "Another Fun Game",
      "offer_id": 00000,
      "teaser": "Download and START",
      "required_actions": "Download and START",
      "link": "http://iframe.fyber.com/mbrowser?appid=000&lpid=00000&uid=player1",
      "store_id": "com.my.fungame",
      "detailed_actions_text": "regsiter and get 20 blocks to stack",
      "instruction_steps": [
        "Register",
        "Get 20 blocks to stack"
      ],
      "offer_types": [
        {
          "offer_type_id": 101,
          "readable": "Download"
        },
        {
          "offer_type_id": 102,
          "readable": "Free"
        }
      ],
      "thumbnail": {
        "lowres": "http://cdn.fyber.com/assets/1000/icon_60.png",
        "hires": "http://cdn.fyber.com/assets/1000/icon_175.png"
      },
      "payout": 90,
      "time_to_payout": {
        "amount": 1800,
        "readable": 30
      },
      "action_steps": [
        {
          "action_id": "SIXTH_MINE",
          "step": "Reach Mine 6 and get u’r reward",
          "payout_distribution": 1.71,
          "rewd_amnt": 1
        },
        {
          "action_id": "EIGHTH_MINE",
          "step": "Reach Mine 8 and get u’r reward",
          "payout_distribution": 4.27,
          "rewd_amnt": 1
        },
        {
          "action_id": "TENTH_MINE",
          "step": "Reach Mine 10 and get u’r reward",
          "payout_distribution": 17.09,
          "rewd_amnt": 5
        },
        {
          "action_id": "FOURTEENTH_MINE",
          "step": "Reach Mine 14 and get u’r reward",
          "payout_distribution": 25.64,
          "rewd_amnt": 8
        },
        {
          "action_id": "TWENTIETH_MINE",
          "step": "Reach Mine 20 and get u’r reward",
          "payout_distribution": 51.29,
          "rewd_amnt": 16
        }
      ],
      "asset_urls": [
        {
          "low": "https://ofw-assets.fyber.com/offer_campaign/0000/00000/e7ab883d-4237-4d1f-ae3a-924f4bf02525_low.mp4",
          "raw": "https://ofw-assets.fyber.com/offer_campaign/0000/00000/e7ab883d-4237-4d1f-ae3a-924f4bf02525_raw.mp4",
          "high": "https://ofw-assets.fyber.com/offer_campaign/0000/00000/e7ab883d-4237-4d1f-ae3a-924f4bf02525_high.mp4",
          "medium": "https://ofw-assets.fyber.com/offer_campaign/0000/00000/e7ab883d-4237-4d1f-ae3a-924f4bf02525_medium.mp4"
        }
      ],
      "url": "//aws.fyber.com/show/fyberappid=0000&uid=uniqueID&client=api&device_model=&platform=android&appname=+0000+My+Fun+Game&traffic_source=offer_api&country_code=DE&pubid=249&ip=192.168.0.1&request_timestamp=1676985764323&request_id=090172a5-7e1b-4881-9cbc-c06c2721e7bc&timestamp=1676968753&ad_id=000000&ad_format=offer&group=Fyber&gdpr_privacy_consent=0&sig=2797caf0485ee6fed3f8bcebe5075de900c68ea0"
    }
  ]
}

Unsuccessful Response

The following is a sample error response for a HTTP status 401:

{
    "code": "ERROR_INVALID_HASHKEY",
    "message": "An invalid hashkey for this appid was given as a parameter in the request."
}

For a complete listing of possible error response codes, see Response Status Codes.

Response Parameters

In the JSON response, DT sends the following response parameters:

PARAMETER TYPE DESCRIPTION
action_steps array Contains details about requirements to receive incremental rewards for Multi-Reward Campaigns.
action_steps.action_id string Unique identifier for the rewarded action.
action_steps.minimum _latency number The minimum time in seconds that the user must take to complete the rewarded action (to prevent fraud).
action_steps.payout_distribution number Percentage of the total virtual currency to be rewarded upon completing the step.
action_steps.rewd_amnt number Amount of virtual currency to reward the user upon completing the action.
action_steps.step string Description of the rewarded action.
asset_urls array List of URLs pointing for graphic assets associated with the offer. These assets may include images, videos, documents, or any other digital files relevant to the offer.
asset_urls.high string URL for high resolution image.
asset_urls.low string URL for low resolution image.
asset_urls.medium string URL for medium resolution image.
asset_urls.raw string URL for raw format image.
attribution_window number Number of days the user has to compelete the offer. Users who complete an offer beyond this timeframe are not eligible to receive the reward.
code number Code that represents the general outcome of your request. Use this code for integration testing and debugging. For more information about all possible response codes, see Response Status Codes.
count number Total number of offers available that meet your request parameters.
information array Contains basic information about your app and reward settings.
information.app_name string Name of your app as entered in the DT Console for Offer Wall.
information.appid number Unique identifier assigned to your app in DT Offer Wall.
information.country string The country of the user as specified in the ip parameter of the associated request. The offers in this response are all targeted to users in this country.
information.language string The language as specified in the locale parameter of the associated request. The offers in this response are presented in the specified language.
information.placement_id string Unique identifier for the Offer Wall Placement you requested to use.
information.report_url string Publisher URL to a report form for inquiries regarding in-progress offers.
information.support_url string Publisher URL to a status page where the user can view all of the offers in which they have participated. If surfaced, the user can click on an in-progress offer, and if needed, file a report using the URL found in the information.report_url parameter.
information.virtual_currency string The name of virtual currency as entered in the Offer Wall Placement in the DT Console.
information.virtual_currency_
sale_enabled		 boolean

This is a boolean field identifying whether a Virtual Currency Sale (VCS) is active at the time the response is generated. If the flag is enabled, the VCS reward multiplier is applied.

For more information about your virtual currency sales settings, see Virtual Currency Sales.
message string

Description of the response code.

Do not evaluate the response based on the value of this parameter. as DT may occasionally alter this text. Instead, use the code parameter to evaluate the success of a response.
net_payout_usd string Amount of currency (in USD) equivalent to the amount of virtual currency paid out to the user before applying the virtual currency exchange rate.
offers array Offers that match the request criteria.
offers.detailed_actions_text string Instructions for each offer step.
offers.instruction_steps string Steps that the user must complete to receive the reward.
offers.link string

URL that the user should be sent to upon selecting this offer.

Important: Some offers may not work within the context of a web view. To ensure that offer links work properly, open the link in the system browser.
offers.mobile_app_primary_category string Advertised app store category for the offered app on Google Play or Apple App Store.
offers.offer_id number Unique identifier for the offer.
offers.offer_types array Offer Types attributed to this offer
offers.offer_types.offer_type_id string Unique identifier for the offer type.
offers.offer_types.readable string Offer Type associated wiht the Offer Type ID. If the request contained a language value for the locale parameter, this response parameter is presented in the specified language. For a complete list of offer types and associated offer type IDs, see Offer Type IDs.
offers.required_actions string Description of the steps needed to complete the offer.
offers.store_id string App package name for the offered app as advertised in Google Play or Apple App Store.
offers.teaser string Text to generate interest in the offer. If there is no teaser available, this parameter contains the same value as the offers.required_actions parameter.
offers.title string Name of the offer.
pages number

If there are more offers available than what DT has returned in this response, this parameter indicates how many more pages of results are available. By default, each page contains a maximum of 30 offers unless you specify a specific number of offers per page in the limit parameter of your request.

To retrieve offers on subsequent pages, send another feed/v1/offers request, and use the page parameter to specify the page number for the offers you want to retrieve.
payout string Amount of virtual currency to reward the user upon their completion of the offer requirements. This amount is based on currency payout and exchange rate specified for your app in the DT Console.
thumbnail array URLs thumbnail images for the offer.
thumbnail.hires string URL to the high resolution thumbnail for the offer.
thumbnail.lowres string URL to the low resolution thumbnail for the offer.
time_to_payout array Amount of time in which the reward should be granted to the user.
time_to_payout.amount number Time, in seconds, in which the reward should be granted to the user.
time_to_payout.readable number Time, in minutes, in which the reward should be granted to the user.
url string

The Request URL to call the show/fyber endpoint which provides additional details about the offer including the URL the user should use to access the offer.

For more information about the show/fyber endpoint, see show/fyber.

Response Status Codes

The following table provides response status codes that you may receive in the response. The table also provides the HTTP status codes associated with each response status.

DT does not process requests that contain errors. If you receive an error response, correct and re-send the request.

HTTP CODE RESPONSE STATUS CODE DESCRIPTION
200 OK Request received and processed successfully.
400 ERROR_INVALID_PAGE The page parameter in the request refers to a non-existing page
400 ERROR_INVALID_APPID Request contained an invalid or missing application ID (appid parameter)
400 ERROR_INVALID_UID Request contained an invalid or missing User ID for the uid parameter.
400 ERROR_INVALID_DEVICE_ID Request contained an invalid or missing unique device identifier for thedevice_id parameter.
400 ERROR_INVALID_IP Request contained an invalid or missing IP address for the ip parameter.
400 ERROR_INVALID_TIMESTAMP Request contained an invalid, expired, or missing timestamp for the timestamp parameter.
400 ERROR_INVALID_LOCALE Request contained an invalid or missing language specification for the locale parameter.
400 ERROR_INVALID_CATEGORY Request contained an invalid offer type ID for the offer_types  parameter.
400 ERROR_INVALID_ITEMID Request contained an invalid or missing Item ID.
401 ERROR_INVALID_HASHKEY Request contained an invalid or missing hashkey for the hashkey parameter.
500 ERROR_INTERNAL_SERVER_ERROR An unknown error occurred on the DT server.

Back to Top ⇧