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 --user dev@example.com \
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 --user dev@example.com \
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 --user dev@example.com \
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 --user dev@example.com \
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 --user dev@example.com \
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 --user dev@example.com \
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 --user dev@example.com \
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 --user dev@example.com \
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 --user dev@example.com \
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 --user dev@example.com \
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 --user dev@example.com \
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 --user dev@example.com \
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 --user dev@example.com \
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 --user dev@example.com \
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 --user dev@example.com \
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 --user dev@example.com \
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 --user dev@example.com \
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 --user dev@example.com \
https://services.adroll.com/api/v1/advertisable/enable_rollcrawl?apikey=MYAPIKEY \
-F advertisable=6SHGRDIZUBDXLHUG4YHFGC                                           \
-F url="http://customer.com/product_feed.xml"
{"results": true}