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.

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 \
-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 -H 'Authorization: Token YOUR_TOKEN' \
https://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 -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

  1. 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"}}
  1. 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"}}
  1. 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}