Motive Feed Integration Documentation (Version 5)
Obtaining your API Key and Affiliate ID
- Go to: http://affiliates.motiveinteractive.com/
-
Click on the "Reporting API" button near the top.
-
Copy the information highlighted in red, you need to use that to build your request URL.
Typical URL Format
When completed, your custom URL will follow the format:
http://motivefeed.com/affiliate/5/campaigns?api_key=[API_KEY]&affiliate_id=[AFFILIATE_ID]&creatives=[TRUE/FALSE]&d[]=[WIDTH]x[HEIGHT]&creatives_limit=[INTEGER]&vertical_id=[VERTICAL_ID]&tag_id=[TAG_ID]&payout_at_least=[INTEGER]&payout_at_most=[INTEGER]&incent_id=[INTEGER]
Request interval
We recommend a max interval pull of once every 5 minutes and a minimum of at least once every hour to ensure the data is synchronized between your application and our server.
Parameter Options
Use these options to help you fill out your URL.
| Parameter | Format | Required? | Description of Input |
|---|---|---|---|
| api_key | STRING | required | Affiliate API Key |
| affiliate_id | INT | required | Affiliate ID |
| country[] | ARRAY | optional | 2 letter ISO country codes. Can have multiple. Example: country[]=us&country[]=de&country[]=ca |
| creatives | BOOL | optional | TRUE/FALSE |
| d[] | ARRAY | optional | Dimension of creatives in this format (WIDTHxHEIGHT). Can have multiple. Example: d[]=300x250&d[]=320x480 |
| creatives_limit | INT | optional | Limit the amount of creatives returned per campaign. Default limit is 50. |
| vertical_id | INT | optional |
Vertical ID View list of available Verticals |
| tag_id | INT | optional |
Tag ID View list of available Tags |
| incent_id | INT | optional |
Incent ID. Return all, non-incent, or incent-only campaigns. Default shows all campaigns. View list of available Incents |
| payout_at_least | INT | optional | Return campaigns with payout equal to or greater than this value. |
| payout_at_most | INT | optional | Return campaigns with payout equal to or less than this value. |
| additional_events | true/false | optional | Returns additional payable events for an offer. |
URL Generator
Response Type:
success - STRING: Request success status
totals_rows - INT: Total number of rows
campaigns > campaign:
campaign_id - INT: Campaign ID
offer_id - INT: Offer ID
offer_name - STRING: Offer Name
offer_contract_id - INT: Offer Contract ID
vertical_name - STRING: Vertical Name
vertical_id - STRING: Vertical ID
tracking_link - STRING: Tracking link URL
payout - STRING: Payout amount in string format with $ in front of the number
> tags: See available tags
> tag:
tag_id - INT: Tag ID
tag_name - STRING: Tag name
> allowed_media_types > media_type > item: See available media types
type_id - INT: Media type ID
type_name - STRING: Media type name
category_id - INT: Media category ID
type_name - STRING: Media category name
> campaign_cap:
cap_interval - STRING: Cap Renewal Interval
cap_total - INT: Total Conversions Capped
cap_remaining - INT: Total Conversions Remaining
> creatives:
> creatives:
creative_id - INT: Creative ID
creative_name - STRING: Creative name
creative_type_id - INT: Creative type ID
creative_type - STRING: Creative type name
creative_status_id - INT: Creative status ID
creative_status - STRING: Creative status name
width - INT: Width
height - INT: Height
creative_file_id - INT: Creative file ID
creative_file_name - STRING: Creative file name
creative_file_link - STRING: Creative file link
date_created - DATETIME: date created
> app_details:
app_id - STRING: Apple App Store/Google Play Store App ID
> app_icons:
app_icon_small - STRING: Small icon image link
app_icon_large - STRING: Large icon image link
app_icon_60x60 - STRING: 60x60 icon image link
app_icon_100x100 - STRING: 100x100 icon image link
app_icon_200x200 - STRING: 200x200 icon image link
developer - STRING: App developer name/company
rating - FLOAT: App rating in decimal, rating is on a scale from 0 - 5
title - STRING: App Title in store
genre - STRING: App Genre as provided by store
content - STRING: App description
maturity_rating - STRING: App Maturity rating. Varies iOS/Android
number_of_reviews - INT: Number of reviews
min_OS_version - STRING: App Minimum OS Requirement. Varies iOS/Android
downloads - STRING: Number of downloads (Only available for Google Play Store apps)
file_size - STRING: File size in MB
app_store_url - STRING: Link to store landing page
> allowed_countries:
allowed_country - STRING: Two letter country code in uppercase
> allowed_devices:
allowed_device - STRING: Allowed device name in lowercase
FAQs
-
How often can I call the feed?
We recommend calling the feed a maximum of once every 5 minutes.
-
How do I return video campaigns?
Using the parameter &video=1 will return campaigns with the download link for a video file.
-
How do I include/exclude incent campaigns?
Use the parameter incent_id= to customize your return to include or exclude incentivized campaigns. Our default is to return all campaigns (incent and non-incent).
To return only incent campaigns: incent_id=3
To return only non-incent campaigns: incent_id=2
To return both incent and non-incent campaigns: incent_id=1
-
How do I return specific creative size?
Use the parameter d[]= to return only specific sizes of creatives. Dimensions should be in WIDTHxHEIGHT format, and can have multiple sizes.
If a campaign does not have creatives with these dimensions, this response field will be blank.
-
How do I return campaigns above a specific price floor?
Use the parameter payout_at_least= to return campaigns with payout equal to or greater than this value.
Value must be in USD currency.
-
What should I pass in the s1 parameter?
This is where you should pass the sub-id, also referred to as a specific placement id, sub-source id, placement id, site id, app id or sub-pub id.
-
Can I pass Device ID in any parameter? Is it required?
Device ID should only be passed in the s5 parameter.
We do not require publishers to pass DeviceID, however some offers do require DeviceID to convert and are tagged with Tag ID 760 "Device ID Required".
-
What is a CPE campaign? How do I include/exclude them from my feed?
CPE campaigns are Cost Per Engagement or Cost Per Event campaigns. They may payout on a registration, purchase, or other specific action within the app, instead of paying on the initial install and open.
Use the parameter CPE= to include or exclude CPE campaigns. CPE=0 excludes CPE campaigns. If the parameter is not used, CPE campaigns are returned by default.
CPE offers are tagged using the format [CPE] - Point of conversion. So for an offer that converts when a user registers, the tag is [CPE] - Registration
-
How do I see an example URL that uses the different parameters?
Check out our URL generator, and use the different parameters to create a URL customized to your needs.
-
What are Caps?
Conversion Cap intervals, totals, and amount remaining are now output under the tag "campaign_cap." Note that this does not override other rules of the feed. While a cap may show conversions remaining it can still be removed at any point for other reasons. Therefore, while the cap output provides extra information for traffic throttling, campaigns are still subject to change.
-
How can I optimize sub IDs via the MotiveFeed API?
We can output sub IDs which are passed to us in the &s1 parameter to blacklist or whitelist on a per campaign basis through MotiveFeed.com in order to increase efficiency of campaign optimizations. Please speak with your account manager if you want to enable this.
Example output:
