# Advertiser Reporting API ## Use Cases **The API described on this page is for fetching reports.** * All monetary values are in dollars as decimals. * Please allow for long timeouts for each request as responses are not instant. * Reports are updated approximately every half hour, so requesting the same report within that timeframe will return the same result set. ## API **Method:** GET\ **Base URL:** `https://api.adgatemedia.com/v1/advertiser/report` ### Required Parameters | Parameter | Description | Type | Example | | ----------- | ----------------------------------------------------------------------------------------------- | ------ | ---------------------------------- | | api\_key | Your API key. Can be found on the [Reporting API page](https://prodegeads.com/client/api/keys). | String | `941bd1fecf7e6596823b895e04df3a0c` | | start\_date | Start date of report in mm-dd-YYYY format | String | `01-30-2020` | | end\_date | End date of report in mm-dd-YYYY format | String | `02-01-2020` | ### Optional Parameters #### Timezones The report data can be retrieved in a custom timezone.\ \ Example: \&data\[]=offer\_id\&timezone=America/Los\_Angeles | Value | Descripion | | -------- | -------------------------------------------------------------------------------------------------------------------------------- | | timezone | [IANA](https://www.iana.org/time-zones) Timezone. A list of valid timezones can be found [here](https://nodatime.org/TimeZones). | **Note:** If timezone is not provided in the request, the data will be retrieved in `America/Los_Angeles` timezone by default. #### Data Column Grouping The data columns to display and group data by. Example: \&data\[]=offer\_id\&data\[]=country\&data\[]=source | Value | Description | | ------------ | -------------------------------------------------------------------- | | offer\_id | Prodege's internal offer ID (default) | | offer\_event | Offer event name\* | | country | Country | | is\_mobile | Is mobile or tablet traffic (boolean) | | browser | Browser | | os | Operating System | | device | Device | | source | String representing the ID of the offer wall or publisher sub-source | | aff\_id | Publisher's internal ID | (\*) Offer events: because the offer event is only known upon conversion and does not apply to clicks, the click counts are duplicated for each offer event. For example, if an offer gets 10 clicks, each offer event in the report will display 10 clicks. Furthermore, if there are only clicks and no conversions, expect the offer\_event to be `null`. We may remove results without conversions in the future. #### Date Interval Grouping Group response by specific time periods. Example: \&intervals\[]=m\&intervals\[]=dt | Value | Description | | ----- | ----------- | | m | Month | | dt | Day | | h | Hour | #### Filters Request to only include reports that match certain criteria. Separate multiple values for each filter using commas. Example: \&filters\[offer\_id]=11045,112340 | Value | Description | | ---------- | ------------------------------------------------------------------------------------------------- | | offer\_id | Filter by specified offer IDs | | country | Filter by specified countries using ISO standards (\&filters\[country]=US,GB) | | is\_mobile | Filter by mobile/tablet traffic. Use `0` for desktop traffic, `1` for mobile/tablet traffic only. | #### Additional Data Optional data that can be added to the response. Example: \&options\[]=impressions\&options\[]=cpm | Value | Description | | -------------------------- | --------------------------------------------------------------------------------- | | offer\_impressions | Include offer impression data | | user\_impressions | Include user impression data | | cpm | Include cost per thousand impressions | | app\_id | Include App ID value in addition to offer ID | | offer\_wall\_position\_avg | Include the average position of an offer on the offer wall for the given data set | ### Response Note that country abbreviations use the ISO standard, e.g. GB instead of UK. #### Sample Response ``` { "data": { "results": [ { "offer_id": 15506, "offer_name": "Survey Sample Savings - Burger King (US) (Incentive)", "is_mobile": true, "unique_impressions_count": 91879, "unique_clicks_count": 34268, "conversions_count": 3105, "costs": 5589, "cpm": 60.83, "rpc": 0.16, "country_code": "US" }, { "offer_id": 17192, "offer_name": "Lifesum iPhone Burst (US) (Incentive)", "is_mobile": true, "unique_impressions_count": 25527, "unique_clicks_count": 7552, "conversions_count": 3442, "costs": 1652.16, "cpm": 64.72, "rpc": 0.21, "country_code": "US" } ], "totalColumns": { "unique_impressions_count": 117406, "unique_clicks_count": 41820, "conversions_count": 6547, "cost": 7241.16, "cpm": 61.68, "calculated_cpc": 0.17, } }, "status": "success" } ``` #### Errors **Request limit:** Only 3 requests are allowed per minute. ``` { "data": [], "status": "error", "error": { "code": 400, "message": "Three reporting API requests have been made with this API key. Please try again in a minute." } } ``` **Invalid Data:** Invalid data field(s) were requested \[ \&data\[]=wrong ]. ``` { "data": [], "status": "error", "error": { "code": 400, "message": "Invalid Data column(s) [ &data[]=wrong ]." } } ``` **Invalid Interval:** Invalid interval is passed \[ \&interval\[]=month ]. ``` { "data": [], "status": "error", "error": { "code": 400, "message": "Invalid interval [ &interval[]=month ]." } } ``` **Invalid Options:** Invalid option(s) are passed \[ \&option\[]=random ]. ``` { "data": [], "status": "error", "error": { "code": 400, "message": "Invalid option [ &option[]=random ]." } } ``` **Invalid Filters:** Invalid filters requested \[ \&filters\['wrong\_key']=check ]. ``` { "data": [], "status": "error", "error": { "code": 400, "message": "Invalid filters [ &filters['wrong_key']=check ]." } } ``` **Invalid Timezone:** Invalid timezone is passsed \[ \&timezone\[]=wrongtimezone ]. ``` { "data": [], "status": "error", "error": { "code": 400, "message": "Timezone wrongtimezone is invalid. Please use a valid timezone." } } ``` **Maximum groupings:** Maximum 5 data grouping columns are allowed. ``` { "data": [], "status": "error", "error": { "code": 400, "message": "Maximum 5 groupings (data + intervals) can be applied at a time." } } ``` #### Response Fields Each row may contain any of the following keys and values, depending on the options passed to the API: | offer\_id | Prodege's internal offer ID | | -------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | offer\_name | Campaign Name | | app\_id | Offer's App ID (from Apple AppStore or Google Play) | | country\_code | 2-letter ISO Country Code | | is\_mobile | Whether the device used was mobile/tablet (boolean) | | browser | Browser used to click the offer | | os | Operating system of the device by which offer was clicked | | offer\_event | Offer event name used as an identifier internally | | offer\_event\_label | Offer event label used in the offer walls | | device | Device by which offer was clicked | | m | Month | | dt | Day of month | | h | Hour | | unique\_clicks\_count | Click count, uniques by IP within the time interval requested | | conversions\_count | Number of conversion within the time span requested | | unique\_impressions\_count | Impressions count, uniques by IP within the time interval requested | | costs | Payout | | rpc | Cost per click | | cpm | Earnings per thousand impressions. | | offer\_wall\_position\_avg | Include the average position of an offer on the offer wall for the given data set | | totalColumns |

The calculations here apply only to the current result set.

| #### More Examples **URL:** This request will group data by (offer\_id, country) for the last month. The result set will be empty if there was no traffic during this time period. #### Example Response ``` { "data": { "results": [ { "offer_id": 15506, "offer_name": "Survey Sample Savings - Burger King (US) (Incentive)", "unique_clicks_count": 34347, "conversions_count": 3116, "costs": 5608.8, "rpc": 0.16, "country_code": "US" }, { "offer_id": 17192, "offer_name": "Lifesum iPhone Burst (US) (Incentive)", "unique_clicks_count": 7552, "conversions_count": 3442, "costs": 1652.16, "rpc": 0.21, "country_code": "US" } ], "totalColumns": { "unique_clicks_count": 41899, "conversions_count": 6558, "cost": 7260.96, "calculated_cpc": 0.17, } }, "status": "success" } ``` **URL:** This request will get a date report that includes impressions and CPM data only for offers 16146 and 15506, grouped by day. Rows for each corresponding day are returned even if there was no traffic during that time frame. #### Example Response ``` { "data": { "results": [ { "dt": "2015-06-02", "unique_impressions_count": 23976, "unique_clicks_count": 8595, "conversions_count": 721, "costs": 1297.8, "cpm": 54.13, "rpc": 0.15 }, { "dt": "2015-06-01", "unique_impressions_count": 1632, "unique_clicks_count": 286, "conversions_count": 12, "costs": 21.6, "cpm": 13.24, "rpc": 0.07 } ], "totalColumns": { "unique_impressions_count": 25608, "unique_clicks_count": 8881, "conversions_count": 733, "cost": 1319.4, "cpm": 51.52, } }, "status": "success" } ``` # User Based API (v1) ## Use Case Our User Based API allows you to display offers compatible with virtual currency applications and display them natively on your website or app. This API allows you to recreate the functionality of the AdGate Rewards offer wall within your own application. With this API you can: * Return a list of optimized offers for a specific user based on their geolocation, device, and user history. * See and display a user's offer interaction history. Endpoints should be called in real-time whenever you would like your users to see offers. Results should not be cached as they are constantly changing. Calls to the endpoints should be made from the server-side, **not** the client-side. ## Endpoints The following endpoints are available: * [Get Offers](/publisher-apis/user-based-api-v1/get-offers) * [Post Devices](/publisher-apis/user-based-api-v1/post-devices) * [Get History](/publisher-apis/user-based-api-v1/get-history) * [Get Offer History](/publisher-apis/user-based-api-v1/get-offer-history-deprecated) Each endpoint accepts parameters passed in the query, e.g.: ``` https://api.adgatemedia.com/v1/user-based-api/history?aff_id=60000&api_key=abcdef&wall_code=nQ&user_id=user12345 ``` Some endpoints may require extra data provided in a JSON body. All endpoints return a JSON response. ## Authentication Each endpoint requires these two parameters: | Parameter | Description | Type | Example | | --------- | ---------------------------------------------------------------------------------------------------------- | ----------- | ---------------------------------- | | aff\_id | Your affiliate ID. Can be found on the [Offers API page](http://panel.adgatemedia.com/affiliate/api/keys). | Any Integer | `60000` | | api\_key | Your API key. Can be found on the [Offers API page](http://panel.adgatemedia.com/affiliate/api/keys). | Any String | `941bd1fecf7e6596823b895e04df3a0c` | # Get Offers Main API endpoint to fetch available offers for a particular user. Use this to display offers in your offer wall. **Method:** GET\ **Base URL:** [**https://api.adgatemedia.com/v1/user-based-api/offers**](https://api.adgatemedia.com/v1/user-based-api/offers) ### Required Query Parameters
ParameterDescriptionTypeExample
aff_idYour affiliate ID. Can be found on the Offers API page.Any Integer60000
api_keyYour API key. Can be found on the Offers API page.Any String941bd1fecf7e6596823b895e04df3a0c
wall_codeWall code that can be found on the AdGate Rewards pageStringnQug
user_idThe affiliate's user ID. Max length 255 bytesStringuser12345
ipIP v4 or v6. Used to target offers geographically.String127.0.0.1
user_agentThe end-user's user agent, used for device targeting.String
Mozilla/5.0 (Windows NT 6.1; Win64; x64; rv:47.0) Gecko/20100101 Firefox/47.0
in_appWill this placement be inside an app? If string "true", we will only return offers that follow App Store and Play Store guidelines."true" or "false"false
### Optional Parameters
ParameterDescriptionTypeExample
rank_methodOne of "cpm" or "cr". Determines how the rank field will be calculated.Stringcpm
s2
s3
s4
s5		Four available subIDs the affiliate can pass to us. We will return them in the affiliate's postback.String
langThe language as provided by the browser (from Accept-Language HTTP header). Defaults to English if not provided.String
en-US,en;q=0.5
categoriesApp metadata categories filter. If provided, we will return the offers that belong to the given app metadata categories. It accepts comma-separated category names with partial matching using asterisk.Stringgame*,entertainment
exclude_categoriesApp metadata categories exclusion filter. If provided, we will return the offers that do not belong to the given app metadata categories. It accepts comma-separated category names with partial matching using asterisk.Stringgame*,entertainment
is_gameIf set to true or false, will return only games or non-games. If not provided both games and non-games are returned.Stringtrue
ageUser's age. If provided, we will return the offers that meet the given age targetng requirement.Integer24
genderUser's gender. If provided, we will return the offers that meet the given gender targetng requirement.Stringmale
override_w2m_devicesA list of the devices the user owns separated by commas. You may use this instead of posting devices to the Devices endpoint. Allowed values are "iphone", "ipad", and "android". Only used if user_agent is a desktop device.Stringiphone,android
### Response An array of offers will be returned on success. Each offer will have the following fields: | Field | Note | Type | Example | | ------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | id | Offer ID | int | 341022 | | anchor | Offer title to display to users | string | Playstation 5 | | things\_to\_know | Offer information that can be presented as a bullet-point list | array | \[ "Enter to win a Playstation 5!", "You must click “Allow” if tracking permission is requested within the app." ] | | session\_hours | Offer is valid for that many hours | int | 720 | | offer\_expires\_at | Offer expiration timestamp | int | 1741370828 | | requirements | What the user should do to complete an offer | string | Sign up with valid information and complete the full survey. | | description | Description to display to the user | string | Enter to win a Playstation 5! | | disclaimer | A field to display with each offer. Replace the ${sitename} macro yourself. | string | This offer is presented to you by ${sitename} on behalf of a third party merchant | | product\_id | A unique string shared between offers which belong to same product, e.g. same mobile app. | string | 01JEEDPNV72ZX4FFY81K2HSSTC | | product\_name | The offer's product name. | string | Product #1 | | confirmation\_time | Text that described how long it takes to receive credit | string | Confirms Instantly | | creatives | Links to offer creatives | object | | | creatives.images | Links to offer images | object | { "275x275": "", "400x400": " | | pending\_time | Time in minutes that a reward will be held from the user following completion | int | 60 | | mobile\_verification\_required | Whether the end user needs to verify their mobile phone number | bool | false | | web2mobile | Whether this offer must be accessed on the user's mobile device. You must send us the devices the user owns via the \[POST devices] endpoints. If no devices are stored, web2mobile offers will not be returned. | bool | FALSE | | web2mobile\_devices | Array of devices the users must access the user on. NULL if not a web2mobile offer. The list of applicable devices is taken from the devices stored for that particular user (see the other devices API endpoint) | array\|null | \["iphone", "ipad"] | | app\_metadata.app\_id | App ID on the mobile app store. It can be either App Store or Google Play Store app ID. | string\|null | 1596736236 | | app\_metadata.categories | An array of app metadata categories. | array\|null | \["Games", "Casual", "Puzzle"] | | app\_metadata.screenshot\_urls | An array of app metadata screenshot URLs. | array\|null | \[""] | | app\_metadata.video\_urls | An array of app metadata video URLs. | array\|null | \[""] | | is\_game | Whether the offer is a game offer | bool | FALSE | | click\_url | URL to redirect the user to | string | | | support\_url | URL of the support form for this offer | string | | | impression\_url | URL to notify that the offer was viewed | string | | | icon\_url | Square icon URL | string | | | categories | Offer categories | array | \[ "CPI", "iPad", "iPhone" ] | | total\_points | Total points the user may earn | float | 126.72 | | total\_points\_promotional | If a promotion is currently in progress, the amount of points they will earn. If not null, this should be used instead of total\_points. | float\|null | 187.9 | | epc | Average network EPC in dollars | string | "0.23" | | sticky | If an offer should be pinned to the top of the offer wall | bool | TRUE | | rank | The rank of the offer according to the "rank\_method" requested | int | 1 | | events | An array of events the user may complete to earn points. Each event is an object. | array | \[see below] | | events.#.uuid | ID of the event | string | 0dc43f54-135a-46a4-a51c-a2c5f3cfdac0 | | events.#.name | Event name to display to the user | string | Completed | | events.#.type | "flat" or "dynamic". Flat events have static point values. Dynamic events will have varying payouts. | string | flat | | events.#.payable | Whether the event pays anything to the publisher | bool | TRUE | | events.#.ttc\_minutes | Minutes to complete this event after the click | int | 43200 | | events.#.expires\_at | Timestamp when the event expires | int | 1741370829 | | events.#.flat\_points | Will be 0 if the event is not payable. | float\|null | 126.72 | | events.#.flat\_payout | Will be 0 if the event is not payable. | float\|null | 46.22 | | events.#.flat\_promotional\_points | Points if there is an ongoing promotion | float\|null | 187.9 | | events.#.dynamic\_display\_type |

Either "up\_to" or "commission". This determines how the potential points are displayed.

"up\_to": display "Up to {dynamic points amount}

"commission": display "{dynamic points amount} per ${dynamic payout amount}

| string\|null | up\_to | | events.#.dynamic\_points | Described above | float\|null | 187.9 | | events.#.dynamic\_payout | For "commission", the dollars amount to use in the phrase above | float\|null | 1 | | events.#.dynamic\_promotional\_points | Described above | float\|null | 0 | | events.#.event\_type\_id | ID used to identify the event type | Integer\|null | 1 | | events.#.time\_played | Time played goal associated with the event. | object\|null | | | events.#.time\_played.id | Time played goal id. | integer | 100 | | events.#.time\_played.goal\_unit |

The unit of time that the goal is measured in.

Allowed values are: NANOS, MICROS, MILLIS, SECONDS, MINUTES, HOURS, HALF\_DAYS, DAYS, WEEKS, MONTHS, YEARS, DECADES, CENTURIES, MILLENNIA, ERAS, FOREVER.

| string | DAYS | | events.#.time\_played.goal\_unit\_count | The quantity of goal unit required to complete the goal. | integer | 7 | | events.#.multiple\_conversions\_allowed | Whether this event can be converted multiple times | bool | true | | events.#.multiple\_conversions\_rules | The rules for multiple event conversions | object\|null | | | events.#.multiple\_conversions\_rules.rule\_type | Can be UNLIMITED, TOTAL\_CONVERSIONS or INTERVAL | string | "UNLIMITED" | | events.#.multiple\_conversions\_rules.x\_conversions | Number of conversions allowed | int | 3 | | events.#.multiple\_conversions\_rules.every\_y\_seconds | Only used for INTERVAL type: allows X conversions every Y seconds | int | 600 | | roas\_goals | Offer-level ROAS: one object per configured cohort day that we support, with goal vs observed ROAS for the offer network-wide. | array |

"roas\_goals": \[
{
"day": 7,
"goal": 1.33,
"roas": 0.89
}
]

| | roas | Offer + affiliate (wall) level: same cohort idea, but scoped to this wall’s / affiliate’s traffic on the offer. Same object shape as roas\_goals. | array |

"roas": \[
{
"day": 7,
"goal": 1.33,
"roas": 0.89
}
]

| #### Sample Response ```json { "data": [ { "id": 1666524, "anchor": "Clash of Clans", "things_to_know": [ "Join millions of players worldwide as you build your village, raise a clan, and compete in epic Clan Wars!", "You must click “Allow” if tracking permission is requested within the app." ], "session_hours": 720, "offer_expires_at": 1741370828, "requirements": "Join millions of players worldwide as you build your village, raise a clan, and compete in epic Clan Wars! You must click “Allow” if tracking permission is requested within the app.", "description": "Clash of Clans", "disclaimer": "*Points will appear as Pending for 30 days. Each person may redeem this offer only ONCE (1 time). This offer is presented to you by ${sitename} on behalf of a third party merchant or sponsor (\"Merchant\"), which advises us when the offer is completed and a reward should be issued. ${sitename} has not evaluated and does not endorse Merchant's views, policies, products or services, which you are encouraged to evaluate for yourself. Have questions? Please contact the ${sitename} Help Center.", "product_id": "01JEEDPNV72ZX4FFY81K2HSSTC", "product_name": "Product #1", "confirmation_time": "Confirms Instantly", "creatives": { "images": {} }, "pending_time": 0, "is_game": true, "mobile_verification_required": false, "app_metadata": { "app_id": "529479190", "categories": [ "Games", "Action", "Entertainment", "Strategy" ], "screenshot_urls": [ "https://is1-ssl.mzstatic.com/image/thumb/Purple221/v4/04/df/6b/04df6bc3-d532-a745-a34c-47df801d8c4d/627799b5-bcad-4b62-8066-ffc4017dc4c4_clash_2208x1242_1.jpg/626x0w.jpg", "https://is1-ssl.mzstatic.com/image/thumb/Purple221/v4/92/5a/71/925a718f-73b4-495e-c7a6-039c4194cf76/59bd05b8-05cc-4e51-9905-7c700424b34b_clash_2208x1242_2.jpg/626x0w.jpg", "https://is1-ssl.mzstatic.com/image/thumb/Purple221/v4/df/34/d0/df34d02e-4609-5a42-360e-c490771fe283/f771935d-9818-48e1-8bc3-eb326d59e774_clash_2208x1242_3.jpg/626x0w.jpg", "https://is1-ssl.mzstatic.com/image/thumb/Purple221/v4/65/d9/0a/65d90adb-eaec-7b0d-5a72-33027b96b717/745ae951-68bc-4827-a9b5-17212cc109ed_clash_2208x1242_4.jpg/626x0w.jpg", "https://is1-ssl.mzstatic.com/image/thumb/Purple221/v4/7a/75/73/7a757339-77aa-a8a9-0077-251432585015/a98b615c-678b-439b-83c9-323526f861d8_clash_2208x1242_5.jpg/626x0w.jpg", "https://is1-ssl.mzstatic.com/image/thumb/Purple221/v4/76/66/d8/7666d852-4b8b-5727-bca4-6e4278149915/bfc194c6-f848-4ed7-ae04-d37a24c00150_clash_2208x1242_6.jpg/626x0w.jpg", "https://is1-ssl.mzstatic.com/image/thumb/Purple221/v4/32/d9/6e/32d96e31-fdb7-17ce-845d-438f3dc7204b/9585bee6-547b-4ed0-bab6-be8ec441a0cb_clash_2208x1242_7.jpg/626x0w.jpg" ], "video_urls": [] }, "web2mobile": false, "web2mobile_devices": null, "click_url": "https://shortlink12.agm.mobi/vc/nqqYp2g/users/smurciac-2797-v2/offers/1666524?source_type=user_based_api&funnel_id=01JKBMPR5QYT91EGGV1R62DB2W", "support_url": "https://wall12.agm.mobi/offer/contact/nqqYp2g/1666524?s1=smurciac-2797-v2", "impression_url": "https://api12.agm.mobi/v1/user-based-api/impression?funnel_id=01JKBMPR5QYT91EGGV1R62DB2W&wall_code=nqqYp2g&user_id=smurciac-2797-v2&offer_id=1666524", "icon_url": "https://main-p.agmcdn.com/static/default_icon.png", "categories": [ "CPI", "iPad", "iPhone" ], "sticky": true, "events": [ { "uuid": "a90457b6-4abf-4403-8d5f-eb4abc8ae6eb", "name": "dynamic_event. Complete within 1 month 2 days", "type": "dynamic", "payable": true, "event_type_id": null, "ttc_minutes": 43200, "expires_at": 1741370829, "flat_points": null, "flat_payout": null, "flat_promotional_points": null, "dynamic_display_type": "commission", "dynamic_points": 10, "dynamic_payout": 1, "dynamic_promotional_points": null, "time_played": null, "multiple_conversions_allowed": true, "multiple_conversions_rules": { "rule_type": "UNLIMITED", "x_conversions": null, "every_y_seconds": null } }, { "uuid": "7c320062-42e2-4312-95b0-ccac4904128e", "name": "flat_event. Complete within 1 month 2 days", "type": "flat", "payable": true, "event_type_id": 4, "ttc_minutes": 43200, "expires_at": 1741370829, "flat_points": 10, "flat_payout": 1, "flat_promotional_points": null, "dynamic_display_type": null, "dynamic_points": null, "dynamic_payout": null, "dynamic_promotional_points": null, "time_played": { "id": 996, "goal_unit": "MINUTES", "goal_unit_count": 6 }, "multiple_conversions_allowed": true, "multiple_conversions_rules": { "rule_type": "UNLIMITED", "x_conversions": null, "every_y_seconds": null } } ], "total_points": 10, "total_promotional_points": null, "epc": "0.00", "funnel_id": "01JKBMPR5QYT91EGGV1R62DB2W", "rank": 1, "roas_goals": [ { "day": 7, "goal": 1.33, "roas": 0.89 } ], "roas": [ { "day": 7, "goal": 1.33, "roas": 0.89 } ], } ] } ``` #### Offer Event Types The following table shows the list of offer event type ids that can be retrieved in the API: | ID | Type | | ---- | ------------------------ | | 1 | Install | | 2 | Event | | 3 | Purchase | | 4 | Dynamic Event: Adjust | | 5 | Dynamic Event: Playtime | | 6 | Dynamic Event: AppsFlyer | | NULL | N/A | ### Response Meta The response retrieves a meta object containing miscellaneous information about the endpoint such as warnings, total count, etc. #### Warnings The following is a list of warnings retrieved in the endpoint: | Name | Description | | -------------- | --------------------------------------------------------------------------- | | private\_relay | Returns true or false indicating if the user is using iCloud Private Relay. | **Sample Response** ```json { "data": [ // ... ], "meta": { "warnings": { "private_relay": true } } } ``` # Get Offers By Ids Gets the available information for the provided offer IDs, including interaction history. Returns offers for the provided offer IDs. Offers with interaction history (click and conversions) will include `history` keys with the same history fields as in the "Get History" endpoint. If offers have no history, the `history` values will be null. If offers have no history and are also not available for the end user to interact with, they will be included in the `unavailable_offers` section with a reason code. Offers that have clicks are still eligible to be clicked again, and thus have a `click_url`. Offers that cannot be clicked will have a `null` click URL. **Method:** GET\ **Base URL:** [**https://api.adgatemedia.com/v1/user-based-api/offers-by-ids**](https://api.adgatemedia.com/v1/user-based-api/offers-by-ids) ### Required Query Parameters
ParameterDescriptionTypeExample
aff_idYour affiliate ID. Can be found on the Offers API page.Any Integer60000
api_keyYour API key. Can be found on the Offers API page.Any String941bd1fecf7e6596823b895e04df3a0c
wall_codeWall code that can be found on the AdGate Rewards pageStringnQug
user_idThe affiliate's user ID. Max length 255 bytesStringuser12345
ipIP v4 or v6. Used to target offers geographically.String127.0.0.1
user_agentThe end-user's user agent, used for device targeting.String
Mozilla/5.0 (Windows NT 6.1; Win64; x64; rv:47.0) Gecko/20100101 Firefox/47.0
offer_idsA comma-separated list of offer IDs to getString123,456,789
### Optional Parameters
ParameterDescriptionTypeExample
rank_methodOne of "cpm" or "cr". Determines how the rank field will be calculated.Stringcpm
s2
s3
s4
s5		Four available subIDs the affiliate can pass to us. We will return them in the affiliate's postback.String
langThe language as provided by the browser (from Accept-Language HTTP header). Defaults to English if not provided.String
en-US,en;q=0.5
override_w2m_devicesA list of the devices the user owns separated by commas. You may use this instead of posting devices to the Devices endpoint. Allowed values are "iphone", "ipad", and "android". Only used if user_agent is a desktop device.Stringiphone,android
### Response The response will contain two arrays: `offers` and `unavailable_offers` Each record in `offers` will contain the following fields: | Field | Note | Type | Example | | ------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | id | Offer ID | int | 341022 | | anchor | Offer title to display to users | string | Playstation 5 | | things\_to\_know | Offer information that can be presented as a bullet-point list | array | \[ "Enter to win a Playstation 5!", "You must click “Allow” if tracking permission is requested within the app." ] | | session\_hours | Offer is valid for that many hours | int | 720 | | offer\_expires\_at | Offer expiration timestamp | int | 1741370828 | | requirements | What the user should do to complete an offer | string | Sign up with valid information and complete the full survey. | | description | Description to display to the user | string | Enter to win a Playstation 5! | | disclaimer | A field to display with each offer. Replace the ${sitename} macro yourself. | string | This offer is presented to you by ${sitename} on behalf of a third party merchant | | product\_id | A unique string shared between offers which belong to same product, e.g. same mobile app. | string | 01JEEDPNV72ZX4FFY81K2HSSTC | | product\_name | The offer's product name | string | Product #1 | | confirmation\_time | Text that described how long it takes to receive credit | string | Confirms Instantly | | creatives | Links to offer creatives | object | | | creatives.images | Links to offer images | object | { "275x275": "", "400x400": " | | pending\_time | Time in minutes that a reward will be held from the user following completion | int | 60 | | mobile\_verification\_required | Whether the end user needs to verify their mobile phone number | bool | false | | web2mobile | Whether this offer must be accessed on the user's mobile device. You must send us the devices the user owns via the \[POST devices] endpoints. If no devices are stored, web2mobile offers will not be returned. | bool | FALSE | | web2mobile\_devices | Array of devices the users must access the user on. NULL if not a web2mobile offer. The list of applicable devices is taken from the devices stored for that particular user (see the other devices API endpoint) | array\|null | \["iphone", "ipad"] | | app\_metadata.app\_id | App ID on the mobile app store. It can be either App Store or Google Play Store app ID. | string\|null | 1596736236 | | app\_metadata.categories | An array of app metadata categories. | array\|null | \["Games", "Casual", "Puzzle"] | | app\_metadata.screenshot\_urls | An array of app metadata screenshot URLs. | array\|null | \[""] | | app\_metadata.video\_urls | An array of app metadata video URLs. | array\|null | \[""] | | is\_game | Whether the offer is a game offer | bool | FALSE | | click\_url | URL to redirect the user to | string | | | support\_url | URL of the support form for this offer | string | | | impression\_url | URL to notify that the offer was viewed | string | | | icon\_url | Square icon URL | string | | | categories | Offer categories | array | \[ "CPI", "iPad", "iPhone" ] | | total\_points | Total points the user may earn | float | 126.72 | | total\_points\_promotional | If a promotion is currently in progress, the amount of points they will earn. If not null, this should be used instead of total\_points. | float\|null | 187.9 | | sticky | If an offer should be pinned to the top of the offer wall | bool | TRUE | | rank | The rank of the offer according to the "rank\_method" requested | int | 1 | | history | End user history of interactions with this offer | object\|null | | | history.completed\_events | Number of completed events | int | 1 | | history.continue\_url | URL to the offer | string | | | history.has\_pending\_conversions | Are there pending conversions? | bool | false | | history.latest\_date | Timestamp of the latest click or conversion | int | 1738615121 | | history.completed | Is offer completed? | bool | false | | history.next\_event | UUID of the next event for the user to complete | string | 8bf0cf49-2f9c-4051-a2a7-9704a15731f3 | | history.next\_payable\_event | UUID of the next event for the user to complete | string | dee3fea7-3c18-4dc3-9b71-021528be51d0 | | history.total\_approved\_events | | int | 1 | | history.total\_approved\_points | | float | 70 | | history.total\_cancelled\_events | | int | 0 | | history.total\_cancelled\_points | | float | 0 | | history.total\_pending\_events | | int | 0 | | history.total\_pending\_points | | float | 0 | | history.hours\_left | How many session hours are left from the first click that has converted. Calculated from session\_hours in Offers endpoints. | int\|null | 720 | | events | An array of events the user may complete to earn points. Each event is an object. | array | \[see below] | | events.#.uuid | ID of the event | string | 0dc43f54-135a-46a4-a51c-a2c5f3cfdac0 | | events.#.name | Event name to display to the user | string | Completed | | events.#.type | "flat" or "dynamic". Flat events have static point values. Dynamic events will have varying payouts. | string | flat | | events.#.payable | Whether the event pays anything to the publisher | bool | TRUE | | events.#.ttc\_minutes | Minutes to complete this event after the click | int | 43200 | | events.#.expires\_at | Timestamp when the event expires | int | 1741370829 | | events.#.flat\_points | Will be 0 if the event is not payable. | float\|null | 126.72 | | events.#.flat\_payout | Will be 0 if the event is not payable. | float\|null | 46.22 | | events.#.flat\_promotional\_points | Points if there is an ongoing promotion | float\|null | 187.9 | | events.#.dynamic\_display\_type |

Either "up\_to" or "commission". This determines how the potential points are displayed.

"up\_to": display "Up to {dynamic points amount}

"commission": display "{dynamic points amount} per ${dynamic payout amount}

| string\|null | up\_to | | events.#.dynamic\_points | Described above | float\|null | 187.9 | | events.#.dynamic\_payout | For "commission", the dollars amount to use in the phrase above | float\|null | 1 | | events.#.dynamic\_promotional\_points | Described above | float\|null | 0 | | events.#.event\_type\_id | ID used to identify the event type | Integer\|null | 1 | | events.#.time\_played | Time played goal associated with the event. | object\|null | | | events.#.time\_played.id | Time played goal id. | integer | 100 | | events.#.time\_played.goal\_unit |

The unit of time that the goal is measured in.

Allowed values are: NANOS, MICROS, MILLIS, SECONDS, MINUTES, HOURS, HALF\_DAYS, DAYS, WEEKS, MONTHS, YEARS, DECADES, CENTURIES, MILLENNIA, ERAS, FOREVER.

| string | DAYS | | events.#.time\_played.goal\_unit\_count | The quantity of goal unit required to complete the goal. | integer | 7 | | events.#.multiple\_conversions\_allowed | Whether this event can be converted multiple times | bool | true | | events.#.multiple\_conversions\_rules | The rules for multiple event conversions | object\|null | | | events.#.multiple\_conversions\_rules.rule\_type | Can be UNLIMITED, TOTAL\_CONVERSIONS or INTERVAL | string | "UNLIMITED" | | events.#.multiple\_conversions\_rules.x\_conversions | Number of conversions allowed | int | 3 | | events.#.multiple\_conversions\_rules.every\_y\_seconds | Only used for INTERVAL type: allows X conversions every Y seconds | int | 600 | | events.#.history | End user interaction with this offer event | object\|null | | | events.#.history.pending\_reasons | An array of reasons why conversion for this event is pending | array\|null | | | events.#.history.pending\_reasons.#.reason | Can be PHONE\_VERIFICATION or DELAYED\_OFFER | string | PHONE\_VERIFICATION | | events.#.history.pending\_reasons.#.auto\_accept\_in\_days | In how many days this pending reason will be auto-resolved or auto-rejected | float | 1 | | events.#.history.pending\_reasons.#.auto\_accept\_in\_hours | In how many hours this pending reason will be auto-resolved or auto-rejected | float | 4 | | events.#.history.pending\_reasons.#.auto\_accept\_in\_minutes | In how many minutes this pending reason will be auto-resolved or auto-rejected | float | 240 | | events.#.history.minutes\_left | How many minutes are left to complete this offer event | float | 40700.21 | | events.#.history.approved\_conversions | | int | 1 | | events.#.history.approved\_points | | float | 65 | | events.#.history.cancelled\_conversions | | int | 0 | | events.#.history.cancelled\_points | | float | 0 | | events.#.history.pending\_conversions | | int | 0 | | events.#.history.pending\_points | | float | 0 | | events.#.history.status | Can be "viewed", "pending", "completed" or "cancelled" | string | "viewed" | | mmp | The MMP this offer uses for tracking | string | "adjust" | | viewed\_timestamp | The timestamp when a member has clicked the offer but not installed (first offer click). | int | 12345678900 | | roas\_goals | Offer-level ROAS: one object per configured cohort day that we support, with goal vs observed ROAS for the offer network-wide. | array |

"roas\_goals": \[
{
"day": 7,
"goal": 1.33,
"roas": 0.89
}
]

| | roas | Offer + affiliate (wall) level: same cohort idea, but scoped to this wall’s / affiliate’s traffic on the offer. Same object shape as roas\_goals. | array |

"roas": \[
{
"day": 7,
"goal": 1.33,
"roas": 0.89
}
]

| Each record in `unavailable_offers` will contain the following fields:
FieldNoteTypeExample
offer_idOffer IDint341011
unavailable_reasonsAn array of reasons why this offer is not availablearray
unavailable_reasons.#.reasonstring"This device or browser is not allowed"
unavailable_reasons.#.codeint2067
#### Sample Response ```json { "data": { "offers": [ { "id": 1666154, "product_id": "01JEEEBHSK572BWPQC0AYQZF30", "product_name": "Product #1", "funnel_id": "01JKBMR540THT79JAE488Q5754", "session_hours": 720, "offer_expires_at": 1741370875, "confirmation_time": "Confirms in 29 days 9 hours", "pending_time": 42300, "anchor": "Unblock Traffic Puzzle", "things_to_know": [ "First Time Users", "Complete all the events mentioned", "Complete in 30 days" ], "requirements": "First Time Users. Complete all the events mentioned. Complete in 30 days", "description": "Get ready for Unblock Traffic Puzzle – the ultimate brain-teaser where you free cars from jam-packed parking lots! Slide vehicles strategically to clear the path for the red car.", "disclaimer": "*Points will appear as Pending for 30 days. Each person may redeem this offer only ONCE (1 time). This offer is presented to you by ${sitename} on behalf of a third party merchant or sponsor (\"Merchant\"), which advises us when the offer is completed and a reward should be issued. ${sitename} has not evaluated and does not endorse Merchant's views, policies, products or services, which you are encouraged to evaluate for yourself. Have questions? Please contact the ${sitename} Help Center.", "creatives": { "images": { "275x275": "https://my-zone.com/cdn-cgi/image/width=275,height=275/http://dash.agm/storage/jlNex38v.png", "400x400": "https://my-zone.com/cdn-cgi/image/width=400,height=400/http://dash.agm/storage/jlNex38v.png", "580x580": "https://my-zone.com/cdn-cgi/image/width=580,height=580/http://dash.agm/storage/jlNex38v.png", "600x300": "https://my-zone.com/cdn-cgi/image/width=600,height=300/http://dash.agm/storage/iUNZPzll.png", "630x315": "https://my-zone.com/cdn-cgi/image/width=630,height=315/http://dash.agm/storage/iUNZPzll.png", "120x60": "https://my-zone.com/cdn-cgi/image/width=120,height=60/http://dash.agm/storage/iUNZPzll.png", "600x200": "https://my-zone.com/cdn-cgi/image/width=600,height=200/http://dash.agm/storage/CWGuVinS.png" }, }, "is_game": true, "icon_url": "https://main-p.agmcdn.com/EqGN4bmOFBQLKI1n7mRex7a6NeU6UZuhHxuMHxqO.webp", "support_url": "https://wall12.agm.mobi/offer/contact/nqqYp2g/1666154?s1=smurciac-2797-v2", "sticky": null, "epc": null, "rank": null, "mobile_verification_required": null, "web2mobile": null, "web2mobile_devices": null, "click_url": null, "impression_url": null, "history": { "completed_events": 0, "continue_url": "https://play.google.com/store/apps/details?id=com.newmegames.unblocktrafficpuzzle", "has_pending_conversions": false, "latest_date": 1738615121, "completed": false, "next_event": "8bf0cf49-2f9c-4051-a2a7-9704a15731f3", "next_payable_event": "dee3fea7-3c18-4dc3-9b71-021528be51d0", "total_approved_events": 0, "total_approved_points": 0, "total_cancelled_events": 0, "total_cancelled_points": 0, "total_pending_events": 0, "total_pending_points": 0, "hours_left": 720 }, "mmp": "adjust", "viewed_timestamp": 12345678900, "app_metadata": { "app_id": "com.newmegames.unblocktrafficpuzzle", "categories": [ "GAME_PUZZLE" ], "screenshot_urls": [ "https://play-lh.googleusercontent.com/Zx1YSHxoCQzS7S-bEbtB19i1ivCh9Hs3UTxH27jC_-qYGZxbZAm6Mt4nUp9MxNPz5A=w1052-h592", "https://play-lh.googleusercontent.com/uD2p8T0RoYXZX56Dojllg_cnt8uStZBhZCV_6ps78xj0W5MTXH9DZrrdVAqh1EB1q-4=w1052-h592", "https://play-lh.googleusercontent.com/cdA_JAY-tg75MgMxMnk8NBPRZ6SCSQNaj1toBlpu6dlTQR47ctJp4TBVs1ydRU1yEc8=w1052-h592", "https://play-lh.googleusercontent.com/_iA9JksfhKOsU1kO08V6AB7BQlyVWgBt-Iyzeci7cUSyo7JPDcxpJ9Vv8eJ6-jKnOA=w1052-h592" ], "video_urls": [] }, "categories": [ "Android", "CPE", "Free" ], "total_points": 147, "total_promotional_points": null, "events": [ { "uuid": "8bf0cf49-2f9c-4051-a2a7-9704a15731f3", "name": "Play the game!", "type": "flat", "event_type_id": null, "payable": false, "ttc_minutes": null, "expires_at": null, "multiple_conversions_allowed": false, "multiple_conversions_rules": null, "flat_points": 0, "flat_payout": 0, "flat_promotional_points": null, "dynamic_display_type": null, "dynamic_points": null, "dynamic_payout": null, "dynamic_promotional_points": null, "time_played": null, "history": { "pending_reasons": null, "minutes_left": null, "approved_conversions": 0, "approved_points": 0, "cancelled_conversions": 0, "cancelled_points": 0, "pending_conversions": 0, "pending_points": 0, "status": "viewed" } }, { "uuid": "dee3fea7-3c18-4dc3-9b71-021528be51d0", "name": "Complete Rank 8. Complete within 1 week", "type": "flat", "event_type_id": null, "payable": true, "ttc_minutes": 10080, "expires_at": 1739219921, "multiple_conversions_allowed": false, "multiple_conversions_rules": null, "flat_points": 6, "flat_payout": 0.63, "flat_promotional_points": null, "dynamic_display_type": null, "dynamic_points": null, "dynamic_payout": null, "dynamic_promotional_points": null, "time_played": null, "history": { "pending_reasons": null, "minutes_left": 7350.765516783334, "approved_conversions": 0, "approved_points": 0, "cancelled_conversions": 0, "cancelled_points": 0, "pending_conversions": 0, "pending_points": 0, "status": "viewed" } }, { "uuid": "e9e572e9-78d3-4c31-a0d5-18c366c781c9", "name": "Complete Rank 20. Complete within 1 week", "type": "flat", "event_type_id": null, "payable": true, "ttc_minutes": 10080, "expires_at": 1739219921, "multiple_conversions_allowed": false, "multiple_conversions_rules": null, "flat_points": 8, "flat_payout": 0.85, "flat_promotional_points": null, "dynamic_display_type": null, "dynamic_points": null, "dynamic_payout": null, "dynamic_promotional_points": null, "time_played": null, "history": { "pending_reasons": null, "minutes_left": 7350.7655043, "approved_conversions": 0, "approved_points": 0, "cancelled_conversions": 0, "cancelled_points": 0, "pending_conversions": 0, "pending_points": 0, "status": "viewed" } }, { "uuid": "8a7c6aaf-948c-49bf-be2b-ae744a4a7e32", "name": "Complete Rank 40. Complete within 1 month 2 days", "type": "flat", "event_type_id": null, "payable": true, "ttc_minutes": 43200, "expires_at": 1741207121, "multiple_conversions_allowed": false, "multiple_conversions_rules": null, "flat_points": 33, "flat_payout": 3.35, "flat_promotional_points": null, "dynamic_display_type": null, "dynamic_points": null, "dynamic_payout": null, "dynamic_promotional_points": null, "time_played": null, "history": { "pending_reasons": null, "minutes_left": 40470.76549773334, "approved_conversions": 0, "approved_points": 0, "cancelled_conversions": 0, "cancelled_points": 0, "pending_conversions": 0, "pending_points": 0, "status": "viewed" } }, { "uuid": "098748ea-fef2-4561-a69c-d16bc4252a21", "name": "Complete Rank 50. Complete within 1 month 2 days", "type": "flat", "event_type_id": null, "payable": true, "ttc_minutes": 43200, "expires_at": 1741207121, "multiple_conversions_allowed": false, "multiple_conversions_rules": null, "flat_points": 100, "flat_payout": 10, "flat_promotional_points": null, "dynamic_display_type": null, "dynamic_points": null, "dynamic_payout": null, "dynamic_promotional_points": null, "time_played": null, "history": { "pending_reasons": null, "minutes_left": 40470.76549113333, "approved_conversions": 0, "approved_points": 0, "cancelled_conversions": 0, "cancelled_points": 0, "pending_conversions": 0, "pending_points": 0, "status": "viewed" } } ], "roas_goals": [ { "day": 7, "goal": 1.33, "roas": 0.89 } ], "roas": [ { "day": 7, "goal": 1.33, "roas": 0.89 } ], } ], "unavailable_offers": [ { "offer_id": 1375646, "unavailable_reasons": [ { "reason": "This device or browser is not allowed [2067]", "code": 2067 } ] }, { "offer_id": 1676274, "unavailable_reasons": [ { "reason": "Offer is inactive [2054]", "code": 2054 } ] } ] } } ``` #### Offer Event Types The following table shows the list of offer event type ids that can be retrieved in the API: | ID | Type | | ---- | ------------------------ | | 1 | Install | | 2 | Event | | 3 | Purchase | | 4 | Dynamic Event: Adjust | | 5 | Dynamic Event: Playtime | | 6 | Dynamic Event: AppsFlyer | | NULL | N/A | ### Response Meta The response retrieves a meta object containing miscellaneous information about the endpoint such as warnings, total count, etc. #### Warnings The following is a list of warnings retrieved in the endpoint: | Name | Description | | -------------- | --------------------------------------------------------------------------- | | private\_relay | Returns true or false indicating if the user is using iCloud Private Relay. | **Sample Response** ```json { "data": [ // ... ], "meta": { "warnings": { "private_relay": true } } } ``` # Post Devices If a user owns a mobile device, call this endpoint to store the devices. If provided, desktop users will be able to see available mobile offers. **Method:** POST\ **Base URL:** [**https://api.adgatemedia.com/v1/user-based-api/devices**](https://api.adgatemedia.com/v1/user-based-api/devices) ### Required Query Parameters | Parameter | Description | Type | Example | | ---------- | ---------------------------------------------------------------------------------------------------------------- | ----------- | ---------------------------------- | | aff\_id | Your affiliate ID. Can be found on the [Offers API page](http://panel.adgatemedia.com/affiliate/api/keys). | Any Integer | `60000` | | api\_key | Your API key. Can be found on the [Offers API page](http://panel.adgatemedia.com/affiliate/api/keys). | Any String | `941bd1fecf7e6596823b895e04df3a0c` | | wall\_code | Wall code that can be found on the [AdGate Rewards page](https://panel.adgatemedia.com/affiliate/vc-walls/index) | String | `nQug` | | user\_id | The affiliate's user ID. Max length 255 bytes | String | `user12345` | ### Required JSON Body Parameters | Field | Note | Type | Example | | ------- | ------------------------------------------------------------------------------------------------------------------ | ----- | ------------------------------- | | devices | An array that any combination of `iphone`, `ipad`, or `android`. Provide an empty array to clear existing devices. | array | `["iphone", "ipad", "android"]` | ### Response The response will contain the list of user devices after the update. #### Sample Response ``` { "data": { "devices": [ "android" ] } } ``` # Get History API endpoint to fetch user history. It returns a list of all offers the user has interacted with, and how many points were earned for each one. Use the "Get Offer History" API endpoint to get more details about each offer. **Method:** GET\ **Base URL:** [**https://api.adgatemedia.com/v1/user-based-api/history**](https://api.adgatemedia.com/v1/user-based-api/history) ### Required Query Parameters | Parameter | Description | Type | Example | | ---------- | ---------------------------------------------------------------------------------------------------------------- | ----------- | ---------------------------------- | | aff\_id | Your affiliate ID. Can be found on the [Offers API page](http://panel.adgatemedia.com/affiliate/api/keys). | Any Integer | `60000` | | api\_key | Your API key. Can be found on the [Offers API page](http://panel.adgatemedia.com/affiliate/api/keys). | Any String | `941bd1fecf7e6596823b895e04df3a0c` | | wall\_code | Wall code that can be found on the [AdGate Rewards page](https://panel.adgatemedia.com/affiliate/vc-walls/index) | String | `nQug` | | user\_id | The affiliate's user ID. Max length 255 bytes | String | `user12345` | ### Optional Query Parameters
ParameterDescriptionTypeExample
ParameterDescriptionTypeExample
langThe language as provided by the browser (from Accept-Language HTTP header). Defaults to English if not provided.String
en-US,en;q=0.5
continue_playingA special boolean flag that can be used to retrieve the offers for "Continue Playing" section.Booltrue
offer_idsA comma-separated list of integer offer IDs to filter by.String1477425,148199
### Response An array of records will be returned on success. Each record will have the following fields: | Field | Note | Type | Example | | ------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | offer\_id | The offer's unique identifier on AdGate Media's dashboard. | integer | 360819 | | product\_id | A unique string shared between offers which belong to same product, e.g. same mobile app. | string | JEEDPNV72ZX4FFY81K2HSSTC | | product\_name | The offer's product name | string | Product #1 | | anchor | The title of the offer as it is displayed to the user. | string | Opinion Labs | | description | Description to display to the user | string | Answer some profile questions about yourself and our system will determine if the selected survey is a good fit based on your answers. Complete surveys honestly and completely. Get paid for your efforts through your favorite rewards platform. | | requirements | What the user should do to complete an offer | string | Enter your profile information and complete one survey from the available options. Fake information will not be credited. Can be completed multiple times. | | disclaimer | A field to display with each offer. Replace the ${sitename} macro yourself. | string | This offer is presented to you by ${sitename} on behalf of a third party merchant | | confirmation\_time | Confirmation time. | string | Confirms Instantly | | categories | An array of the category names that the offer belongs to. | array | \["Free", "Surveys", "CPA"] | | icon\_url | Square image to display to the user. | string | | | app\_metadata.app\_id | App ID on the mobile app store. It can be either App Store or Google Play Store app ID. | string\|null | 1596736236 | | app\_metadata.categories | An array of app metadata categories. | array\|null | \["Games", "Casual", "Puzzle"] | | app\_metadata.screenshot\_urls | An array of app metadata screenshot URLs. | array\|null | \[""] | | app\_metadata.video\_urls | An array of app metadata video URLs. | array\|null | \[""] | | continue\_url | URL to redirect the user to | string | | | latest\_date | Date of the latest click or conversions | timestamp | 1676040060 | | points | Total points earned by the user for this offer. This does not include any points that are pending. | float | 300.02 | | completed\_events | Total number of events that the user has completed for this offer. | integer | 1 | | completed | Whether all events have been completed on the offer. Can be used to display the offer in a "Completed" section. | bool | false | | total\_points | Total number of points earnable on the offer. | float | 100 | | total\_promotional\_points | Total number of promotional points earnable on the offer. | float\|null | | | total\_approved\_points | Sum of approved event points. | float | 0 | | total\_pending\_points | Sum of pending event points. | float | 0 | | total\_cancelled\_points | Sum of charged back event points. | float | 0 | | total\_events | Total number of visible events. | int | 1 | | total\_approved\_events | Total number of events approved, including non payable. | int | 0 | | total\_pending\_events | Total number of events pending, including non payable. | int | 0 | | total\_cancelled\_events | Total number of events charged back, including non payable. | int | 0 | | tx\_id | The primary transaction ID, or click ID, associated with this offer. | string | 12972967ae33a42154a0794dc3801866a | | has\_pending\_conversions | If the offer has pending conversions | bool | false | | contact\_url | Link to the contact page | string | | | next\_event | ID of the next event that the user can complete, including non-payable events. | string\|null | 0dc43f54-135a-46a4-a51c-a2c5f3cfdac0 | | next\_payable\_event | ID of the next payable event that the user can complete. | string\|null | 0dc43f54-135a-46a4-a51c-a2c5f3cfdac0 | | hours\_left | How many session hours are left from the first click that has converted. Calculated from session\_hours in Offers endpoints. | int\|null | 720 | | events | An array of events the user may complete to earn points. Each event is an object. | array | | | events.#.uuid | ID of the event | string | 0dc43f54-135a-46a4-a51c-a2c5f3cfdac0 | | events.#.name | Event name to display to the user | string | Completed | | events.#.type | "flat" or "dynamic". Flat events have static point values. Dynamic events will have varying payouts. | string | flat | | events.#.multiple\_conversions\_allowed | Whether the user is allowed to complete the event multiple times. | bool | true | | events.#.multiple\_conversions\_rules | The rules for multiple event conversions | object\|null | | | events.#.multiple\_conversions\_rules.rule\_type | Can be UNLIMITED, TOTAL\_CONVERSIONS or INTERVAL | string | "UNLIMITED" | | events.#.multiple\_conversions\_rules.x\_conversions | Number of conversions allowed | int | 3 | | events.#.multiple\_conversions\_rules.every\_y\_seconds | Only used for INTERVAL type: allows X conversions every Y seconds | int | 600 | | events.#.payable | Whether the event pays anything to the user | bool | true | | events.#.status | One of the following: 'viewed', 'pending', 'completed', 'cancelled' | string | viewed | | events.#.expires\_at | If there is a time limit for this event, this contains the unix timestamp when the event expires. | int\|null | 1738598535 | | events.#.minutes\_left | If there is a time limit for this event, this contains the minutes remaining. | float\|null | 67.1 | | events.#.flat\_points | The number of points the user was promised to be rewarded upon completion. Will be 0 if the event is not payable. Will be null if the event is a dynamic payout type. | float\|null | 126.72 | | events.#.flat\_promotional\_points | The number of promotional points the user was promised to be rewarded upon completion. `null`if there was no promotion. | float\|null | 146.72 | | events.#.flat\_payout | The payout that will be awarded for completing this event. Will be 0 if the event is not payable. | float\|null | 46.22 | | events.#.dynamic\_display\_type |

Either "up\_to" or "commission". This determines how the potential points are displayed.

"up\_to": display "Up to {dynamic points amount}

"commission": display "{dynamic points amount} per ${dynamic payout amount}

| string\|null | up\_to | | events.#.dynamic\_points |

Amount of dynamic points promised to the user per the {payout} below.

Example: "Earn {promised\_dynamic\_points} per ${promised\_dynamic\_payout}" -- "Earn 100 points per $1".

| float\|null | 187.9 | | events.#.dynamic\_promotional\_points | Amount of promotional dynamic points promised to the user per the {payout} below. `null`if there was no promotion. | | | | events.#.dynamic\_payout | The dollar amount to display for dynamic display. Example: "Earn {promised\_dynamic\_points} per ${promised\_dynamic\_payout}" -- "Earn 100 points per $1". | float\|null | 0.1 | | events.#.approved\_conversions | How many approved (payable) conversions there are. | int | 0 | | events.#.approved\_points | How many approved (payable) points there are. | float\|null | 0 | | events.#.pending\_conversions | How many conversions are pending | int | 0 | | events.#.pending\_points | How many points are pending. | float\|null | 0 | | events.#.event\_type\_id | ID used to identify the event type. See bottom of this page for the complete list. | int\|null | 1 | | events.#.time\_played | Time played goal associated with the event. | object\|null | | | events.#.time\_played.id | Time played goal id. | int | 100 | | events.#.time\_played.goal\_unit |

The unit of time that the goal is measured in.

Allowed values are: NANOS, MICROS, MILLIS, SECONDS, MINUTES, HOURS, HALF\_DAYS, DAYS, WEEKS, MONTHS, YEARS, DECADES, CENTURIES, MILLENNIA, ERAS, FOREVER.

| string | DAYS | | events.#.time\_played.goal\_unit\_count | The quantity of goal unit required to complete the goal. | int | 7 | | events.#.timestamp | The UNIX timestamp of the last conversion, if any. | int\|null | 1234567890 | | creatives | Links to offer creatives | object | | | creatives.images | Links to offer images | object | { "275x275": "", "400x400": " | | is\_game | Whether the offer is a game offer. | bool | FALSE | | started\_on | The UNIX timestamp of the first click. | int | 1234567890 | | things\_to\_know | An extra requirement to offers. | array\ | \["You must click \\"Allow\” if tracking permission is requested within the app."] | | hours\_left | The number of hours left to convert any offer event. | integer\|null | 1 | | operating\_systems | OS information | object | | | operating\_systems.min\_os\_version | Min OS version | string | 10 | | operating\_systems.max\_os\_version | Max OS version | string | 10.2 | | operating\_systems.operating\_system | OS name | string | "ios" | #### Sample Response ```json { "data": [ { "offer_id": 360819, "product_id": "01JEEEBHSK572BWPQC0AYQZF30", "product_name": "Product #1", "icon_url": "https://main-p.agmcdn.com/offers/1613580417599.gif", "anchor": "Opinion Labs", "latest_date": 1676040060, "points": 0, "completed_events": 0, "completed": false, "total_points": 100, "total_promotional_points": null, "total_approved_points": 0, "total_pending_points": 0, "total_cancelled_points": 0, "total_events": 0, "total_approved_events": 0, "total_pending_events": 0, "total_cancelled_events": 0, "tx_id": "12972967ae33a42154a0794dc3801866a", "events": [ { "uuid": "7731b964-845d-46f1-8028-10b892ee8a67", "name": "Completed", "type": "flat", "payable": true, "event_type_id": 1, "flat_points": 490, "flat_payout": 4.9, "flat_promotional_points": null, "dynamic_display_type": null, "dynamic_points": null, "dynamic_payout": null, "dynamic_promotional_points": null, "approved_points": 0, "approved_conversions": 0, "pending_points": 0, "pending_conversions": 0, "cancelled_points": 0, "cancelled_conversions": 0, "status": "viewed", "timestamp": 12345567890 } ], "operating_systems": [ { "max_os_version": null, "min_os_version": null, "operating_system": "ios" } ], "next_event": "7731b964-845d-46f1-8028-10b892ee8a67", "next_payable_event": "7731b964-845d-46f1-8028-10b892ee8a67", "description": "Answer some profile questions about yourself and our system will determine if the selected survey is a good fit based on your answers. Complete surveys honestly and completely. Get paid for your efforts through your favorite rewards platform.", "requirements": "Enter your profile information and complete one survey from the available options. Fake information will not be credited. Can be completed multiple times.", "disclaimer": "This offer is presented to you by ${sitename} on behalf of a third party merchant", "confirmation_time": "Confirms Instantly", "categories": [ "Free", "Surveys", "CPA" ], "creatives": { "images": { "275x275": "https://my-zone.com/cdn-cgi/image/width=275,height=275/http://dash.agm/storage/jlNex38v.png", "400x400": "https://my-zone.com/cdn-cgi/image/width=400,height=400/http://dash.agm/storage/jlNex38v.png", "580x580": "https://my-zone.com/cdn-cgi/image/width=580,height=580/http://dash.agm/storage/jlNex38v.png", "600x300": "https://my-zone.com/cdn-cgi/image/width=600,height=300/http://dash.agm/storage/iUNZPzll.png", "630x315": "https://my-zone.com/cdn-cgi/image/width=630,height=315/http://dash.agm/storage/iUNZPzll.png", "120x60": "https://my-zone.com/cdn-cgi/image/width=120,height=60/http://dash.agm/storage/iUNZPzll.png", "600x200": "https://my-zone.com/cdn-cgi/image/width=600,height=200/http://dash.agm/storage/CWGuVinS.png" }, }, "contact_url": "https://adgaterewards.com/contact/nQ/user12345/360819", "continue_url": "ttps://seek.gg/vc/nQ/users/testing-prodege/offers/360819?source_type=live_offer_api", "has_pending_conversions": false, "hours_left": 720, "is_game": false, "started_on": 12345567890, "hours_left": 1, "things_to_know": [ "You must click \“Allow\” if tracking permission is requested within the app." ], } ] } ``` #### Offer Event Types The following table shows the list of offer event type ids that can be retrieved in the API: | ID | Type | | ---- | ------------------------ | | 1 | Install | | 2 | Event | | 3 | Purchase | | 4 | Dynamic Event: Adjust | | 5 | Dynamic Event: Playtime | | 6 | Dynamic Event: AppsFlyer | | NULL | N/A | # Store Mobile Advertising Id This endpoint stores the Mobile Advertising ID (GAID for Android or IDFA for iOS) for a new user in the system.\ By collecting this identifier, AdGate Media can: * Exclude offers the user has already installed. * Improve offer targeting to increase engagement and conversion rates. **Method:** POST\ **Base URL:** [**https://api.adgatemedia.com/v1/user-based-api/store-maid**](https://api.adgatemedia.com/v1/user-based-api/store-maid) ### **Request Parameters** | Parameter | Description | Type | Required | | ----------- | --------------------------------------------------------- | ------- | -------- | | `aff_id` | Your affiliate ID. Can be found on the Offers API page. | Integer | Yes | | `api_key` | Your API key. Can be found on the Offers API page. | String | Yes | | `wall_code` | Wall code that can be found on the AdGate Rewards page. | String | Yes | | `user_id` | The affiliate's unique user ID (max length 255 bytes). | String | Yes | | `MAID` | The device’s Mobile Advertising ID (GAID or IDFA). | String | Yes | | `type` | The type of ID provided. Accepted values: `gaid`, `idfa`. | String | Yes | # Get Offer History - DEPRECATED API endpoint to fetch historical details for a specific offer. Use it to get the status of each offer event. {% hint style="danger" %} **This endpoint is deprecated and will no longer be updated. Please use the "Get History" endpoint with the \`offer\_ids\` filter instead.** {% endhint %} **Method:** GET\ **Base URL:** [**https://api.adgatemedia.com/v1/user-based-api/offer-history**](https://api.adgatemedia.com/v1/user-based-api/offer-history) ### Required Query Parameters | Parameter | Description | Type | Example | | ---------- | ---------------------------------------------------------------------------------------------------------------- | ----------- | ---------------------------------- | | aff\_id | Your affiliate ID. Can be found on the [Offers API page](http://panel.adgatemedia.com/affiliate/api/keys). | Any Integer | `60000` | | api\_key | Your API key. Can be found on the [Offers API page](http://panel.adgatemedia.com/affiliate/api/keys). | Any String | `941bd1fecf7e6596823b895e04df3a0c` | | wall\_code | Wall code that can be found on the [AdGate Rewards page](https://panel.adgatemedia.com/affiliate/vc-walls/index) | String | `nQug` | | user\_id | The affiliate's user ID. Max length 255 bytes | String | `user12345` | | offer\_id | The ID of the offer | Integer | `12345` | ### Optional Query Parameters
ParameterDescriptionTypeExample
langThe language as provided by the browser (from Accept-Language HTTP header). Defaults to English if not provided.String
en-US,en;q=0.5
### Response
FieldNoteTypeExample
offer_idOffer IDint341022
anchorOffer title to display to usersstringPlaystation 5
descriptionDescription to display to the userstringEnter to win a Playstation 5!
requirementsWhat the user should do to complete an offerstringSign up with valid information and complete the full survey.
disclaimerA field to display with each offer. Replace the ${sitename} macro yourself.stringThis offer is presented to you by ${sitename} on behalf of a third party merchant
icon_urlSquare icon URLstringhttps://main-p.agmcdn.com/offers/1639000851514.jpg
contact_urlLink to the contact pagestringhttps://seek.gg/contact/nQ/testing-prodege/360819
continue_urlURL to redirect the user tostringttps://seek.gg/vc/nQ/users/testing-prodege/offers/360819?source_type=live_offer_api
started_onThe unix timestamp of the first clickint1676040060
app_metadata.app_idApp ID on the mobile app store. It can be either App Store or Google Play Store app ID.string|null1596736236
app_metadata.categoriesAn array of app metadata categories.array|null["Games", "Casual", "Puzzle"]
app_metadata.screenshot_urlsAn array of app metadata screenshot URLs.array|null["https://is1-ssl.mzstatic.com/image/thumb/Purple126/v4/39/88/3a/39883ae6-4f45-9879-c849-aedb4d5ab40c/2e706b4c-baf0-456b-ad67-81db322f75a8_CLASSIC22_202203_2688x1242_Screenshots_01_en-US.png/643x0w.png"]
app_metadata.video_urlsAn array of app metadata video URLs.array|null["https://play.google.com/video/lava/web/player/yt:movie:dSg_iqQpKYA?autoplay=1&authuser=0&embed=play"]
eventsAn array of events the user may complete to earn points. Each event is an object.array[see below]
events.#.uuidID of the eventstring0dc43f54-135a-46a4-a51c-a2c5f3cfdac0
events.#.nameEvent name to display to the userstringCompleted
events.#.type"flat" or "dynamic". Flat events have static point values. Dynamic events will have varying payouts.stringflat
events.#.multiple_conversions_allowedWhether the user is allowed to complete the event multiple times.boolFALSE
events.#.payableWhether the event pays anything to the userboolTRUE
events.#.statusOne of the following: 'viewed', 'pending', 'completed', 'cancelled'stringviewed
events.#.timestampThe unix timestamp of the last conversion, if anyint|null1672242051
events.#.promised_flat_pointsThe number of points the user will be rewarded upon completion. Will be 0 if the event is not payable. Will be null if the event is a dynamic payout type.float|null126.72
events.#.promised_flat_payoutThe payout that will be awarded for completing this event. Will be 0 if the event is not payable.float|null46.22
events.#.dynamic_display_typeEither "up_to" or "commission". This determines how the potential points are displayed.string|nullup_to
"up_to": display "Up to {dynamic points amount}
"commission": display "{dynamic points amount} per ${dynamic payout amount}
events.#.promised_dynamic_pointsAmount of dynamic points promised to the user per the {payout} below. Example: "Earn {promised_dynamic_points} per ${promised_dynamic_payout}" -- "Earn 100 points per $1".float|null187.9
events.#.promised_dynamic_payoutThe dollar amount to display for dynamic display. Example: "Earn {promised_dynamic_points} per ${promised_dynamic_payout}" -- "Earn 100 points per $1".float|null0.1
events.#.approved_conversionsHow many approved (payable) conversions there are.int0
events.#.approved_pointsHow many approved (payable) points there are.float0
events.#.pending_conversionsHow many conversions are pendingint0
events.#.pending_pointsHow many points are pending.float0
events.#.pending_reasonsExplains, in text, why the event is in "pending" status.stringWaiting for phone verification
events.#.event_type_idID used to identify the event typeint|null1
events.#.time_playedTime played goal associated with the event.object|null
events.#.time_played.idTime played goal id.int100
#### Sample Response ```json { "data": { "offer_id": 360819, "anchor": "Opinion Labs", "description": "Answer some profile questions about yourself and our system will determine if the selected survey is a good fit based on your answers. Complete surveys honestly and completely. Get paid for your efforts through your favorite rewards platform. ", "requirements": "Enter your profile information and complete one survey from the available options. Fake information will not be credited. Can be completed multiple times.", "disclaimer": "This offer is presented to you by ${sitename} on behalf of a third party merchant", "icon_url": "https://main-p.agmcdn.com/offers/1613580417599.gif", "events": [ { "uuid": "48097169-5ef7-476a-92ac-869884120096", "name": "Completed", "type": "flat", "multiple_conversions_allowed": true, "approved_conversions": 0, "approved_points": 0, "pending_conversions": 0, "event_type_id": 1, "pending_points": 0, "status": "viewed", "payable": true, "timestamp": null, "pending_reasons": "", "flat_points": 125, "flat_payout": 1.25, "flat_promotional_points": null, "dynamic_display_type": null, "dynamic_points": null, "dynamic_payout": null, "dynamic_promotional_points": null } ], "started_on": 1676040060, "contact_url": "https://adgaterewards.com/contact/nQ/user12345/360819", "continue_url": "ttps://seek.gg/vc/nQ/users/testing-prodege/offers/360819?source_type=live_offer_api" } } ``` #### Offer Event Types The following table shows the list of offer event type ids that can be retrieved in the API: | ID | Type | | ---- | ------------------------ | | 1 | Install | | 2 | Event | | 3 | Purchase | | 4 | Dynamic Event: Adjust | | 5 | Dynamic Event: Playtime | | 6 | Dynamic Event: AppsFlyer | | NULL | N/A | # Offers API (v3) ## Use Case Our offers API allow you to pull offers compatible with virtual currency applications and display them natively on your website or app. This API will return a complete list of offers available on the AdGate Media platform. You will need to store this list within your application and decide which offers to display to your users. It is recommended to get a fresh list of offers every 10 minutes. Please do not use live traffic to request offers; the API should be called periodically from the backend. ## Limitations There are certain features that are available via the AdGate Rewards offer wall that are currently not accessible via the offers API. These include: * A page that displays user history * Access to thousands of market research surveys via the AdGate Rewards routing system Please keep this in mind prior to implementation. ## API **Method:** GET\ **Base URL:** ### Required Parameters | Parameter | Description | Type | Example | | ---------- | ---------------------------------------------------------------------------------------------------------------- | ----------- | ---------------------------------- | | aff | Your affiliate ID. Can be found on the [Offers API page](http://panel.adgatemedia.com/affiliate/api/keys). | Any Integer | `60000` | | api\_key | Your API key. Can be found on the [Offers API page](http://panel.adgatemedia.com/affiliate/api/keys). | Any String | `941bd1fecf7e6596823b895e04df3a0c` | | wall\_code | Wall code that can be found on the [AdGate Rewards page](https://panel.adgatemedia.com/affiliate/vc-walls/index) | String | `nQug` | ### Optional Parameters | Parameter | Description | Type | Example | | ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- | ------------------- | | countries | Filter by specific countries. Accepts a list of comma separated country codes. | String | `gb,us,ca` | | offer | Filter by specific offers. Accepts a list of comma separated offer IDs. | String | `4849,5201,4809` | | paymin | Filter by offers above a minimum payout. Values are in USD. | Decimal | `0.50` | | minepc | Filter by offers above a minimum EPC. Values are in USD. | Decimal | `0.05` | | categories | Filter by offers in certain categories. Accepts a comma separated list of category IDs. Please see the table below for the category ID list. | String | `4,10,11` | | platform | Filter by specific platforms. Accepts a list of comma separated platforms from this list: `desktop`, `smartphone`, `tablet` | String | `smartphone,tablet` | | orderby |

Order results by either payout,epc , or id(offer id) in descending order.

payout is calculated as the maximum payout from the offer's events. Default is epc.

| String | `payout` | | take | Limit the number of results to X. By default all results are returned. | Integer | `200` | | skip | Skips the first X number of results. Useful when combined with limiting (see above). By default, no offers are skipped. | Integer | | #### Category List | Category ID | Category Name | | ----------- | -------------------- | | 1 | Android | | 2 | Downloads | | 3 | Email Submits | | 4 | Free | | 10 | iPad | | 11 | iPhone | | 12 | Lead Gen | | 13 | Credit Card Required | | 14 | Mobile Subscription | | 16 | Surveys | | 17 | Videos | | 18 | CPC | | 19 | Pay Per Call | | 20 | Cash Back | | 21 | CPI | | 22 | CPE | | 23 | CPA | ### Response Note that country abbreviations use the ISO standard, e.g. GB instead of UK. #### Sample Response ```json5 [ { "status": "success", "data": [ { "id": 100677, "name": "Final Fantasy XV iPhone CPE (US) (Incentive)", "product_id": "01JEEDPNV72ZX4FFY81K2HSSTC", "product_name": "Product #1", "anchor": "Final Fantasy XV", "description": "Be the hero of your own Final Fantasy XV adventure in the brand new mobile strategy game Final Fantasy XV!", "requirements": "Install and Reach Citadel level 10.", "pending_time": 60, "translations": { "de": { "anchor": "Final Fantasy XV", "description": "Sei der Held deines eigenen Final Fantasy XV Abenteuers im brandneuen mobilen Strategiespiel Final Fantasy XV!", "requirements": "Installieren und Erreichen der Zitadellebene 10!" } }, "device_targeting": { "browsers": [ {"name": "chrome mobile"} ], "operating_systems": [ { "name": "android", "min_version": "4.4", "max_version": null } ], "devices": [ {"name": "samsung"} ], "platforms": [ {"name": "smartphone"}, {"name": "tablet"} ] }, "geo_targeting": { "countries": [ {"country_code": "US"}, {"country_code": "CA"} ], "states": [ {"geoname_id": 5883102, "name": "Alberta"} ], "cities": [ {"geoname_id": 5913490, "name": "Calgary"} ], "postal_codes": [ {"code": "T1X 0L3"} ] }, "demographic_targeting": { "age": { "exclude": false, "unknown_allowed": false, "options": [ { "min_age": 18, "max_age": 25 }, { "min_age": 60, "max_age": null } ] }, "gender": { "exclude": false, "unknown_allowed": true, "options": [ "male", "female" ] } }, "creatives": { "icon": "" }, "epc": 1.98, "categories": [ "iPhone" ], "events": [ { "id": "a9bf882a-5e06-49de-8cf7-a708ac653636", "name": "install app", "payout_type": "flat", "payout": 1.30, "is_cpc": false, "event_type_id": 1, "multiple_conversions_allowed": false, "translations": { "de": { "label": "App installieren", } }, }, { "id": "68c2dabe-c5f6-4785-9ea2-582fc039fe09", "name": "make an in-app purchase", "payout_type": "flat", "payout": 20, "is_cpc": false, "event_type_id": 2, "multiple_conversions_allowed": true, "multiple_conversions_rules": { "rule_type": "INTERVAL", "x_conversions": 1, "every_y_seconds": 60 }, "translations": { "de": { "label": "einen In-App-Kauf tätigen", } }, } ], "click_url": "", "support_url": "", "preview_url": "", "country_stats": [ { "country_code": "US", "mobile_rank": 1, "desktop_rank": 442 }, { "country_code": "CA", "mobile_rank": 259, "desktop_rank": 189 } ], "session_hours": 720 }, "roas_goals": [ { "day": 7, "goal": 1.33, "roas": 0.89 } ], "roas": [ { "day": 7, "goal": 1.33, "roas": 0.89 } ], ...... ] } ] ``` #### Response Parameters
Key NameDescription
Key NameDescription
idAdGate offer id.
nameAdGate's internal offer name, not to be displayed to end-users.
product_idA unique string shared between offers which belong to same product, e.g. same mobile app.
product_nameThe offer's product name.
anchorOffer title as shown to the end-user.
country_statsMobile and desktop ranks that indicate how well the offer performs compared to other offers within the same country. If API options are provided that filter the results, such as categories or platform, the ranks are calculated within the filtered result set. Note: the ranking algorithm is subject to change in the future. Please allow for gaps in the numeric ranks.
descriptionOffer description.
requirementsOffer requirements. The user must complete these requirements in order to convert.
pending_timeTime in minutes that a reward will be held from the user following completion.
translationsAvailable translations for the offer anchor, description and requirements.
device_targeting
device_targeting.browsers[].name

If present, the offer requires one of the specified browsers.
Possible values are:

  • chrome
  • firefox
  • safari
  • edge
  • internet explorer
  • chrome mobile
  • mobile safari

(More values may be added in the future)

device_targeting.platforms[].name

If present, the offer requires one of the specified platforms.

Possible values are:

  • smartphone
  • tablet
  • desktop

(More values may be added in the future)

device_targeting.devices[].name

If present, the offer requires one of the specified device manufacturers.

Possible values are:

  • samsung

(More values may be added in the future)

device_targeting.device_models[].name

If present, the offer requires one of the specified device models.

Possible values are:

  • iphone
  • ipad

(More values may be added in the future)

device_targeting.operating_systems[].name

If present, the offer requires one of the specified operating systems.

Possible values are:

  • windows
  • mac os
  • ios
  • android

(More values may be added in the future)

device_targeting.operating_systems[].min_versionMinimum version number of the operating system above. If there is no minimum version requirement, this value will be null.
device_targeting.operating_systems[].min_versionMaximum version number of the operating system above. If there is no minimum version requirement, this value will be null.
geo_targeting
geo_targeting.countries[].country_codeThe two-letter country codes this offer is available to. If no countries are provided, all countries are permitted. Use "GB" for the UK.
geo_targeting.states[].geoname_idThe states/regions that the offer is limited to, provided by the geoname ID. You may find a searchable and downloadable database of geoname IDs from https://www.geonames.org/
geo_targeting.states[].nameThe name of the state/region as provided by Geonames.
geo_targeting.cities[].geoname_idThe cities that the offer is limited to, provided by the geoname ID.
geo_targeting.cities[].nameThe name of the city as provided by Geonames.
geo_targeting.postal_codes[].codeThe postal code the offer is limited to.
demographic_targeting.age.excludeWhether to exclude the specified age groups from the targeting.
demographic_targeting.age.unknown_allowedWhether to allow users with unknown or unspecified age.
demographic_targeting.age.options[].min_ageThe minimum age for the range (inclusive).
demographic_targeting.age.options[].max_ageThe maximum age for the range (inclusive).
demographic_targeting.gender.excludeWhether to exclude the specified gender groups from the targeting.
demographic_targeting.gender.unknown_allowedWhether to allow users with unknown or unspecified gender.
demographic_targeting.gender.options[]An array of strings specifying the genders.
creativesObject of key-values representing creatives, such as the offer's icon.
epcNetwork-wide EPCs
categoriesAn array of offer categories (listed above)
eventsAn array of offer events.
event.idUUID of the event
event.nameEvent title
event.payout_typeOne of "flat" or "dynamic". Flat payouts don't change. Dynamic payouts vary. Only 'flat' events are served at the moment.
event.payoutThe dollar amount.
event.is_cpcBoolean. Indicates if the offer event is CPC (cost-per-click).
event.multiple_conversions_allowedBoolean. Indicates if the offer event allows multiple conversions for a single user (IP), according to the rules specified in "multiple_conversions_rules".
event.multiple_conversions_rulesOnly present if "multiple_conversions_allowed" is true. It is an object with the following values:

rule_type: Can be one of "UNLIMITED" or "INTERVAL". "UNLIMITED" means that the offer event can be completed an indefinite amount of times without time limit. "INTERVAL" means the offer event can be completed a certain amount of times in a given amount of time, in the format "allow X conversions every Y seconds".
x_conversions: Integer when the rule type is "INTERVAL", "null" otherwise.
every_y_seconds: Integer when the rule type is "INTERVAL", "null" otherwise.

More attempts than the rule allows will not result in a conversion.
event.event_type_idID used to identify the event type
event.translationsAvailable translations for the event name (label).
click_urlTracking link. The s1 parameter should include the ID of the user accessing the offer. The ID can be any string up to 255 characters long. s2,s3,s4 and s5 subids are available.
support_urlThe URL the user can access to get support in case they are not rewarded. The s1 parameter is required (see click_url above for info.) Note that most offers require waiting at least one hour after clicking an offer to be able to contact support.
preview_urlPreview of the offer's landing page.
app_metadata.app_idApp ID on the mobile app store. It can be either App Store or Google Play Store app ID.
app_metadata.categoriesAn array of app metadata categories.
app_metadata.screenshot_urlsAn array of app metadata screenshot URLs.
app_metadata.video_urlsAn array of app metadata video URLs.
is_gameWhether the offer is a game offer
session_hoursThe maximum number of hours that a user has to complete the offer after clicking it.
roas_goalsOffer-level ROAS: one object per configured cohort day that we support, with goal vs observed ROAS for the offer network-wide.
roasOffer + affiliate (wall) level: same cohort idea, but scoped to this wall’s / affiliate’s traffic on the offer. Same object shape as roas_goals.
#### Offer Event Types The following table shows the list of offer event type ids that can be retrieved in the API: | ID | Type | | ---- | ------------------------ | | 1 | Install | | 2 | Event | | 3 | Purchase | | 4 | Dynamic Event: Adjust | | 5 | Dynamic Event: Playtime | | 6 | Dynamic Event: AppsFluer | | NULL | N/A | # Offers API (v2) ### **WARNING!** This is our old API. Please update to [API v3](/publisher-apis/offers-api) . ## Use Case Our offers API allow you to pull offers compatible with virtual currency applications and display them natively on your website or app. It is recommended to get a fresh list of offers every 10 minutes. Please do not use live traffic to request offers; the API should be called periodically from the backend. ## Limitations There are certain features that are available via the AdGate Rewards offer wall that are currently not accessible via the offers API. These include: * A page that displays user history * Access to offers that are hyper-targeted (state or postal code specific) * Access to thousands of market research surveys via the AdGate Rewards routing system Please keep this in mind prior to implementation. ## API **Method:** GET\ **Base URL:** ### Required Parameters | Parameter | Description | Type | Example | | ---------- | ---------------------------------------------------------------------------------------------------------------- | ----------- | ---------------------------------- | | aff | Your affiliate ID. Can be found on the [Offers API page](http://panel.adgatemedia.com/affiliate/api/keys). | Any Integer | `60000` | | api\_key | Your API key. Can be found on the [Offers API page](http://panel.adgatemedia.com/affiliate/api/keys). | Any String | `941bd1fecf7e6596823b895e04df3a0c` | | wall\_code | Wall code that can be found on the [AdGate Rewards page](https://panel.adgatemedia.com/affiliate/vc-walls/index) | String | `nQug` | ### Optional Parameters | Parameter | Description | Type | Example | | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------ | ------- | ---------------- | | countries | Filter by specific countries. Accepts a list of comma separated country codes. | String | `gb,us,ca` | | offer | Filter by specific offers. Accepts a list of comma separated offer IDs. | String | `4849,5201,4809` | | paymin | Filter by offers above a minimum payout. Values are in USD. | Decimal | `0.50` | | minepc | Filter by offers above a minimum EPC. Values are in USD. | Decimal | `0.05` | | mobile\_only | Filter by offers that can only be displayed on mobile devices. Accepted values are `1` or `0`. A value of `0` will display all offers (default). | Integer | `1` | | categories | Filter by offers in certain categories. Accepts a comma separated list of category IDs. Please see the table below for the category ID list. | String | `4,10,11` | | orderby | Order results by either `payout`,`epc` , or `id`(offer id) in descending order. Default is `epc`. | String | `payout` | | take | Limit the number of results to X. By default all results are returned. | Integer | `200` | | skip | Skips the first X number of results. Useful when combined with limiting (see above). By default, no offers are skipped. | Integer | | #### Category List | Category ID | Category Name | | ----------- | -------------------- | | 1 | Android | | 2 | Downloads | | 3 | Email Submits | | 4 | Free | | 10 | iPad | | 11 | iPhone | | 12 | Lead Gen | | 13 | Credit Card Required | | 14 | Mobile Subscription | | 16 | Surveys | | 17 | Videos | | 18 | CPC | | 19 | Pay Per Call | | 20 | Cash Back | | 21 | CPI | | 22 | CPE | | 23 | CPA | ### Response Note that country abbreviations use the ISO standard, e.g. GB instead of UK. #### Sample Response ``` [ { "status": "success", "data": [ { "id": 100677, "name": "Final Fantasy XV iPhone CPE (US) (Incentive)", "anchor": "Play Final Fantasy XV on your iPhone!", "requirements": "Install and Reach Citadel level 10.", "user_agent": [ "iphone" ], "mobile_only": true, "creatives": { "icon": "https://linkhere" }, "epc": "1.98", "categories": [ "iPhone" ], "tools": [ "content_locking", "virtual_currency" ], "adgate_rewards": { "cpm": "0.00", "anchor": "Final Fantasy XV", "requirements": "Install and Reach Citadel level 10. Eligibility: Must be installing the app for the first time. ***New Users Only*** Users must download and OPEN the app within 15 minutes of starting (clicking) the offer.", "description": "Be the hero of your own Final Fantasy XV adventure in the brand new mobile strategy game Final Fantasy XV: A New Empire! Build your own kingdom, discover powerful magic, and dominate the realm alongside all of your friends! " }, "lockers": { "epc":"0.07", "desktop_average_epc":"0.05", "mobile_average_epc":"0.08" }, "countries": [ "US" ], "type": "flat", "payout": "18.00", "click_url": "https://agm.mobi/vc/nQ/offers/100677?s1=", "support_url": "https://wall.adgaterewards.com/offer/contact/nQ/345862?s1=", "preview_url": "https://itunes.apple.com/app/final-fantasy-xv-a-new-empire/id1186994231?mt=8", "multiple_conversions_allowed": true, "multiple_conversions_rules": { "rule_type": "INTERVAL", "x_conversions": 1, "every_y_seconds": 10 } }, ...... ] } ] ``` #### Response Parameters | Key Name | Description | | ------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | id | AdGate offer id. | | name | AdGate's internal offer name, not to be displayed to end-users. | | anchor | Deprecated value. Do not use this. Use "title" from the "adgate\_rewards" section. | | requirements | Deprecated value. Do not use this. Use "requirements" from the "adgate\_rewards" section. | | user\_agent | An array of strings that must be present in the end-user's user agent. If an empty array, then any user agent is permitted. | | mobile\_only | Mobile and tablet traffic only. If false, allowed on any device. | | creatives | Object of key-values representing creatives. | | epc | Network-wide EPCs | | categories | Array offer categories (listed above) | | tools | The types of traffic and AdGate tools this offer can be displayed on. May include one or more of: super\_urls, content\_locking, incent\_mobile\_app\_walls, non\_incent\_mobile\_app\_walls, virtual\_currency, video | | adgate\_rewards |

If "virtual\_currency" is listed in "tools" above, the "adgate\_rewards" key will be present, which is an object that provides the following key-value pairs:

cpm: deprecated value, always returns 0.00
anchor: Offer title to display to end-users
requirements: Offer requirements to display to end users.
description: Offer description to display to end users

| | lockers |

If "content\_locking" is listed in the "tools" array, this "lockers" key will contains content locking EPCs as an object containing the following key-value pairs:

epc: Network-wide locker traffic EPC
desktop\_average\_epc: Network-wide desktop locker traffic EPC
mobile\_average\_epc: Network-wide mobile locker traffic EPC

| | countries | Array of two-letter country codes this offer is available to. If this array is empty, all countries are allowed. Use "GB" for the UK. | | type | One of "flat" or "dynamic". Flat payouts don't change. Dynamic payouts vary. | | payout | The dollar amount if "type" above is "flat". | | click\_url | Tracking link. The `s1` parameter should include the ID of the user accessing the offer. The ID can be any string up to 255 characters long. s2-5 subids are available. | | support\_url | The URL the user can access to get support in case they are not rewarded. The `s1` parameter is required (see `click_url` above for info.) Note that most offers require waiting at least one hour after clicking an offer to be able to contact support. | | preview\_url | Preview of the offer's landing page. | | multiple\_conversions\_allowed | Boolean. Indicates if the offer allows multiple conversions for a single user (IP), according to the rules specified in "multiple\_conversions\_rules". | | multiple\_conversions\_rules |

If "multiple\_conversions\_allowed" is false then this will be null. Otherwise, it will be an object with the following values:

rule\_type: Can be one of "UNLIMITED" or "INTERVAL". "UNLIMITED" means ths offer can be completed an indefinite amount of times without time limit. "INTERVAL" means the offer can be completed a certain amount of times in a given amount of time, in the format "allow X conversions every Y seconds".
x\_conversions: Integer when the rule type is "INTERVAL", "null" otherwise.
every\_y\_seconds: Integer when the rule type is "INTERVAL", "null" otherwise.

More attempts than the rule allows will not result in a conversion.

| # Publisher Reporting API ## Use Cases **The API described on this page is for fetching reports.** * All dates and data are calculated in the EST timezone. * All monetary values are in dollars as decimals. * Please allow for long timeouts for each request as responses are not instant. * Reports are updated approximately every half hour, so requesting the same report within that timeframe will return the same result set. ## API **Method:** GET\ **Base URL:** `https://api.adgatemedia.com/v1/affiliate/report` ### Required Parameters | Parameter | Description | Type | Example | | ----------- | -------------------------------------------------------------------------------------------------------------- | ------- | ---------------------------------- | | aff | Your affiliate ID. Can be found on the [Reporting API page](https://panel.adgatemedia.com/affiliate/api/keys). | Integer | `60000` | | api\_key | Your API key. Can be found on the [Reporting API page](https://panel.adgatemedia.com/affiliate/api/keys). | String | `941bd1fecf7e6596823b895e04df3a0c` | | start\_date | Start date of report in mm-dd-YYYY format | String | `01-30-2020` | | end\_date | End date of report in mm-dd-YYYY format | String | `02-01-2020` | ### Optional Parameters #### Data Column Grouping The data columns to display and group data by. Example: \&data\[]=offer\_id\&data\[]=aff\_id. | Value | Description | | ---------- | ------------------------------------- | | offer\_id | AdGate's internal offer ID (default) | | country | Country | | is\_mobile | Is mobile or tablet traffic (boolean) | | browser | Browser | | os | Operating System | | device | Device | | tool | AdGate Monetization Tool | | s1 | SubID 1 | | s2 | SubID 2 | | s3 | SubID 3 | | s4 | SubID 4 | | s5 | SubID 5 | #### Date Interval Grouping Group response by specific time periods. Example: \&intervals\[]=m\&intervals\[]=dt | Value | Description | | ----- | ----------- | | m | Month | | dt | Day | | h | Hour | #### Filters Request to only include reports that match certain criteria. Separate multiple values for each filter using commas. Example: \&filters\[offer\_id]=11045,112340 | Value | Description | | --------- | ----------------------------------------------------------------------------- | | offer\_id | Filter by specified offer IDs | | country | Filter by specified countries using ISO standards (\&filters\[country]=US,GB) | | s1 | Filter by SubID 1 | #### Additional Data Optional data that can be added to the response. Example: \&options\[]=impressions\&options\[]=cpm | Value | Description | | ------------------ | -------------------------------------------- | | offer\_impressions | Include offer impression data | | user\_impressions | Include user impression data | | cpm | Include cost per thousand impressions | | app\_id | Include App ID value in addition to offer ID | #### Pagination | Parameter | Description | Type | Example | | --------- | -------------------------------------------------------------------------------------- | ------- | ------- | | offset | Starting offset to fetch data, default is 0. | Integer | `20` | | limit | Number of records to return in one page, default is 10,000, maximum is 20,000 records. | Integer | `12000` | ### Response Note that country abbreviations use the ISO standard, e.g. GB instead of UK. #### Sample Response ``` { "data": { "results": [ { "offer_id": 15506, "offer_name": "Survey Sample Savings - Burger King (US) (Incentive)", "is_mobile": true, "unique_impressions_count": 91879, "unique_clicks_count": 34268, "conversions_count": 3105, "payout_sum": 5589, "cpm": 60.83, "conversion_rate": 0.0906, "ppc": 0.16, "country_code": "US" }, { "offer_id": 17192, "offer_name": "Lifesum iPhone Burst (US) (Incentive)", "is_mobile": true, "unique_impressions_count": 25527, "unique_clicks_count": 7552, "conversions_count": 3442, "payout_sum": 1652.16, "cpm": 64.72, "conversion_rate": 0.4558, "ppc": 0.21, "country_code": "US" } ], "totalColumns": { "unique_impressions_count": 117406, "unique_clicks_count": 41820, "conversions_count": 6547, "payout_sum": 7241.16, "cpm": 61.68, "ppc": 0.17, "conversion_rate": 0.1565 }, "paging": { "next": null, "prev": null } }, "status": "success" } ``` #### Errors **Request limit:** Only 3 requests are allowed per minute. ``` { "data": [], "status": "error", "error": { "code": 400, "message": "Three reporting API requests have been made with this API key. Please try again in a minute." } } ``` **Invalid Data:** Invalid data field(s) were requested \[ \&data\[]=wrong ]. ``` { "data": [], "status": "error", "error": { "code": 400, "message": "Invalid Data column(s) [ &data[]=wrong ]." } } ``` **Invalid Interval:** Invalid interval is passed \[ \&interval\[]=month ]. ``` { "data": [], "status": "error", "error": { "code": 400, "message": "Invalid interval [ &interval[]=month ]." } } ``` **Invalid Options:** Invalid option(s) are passed \[ \&option\[]=random ]. ``` { "data": [], "status": "error", "error": { "code": 400, "message": "Invalid option [ &option[]=random ]." } } ``` **Invalid Filters:** Invalid filters requested \[ \&filters\['wrong\_key']=check ]. ``` { "data": [], "status": "error", "error": { "code": 400, "message": "Invalid filters [ &filters['wrong_key']=check ]." } } ``` **Maximum groupings:** Maximum 5 data grouping columns are allowed. ``` { "data": [], "status": "error", "error": { "code": 400, "message": "Maximum 5 groupings (data + intervals) can be applied at a time." } } ``` #### Response Fields Each row may contain any of the following keys and values, depending on the options passed to the API: | Key | Description | | -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | offer\_id | AdGate's internal offer ID | | offer\_name | AdGate's internal offer name | | app\_id | Offer's App ID (from Apple AppStore or Google Play) | | country\_code | 2-letter ISO Country Code | | is\_mobile | Whether the device used was mobile/tablet (boolean) | | browser | Browser used to click the offer | | os | Operating system of the device by which offer was clicked | | device | Device by which offer was clicked | | tool\_name | Name of the monetization tool | | s1 | SubID 1 | | s2 | SubID 2 | | s3 | SubID 3 | | s4 | SubID 4 | | s5 | SubID 5 | | m | Month | | dt | Day of month | | h | Hour | | unique\_clicks\_count | Click count, uniques by IP within the time interval requested | | conversions\_count | Number of conversion within the time span requested | | unique\_impressions\_count | Impressions count, uniques by IP within the time interval requested | | payout\_sum | Payout | | ppc | Average payout per click | | conversion\_rate | Average conversion rate, as decimal, e.g. 0.023 is 2.3%. | | cpm | Earnings per thousand impressions. | | totalColumns |

The calculations here apply only to the current result set.

  • unique\_impressions\_count: Total unique impressions.
  • unique\_clicks\_count: Total unique clicks.
  • conversions\_count: Total conversions.
  • conversions\_rate: Average conversion rate, as decimal, e.g. 0.023 is 2.3%.
  • payout\_sum: Total payout.
  • ppc: Average payout per click.
  • cpm: Average earnings per thousand impressions.
| | paging |

Links to fetch results for the next and previous page.

  • next: URL to fetch next page.
  • prev: URL to fetch previous page.
| #### More Examples **URL:** This request will group data by (offer\_id, country) for the last month, with a limit of 100 results per page. The result set will be empty if there was no traffic during this time period. #### Example Response ``` { "data": { "results": [ { "offer_id": 15506, "offer_name": "Survey Sample Savings - Burger King (US) (Incentive)", "unique_clicks_count": 34347, "conversions_count": 3116, "payout_sum": 5608.8, "conversion_rate": 0.0907, "ppc": 0.16, "country_code": "US" }, { "offer_id": 17192, "offer_name": "Lifesum iPhone Burst (US) (Incentive)", "unique_clicks_count": 7552, "conversions_count": 3442, "payout_sum": 1652.16, "conversion_rate": 0.4558, "ppc": 0.21, "country_code": "US" } ], "totalColumns": { "unique_clicks_count": 41899, "conversions_count": 6558, "payout_sum": 7260.96, "ppc": 0.17, "conversion_rate": 0.1565 }, "paging": { "next": null, "prev": null } }, "status": "success" } ``` **URL:** This request will get a date report that includes impressions and CPM data only for offers 16146 and 15506, grouped by day. Rows for each corresponding day are returned even if there was no traffic during that time frame. #### Example Response ``` { "data": { "results": [ { "dt": "2015-06-02", "unique_impressions_count": 23976, "unique_clicks_count": 8595, "conversions_count": 721, "payout_sum": 1297.8, "cpm": 54.13, "conversion_rate": 0.0839, "ppc": 0.15 }, { "dt": "2015-06-01", "unique_impressions_count": 1632, "unique_clicks_count": 286, "conversions_count": 12, "payout_sum": 21.6, "cpm": 13.24, "conversion_rate": 0.042, "ppc": 0.07 } ], "totalColumns": { "unique_impressions_count": 25608, "unique_clicks_count": 8881, "conversions_count": 733, "payout_sum": 1319.4, "cpm": 51.52, "ppc": 0.15, "conversion_rate": 0.0825 }, "paging": { "next": null, "prev": null } }, "status": "success" } ``` # AdGate Rewards Setup This page describes how to setup your AdGate Rewards offer wall. ## Creating a new AdGate Rewards Offer Wall In order to use AdGate Rewards, you must have an approved Publisher account with AdGate Media. If you do not already have an account, you can [signup here](https://dash.adgatemedia.com/account/signup). ### Step 1: In the AdGate Media dashboard go to Monetization Tools > [AdGate Rewards](https://dash.adgatemedia.com/affiliate/vc-walls) ### Step 2: Click Create AdGate Rewards Wall ### Step 3: Fill out the following form, each field is described below. | Field | Description | | ---------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Name** | This is an internal identifier. It will be used to identify your wall on our panel and reporting. | | **Allowed Offer Categories** | This determines what types of offers will show up your offer wall. For maximum revenue, we recommend leaving this on the default settings. | | **Points (plural)** | The plural form of your currency. *Ex: Coins* | | **Points (singular)** | The singular form of your currency. *Ex: Coin* | | **Points (abbreviation)** |

The abbreviated form of your currency. Ex: C

If there is no abbreviated form, just use the Plural form. Ex: Coins

| | **Conversion rate** | The amount of currency you will award your users for every $1 you earn. *Ex: A value of 100 will mean your users earn 100 Coins for every $1 AdGate Media pays you.* | | **URL of the wall** | Enter the URL of your website or app where the wall will be displayed. | | **Postback** | The URL you would like us to notify when a conversion occurs. For more information on Postbacks please the link below. | | **Rounding** | You can choose how you want decimals rounded when awarding currency. There is also an option to keep currencies as a decimal, up to two decimal places. | {% content-ref url="/pages/-MPACl3rzGQBeW8b9SqC" %} [Postback Information](/postbacks/postback-information) {% endcontent-ref %} The next step is integrating the AdGate Rewards wall on your app or website. # Web Integration If you wish to integrate the offer wall on your website, this page describes the steps needed to do so. ## Placing your wall ### Step 1: Obtain your wall code You can find your wall code [here](https://dash.adgatemedia.com/affiliate/vc-walls/index). It will look like the following image: ![You can see the wall code here is nq6Upw](/files/-MPAAdVfJQI4Xq4xbfms) ### Step 2: Determine the user ID This is a dynamic value that should be replaced with a unique identifier for each of your users. The user id may be any string up to 255 characters long. We recommend using a hashed value if possible. ### Step 3: Adding the iframe to your site You will take both of the pieces of information obtained in Step 1 & 2 and create an iframe using the following guideline: `https://wall.adgaterewards.com/**YOUR WALL CODE (Step 1)**/** USER ID (Step 2)**`. For example: ```markup ``` It is also recommended to set the iframe height to that of the users browser. This can be done in either [CSS](http://www.tagindex.net/css/frame/width_height.html) or [inline of the iframe.](http://www.w3schools.com/tags/att_iframe_height.asp) Alternatively, you can use the URL generated above to open the AdGate Rewards offer wall in a new tab. # iOS SDK This page describes how to install the AdGate Media iOS SDK. ## Requirements • iOS version 8.0 or higher ## 1. Install SDK ### Installation with CocoaPods 1. To install via CocoaPods, simply add the following line to your Podfile: ```ruby pod 'AdGateMedia' ``` 1. Run `pod install` to install AdGateMedia dependency. ### Installation with Framework (.framework) 1. Download the **AdGateMedia\_UniversalFramework.zip** file from the [Releases](https://github.com/adgatemedia/adgate-rewards-ios-sdk/releases) page. Drag and drop `AdGateMedia.framework` and `AdGateMedia.bundle` into your project. (Note that when you would like to upload your app to app store you must use device only version which is **AdGateMedia\_DeviceFramework.zip** otherwise your app will be rejected [Radar](http://www.openradar.me/radar?id=6409498411401216)) 2. Go to **General/Linked Frameworks and Libraries** and add `AVFoundation.framework`, `AdSupport.framework` `CoreMedia.framework`, and `WebKit.framework`. 3. Go to **Build Settings/Linking/Other Linker Flags** and add **-ObjC** flag. 4. Make sure **Build Settings/Search Paths/Framework Search Paths** includes the path of our framework, Otherwise add framework path. For example if your framework exist in your project directory then you could add `$(PROJECT_DIR)` . 5. Make sure **AdGateMedia.bundle** is added in **Build Phases/Copy Bundle Resources**. ### Installation with Library (.a) 1. Download the **AdGateMediaLibrary.zip** file from the [Releases](https://github.com/adgatemedia/adgate-rewards-ios-sdk/releases) page. Drag and drop `libAdGateMedia.a`, `AdGateMedia.bundle` and `include` folder into your project. (Note that when you would like to upload your app to app store you must use device only version which is **AdGateMedia\_DeviceLibrary.zip** otherwise your app will be rejected [Radar](http://www.openradar.me/radar?id=6409498411401216)) 2. Go to **General/Linked Frameworks and Libraries** and add `AVFoundation.framework`, `AdSupport.framework` `CoreMedia.framework`, and `WebKit.framework`. 3. Go to **Build Settings/Linking/Other Linker Flags** and add **-ObjC** flag. 4. Make sure **Build Settings/Search Paths/Library Search Paths** includes the path of our library, otherwise add library path. For example if library exist in project directory then you could add `$(PROJECT_DIR)`. 5. Make sure **AdGateMedia.bundle** is added in **Build Phases/Copy Bundle Resources**. 6. Go to **Build Settings/Search Paths/Header Search Paths** and add **$(PROJECT\_DIR)/include** or actual directory path where library header file copied. In order to get started you are required to add the following header file to either your project's .pch file or at the location you are displaying the offer wall: ``` #import "AdGateMedia.h" //#import if using framework ``` ### Installation in Swift project Follow all bullet points of installation steps mentioned above and do these additional steps. 1. Create Bridging header file (If not already created). It's name should be `${YOURPROJ}-Bridging-Header.h` while ${YOURPROJ} is your project name. 2. If you created bridging header manually then Go to **Build Settings->Swift Compiler - General->Objective-C Bridging Header** and add bridging header manually by specifying `$(PROJECT_DIR)/$(PROJECT_NAME)/$(PROJECT_NAME)-Bridging-Header.h` 3. In the Bridging header file, import your framework using the standard Objective C import syntax. In our case, it will be ``` #import ``` **Note** 4. Please note that method names may be little bit shorter when you use this framework inside swift project. 5. We have included a demo project written in swift for your convenience. ## 2. Load & Display the Offer wall Add the following lines of code where you want to launch the offer wall: ``` @implementation ViewController -(void)showOfferWall { NSString * rewardCode = @"YOUR_WALL_CODE"; NSString * userId = @"YOUR_USER_ID"; AdGateMedia *media = [[AdGateMedia alloc] initWithRewardCode:rewardCode userId:userId parentViewController:self]; NSDictionary *parameter = @{ @"s2" : @"Value s2", @"s3" : @"Value s3", @"s4" : @"Value s4", @"s5" : @"Value s5", }; //Below code will show offer wall immediately before loading BOOL success = [media loadOfferWall: parameter onOfferWallLoadSuccess:^{ NSLog(@"Successfully loaded wall"); } OnOfferWallLoadFailed:^(NSError *error){ NSLog(@"Failed to load wall"); }]; if (success) { [self.adGateMedia showOfferWall:^{ NSLog(@"Closed wall"); }]; } } @end ``` To change the offer wall code and user name, use the following code: ``` @interface ViewController : UIViewController @property (nonatomic, strong) AdGateMedia *media; @end @implementation ViewController -(void)showOfferWall { NSString * rewardCode = @"YOUR_WALL_CODE"; NSString * userId = @"YOUR_USER_ID"; if (self.media == nil) { self.media = [[AdGateMedia alloc] initWithRewardCode:rewardCode userId:userId parentViewController:self]; } else { self.media.rewardCode = rewardCode; self.media.userId = userId; } NSDictionary *parameter = @{ @"s2" : @"Value s2", @"s3" : @"Value s3", @"s4" : @"Value s4", @"s5" : @"Value s5", }; //Below code will show offer wall once it's loaded successfully [self.media loadOfferWall: parameter onOfferWallLoadSuccess:^{ [media showOfferWall:^{ NSLog(@"Closed wall"); }]; } OnOfferWallLoadFailed:^(NSError *error){ NSLog(@"Failed to load wall"); }]; } @end ``` Set the rewardCode and userId to the appropriate values. You may get your wall code from [this page](https://panel.adgatemedia.com/affiliate/vc-walls/index) on the affiliate dashboard. 1. You can pass subids while loading the offer wall, specifically, s2, s3, s4 and s5. 2. Once the offer wall is loaded you can display it using the `showOfferWall` method. User can see it called in the above code after the wall is successful loaded. ``` [media showOfferWall:^{ NSLog(@“Closed wall”); }]; ``` ## 3. Get a list of the latest offer wall conversions To get the list of the latest offer wall conversions, use the `getConversions` method. Add the following lines of code in your class (i.e ViewController) ``` NSString * rewardCode = @"YOUR_WALL_CODE"; NSString * userId = @"YOUR_USER_ID"; AdGateMedia *media = [[AdGateMedia alloc] initWithRewardCode:rewardCode userId:userId parentViewController:self]; NSDictionary *parameter = @{ @"s2" : @"Value s2", @"s3" : @"Value s3", @"s4" : @"Value s4", @"s5" : @"Value s5", }; [media getConversions:parameter rewardCode:rewardCode userId:userId completionHandler:^(NSArray * _Nullable offers, NSError * _Nullable error) { if (error) { NSLog(@"Error: %@",error); //Show error }else { //Show offers NSLog(@"offers: %@",offers); } }]; ``` ## 4. Debug mode: Step 1: Select the Edit Scheme from XCode where you set your active scheme. Step 2: Goto Run -> Info -> Build Configuration -> Debug option -> Close. Note: Use NSLog to print result after selecting the Debug build configuration. NSLog is used to print the value in the console for debug mode. ## 5. Demo App. [This repository](https://github.com/adgatemedia/adgate-rewards-ios-sdk/) contains a demo iOS app that shows how to implement our SDK. # Android SDK This page describes how to install the AdGate Media iOS SDK. ## Requirements * Android SDK minimum version 14 (Ice Cream Sandwich 4.0) * Minimum hardware requirement is ARMV7 * Java JDK 1.6 or greater ## 1. Install SDK > Instructions provided here are for Android Studio. aar libraries are not yet supported on Eclipse, though some solutions are available online. 1. Download the latest aar file from 2. Add the aar file to your project, by copying it into your project's libs folder. ![image1](https://cloud.githubusercontent.com/assets/12953988/11656906/54b19416-9dde-11e5-8c65-49dcd16c9fd2.png) 3. Add the following lines of code to your app's `build.gradle` file, so that Android Studio recognizes and builds the library along with your app. ```markup repositories { flatDir { dirs 'libs' } } dependencies { implementation 'com.google.android.gms:play-services-iid:10.2.1' implementation 'com.google.android.gms:play-services-ads:10.2.1' implementation 'com.google.code.gson:gson:2.8.0' implementation 'com.squareup.okio:okio:1.12.0' implementation 'com.squareup.okhttp3:okhttp:3.7.0' implementation 'androidx.legacy:legacy-support-v4:1.0.0' implementation 'com.facebook.network.connectionclass:connectionclass:1.0.1' implementation(name:'adgatemediasdk', ext:'aar') } ``` At this point Android Studio shouldn't throw any errors related to the library. ## 2. Load the offer wall 1. In your activity, where you intend to show the offer wall, add the following import statement: ```java import com.adgatemedia.sdk.classes.AdGateMedia; ``` 1. To load the offer wall, from any place in your running activity add the following code: ```java final HashMap subids = new HashMap(); subids.put("s2", "my sub id"); AdGateMedia adGateMedia = AdGateMedia.getInstance(); adGateMedia.loadOfferWall(YourActivity.this, wallCode, userId, subids, new OnOfferWallLoadSuccess() { @Override public void onOfferWallLoadSuccess() { // Here you can call adGateMedia.showOfferWall(); } }, new OnOfferWallLoadFailed() { @Override public void onOfferWallLoadFailed(String reason) { // Here you handle the errors with provided reason } }); ``` Remember to set `wallCode` and `userId` to the appropriate values. You can get your AdGate Rewards wall code from the [Dashboard](https://panel.adgatemedia.com/affiliate/vc-walls/index). The `userId` values can be any alphanumeric string. You may add up to 4 subid strings to the HashMap: s2, s3, s4, and s5. ## 3. Display the offer wall Once offer wall is loaded you can display it by calling the showOfferWall method. ```java AdGateMedia.getInstance().showOfferWall(YourActivity.this, new AdGateMedia.OnOfferWallClosed() { @Override public void onOfferWallClosed() { // Here you handle the 'Offer wall has just been closed' event } }); ``` ## 4. Get a list of the latest offer wall conversions To get a list of latest offer wall conversions for a particular user run the following code in your activity: ```java final HashMap subids = new HashMap(); subids.put("s2", "my sub id"); AdGateMedia.getInstance().getConversions(this, wallCode, userId, subids, new OnConversionsReceived() { @Override public void onSuccess(List conversions) { // Here you can loop through every conversion and process it. // conversions.size() holds the amount of new conversions to process. for (Conversion conversion : conversions) { Log.i("AdGateRewards", "Received new conversion: " + "offer ID: " + String.valueOf(conversion.offerId) + " offer title: " + conversion.title + " transaction ID: " + conversion.txId + " points earned: " + String.valueOf(conversion.points) + " payout in cents:" + String.valueOf(conversion.payout) + " subid 2: "+conversion.subid2 + " subid 3: "+conversion.subid3 + " subid 4: "+conversion.subid4 + " subid 5: "+conversion.subid5 ); } } @Override public void onError(String message) { // Fired when any error occurs } }); ``` The `wallCode` for your AdGate Rewards wall can be found on the [AdGate Rewards panel page](https://panel.adgatemedia.com/affiliate/vc-walls). The `userId` value is your app's internal user id for whom you'd like to check for conversions. `subids` is a hashmap of the subid's that was used when loading the offer wall. If the call was successful, a list of conversions is passed to the `onSuccess` method. Each Conversion model has the following class definition: ```java public class Conversion implements Serializable { public int offerId; public String title; public String txId; public double points; public int payout; // in cents USD public String subid2; public String subid3; public String subid4; public String subid5; } ``` ## 6. Enable console messages To enable debugging, warning, and error messages run the following line of code: ```java AdGateMedia.getInstance().setDebugMode(true); ``` This will log messages to the console as well as to a log file. Make sure you disable debug mode before publishing your app to the Google Play Store. ## 7. Demo app [This repository](https://github.com/adgatemedia/adgate-rewards-android-sdk) contains a demo Android app that shows how to implement our SDK. # Unity SDK This page describes how to install the AdGate Media Unity SDK. ## Requirements * Unity version 2019.1 and up ## 1. Install SDK 1. Download the latest Unity Package Release from the [GitHub Releases page](https://github.com/adgatemedia/adgate-rewards-unity-sdk/releases/). 2. Double-click on the package or drag the package into your Unity scene to import it. 3. This SDK depends on the following third-party assets, if you have any of the following in your project please do not re-import them. 1. JsonDotNet 2. UniWebView 4. Click import to complete the SDK installation. 5. Locate the config file located in `AdGate/Resources/Config/AdGateConfig.asset`. You can turn debug mode on or off depending on your requirements. Debug messages will be completely ignored by the SDK when this is turned off. ## 2. Using the SDK To start using the SDK, You need to implement usage of the “AdGate” namespace by adding this above the script: ``` using AdGate; ``` Now you can use any of the SDK methods. ### Load Offer Wall ``` AdGateManager.LoadOfferWall(string wallCode, string userId, List subIds = null, Action onOfferWallLoadedSuccess = null, Action onOfferWallLoadingFailed = null); ``` Parameters: * `wallCode`: a string that corresponds to the ID of your offer wall, which you can retrieve from [this page](https://panel.adgatemedia.com/affiliate/vc-walls). * `userId`: a string that corresponds to the current user accessing the wall * `subIds`: a list of subids you wish to use. They may be any string up to 255 characters long. The available sub ids are `s2`, `s3`, `s4`, and `s5`. * `onOfferWallLoadedSuccess`: A C# delegate action that is called as soon as the offer wall loading succeeded. It does not pass any variable back as it assumes anytime you get this callback, the offerwall loading was successful. * `onOfferWallLoadingFailed`: A C# delegate action with an error code variable. If this is ever fired, the error code can tell you more about what has happened. You can get more information about the meaning of the codes [here](https://developer.android.com/reference/android/webkit/WebViewClient). Example code: ``` public string wallCode; public string userId; public List subIds = new List(); AdGateManager.LoadOfferWall(wallCode, userId, subIds, () => { offerWallStatus.text = "Offers Loaded"; offerWallLoaded = true; showOfferBtn.interactable = true; }, (code) => { loadOfferBtn.interactable = true; showOfferBtn.interactable = false; offerWallStatus.text = "Offer loading failed with errorcode " + code; }); ``` ### Show Offer Wall ``` AdGateManager.ShowOfferWall(Action onOfferWallShown = null, Action onOfferWallClosed = null); ``` Parameters: * `onOfferWallShown`: A C# delegate that is fired once the offer wall has been displayed to the user * `onOfferWallClosed`: A C# delegate that is fired once the offer wall has been closed by the user Example code: ``` AdGateManager.ShowOfferWall(() => { offerWallStatus.text = "Offer was shown"; }, () => { showOfferBtn.interactable = false; offerWallStatus.text = "No more offers, Please load some more"; }); ``` ### Get Latest Conversions ``` AdGateManager.GetConversionDetails(string wallCode, string userId, List subIds = null, Action onConversionDetailsAvailable = null, Action onConversionDetailsFailedToLoad = null); ``` Parameters: * `wallCode`: a string that corresponds to the ID of your offer wall * `userId`: a string that corresponds to the current user accessing the wall * `subIds`: a list of subids you wish to use. They may be any string up to 255 characters long. The available sub ids are `s2`, `s3`, `s4`, and `s5`. * `onConversionDetailsAvailable`: A C# delegate action that is called as soon as the offer wall loading succeeded. It does not pass any variable back as it assumes anytime you get this callback, the offerwall loading was successful. * `onOfferWallLoadingFailed`: A C# delegate action that is called as soon as conversion details are received from the server. It returns a variable of `ConversionResponse` type. Here is a sample of the class structure: ``` public class ConversionResponse : AdGateDefaultResponse { public AdGateConversionData data { get; set; } } public class AdGateConversionData { public string tool_id { get; set; } public string user_id { get; set; } public AdGateConversion[] conversions { get; set; } } ``` If this callback is fired, it is assumed that connection to the server was successful. However, the conversions variable can be null or an empty array if there is no conversion available at the moment the server request was made. * `onConversionDetailsFailedToLoad`: A C# delegate action with an error and error code variable. If this is ever fired, the error code can tell you more about what has happened. This would be a standard server error code, while the error message would be any message sent from the server. Example code: ``` AdGateManager.GetConversionDetails(wallCode, userId, subIds, (response) => { if (response.success) { conversionBtn.interactable = true; conversionDetails.text = response.text; } }, (message, code) => { conversionDetails.text = "Conversion Details failed with error " + message; conversionBtn.interactable = true; }); ``` ## Example Project You can view an example project from the [SDK github page](https://github.com/adgatemedia/adgate-rewards-unity-sdk). In this project you will find sample code on how to use the SDK. ## Updating the SDK Please follow the same installation guide above but remember to untick AdGate/Resources/Config/AdGateConfig.asset from being imported. Otherwise, your config choice will be lost. Please also remember that if you made prior changes to the SDK code, it will be overwritten by the new code. # Magic Receipts Standalone This page describes how to setup Magic Receipts as a standalone offering. ## What is Magic Receipts? Magic Receipts is a product that allows your user to scan receipts of their recent purchases in exchange for rewards.
## How to Integrate Magic Receipts as a Standalone Offering The Magic Receipts offering is automatically included in the AdGate Rewards Offer Wall. However, publishers may also display Magic Receipts as a standalone offering within their website or app. ### Step 1: Create an AdGate Rewards Offer Wall Follow the steps listed [here](https://docs.adgatemedia.com/adgate-rewards-monetization/untitled) to setup your AdGate Rewards offer wall. You may skip this step if you already have an AdGate Rewards offer wall created. ### Step 2: Obtain your wall code You can find your wall code [here](https://panel.adgatemedia.com/affiliate/vc-walls/index). It will look like the following image:

You can see the wall code here is nq6Upw

### Step 3: Create your unique link Replace the **WALLCODE** text below with the value from the previous step. Replace **USERID** with the unique identifying value for each of your users. \*\* Optionally, you may also append additional tracking parameters to the url. ex: ### Step 4: Append Offer Wall Information (Optional) By default, all point and conversion information will be taken from your AdGate Rewards Wall settings as configured on the dashboard. However, if you wish to dynamically pass that information in, you can do so by following the steps below. You may append the following offer wall information to the link: | Parameter | Description | Type | Example | | --------- | ------------------- | ------- | ------- | | cr | Conversion rate | Integer | 100 | | pp | Plural points | String | Points | | ps | Singular points | String | Point | | pa | Points abbreviation | String | Pts | **Example:**\ \ **NOTE:** If you want to append the conversion rate in the link, you need to hash the url for security purposes. #### **Hashing** To hash the link you need to encrypt everything after the domain name () with the HMAC SHA-256 hashing algorithm, and append the hash to the link. Here is a list of steps you need to follow to do the hashing: Example URL: `https://seek.gg/magic/WALLCODE/USERID?cr=100&pp=Points&ps=Point&pa=Pts` 1. Ask your account manager for your publisher secret key. 2. Generate a hash by encrypting the path and query using your secret key with this pseudo-code:\ hash = *hmac\_256("/magic/WALLCODE/USERID?cr=100\&pp=Points\&ps=Point\&pa=Pts", secret\_key)* 3. Append the hash to the url with the parameter "hash":\ `https://seek.gg/magic/WALLCODE/USERID?cr=100&pp=Points&ps=Point&pa=Pts&hash=abcdefg123` **PHP Script** ```php // We hash only path and query. // Root path "/" is always included in the data to sign. // "?" included only if query string is not empty. $path = parse_url($url, PHP_URL_PATH); $query = parse_url($url, PHP_URL_QUERY); $pathAndQuery = $path . ($query !== null ? ('?' . $query) : ''); $hash = hash_hmac( 'sha256', utf8_encode($pathAndQuery), $secretKey, ); $url .= "&hash={$hash}"; ``` ### Step 5: Send users through your link Use your newly generated link to send users to the Magic Receipts product. You will receive a [postback](https://docs.adgatemedia.com/postbacks/postback-information) for each successfully scanned receipt. # Postback Information This page describes how a postback works. ## What is a Postback? A postback allows you to receive notifications on your server every time your account receives a conversion. This is necessary in order for you to be able to provide your users with rewards. For example, whenever you receive a conversion, you may wish to be notified what the payout, user ID, and point value is. We are also able to send you a postback in the case that a lead may be reversed. **Example Postback URL: `http://yoururl.com/postback/?conversion_id={conversion_id}&user_id={s1}&point_value={points}&usd_value={payout}&offer_title={vc_title}`** We will replace all of the macros, such as `{conversion_id}`, with the actual value (such as "4d63afe33875ceeec17dd7eab41b8590a".) On your server, you will read the "conversion\_id" GET variable to retrieve this macro's value. ### Receiving postbacks Chargebacks: in order to receive postbacks for chargebacks/reversals, your postback URL must contain the `{state}` macro. Non-payable events: offers can have events that are for informational purposes only, and do not provide a payout. To receive postbacks for these events, your postback URL must contain the `{event_id}` macro. The `{payout}` value for these event will be 0. ## Available Macros You may add any of the following macros to your postback URLs. They will be replaced with the corresponding values. | Macro | Replaced Value | Variable Type | | -------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------ | | {s1} | User ID | String or Integer | | {source} | Represents the ID of the offer wall or publisher sub-source in the format `vc-[int]` -- e.g. `vc-123` | String | | {points} | Number of points/credits the user should be rewarded with | Decimal or Integer | | {vc\_title} | Title of the offer as it was displayed on the offer wall. | String | | {payout} | Amount in USD that you earned for this conversion | Decimal | | {state} |

This is the state of the conversion. Possible values are:

approved - the conversion is approved

rejected - a conversion that was previously pending or approved was reversed

pending - the user has completed the offer but the conversion will be approved at a later date

If this macro is not present in your postback URL, postbacks will only be sent for approved conversions.

| String | | ~~{status}~~ |

DEPRECATED VALUE: please use {state} instead.

Value will be 1 for a new approved conversion. If this macro is present in your postback, then the postback will also be resent in the case of a reversed conversion. In that case, the value will change to 0 while all other values will remain the same.

| Integer | | {offer\_id} | ID of the offer as displayed on the AdGate Media dashboard | Integer | | {product\_id} | ID of the product as displayed on the Adgate Media dashbaord | String | | {offer\_name} | Name of the offer as displayed on the AdGate Media dashboard | String | | {event\_id} | UUID of the specific event that was converted | String | | {event\_id\_nodash} | Use this event UUID only if your data type does not support dashes. | String | | {event\_name} | Description of the event as displayed to the user | String | | {s2},{s3},{s4},{s5} | Additional subID values that can be appended to your offer wall URL | String | | {conversion\_id} | Unique ID of the conversion generated by AdGate Media | String | | {session\_ip} | IP address of the user that completed the offer | String | | {date} | Current date of conversion formatted as YYYY-MM-DD | String | | {time} | Current time of conversion formatted as HH:MM:SS | String | | {created\_at} | Current timestamp of the conversion as unix timestamp in seconds | Integer | | {ran} | Randomly generated number | Integer | | {country} | Two letter country code representing the user's location. | String | | {delay} | Delay in minutes before the conversion is approved. | Integer | | {recommended\_delay} | Recommended delay in minutes before the conversion should be approved. | Integer | | {event\_type} | ID used to identify the type of the converted event | Integer | | {is\_lead\_credit} | Indicates if the conversion is a lead credit | Integer | | {is\_game} | Indicates if the offer is a game | integer | | {is\_timeplayed} | Indicates if the event is a time played goal | integer | | {funnel\_id} | Unique identifier of the request to the User Based API to track the impression to conversion funnel | string | All values are URL encoded. ## Rejected Reasons The system returns the internal rejection reason codes directly. Here are the possible rejection reason codes: | `DUPE_COOKIE` | Duplicate Cookie | | ---------------------------------------------- | -------------------------------- | | `POSTBACK_COUNTRY_MISMATCH` | Country Mismatch | | `SKIPPED_EVENTS` | Skipped Events | | `HIGH_FRAUD_SCORE` | High Fraud Score | | `HIGH_IPQS_FRAUD_SCORE` | High IPQS Fraud Score | | `ADJUST_FRAUD` | Adjust Fraud | | `DCH_IP_BLOCK` | DCH IP Block | | `DEVICE_NOT_ALLOWED` | Device Not Allowed | | `VC_USER_ALREADY_CONVERTED` | User Already Converted | | `TXID_ALREADY_CONVERTED` | Transaction ID Already Converted | | `IP_ALREADY_CONVERTED` | IP Already Converted | | `CHARGEBACK` | Chargeback | | `EVENT_NOT_PROMISED` | Event Not Promised | | `CLICK_EXPIRED` | Click Expired | | `OFFER_EVENT_EXPIRED` | Offer Event Expired | | `VC_USER_BLOCKED` | User Blocked | | `NOT_TIME_PLAYED_EVENT` | Not Time Played Event | | `TIME_PLAYED_GOAL_MISMATCH` | Time Played Goal Mismatch | | `NO_TP_GOAL_ID_PROVIDED_FOR_TIME_PLAYED_EVENT` | No TP Goal ID Provided | | `REATTRIBUTED` | Reattributed | ## Expected Response AdGate Media's servers expect an HTTP Status Code 200 from your postback URL. If this response is not received from your URL, we will attempt to resend the postback up to 5 times. There is a 5 minute delay between each attempt. ## Security Recommendations To prevent tampering, it is important that the postback URL that is used is unique to AdGate Media. \ \ For additional security, you may whitelist the following server IPs: * 52.42.57.125 * 54.186.70.83 * 52.39.181.185 * 54.190.14.75 * 52.11.36.128 * 54.191.9.88 * 3.21.111.51 * 3.135.140.42 * 3.133.245.65 ## Testing and Troubleshooting To test the postback functionality on your AdGate Rewards offer wall, you may enable the "Test Mode" feature in your offer wall settings. Enabling Test Mode will create an offer at the top of your offer wall. This offer will convert immediately upon click for easy postback testing. We do not recommend enabling this feature on a live offer wall. To troubleshoot any postback issues, you may visit your Postback Reports page here: [https://dash.adgatemedia.com/affiliate/reports/postbacks](https://panel.adgatemedia.com/affiliate/reports/postbacks) This page will show a 30 day history of all postbacks on your account. # Magic Receipts Postbacks This page describes how Magic Receipts postback works. ## Intro A user can upload an image of a receipt that contains purchases for multiple items, for example Chocolate and Apples. Use Magic Receipts postbacks to receive notifications on your server whenever the status of each offer item in the receipt changes. There are four possible statuses: * AWARD\_PENDING * APPROVED * REJECTED * MANUAL\_REVIEW Once an offer is APPROVED, it cannot transition to another status. ### Setting Up a Postback In order to receive postbacks for Magic Receipts events, you must set a URL that we should fire within the AdGate dashboard on the Postbacks page. 1. Log in to the AdGate dashboard and open the [Postbacks page](https://dash.adgatemedia.com/affiliate/postbacks). 2. In the Offer-Specific Postbacks section, click Add Offer Postback and search for "397622", which is the "Shopper Marketing" offer ID. 3. Enter the URL you would like us to send postbacks to and press Submit. **Example Postback URL: `http://yoururl.com/postback/?conversion_id={conversion_id}&user_id={s1}&point_value={points}&usd_value={payout}&shm_upload_id={shm_upload_id}&shm_upload_offer_id={shm_upload_offer_id}&shm_status={shm_status}&shm_event_id={shm_event_id}`** The postback URL will be fired as a `POST` request. We will replace all of the macros, such as `{conversion_id}`, with the actual value (such as "4d63afe33875ceeec17dd7eab41b8590a".) On your server, you will read the "conversion\_id" GET variable to retrieve this macro's value. ### Understanding IDs * Each receipt that is uploaded corresponds to a single Upload ID * Each Upload can have multiple Offer IDs associated with it * Each offer on the receipt has its own Upload Offer ID, which is unique to an Upload and Offer. * Whenever a status changes for an offer, there is a corresponding Event ID * A single Offer or Upload Offer may have multiple approvals or other statuses. For example, if an offer is for purchasing Apples, then 3 purchased apples result in one offer with multiple approval (and other) events. ## Available Macros You may add any of the following macros to your postback URLs. They will be replaced with the corresponding values. | {s1} | User ID | String or Integer | | ------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------ | | {points} | Number of points/credits the user should be rewarded with | Decimal or Integer | | {payout} | Amount in USD that you earned for this event. It will be a positive number for APPROVED statuses. | Decimal | | {state} |

Provided only for APPROVED statuses. This is the state of the conversion. Possible values are:

approved - the conversion is approved

rejected - a conversion that was previously pending or approved was reversed

pending - the user has completed the offer but the conversion will be approved at a later date

If this macro is not present in your postback URL, postbacks will only be sent for approved conversions.

| String | | {s2},{s3},{s4},{s5} | Additional subID values that can be appended to your offer wall URL | String | | {conversion\_id} | Unique ID of the conversion generated by AdGate Media. Applicable only for the APPROVED status. | String | | {session\_ip} | IP address of the user that completed the offer | String | | {date} | Date of the APPROVED status formatted as YYYY-MM-DD | String | | {time} | Current time of conversion formatted as HH:MM:SS | String | | {ran} | Randomly generated number | Integer | | {country} | Two letter country code representing the user's location. | String | | {delay} | Delay in minutes before the conversion is approved. | Integer | | {shm\_upload\_id} | A unique ID for the uploaded receipt. | Integer | | {shm\_upload\_offer\_id} | A unique ID given for a specific offer found on a specific receipt (upload). | Integer | | {shm\_offer\_id} | The global ID for the offer that was uploaded (e.g. for Apples) | Integer | | {shm\_offer\_name} | The name of the offer that was uploaded (e.g. "Apples") | String | | {shm\_status} |

The status of the Magic Receipt upload for an individual offer. Possible values are:

MANUAL\_REVIEW - the upload is under review.

AWARD\_PENDING - An award will likely awarded later, barring any fraud issues.

APPROVED - the upload is approved.

REJECTED - the upload is rejected.

| String | | {shm\_event\_id} | Unique ID for the status update. | Integer | | {shm\_reason\_text} | The reason for the current status. For example, if a receipt is rejected, a reason might be "No Matching Offers". | String | | {shm\_datetime} | The datetime of the upload status update formatted as `YYYY-MM-DD HH:MM:SS` | String | All values are URL encoded. With this postback, you can receive the receipt image URLs that can be retrieved from the POST request body. The image URLs have a limited lifetime of 7 days. The request body you can expect is a JSON object of this format: ``` { "images": [ "https://example.com/img/7f213800-9260-4d54-815d-d59fd4310564_1.png", "https://example.com/img/7f213800-9260-4d54-815d-d59fd4310564_2.png" ] } ``` ## Expected Response AdGate Media's servers expect an HTTP Status Code 200 from your postback URL. If this response is not received from your URL, we will attempt to resend the postback up to 5 times. There is a 5 minute delay between each attempt. ## Security Recommendations To prevent tampering, it is important that the postback URL that is used is unique to AdGate Media. \ \ For additional security, you may whitelist the following server IP: `52.42.57.125` ## Troubleshooting To troubleshoot any postback issues, you may visit your Postback Reports page here: This page will show a 30 day history of all postbacks on your account. # PHP Postback Examples See some sample code for capturing postbacks on your server. ## PHP PDO Example This an example of a plain PHP script handling Postbacks with a PDO database connection . ``` setAttribute(PDO::ATTR_ERRMODE, PDO::ERRMODE_EXCEPTION); $conn->prepare("INSERT INTO Postbacks (tx_id, user_id, offer_id) VALUES (:tx_id,:user_id. :offer_id)"); $conn->bindValue(':tx_id', $data['tx_id']); $conn->bindValue(':user_id', $data['user_id']); $conn->bindValue('offer_id', $data['offer_id']); // use exec() because no results are returned $conn->exec(); echo "New Postback recorded successfully"; } catch(PDOException $e) { echo $sql . "
" . $e->getMessage(); } $conn = null; /** * Processing Example * This example shows sending an notification to an admin when receiving a charge back of a conversion * being sent to the postback url. * * The example uses a Static Notify class, use your own notification class or one provided by your framework * of choice. */ if($data['status'] == 0) { Notify::admin("Conversion charge back for offer " . $data['offer_id'] . " on transaction " . $data['tx_id'] . "!"); } ``` ## PHP Object Example This is an example of a plain PHP script handling Postbacks with an Object. ```