AdRoll CRUD API Examples

The following examples use the tool cURL to submit requests to the AdRoll web service. This method was chosen for its ubiquity, clarity, and compact syntax. Your organization’s method for calling the AdRoll 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.

Get info for your organization (including EID)

curl https://johnny_api:password@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 https://johnny_api:password@services.adroll.com/api/v1/advertisable/create?apikey=MYAPIKEY \
-F name=Test                                                           \
-F organization=I5E7IOHF4BD6PNI5ZFEPMH                                 \
-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 https://johnny_api:password@services.adroll.com/api/v1/advertisable/get_pixel?apikey=MYAPIKEY \
-F advertisable=6SHGRDIZUBDXLHUG4YHFGC
{"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 https://johnny_api:password@services.adroll.com/api/v1/pixel/get_segments?apikey=MYAPIKEY \
-F pixel=XCOW5YUNQFGR5J5VSDITAX
{"results": [{"duration_sec": 7776000,
              "eid": "TJ5XB3USVBBMDCRNFBU2H3",
              "conversion_value": null}]}

Create an additional rule to match users against

curl https://johnny_api:password@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 https://johnny_api:password@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 https://johnny_api:password@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 https://johnny_api:password@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 https://johnny_api:password@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 https://johnny_api:password@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 https://johnny_api:password@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 https://johnny_api:password@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 https://johnny_api:password@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 https://johnny_api:password@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

  1. Create the campaign
curl https://johnny_api:password@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"}}
  1. Create the AdGroup
curl https://johnny_api:password@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"}}
  1. Add geotargets for DMA’s in Alaska
curl https://johnny_api:password@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 AdRoll’s system for creating and managing dynamic creatives. Dynamic Creative is an effective way to produce personalized ads dynamically for both General Web and Facebook. To enable Dynamic Creative, your AdRoll user account must be whitelisted. To learn more, please reach out to bizdev@adroll.com

curl https://johnny_api:password@services.adroll.com/api/v1/advertisable/enable_rollcrawl?apikey=MYAPIKEY \
-F advertisable=6SHGRDIZUBDXLHUG4YHFGC                                           \
-F url="http://customer.com/product_feed.xml"
{"results": true}