AdRoll CRUD API Examples

The following examples use the tool cURL to submit requests to the AdRoll webservice. This method was chosen for its ubiquity, clarity, and compact syntax. Your organization’s method for calling the AdRoll webservice will vary depending on programming language and operating system. The server response shown below each webservice 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@api.adroll.com/v1/organization/get
{"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@api.adroll.com/v1/advertisable/create \
-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@api.adroll.com/v1/advertisable/get_pixel \
-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@api.adroll.com/v1/pixel/get_segments \
-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@api.adroll.com/v1/rule/create \
-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@api.adroll.com/v1/rule/create \
-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@api.adroll.com/v1/campaign/create \
-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@api.adroll.com/v1/adgroup/create \
-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@api.adroll.com/v1/ad/create \
-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@api.adroll.com/v1/ad/create \
-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@api.adroll.com/v1/adgroup/select_ads \
-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@api.adroll.com/v1/adgroup/add_segments \
-F adgroup=RUXJF6GPBZDQLAUFVL7MII                                       \
-F segments=TJ5XB3USVBBMDCRNFBU2H3
{"results": true}

Exclude a converted segment from the new AdGroup

curl https://johnny_api:password@api.adroll.com/v1/adgroup/add_segments \
-F adgroup=RUXJF6GPBZDQLAUFVL7MII                                       \
-F segments=O230V3IVOWVNIEOPLWMO2P                                      \
-F is_negative=True
{"results": true}

Fetch a report for the campaign

curl https://johnny_api:password@api.adroll.com/v1/report/campaign \
-F campaigns=CEA4BUOVRNDJPDFVS6KTEP                                \
-F past_days=1                                                     \
-F data_format=entities
{"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 Facebook (Right-hand side) retargeting campaign

curl https://johnny_api:password@api.adroll.com/v1/campaign/create \
-F advertisable=6SHGRDIZUBDXLHUG4YHFGC                             \
-F name="Test RHS Campaign"                                        \
-F networks="f"                                                    \
-F start_date=2013-12-10                                           \
-F end_date=2014-02-14                                             \
-F budget=500.00
{"results": {"adgroups": [],
             "advertisable": "6SHGRDIZUBDXLHUG4YHFGC",
             "budget": 500.00,
             "cpc": null,
             "cpm": null,
             "created_date": "2011-01-04 18:50:21",
             "eid": "HF29VUJNV39CIKSMMGE217",
             "end_date": "2013-12-10 00:00:00",
             "is_active": true,
             "is_facebook": true,
             "is_fbx_newsfeed": false,
             "is_retargeting": true,
             "max_cpm": null,
             "name": "Test RHS Campaign",
             "start_date": "2014-02-14 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@api.adroll.com/v1/adgroup/create \
-F campaign=HF29VUJNV39CIKSMMGE217                                \
-F name="Test AdGroup"
{"results": {"ad_optimization": "",
             "campaign": "ZO245MTLPFGJ3E3CDJLCK4",
             "created_date": "2011-01-04 18:52:45",
             "eid": "24IU3G9VUJVIISG02XLKQ0",
             "geo_targets": [],
             "name": "Test AdGroup",
             "segments": [],
             "site_exclusions": [],
             "space_optimization": "",
             "status": "approved",
             "updated_date": "2011-01-04 18:52:45"}}

Upload a Facebook ad (RHS)

curl https://johnny_api:password@api.adroll.com/v1/ad/create \
-F advertisable=V7PRCKI2ZRAEJMK4OLWF7I                       \
-F name="Test Ad FB RHS"                                     \
-F destination_url=http://customer.com/fb                    \
-F headline="My excellent ad"                                \
-F body="This is a pretty fantastic Facebook ad!"            \
-F file=@fb_ad_rhs.jpg
{"results": {"ad_format": "100 wide x 72 high",
             "ad_format_id": 19,
             "ad_format_name": "100x72",
             "adgroups": [],
             "advertisable": "V7PRCKI2ZRAEJMK4OLWF7I",
             "body": "This is a pretty fantastic Facebook ad!",
             "created_date": "2011-01-04 19:19:52",
             "destination_url": "http://customer.com/fb",
             "eid": "JKASD93NVUN3ENNCWOCM2D",
             "has_edits": false,
             "has_future_campaigns": false,
             "has_pending_edits": false,
             "headline": "My excellent ad",
             "height": 100,
             "is_active": true,
             "is_outlined": false,
             "message": null,
             "name": "Test Ad FB RHS",
             "original_ad": null,
             "outline_color": null,
             "src": "https://adroll-main-storage-west-2.s3.amazonaws.com/a/FBU/D7A/JKASD93NVUN3ENNCWOCM2D.jpg",
             "status": "approved",
             "type": "image",
             "updated_date": "2011-01-04 19:19:52",
             "valid_clicktag": null,
             "width": 72}}

Create a new Facebook (Newsfeed) retargeting campaign

curl https://johnny_api:password@api.adroll.com/v1/campaign/create \
-F advertisable=6SHGRDIZUBDXLHUG4YHFGC                             \
-F name="Test Newsfeed Campaign"                                   \
-F networks="f"                                                    \
-F is_fbx_newsfeed="true"                                          \
-F start_date=2013-12-10                                           \
-F end_date=2014-02-14                                             \
-F budget=500.00
{"results": {"adgroups": [],
             "advertisable": "6SHGRDIZUBDXLHUG4YHFGC",
             "budget": 500.00,
             "cpc": null,
             "cpm": null,
             "created_date": "2011-01-04 18:50:21",
             "eid": "38RGJO3VJEIC39032LLDJN",
             "end_date": "2013-12-10 00:00:00",
             "is_active": true,
             "is_facebook": true,
             "is_fbx_newsfeed": true,
             "is_retargeting": true,
             "max_cpm": null,
             "name": "Test Newsfeed Campaign",
             "start_date": "2014-02-14 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@api.adroll.com/v1/adgroup/create \
-F campaign=38RGJO3VJEIC39032LLDJN                                \
-F name="Test AdGroup"
{"results": {"ad_optimization": "",
             "campaign": "ZO245MTLPFGJ3E3CDJLCK4",
             "created_date": "2011-01-04 18:52:45",
             "eid": "LWNVERJNBIU340J3RJQFGH",
             "geo_targets": [],
             "name": "Test AdGroup",
             "segments": [],
             "site_exclusions": [],
             "space_optimization": "",
             "status": "approved",
             "updated_date": "2011-01-04 18:52:45"}}

Upload a Facebook ad (Newsfeed)

curl https://johnny_api:password@api.adroll.com/v1/ad/create \
-F advertisable=V7PRCKI2ZRAEJMK4OLWF7I                       \
-F name="Test Ad FB Newsfeed"                                \
-F destination_url=http://customer.com/fb                    \
-F headline="My excellent ad"                                \
-F body="This is a pretty fantastic Facebook ad!"            \
-F message="It even has a message!"                          \
-F file=@fb_ad_nf.jpg
{"results": {"ad_format": "90 wide x 90 high",
             "ad_format_id": 14,
             "ad_format_name": "90x90",
             "adgroups": [],
             "advertisable": "V7PRCKI2ZRAEJMK4OLWF7I",
             "body": "This is a pretty fantastic Facebook ad!",
             "created_date": "2011-01-04 19:23:40",
             "destination_url": "http://customer.com/fb",
             "eid": "NF4KDF98VN3JV3G4VOCJ39",
             "has_edits": false,
             "has_future_campaigns": false,
             "has_pending_edits": false,
             "headline": "My excellent ad",
             "height": 90,
             "is_active": true,
             "is_outlined": false,
             "message": "It even has a message!",
             "name": "Test Ad FB Newsfeed",
             "original_ad": null,
             "outline_color": null,
             "src": "https://adroll-main-storage-west-2.s3.amazonaws.com/a/FBU/D7A/NF4KDF98VN3JV3G4VOCJ39.jpg",
             "status": "approved",
             "type": "image",
             "updated_date": "2011-01-04 19:23:40",
             "valid_clicktag": null,
             "width": 90}}

Create a new run-of-network campaign with DMA geotargets

  1. Create the campaign
curl https://johnny_api:password@api.adroll.com/v1/campaign/create \
-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@api.adroll.com/v1/adgroup/create   \
-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@api.adroll.com/v1/adgroup/add_geo_target \
-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@api.adroll.com/v1/advertisable/enable_rollcrawl \
-F advertisable=6SHGRDIZUBDXLHUG4YHFGC                                           \
-F url="http://customer.com/product_feed.xml"
{"results": true}