CRUD API Examples¶
The following examples use the tool cURL to submit requests to the web service. This method was chosen for its ubiquity, clarity, and compact syntax. Your organization’s method for calling the web service will vary depending on programming language and operating system. The server response shown below each web service call excludes the HTTP headers and is formatted for readability. Actual response bodies contain less whitespace, but still conform to the JSON marshalling standard.
Examples on this page
Get info for your organization (including EID)¶
curl -H 'Authorization: Token YOUR_TOKEN' \
https://services.adroll.com/api/v1/organization/get?apikey=MYAPIKEY
{"results": {"account_balance": 0.0,
"created_date": "2009-07-21 23:28:44",
"eid": "I5E7IOHF4BD6PNI5ZFEPMH",
"is_prepaid": true,
"last_billed_date": null,
"last_paid_date": null,
"minimum_payment_amount": 20.0,
"outstanding_balance": 0.0,
"updated_date": "2010-10-20 16:49:21"}}
Create an advertisable¶
curl -H 'Authorization: Token YOUR_TOKEN' \
https://services.adroll.com/api/v1/advertisable/create?apikey=MYAPIKEY \
-F name=Test \
-F organization=I5E7IOHF4BD6PNI5ZFEPMH \
-F country_code=us \
-F url=http://customer.com
{"results": {"click_through_conversion_window": 30,
"created_date": "2011-01-04 02:18:35",
"eid": "6SHGRDIZUBDXLHUG4YHFGC",
"name": "Test",
"organization": "I5E7IOHF4BD6PNI5ZFEPMH",
"status": "admin_review",
"updated_date": "2011-01-04 02:18:35",
"url": "https://customer.com",
"view_through_conversion_window": 30}}
Get the info for the newly created pixel (created along with the advertisable)¶
curl -H 'Authorization: Token YOUR_TOKEN' \
"https://services.adroll.com/api/v1/advertisable/get_pixel?apikey=MYAPIKEY&advertisable=MY_ADVERTISALE_EID"
{"results": {"code": "<script type="text/javascript">\n
adroll_adv_id = "6SHGRDIZUBDXLHUG4YHFGC";\n
adroll_pix_id = "XCOW5YUNQFGR5J5VSDITAX";\n
(function () {\n
var oldonload = window.onload;\n
window.onload = function(){\n
__adroll_loaded=true;\n
var scr = document.createElement("script");\n
var host = (("https:" == document.location.protocol) ? "https://localhost" : "https://localhost");\n
scr.setAttribute("async", "true");\n
scr.type = "text/javascript";\n
scr.src = host + "/j/roundtrip.js";\n
document.documentElement.firstChild.appendChild(scr);\n
if(oldonload){oldonload()}};\n
}());\n
</script>\n",
"eid": "XCOW5YUNQFGR5J5VSDITAX",
"status": "pending"}}
Get the new segment (created by the advertisable)¶
curl -H 'Authorization: Token YOUR_TOKEN' \
"https://services.adroll.com/api/v1/pixel/get_segments?apikey=MYAPIKEY&pixel=MY_ADVERTISALE_EID"
{"results": [{"duration_sec": 7776000,
"eid": "TJ5XB3USVBBMDCRNFBU2H3",
"conversion_value": null}]}
Create an additional rule to match users against¶
curl -H 'Authorization: Token YOUR_TOKEN' \
https://services.adroll.com/api/v1/rule/create?apikey=MYAPIKEY \
-F pixel=XCOW5YUNQFGR5J5VSDITAX \
-F type=s \
-F name=shopping_cart \
-F pattern=*/cart/ \
-F order=3 \
-F duration=60
{"results": {"name": "shopping_cart,
"eid": "4039IJRGINVWNO43WA2KDW",
"type": "s",
"order": 3,
"pattern": "*/cart/",
"segments": [{"name": "shopping_cart,
"duration": 60,
"duration_sec": 5184000,
"type": "s",
"eid": "IJ34IJR9JEVNVOOQWI90W0",
"pattern": "*/cart/",
"rule": "4039IJRGINVWNO43WA2KDW",
"conversion_value": null}]}
Create a conversion rule to match users against¶
curl -H 'Authorization: Token YOUR_TOKEN' \
https://services.adroll.com/api/v1/rule/create?apikey=MYAPIKEY \
-F pixel=XCOW5YUNQFGR5J5VSDITAX \
-F type=c \
-F name=converted \
-F pattern=*/checkout_complete/ \
-F order=2 \
-F duration=90
{"results": {"name": "converted,
"eid": "LJKEGNO3O30NDKSKLLW245",
"type": "c",
"order": 3,
"pattern": "*/checkout_complete/",
"segments": [{"name": "converted",
"duration": 90,
"duration_sec": 7776000,
"type": "c",
"eid": "O230V3IVOWVNIEOPLWMO2P",
"pattern": "*/checkout_complete/",
"rule": "LJKEGNO3O30NDKSKLLW245",
"conversion_value": null}]}
Create a new retargeting campaign¶
curl -H 'Authorization: Token YOUR_TOKEN' \
https://services.adroll.com/api/v1/campaign/create?apikey=MYAPIKEY \
-F advertisable=6SHGRDIZUBDXLHUG4YHFGC \
-F name="Test Campaign" \
-F start_date=2020-01-01 \
-F end_date=2020-02-28 \
-F budget=30.5
{"results": {"adgroups": [],
"advertisable": "V7PRCKI2ZRAEJMK4OLWF7I",
"is_retargeting": true,
"budget": 30.5,
"cpc": null,
"cpm": null,
"created_date": "2011-01-04 18:50:21",
"eid": "ZO245MTLPFGJ3E3CDJLCK4",
"end_date": "2020-02-28 00:00:00",
"name": "Test Campaign",
"start_date": "2020-01-01 00:00:00",
"status": "admin_review",
"updated_date": "2011-01-04 18:50:21"}}
Create a new AdGroup for the campaign¶
curl -H 'Authorization: Token YOUR_TOKEN' \
https://services.adroll.com/api/v1/adgroup/create?apikey=MYAPIKEY \
-F campaign=ZO245MTLPFGJ3E3CDJLCK4 \
-F name="Test AdGroup"
{"results": {"ad_optimization": "",
"campaign": "ZO245MTLPFGJ3E3CDJLCK4",
"created_date": "2011-01-04 18:52:45",
"eid": "RUXJF6GPBZDQLAUFVL7MII",
"geo_targets": [],
"name": "Test AdGroup",
"space_optimization": "",
"status": "approved",
"updated_date": "2011-01-04 18:52:45"}}
Upload an ad¶
curl -H 'Authorization: Token YOUR_TOKEN' \
https://services.adroll.com/api/v1/ad/create?apikey=MYAPIKEY \
-F advertisable=V7PRCKI2ZRAEJMK4OLWF7I \
-F name="Test Ad 728" \
-F destination_url=http://customer.com \
-F file=@ad1.jpg
{"results": {"ad_format": "728 wide x 90 high",
"ad_format_id": 3,
"ad_format_name": "728x90",
"adgroups": [],
"advertisable": "V7PRCKI2ZRAEJMK4OLWF7I",
"body": null,
"created_date": "2011-01-04 19:01:01",
"destination_url": "http://customer.com",
"eid": "OAX4PI4NWZBYHHEWI4TUJU",
"has_edits": false,
"has_future_campaigns": false,
"has_pending_edits": false,
"headline": null,
"height": 728,
"is_active": true,
"is_outlined": false,
"message": null,
"name": "Test Ad 728",
"original_ad": null,
"outline_color": null,
"src": "https://adroll-main-storage-west-2.s3.amazonaws.com/a/OAX/4PI/OAX4PI4NWZBYHHEWI4TUJU.jpg",
"status": "approved",
"type": "image",
"updated_date": "2011-01-04 19:01:01",
"valid_clicktag": null,
"width": 90}}
Upload another ad¶
curl -H 'Authorization: Token YOUR_TOKEN' \
https://services.adroll.com/api/v1/ad/create?apikey=MYAPIKEY \
-F advertisable=V7PRCKI2ZRAEJMK4OLWF7I \
-F name="Test Ad 160" \
-F destination_url=http://customer.com \
-F file=@ad2.jpg
{"results": {"ad_format": "728 wide x 90 high",
"ad_format_id": 3,
"ad_format_name": "728x90",
"adgroups": [],
"advertisable": "V7PRCKI2ZRAEJMK4OLWF7I",
"body": null,
"created_date": "2011-01-04 19:15:00",
"destination_url": "http://customer.com",
"eid": "FBUD7AQR7ZBNHHWQ7IOMWA",
"has_edits": false,
"has_future_campaigns": false,
"has_pending_edits": false,
"headline": null,
"height": 728,
"is_active": true,
"is_outlined": false,
"message": null,
"name": "Test Ad 728",
"original_ad": null,
"outline_color": null,
"src": "https://adroll-main-storage-west-2.s3.amazonaws.com/a/FBU/D7A/FBUD7AQR7ZBNHHWQ7IOMWA.jpg",
"status": "approved",
"type": "image",
"updated_date": "2011-01-04 19:15:00",
"valid_clicktag": null,
"width": 90}}
Attach both image ads to the new AdGroup¶
curl -H 'Authorization: Token YOUR_TOKEN' \
https://services.adroll.com/api/v1/adgroup/select_ads?apikey=MYAPIKEY \
-F adgroup=RUXJF6GPBZDQLAUFVL7MII \
-F ads=FBUD7AQR7ZBNHHWQ7IOMWA,OAX4PI4NWZBYHHEWI4TUJU
{"results": [{"ad": "FBUD7AQR7ZBNHHWQ7IOMWA", "errors": []},
{"ad": "OAX4PI4NWZBYHHEWI4TUJU", "errors": []}]}
Attach a retargeting segment to the new AdGroup¶
curl -H 'Authorization: Token YOUR_TOKEN' \
https://services.adroll.com/api/v1/adgroup/add_segments?apikey=MYAPIKEY \
-F adgroup=RUXJF6GPBZDQLAUFVL7MII \
-F segments=TJ5XB3USVBBMDCRNFBU2H3
{"results": true}
Exclude a converted segment from the new AdGroup¶
curl -H 'Authorization: Token YOUR_TOKEN' \
https://services.adroll.com/api/v1/adgroup/add_segments?apikey=MYAPIKEY \
-F adgroup=RUXJF6GPBZDQLAUFVL7MII \
-F segments=O230V3IVOWVNIEOPLWMO2P \
-F is_negative=True
{"results": true}
Fetch a report for the campaign¶
curl -H 'Authorization: Token YOUR_TOKEN' \
https://services.adroll.com/api/v1/report/campaign?apikey=MYAPIKEY \
-F campaigns=CEA4BUOVRNDJPDFVS6KTEP \
-F past_days=1 \
-F data_format=entity
{"results": [{"campaign": "My campaign 1",
"eid": "CEA4BUOVRNDJPDFVS6KTEP",
"advertiser": "My Advertisable",
"type": "Retargeting",
"status": "approved",
"created_date": "2010-02-23",
"start_date": "2010-02-23",
"end_date": null,
"budget": 3234.0,
"cpc": 1.0,
"ctr": 0.234,
"cpm": 2.34,
"cost": 500.00,
"impressions": 213675,
"clicks": 500,
"uniques": 6983}]}
Create a new run-of-network campaign with DMA geotargets¶
Create the campaign
curl -H 'Authorization: Token YOUR_TOKEN' \
https://services.adroll.com/api/v1/campaign/create?apikey=MYAPIKEY \
-F advertisable=6SHGRDIZUBDXLHUG4YHFGC \
-F name="Test Geo Campaign" \
-F start_date=2020-01-01 \
-F end_date=2020-02-28 \
-F budget=50
{"results": {"adgroups": [],
"advertisable": "V7PRCKI2ZRAEJMK4OLWF7I",
"budget": 30.5,
"cpc": null,
"cpm": null,
"created_date": "2011-01-04 18:50:21",
"eid": "PFL30SXLKA033IOPFHDJ9SAX",
"end_date": "2020-02-28 00:00:00",
"name": "Test Geo Campaign",
"start_date": "2020-01-01 00:00:00",
"status": "admin_review",
"updated_date": "2011-01-04 18:50:21"}}
Create the AdGroup
curl -H 'Authorization: Token YOUR_TOKEN' \
https://services.adroll.com/api/v1/adgroup/create?apikey=MYAPIKEY \
-F campaign=PFL30SXLKA033IOPFHDJ9SAX \
-F name="Test AdGroup"
{"results": {"ad_optimization": "",
"campaign": "PFL30SXLKA033IOPFHDJ9SAX",
"created_date": "2011-01-04 18:52:45",
"eid": "RUXJF6GPBZDQLAUFVL7MII",
"geo_targets": [],
"name": "Test AdGroup",
"space_optimization": "",
"status": "approved",
"updated_date": "2011-01-04 18:52:45"}}
Add geotargets for DMA’s in Alaska
curl -H 'Authorization: Token YOUR_TOKEN' \
https://services.adroll.com/api/v1/adgroup/add_geo_target?apikey=MYAPIKEY \
-F adgroup=RUXJF6GPBZDQLAUFVL7MII \
-F type="usmetro" \
-F targets="743,745,747"
{"results":true}
Enable Dynamic Creative for your Advertisable (Advanced)¶
Dynamic Creative is an effective way to produce personalized ads dynamically for both General Web and Facebook.
curl -H 'Authorization: Token YOUR_TOKEN' \
https://services.adroll.com/api/v1/advertisable/enable_rollcrawl?apikey=MYAPIKEY \
-F advertisable=6SHGRDIZUBDXLHUG4YHFGC \
-F url="http://customer.com/product_feed.xml"
{"results": true}