# index.html.md
# NextRoll API Documentation
## Get Started
To get started, [check out our guide](guides/get-started.md#guide-get-started).
AdRoll ABM (formerly RollWorks) customer? Check out our [API guide for AdRoll ABM customers](guides/get-started-rollworks.md#guide-get-started-rollworks).
## Overview
The NextRoll API allows you to build marketing technology solutions that enable you to drive more demand for your customers and create new revenue streams.
The NextRoll API is divided into several services, each with its own focus:
[CRUD API](crud-api/index.md#crud-api-index)
: Provides most of the functionality found in the dashboard. You can manage campaigns, advertisements, pixels and more.
[GraphQL Reporting API](graphql-reporting-api/index.md#graphql-reporting-api-index)
: Provides access to all reporting data so you can generate your own reports.
[Audience API](audience-api/index.md#audience-api-index)
: The Audience API allows you to create and update [CRM segments](https://help.adroll.com/hc/en-us/articles/211845528).
[User Lists API](user-lists-api/index.md#user-lists-api-index)
: The User Lists API allows you to retrieve the size of your audiences.
[Prospecting API](prospecting-api/index.md#prospecting-api-index)
: Prospecting attracts new audiences.
[Geotargeting API](geotargeting-api/index.md#geotargeting-api-index)
: Search for geotargeting EIDs that are used when setting geotargets on your campaigns
[Site Traffic Revealer](site-traffic-revealer/index.md#site-traffic-revealer-index)
: Provides firmographic data about the site visitor. It’s a JavaScript API.
[Server-to-Server (S2S) API](server-to-server-api/index.md#s2s-api-index)
: Allows you directly send events to complement pixel and MMP events.
## Contents
* [Developer Home](https://developers.nextroll.com/)
* [CRUD API](crud-api/index.md)
* [Overview](crud-api/overview.md)
* [Usage](crud-api/api-usage.md)
* [Example API calls](crud-api/examples.md)
* [API Reference](crud-api/reference.md)
* [GraphQL Reporting API](graphql-reporting-api/index.md)
* [Overview](graphql-reporting-api/overview.md)
* [GraphQL Schema](graphql-reporting-api/schema.md)
* [API Reference](graphql-reporting-api/reference.md)
* [Examples](graphql-reporting-api/examples.md)
* [Migrate from the Reporting API](graphql-reporting-api/reporting-api-migration.md)
* [Audience API](audience-api/index.md)
* [Overview](audience-api/overview.md)
* [Examples](audience-api/examples/index.md)
* [API Reference](audience-api/reference.md)
* [Prospecting API](prospecting-api/index.md)
* [Overview](prospecting-api/overview.md)
* [Examples](prospecting-api/examples.md)
* [API Reference](prospecting-api/reference.md)
* [Automated Campaigns API](automated-campaigns-api/index.md)
* [Overview](automated-campaigns-api/overview.md)
* [Examples](automated-campaigns-api/examples.md)
* [API Reference](automated-campaigns-api/reference.md)
* [Universal Campaigns API](universal-campaigns-api/index.md)
* [Overview](universal-campaigns-api/overview.md)
* [Examples](universal-campaigns-api/examples.md)
* [API Reference](universal-campaigns-api/reference.md)
* [User Lists API](user-lists-api/index.md)
* [Overview](user-lists-api/overview.md)
* [Examples](user-lists-api/examples.md)
* [API Reference](user-lists-api/reference.md)
* [Geotargeting API](geotargeting-api/index.md)
* [Overview](geotargeting-api/overview.md)
* [Examples](geotargeting-api/examples.md)
* [API Reference](geotargeting-api/reference.md)
* [Site Traffic Revealer](site-traffic-revealer/index.md)
* [Overview](site-traffic-revealer/overview.md)
* [Examples](site-traffic-revealer/examples.md)
* [Server-to-Server (S2S) API](server-to-server-api/index.md)
* [Overview](server-to-server-api/overview.md)
* [Events](server-to-server-api/events.md)
* [API Reference](server-to-server-api/reference.md)
* [Guides](guides/index.md)
* [Get Started with the NextRoll API](guides/get-started.md)
* [AdRoll ABM API Documentation](guides/get-started-rollworks.md)
* [Get to know NextRoll](guides/object-structure.md)
* [Get Started with OAuth 2.0](guides/oauth.md)
* [Creating Web Ads](guides/create-web-ads.md)
* [Creating Audiences](guides/create-audiences.md)
* [Setup Product Feeds for Dynamic Creative](guides/product-feed-setup.md)
* [Create Your First Prospecting Campaign](guides/create-prospecting-campaign.md)
* [Manage External Data Segments](guides/external-segments.md)
* [Migrating to API Keys](guides/api-key-migration.md)
* [Reporting Platforms Guide](guides/reporting-platforms.md)
* [Marketing Platforms Guide](guides/marketing-platforms.md)
* [Marketplaces Guide](guides/marketplace-integration.md)
* [Publishers Guide](guides/publishers.md)
* [Integration guide for E-commerce Platforms](guides/ecommerce-integration.md)
* [Access AdRoll ABM Account Metrics](guides/account-metrics.md)
* [Manage Target Account Lists](guides/target-account-lists.md)
* [Working with AdRoll ABM Playbooks](guides/rollworks-playbooks.md)
* [Pixel JavaScript API](guides/pixel-javascript-api.md)
* [Developer Site Migration](guides/developer-site-migration.md)
* [Manage Product Sets](guides/product-sets.md)
* [Share Audiences](guides/audience-sharing.md)
* [Frequently Asked Questions](faq.md)
* [When does reporting data become available?](faq.md#when-does-reporting-data-become-available)
* [How to use display_url_override parameter?](faq.md#how-to-use-display-url-override-parameter)
* [How can I tell if an ad has been deleted?](faq.md#how-can-i-tell-if-an-ad-has-been-deleted)
* [Is there a limit to the size of GraphQL queries?](faq.md#is-there-a-limit-to-the-size-of-graphql-queries)
* [Support](support.md)
* [Technical Request](support.md#technical-request)
* [Rate limit increase](support.md#rate-limit-increase)
## Indices and tables
* [HTTP Routing Table](http-routingtable.md)
* [Index](genindex.md)
* [Search Page](search.md)
# index.html.md
# Audience API
* [Overview](overview.md)
* [Authentication](overview.md#authentication)
* [Segment Types](overview.md#segment-types)
* [Segment Response](overview.md#segment-response)
* [User Record](overview.md#user-record)
* [User Record examples](overview.md#user-record-examples)
* [Examples](examples/index.md)
* [Guides](examples/guides.md)
* [Target Account List Examples](examples/tal.md)
* [List all Target Account Lists](examples/tal.md#list-all-target-account-lists)
* [List all accounts in a Target Account List](examples/tal.md#list-all-accounts-in-a-target-account-list)
* [Add new accounts to a Target Account List](examples/tal.md#add-new-accounts-to-a-target-account-list)
* [Remove accounts from a Target Account List](examples/tal.md#remove-accounts-from-a-target-account-list)
* [API Reference](reference.md)
* [Description](reference.md#description)
* [Operations by Tag](reference.md#operations-by-tag)
* [Target Account Lists](reference.md#target-account-lists)
* [Untagged](reference.md#untagged)
* [Operations](reference.md#operations)
* [Definitions](reference.md#definitions)
# index.html.md
# Automated Campaigns API
#### WARNING
The Automated Campaigns API will be retired April 2025.
* [Overview](overview.md)
* [Authentication](overview.md#authentication)
* [Service Walkthrough](overview.md#service-walkthrough)
* [Examples](examples.md)
* [Create a Strategy](examples.md#create-a-strategy)
* [Fetch a Strategy](examples.md#fetch-a-strategy)
* [Fetch Campaigns for a Strategy](examples.md#fetch-campaigns-for-a-strategy)
* [API Reference](reference.md)
* [Description](reference.md#description)
* [List of Operations](reference.md#list-of-operations)
* [Operations](reference.md#operations)
* [Definitions](reference.md#definitions)
# index.html.md
# CRUD API
* [Overview](overview.md)
* [Authentication](overview.md#authentication)
* [Getting Started](overview.md#getting-started)
* [Service Walkthrough](overview.md#service-walkthrough)
* [Usage](api-usage.md)
* [REST Semantics](api-usage.md#rest-semantics)
* [Request Headers](api-usage.md#request-headers)
* [Response Values](api-usage.md#response-values)
* [Errors](api-usage.md#errors)
* [Data Types](api-usage.md#data-types)
* [Statuses](api-usage.md#statuses)
* [Example API calls](examples.md)
* [Get info for your organization (including EID)](examples.md#get-info-for-your-organization-including-eid)
* [Create an advertisable](examples.md#create-an-advertisable)
* [Get the info for the newly created pixel (created along with the advertisable)](examples.md#get-the-info-for-the-newly-created-pixel-created-along-with-the-advertisable)
* [Get the new segment (created by the advertisable)](examples.md#get-the-new-segment-created-by-the-advertisable)
* [Create an additional rule to match users against](examples.md#create-an-additional-rule-to-match-users-against)
* [Create a conversion rule to match users against](examples.md#create-a-conversion-rule-to-match-users-against)
* [Create a new retargeting campaign](examples.md#create-a-new-retargeting-campaign)
* [Create a new AdGroup for the campaign](examples.md#create-a-new-adgroup-for-the-campaign)
* [Upload an ad](examples.md#upload-an-ad)
* [Upload another ad](examples.md#upload-another-ad)
* [Attach both image ads to the new AdGroup](examples.md#attach-both-image-ads-to-the-new-adgroup)
* [Attach a retargeting segment to the new AdGroup](examples.md#attach-a-retargeting-segment-to-the-new-adgroup)
* [Exclude a converted segment from the new AdGroup](examples.md#exclude-a-converted-segment-from-the-new-adgroup)
* [Fetch a report for the campaign](examples.md#fetch-a-report-for-the-campaign)
* [Create a new run-of-network campaign with DMA geotargets](examples.md#create-a-new-run-of-network-campaign-with-dma-geotargets)
* [Enable Dynamic Creative for your Advertisable (Advanced)](examples.md#enable-dynamic-creative-for-your-advertisable-advanced)
* [API Reference](reference.md)
* [Description](reference.md#description)
* [Operations by Tag](reference.md#operations-by-tag)
* [Ad](reference.md#ad)
* [Adgroup](reference.md#adgroup)
* [Advertisable](reference.md#advertisable)
* [Advertisable Logo](reference.md#advertisable-logo)
* [Campaign](reference.md#campaign)
* [Consent Banner](reference.md#consent-banner)
* [Contextual Categories](reference.md#contextual-categories)
* [Dynamic Configuration](reference.md#dynamic-configuration)
* [Dynamic Template](reference.md#dynamic-template)
* [Dynamic Template Capability Description](reference.md#dynamic-template-capability-description)
* [Feed](reference.md#feed)
* [Invoice](reference.md#invoice)
* [Marketplace](reference.md#marketplace)
* [Marketplace Deals](reference.md#marketplace-deals)
* [Organization](reference.md#organization)
* [Pixel](reference.md#pixel)
* [Policy](reference.md#policy)
* [Product Feeds](reference.md#product-feeds)
* [Report](reference.md#report)
* [Rule](reference.md#rule)
* [Segment](reference.md#segment)
* [Untagged](reference.md#untagged)
* [User](reference.md#user)
* [Xdevice Opt In](reference.md#xdevice-opt-in)
* [Operations](reference.md#operations)
# index.html.md
# Geotargeting API
* [Overview](overview.md)
* [Authentication](overview.md#authentication)
* [Examples](examples.md)
* [Search for a geotarget](examples.md#search-for-a-geotarget)
* [Attach a GeoTarget to an AdGroup](examples.md#attach-a-geotarget-to-an-adgroup)
* [API Reference](reference.md)
* [Description](reference.md#description)
* [List of Operations](reference.md#list-of-operations)
* [Operations](reference.md#operations)
* [Definitions](reference.md#definitions)
# index.html.md
# GraphQL Reporting API
* [Overview](overview.md)
* [What is GraphQL?](overview.md#what-is-graphql)
* [Authentication](overview.md#authentication)
* [Getting Started](overview.md#getting-started)
* [Your First Query](overview.md#your-first-query)
* [Error Handling](overview.md#error-handling)
* [Error Response Structure](overview.md#error-response-structure)
* [Basic Error Handling](overview.md#basic-error-handling)
* [Example Error Response](overview.md#example-error-response)
* [Error Propagation](overview.md#error-propagation)
* [Troubleshooting](overview.md#troubleshooting)
* [Best Practices](overview.md#best-practices)
* [GraphQL Schema](schema.md)
* [Objects](schema.md#objects)
* [List](schema.md#list)
* [Descriptions](schema.md#descriptions)
* [Scalars](schema.md#scalars)
* [List](schema.md#id2)
* [Descriptions](schema.md#id3)
* [API Reference](reference.md)
* [Description](reference.md#description)
* [List of Operations](reference.md#list-of-operations)
* [Operations](reference.md#operations)
* [Definitions](reference.md#definitions)
* [Examples](examples.md)
* [List of Advertisables for your Organization](examples.md#list-of-advertisables-for-your-organization)
* [List of Campaigns for an Advertisable](examples.md#list-of-campaigns-for-an-advertisable)
* [Delivery and Attribution data for all Campaigns](examples.md#delivery-and-attribution-data-for-all-campaigns)
* [Delivery and Attribution data for a Campaign](examples.md#delivery-and-attribution-data-for-a-campaign)
* [Delivery and Attribution data for an AdGroup](examples.md#delivery-and-attribution-data-for-an-adgroup)
* [Delivery and Attribution data for an Ad](examples.md#delivery-and-attribution-data-for-an-ad)
* [Connected TV Campaign Metrics](examples.md#connected-tv-campaign-metrics)
* [Granular Conversions for an Advertisable](examples.md#granular-conversions-for-an-advertisable)
* [Migrate from the Reporting API](reporting-api-migration.md)
* [Helpful tips](reporting-api-migration.md#helpful-tips)
* [Replacement GraphQL queries](reporting-api-migration.md#replacement-graphql-queries)
* [Metrics by Advertisable](reporting-api-migration.md#metrics-by-advertisable)
* [Metrics by Campaign](reporting-api-migration.md#metrics-by-campaign)
* [Metrics by AdGroup](reporting-api-migration.md#metrics-by-adgroup)
* [Metrics by Ad](reporting-api-migration.md#metrics-by-ad)
* [Metrics by Delivery Account](reporting-api-migration.md#metrics-by-delivery-account)
* [Granular Conversions](reporting-api-migration.md#granular-conversions)
# index.html.md
# Guides
* [Get Started with the NextRoll API](get-started.md)
* [Register as a Developer](get-started.md#register-as-a-developer)
* [Base URL](get-started.md#base-url)
* [Authentication](get-started.md#authentication)
* [OAuth 2.0](get-started.md#oauth-2-0)
* [Personal Access Tokens](get-started.md#personal-access-tokens)
* [Your First API Call](get-started.md#your-first-api-call)
* [Next Steps](get-started.md#next-steps)
* [AdRoll ABM API Documentation](get-started-rollworks.md)
* [Available APIs](get-started-rollworks.md#available-apis)
* [Site Traffic Revealer](get-started-rollworks.md#site-traffic-revealer)
* [Reporting API](get-started-rollworks.md#reporting-api)
* [Playbooks API](get-started-rollworks.md#playbooks-api)
* [Target Account List API](get-started-rollworks.md#target-account-list-api)
* [Account Metrics API](get-started-rollworks.md#account-metrics-api)
* [Email Contact List API](get-started-rollworks.md#email-contact-list-api)
* [Get to know NextRoll](object-structure.md)
* [Terminology](object-structure.md#terminology)
* [Get Started with OAuth 2.0](oauth.md)
* [Endpoints](oauth.md#endpoints)
* [Supported Grant Types](oauth.md#supported-grant-types)
* [Supported Scopes](oauth.md#supported-scopes)
* [Token Lifetime](oauth.md#token-lifetime)
* [Making Authenticated Requests](oauth.md#making-authenticated-requests)
* [Authorization Request Header](oauth.md#authorization-request-header)
* [Form-Encoded Body Parameter](oauth.md#form-encoded-body-parameter)
* [URL Query Parameter](oauth.md#url-query-parameter)
* [Your First API Call](oauth.md#your-first-api-call)
* [Python](oauth.md#python)
* [Node.js](oauth.md#node-js)
* [Outline for a server to server integration](oauth.md#outline-for-a-server-to-server-integration)
* [Creating Web Ads](create-web-ads.md)
* [Static Web Ads](create-web-ads.md#static-web-ads)
* [Native Ads](create-web-ads.md#native-ads)
* [Dynamic Native Ads](create-web-ads.md#dynamic-native-ads)
* [Dynamic Web Ads](create-web-ads.md#dynamic-web-ads)
* [Upload a Logo](create-web-ads.md#upload-a-logo)
* [Create the Dynamic Web Ads](create-web-ads.md#create-the-dynamic-web-ads)
* [Retrieve List of Dynamic Web Templates](create-web-ads.md#retrieve-list-of-dynamic-web-templates)
* [Retrieve List of Dynamic Web Templates Capabilities](create-web-ads.md#retrieve-list-of-dynamic-web-templates-capabilities)
* [Dynamic Web Templates](create-web-ads.md#dynamic-web-templates)
* [Classic Spotlight](create-web-ads.md#classic-spotlight)
* [Classic carousel](create-web-ads.md#classic-carousel)
* [Duotone carousel](create-web-ads.md#duotone-carousel)
* [Holiday spotlight](create-web-ads.md#holiday-spotlight)
* [Holiday carousel](create-web-ads.md#holiday-carousel)
* [Valentine carousel](create-web-ads.md#valentine-carousel)
* [Valentine spotlight](create-web-ads.md#valentine-spotlight)
* [Fall carousel](create-web-ads.md#fall-carousel)
* [Fall spotlight](create-web-ads.md#fall-spotlight)
* [Black Friday carousel](create-web-ads.md#black-friday-carousel)
* [Cyber Monday carousel](create-web-ads.md#cyber-monday-carousel)
* [Holiday Bow carousel](create-web-ads.md#holiday-bow-carousel)
* [Holiday Sparkle carousel](create-web-ads.md#holiday-sparkle-carousel)
* [Valentine 2018 spotlight](create-web-ads.md#valentine-2018-spotlight)
* [Valentine 2018 carousel](create-web-ads.md#valentine-2018-carousel)
* [Product Gladiator](create-web-ads.md#product-gladiator)
* [Spring Stripes](create-web-ads.md#spring-stripes)
* [Summer Polka Dots](create-web-ads.md#summer-polka-dots)
* [Summer Beach](create-web-ads.md#summer-beach)
* [Creating Audiences](create-audiences.md)
* [URL](create-audiences.md#url)
* [CRM](create-audiences.md#crm)
* [Partner](create-audiences.md#partner)
* [External Data](create-audiences.md#external-data)
* [Attribute](create-audiences.md#attribute)
* [Composite](create-audiences.md#composite)
* [CrossChannel Lookalike](create-audiences.md#crosschannel-lookalike)
* [Setup Product Feeds for Dynamic Creative](product-feed-setup.md)
* [Register product feeds](product-feed-setup.md#register-product-feeds)
* [Automatic Setup](product-feed-setup.md#automatic-setup)
* [Manual Setup](product-feed-setup.md#manual-setup)
* [Add your first feed configuration](product-feed-setup.md#add-your-first-feed-configuration)
* [Edit your feed configuration](product-feed-setup.md#edit-your-feed-configuration)
* [Add Parser Configurations](product-feed-setup.md#add-parser-configurations)
* [Capture product views and actions](product-feed-setup.md#capture-product-views-and-actions)
* [Verify product feed set up](product-feed-setup.md#verify-product-feed-set-up)
* [Create Your First Prospecting Campaign](create-prospecting-campaign.md)
* [Create a campaign](create-prospecting-campaign.md#create-a-campaign)
* [Add AdGroups to your campaign](create-prospecting-campaign.md#add-adgroups-to-your-campaign)
* [Add an audience to your AdGroups (Optional)](create-prospecting-campaign.md#add-an-audience-to-your-adgroups-optional)
* [Add flights to your AdGroups (Optional)](create-prospecting-campaign.md#add-flights-to-your-adgroups-optional)
* [Manage External Data Segments](external-segments.md)
* [Create the segment](external-segments.md#create-the-segment)
* [Retrieve the segment](external-segments.md#retrieve-the-segment)
* [Update the segment](external-segments.md#update-the-segment)
* [Delete the segment](external-segments.md#delete-the-segment)
* [External Data Expressions](external-segments.md#external-data-expressions)
* [Migrating to API Keys](api-key-migration.md)
* [Background](api-key-migration.md#background)
* [Migration Instructions](api-key-migration.md#migration-instructions)
* [Reporting Platforms Guide](reporting-platforms.md)
* [Get to know the NextRoll API](reporting-platforms.md#get-to-know-the-nextroll-api)
* [AdRoll and AdRoll ABM similarities](reporting-platforms.md#adroll-and-adroll-abm-similarities)
* [AdRoll ABM differences](reporting-platforms.md#adroll-abm-differences)
* [Authentication](reporting-platforms.md#authentication)
* [Retrieve Metrics](reporting-platforms.md#retrieve-metrics)
* [Advertisables for user](reporting-platforms.md#advertisables-for-user)
* [Metrics for Advertisables](reporting-platforms.md#metrics-for-advertisables)
* [Metrics for Campaigns](reporting-platforms.md#metrics-for-campaigns)
* [AdGroup metrics for a campaign](reporting-platforms.md#adgroup-metrics-for-a-campaign)
* [Ad metrics for a campaign](reporting-platforms.md#ad-metrics-for-a-campaign)
* [Account metrics for a campaign](reporting-platforms.md#account-metrics-for-a-campaign)
* [Optimizing queries](reporting-platforms.md#optimizing-queries)
* [Paginate your queries](reporting-platforms.md#paginate-your-queries)
* [Reusable queries](reporting-platforms.md#reusable-queries)
* [Marketing Platforms Guide](marketing-platforms.md)
* [Getting to know the NextRoll API](marketing-platforms.md#getting-to-know-the-nextroll-api)
* [Overview](marketing-platforms.md#overview)
* [Organization Setup](marketing-platforms.md#organization-setup)
* [Onboarding a Customer](marketing-platforms.md#onboarding-a-customer)
* [Creating an Advertisable](marketing-platforms.md#creating-an-advertisable)
* [Pixel Setup](marketing-platforms.md#pixel-setup)
* [Enhanced Conversion Tracking](marketing-platforms.md#enhanced-conversion-tracking)
* [Cross-Device Targeting](marketing-platforms.md#cross-device-targeting)
* [Create Ads](marketing-platforms.md#create-ads)
* [Define Audiences](marketing-platforms.md#define-audiences)
* [Launching a Campaign](marketing-platforms.md#launching-a-campaign)
* [Campaign Management](marketing-platforms.md#campaign-management)
* [Pausing the Campaign](marketing-platforms.md#pausing-the-campaign)
* [Resuming the Campaign](marketing-platforms.md#resuming-the-campaign)
* [Generating Reports](marketing-platforms.md#generating-reports)
* [Offboarding a Customer](marketing-platforms.md#offboarding-a-customer)
* [Marketplaces Guide](marketplace-integration.md)
* [Getting to know the NextRoll API](marketplace-integration.md#getting-to-know-the-nextroll-api)
* [Definition Of Terms](marketplace-integration.md#definition-of-terms)
* [Overview](marketplace-integration.md#overview)
* [Organization Setup](marketplace-integration.md#organization-setup)
* [Pixel Setup](marketplace-integration.md#pixel-setup)
* [Marketplace Mapping](marketplace-integration.md#marketplace-mapping)
* [Enhanced Conversion Tracking](marketplace-integration.md#enhanced-conversion-tracking)
* [Cross-Device Targeting](marketplace-integration.md#cross-device-targeting)
* [Onboarding a Merchant](marketplace-integration.md#onboarding-a-merchant)
* [Creating an Account](marketplace-integration.md#creating-an-account)
* [Configure Marketplace Mapping](marketplace-integration.md#configure-marketplace-mapping)
* [Adding a Product Feed](marketplace-integration.md#adding-a-product-feed)
* [Create Ads](marketplace-integration.md#create-ads)
* [Defining Audiences](marketplace-integration.md#defining-audiences)
* [Launching a Campaign](marketplace-integration.md#launching-a-campaign)
* [Campaign Management](marketplace-integration.md#campaign-management)
* [Pause the Campaign](marketplace-integration.md#pause-the-campaign)
* [Resume the Campaign](marketplace-integration.md#resume-the-campaign)
* [Generate Reports](marketplace-integration.md#generate-reports)
* [Offboarding a Merchant](marketplace-integration.md#offboarding-a-merchant)
* [Variations](marketplace-integration.md#variations)
* [Website per Merchant](marketplace-integration.md#website-per-merchant)
* [Publishers Guide](publishers.md)
* [Getting to know the NextRoll API](publishers.md#getting-to-know-the-nextroll-api)
* [Overview](publishers.md#overview)
* [Organization Setup](publishers.md#organization-setup)
* [Pixel Setup](publishers.md#pixel-setup)
* [Enhanced Conversion Tracking](publishers.md#enhanced-conversion-tracking)
* [Cross-Device Targeting](publishers.md#cross-device-targeting)
* [Onboarding a Customer](publishers.md#onboarding-a-customer)
* [Define Audiences](publishers.md#define-audiences)
* [Creating an Advertisable](publishers.md#creating-an-advertisable)
* [Create Ads](publishers.md#create-ads)
* [Launching a Campaign](publishers.md#launching-a-campaign)
* [Campaign Management](publishers.md#campaign-management)
* [Pause the Campaign](publishers.md#pause-the-campaign)
* [Resume the Campaign](publishers.md#resume-the-campaign)
* [Generate Reports](publishers.md#generate-reports)
* [Offboarding a Customer](publishers.md#offboarding-a-customer)
* [Integration guide for E-commerce Platforms](ecommerce-integration.md)
* [Get to know the NextRoll API](ecommerce-integration.md#get-to-know-the-nextroll-api)
* [Overview](ecommerce-integration.md#overview)
* [Connect using OAuth](ecommerce-integration.md#connect-using-oauth)
* [Retrieve the Pixel](ecommerce-integration.md#retrieve-the-pixel)
* [Place the Pixel](ecommerce-integration.md#place-the-pixel)
* [Enhanced Conversion Tracking](ecommerce-integration.md#enhanced-conversion-tracking)
* [Cross Device Targeting](ecommerce-integration.md#cross-device-targeting)
* [Link to Onboarding Flow](ecommerce-integration.md#link-to-onboarding-flow)
* [Conclusion](ecommerce-integration.md#conclusion)
* [Access AdRoll ABM Account Metrics](account-metrics.md)
* [Get to know the NextRoll API](account-metrics.md#get-to-know-the-nextroll-api)
* [Authentication](account-metrics.md#authentication)
* [Retrieve account metrics](account-metrics.md#retrieve-account-metrics)
* [Manage Target Account Lists](target-account-lists.md)
* [Get to know Target Account Lists](target-account-lists.md#get-to-know-target-account-lists)
* [Retrieve all Target Account Lists](target-account-lists.md#retrieve-all-target-account-lists)
* [Retrieve the Accounts in a Target Account List](target-account-lists.md#retrieve-the-accounts-in-a-target-account-list)
* [Add an Account to a Target Account List](target-account-lists.md#add-an-account-to-a-target-account-list)
* [Remove an Account from a Target Account List](target-account-lists.md#remove-an-account-from-a-target-account-list)
* [Working with AdRoll ABM Playbooks](rollworks-playbooks.md)
* [Playbook reporting](rollworks-playbooks.md#playbook-reporting)
* [Retrieve Playbook objects](rollworks-playbooks.md#retrieve-playbook-objects)
* [Pixel JavaScript API](pixel-javascript-api.md)
* [Overview](pixel-javascript-api.md#overview)
* [Prerequisites](pixel-javascript-api.md#prerequisites)
* [Tracking Events](pixel-javascript-api.md#tracking-events)
* [Basic Event Tracking](pixel-javascript-api.md#basic-event-tracking)
* [Event with Product Data](pixel-javascript-api.md#event-with-product-data)
* [Supported Events](pixel-javascript-api.md#supported-events)
* [B2C Events](pixel-javascript-api.md#b2c-events)
* [B2B/ABM Events](pixel-javascript-api.md#b2b-abm-events)
* [Event Attributes](pixel-javascript-api.md#event-attributes)
* [Example: E-commerce Tracking](pixel-javascript-api.md#example-e-commerce-tracking)
* [Product Page View](pixel-javascript-api.md#product-page-view)
* [Add to Cart](pixel-javascript-api.md#add-to-cart)
* [Purchase Conversion](pixel-javascript-api.md#purchase-conversion)
* [Retrieving the First-Party Cookie](pixel-javascript-api.md#retrieving-the-first-party-cookie)
* [Best Practices](pixel-javascript-api.md#best-practices)
* [Use Supported Event Names](pixel-javascript-api.md#use-supported-event-names)
* [Product IDs](pixel-javascript-api.md#product-ids)
* [Test Your Implementation](pixel-javascript-api.md#test-your-implementation)
* [Related Resources](pixel-javascript-api.md#related-resources)
* [Developer Site Migration](developer-site-migration.md)
* [How to access your existing applications](developer-site-migration.md#how-to-access-your-existing-applications)
* [Common questions](developer-site-migration.md#common-questions)
* [I don’t know which email address my application belongs to](developer-site-migration.md#i-dont-know-which-email-address-my-application-belongs-to)
* [What should I do if I no longer have access to the email that owns my application?](developer-site-migration.md#what-should-i-do-if-i-no-longer-have-access-to-the-email-that-owns-my-application)
* [I’ve got a question that isn’t answered here](developer-site-migration.md#ive-got-a-question-that-isnt-answered-here)
* [Manage Product Sets](product-sets.md)
* [Product Sets](product-sets.md#product-sets)
* [Create a Product Set](product-sets.md#create-a-product-set)
* [Edit a Product Set](product-sets.md#edit-a-product-set)
* [List Product Sets for an Advertisable](product-sets.md#list-product-sets-for-an-advertisable)
* [Get a Product Set](product-sets.md#get-a-product-set)
* [Delete a Product Set](product-sets.md#delete-a-product-set)
* [Use Product Sets with Web Retargeting campaigns](product-sets.md#use-product-sets-with-web-retargeting-campaigns)
* [Attach Product Sets to an AdGroup](product-sets.md#attach-product-sets-to-an-adgroup)
* [Edit an AdGroup with a Product Set attached](product-sets.md#edit-an-adgroup-with-a-product-set-attached)
* [Remove a Product Set from an AdGroup](product-sets.md#remove-a-product-set-from-an-adgroup)
* [Share Audiences](audience-sharing.md)
* [Create a share invitation](audience-sharing.md#create-a-share-invitation)
* [Fetch share invitations](audience-sharing.md#fetch-share-invitations)
* [Accept a share invitation](audience-sharing.md#accept-a-share-invitation)
* [Attach a shared audience to a campaign](audience-sharing.md#attach-a-shared-audience-to-a-campaign)
* [Revoke a shared audience](audience-sharing.md#revoke-a-shared-audience)
# index.html.md
# Prospecting API
* [Overview](overview.md)
* [Authentication](overview.md#authentication)
* [Getting Started](overview.md#getting-started)
* [Service Walkthrough](overview.md#service-walkthrough)
* [Examples](examples.md)
* [API Reference](reference.md)
* [Description](reference.md#description)
* [Operations by Tag](reference.md#operations-by-tag)
* [Adgroups](reference.md#adgroups)
* [Advertisables](reference.md#advertisables)
* [Audiences](reference.md#audiences)
* [Campaigns](reference.md#campaigns)
* [Flights](reference.md#flights)
* [Untagged](reference.md#untagged)
* [Operations](reference.md#operations)
# index.html.md
# Server-to-Server (S2S) API
#### NOTE
The S2S event API is under active development. Although the API is generally stable, it may change. Event processing is not yet fully complete. [Send us a message](../support.md#support) if you have questions.
* [Overview](overview.md)
* [Introduction](overview.md#introduction)
* [Data flow](overview.md#data-flow)
* [User identifiers](overview.md#user-identifiers)
* [Click ID (`adct`)](overview.md#click-id-adct)
* [First-Party Cookie](overview.md#first-party-cookie)
* [Fetch first-party cookie](overview.md#fetch-first-party-cookie)
* [Generate a first-party cookie](overview.md#generate-a-first-party-cookie)
* [Mobile device ID](overview.md#mobile-device-id)
* [Email](overview.md#email)
* [Custom user ID](overview.md#custom-user-id)
* [Events](events.md)
* [Event format](events.md#event-format)
* [Required Fields](events.md#required-fields)
* [Optional Fields](events.md#optional-fields)
* [Specifying products](events.md#specifying-products)
* [Mobile app URLs](events.md#mobile-app-urls)
* [Event types](events.md#event-types)
* [B2C event types](events.md#b2c-event-types)
* [Page view event](events.md#page-view-event)
* [Home view event](events.md#home-view-event)
* [Product search event](events.md#product-search-event)
* [Add to cart event](events.md#add-to-cart-event)
* [Purchase event](events.md#purchase-event)
* [B2B/ABM event types](events.md#b2b-abm-event-types)
* [High-value page event](events.md#high-value-page-event)
* [Gated content event](events.md#gated-content-event)
* [Demo request event](events.md#demo-request-event)
* [Signup plan event](events.md#signup-plan-event)
* [Signup trial event](events.md#signup-trial-event)
* [Contact sales event](events.md#contact-sales-event)
* [Live chat event](events.md#live-chat-event)
* [Form fill event](events.md#form-fill-event)
* [API Reference](reference.md)
* [API endpoint](reference.md#api-endpoint)
* [Authentication](reference.md#authentication)
* [Request Body](reference.md#request-body)
# index.html.md
# Site Traffic Revealer
* [Overview](overview.md)
* [Setup](overview.md#setup)
* [Examples](examples.md)
* [Get Visitor Attributes](examples.md#get-visitor-attributes)
* [Data Dictionary](examples.md#data-dictionary)
# index.html.md
# Universal Campaigns API
#### WARNING
The Universal Campaigns API will be retired April 2025.
* [Overview](overview.md)
* [Authentication](overview.md#authentication)
* [Service Walkthrough](overview.md#service-walkthrough)
* [Migration from Automated Campaigns API](overview.md#migration-from-automated-campaigns-api)
* [Examples](examples.md)
* [Create a Universal Campaign](examples.md#create-a-universal-campaign)
* [Create a Universal AdGroup](examples.md#create-a-universal-adgroup)
* [Fetch a Universal Campaign](examples.md#fetch-a-universal-campaign)
* [API Reference](reference.md)
* [Description](reference.md#description)
* [List of Operations](reference.md#list-of-operations)
* [Operations](reference.md#operations)
* [Definitions](reference.md#definitions)
# index.html.md
# User Lists API
* [Overview](overview.md)
* [Authentication](overview.md#authentication)
* [Examples](examples.md)
* [Retrieve the size of a segment](examples.md#retrieve-the-size-of-a-segment)
* [API Reference](reference.md)
* [Description](reference.md#description)
* [List of Operations](reference.md#list-of-operations)
* [Operations](reference.md#operations)
* [Definitions](reference.md#definitions)
# index.html.md
# Audience API Examples
* [Guides](guides.md)
* [Target Account List Examples](tal.md)
* [List all Target Account Lists](tal.md#list-all-target-account-lists)
* [List all accounts in a Target Account List](tal.md#list-all-accounts-in-a-target-account-list)
* [Add new accounts to a Target Account List](tal.md#add-new-accounts-to-a-target-account-list)
* [Remove accounts from a Target Account List](tal.md#remove-accounts-from-a-target-account-list)
# account-metrics.html.md
# Access AdRoll ABM Account Metrics
You can access AdRoll ABM account metrics using the GraphQL Reporting API. Metrics are available per account for a list of campaigns in an advertisable. You can specify any date range as long as it doesn’t exceed thirty days. If you need more than thirty days of data, you can make multiple queries and iterate on the date range.
## Get to know the NextRoll API
Before you start building your integration, it helps to have a basic understanding of the NextRoll API.
[Get Started with the NextRoll API](get-started.md#guide-get-started) will help you make your first API call.
[Get to know NextRoll](object-structure.md#guides-object-structure) provides an overview of the object structure and defines common terminology.
## Authentication
Use [OAuth 2.0](oauth.md#guide-oauth) to gain access to a user’s account. Our OAuth 2.0 implementation is compatible with standard libraries. You should be able to plug-in our token and authorization URLs into your favorite library.
See also:
- [Get Started with OAuth 2.0](oauth.md#guide-oauth)
## Retrieve account metrics
To retrieve account metrics, you’ll need to use the [GraphQL Reporting API](../graphql-reporting-api/overview.md#graphql-reporting-api-overview).
When querying the data, you’ll need to specify:
- Advertisable EID
- One or more campaign EIDs
- Start and end date
- Metrics that you want to retrieve. See [`FieldAccountMetrics`](../graphql-reporting-api/schema.md#FieldAccountMetrics) for the complete list.
The response contains metrics for up to 1,000 accounts, ordered alphabetically by domain.
The response contains account metrics aggregated for all campaigns specified and the entire date range. If you want fine-grained reporting, you’ll need to query for a single campaign EID and day at a time.
#### NOTE
You can experiment with building queries using [GraphiQL](https://app.adroll.com/reporting/graphiql)
The following is an example GraphQL query that shows account metrics
for your campaigns:
```graphql
{
accountMetrics {
summary(start: "yyyy-mm-dd", end: "yyyy-mm-dd", advertisableEID: "YOUR_ADVERTISABLE_EID", campaignEIDs: ["YOUR_CAMPAIGN_EID1", "YOUR_CAMPAIGN_EID2", "YOUR_CAMPAIGN_EID3"]) {
domain
cost
impressions
clicks
adjustedClickThroughs
adjustedViewThroughs
pageViews
uniqueVisitors
}
}
}
```
If you’re unfamiliar with how to make a GraphQL query using HTTP. See [Your First Query](../graphql-reporting-api/overview.md#your-first-graphql-query) for an example of how to package a query into an HTTP API call.
# api-key-migration.html.md
# Migrating to API Keys
We now require all NextRoll API developers to register applications and use an API key for all requests. This guide explains why we’ve migrated and how to get your application started.
Don’t care about the background story? Jump straight to the [Migration Instructions](#api-key-migration-instructions).
## Background
We’ve re-launched the developer program with the goal to improve communication and support for our API. Here’s what we’ve released:
- A new developer site with application registration: [developers.nextroll.com](https://developers.nextroll.com/)
- A new subdomain for API calls that enforces API keys and rate limiting: `services.adroll.com`
The new developer site allows you to register as a developer. Once registered, you can create one or more applications, each with their own API key. By registering as a developer and creating applications, we’ll be able to better understand how developers are using the NextRoll API. It will be easier to see how changes will impact developers and allow us to keep you informed of changes.
We offer two tiers of API access: Basic and Partner. Most developers will select the Basic tier when creating their applications. This gives access to all API features, with a daily limit of 10,000 API calls. When you register for Basic access, you’ll be able to make API calls right away. If you select Partner access, your application will need to be approved before you can make API calls. As we roll out API quotas, we may need to fine-tune the default limit. If you’re concerned about usage, [send us a message](../support.md#support).
Looking to the future, we plan to roll out support for OAuth 2.0 so that you don’t need to deal with passwords when making API calls. We’ll also be writing guides and tutorials to help you get started and make maximum use out of our APIs.
## Migration Instructions
Ready to migrate? Here’s what you need to do:
1. [Create a developer account](https://developers.nextroll.com/accounts/create)
2. [Create an application](https://developers.nextroll.com/my-apps/new-app)
3. Change all calls from `api.adroll.com` or `app.adroll.com` to `services.adroll.com`
4. Include your new API key in every request via the `apikey` query parameter
#### NOTE
The [CRUD API](../crud-api/index.md#crud-api-index) basepath, `/api`, was optional for calls to `api.adroll.com`. This meant that calls to `api.adroll.com/v1/` were equivalent to `api.adroll.com/api/v1/`.
When you migrate, you’ll need to use the `/api` basepath. For example: `api.adroll.com/v1/` calls become `services.adroll.com/api/v1/`.
#### NOTE
Once you’ve registered your application, you’ll see both a consumer key and secret. We currently do not use the secret. You’ll only use the consumer key when making API calls.
Now you can make an API call:
```shell
curl -H 'Authorization: Token YOUR_TOKEN' \
https://services.adroll.com/api/v1/organization/get?apikey=MYAPIKEY
```
# api-usage.html.md
# CRUD API Usage
## REST Semantics
The CRUD API is RESTful. The API is made up of a number of services, and each service has operations such as create, get, edit, and deactivate/delete. The reference page is the source of truth for each endpoint’s exact HTTP method, but the common mappings are:
| Verb | Function |
|---------------------------------------------------------------------------------------------------------------------------------|-------------------|
| [POST](https://www.rfc-editor.org/rfc/rfc7231#section-4.3.3) | create |
| [GET](https://www.rfc-editor.org/rfc/rfc7231#section-4.3.1) | get |
| [PUT](https://www.rfc-editor.org/rfc/rfc7231#section-4.3.4) or
[POST](https://www.rfc-editor.org/rfc/rfc7231#section-4.3.3) | edit |
| [DELETE](https://www.rfc-editor.org/rfc/rfc7231#section-4.3.5) | deactivate/delete |
When using `PUT` or `POST`, parameters can be passed in the body of the request or in the URL query.
To pass parameters in the body of the request, use either *application/x-www-form-urlencoded* or *multipart/form-data* MIME types.
For `PUT` and `POST` requests you can also place parameters in the URL query:
```default
POST https://services.adroll.com/api/v1/ad/create?apikey=MYAPIKEY&advertisable=MY_ADVERTISABLE_EID&name=My+Ad
PUT https://services.adroll.com/api/v1/ad/edit?apikey=MYAPIKEY&ad=XJCACTZQ2RHKRHU34YPFXQ&name=My+Ad
```
## Request Headers
Please set the HTTP [Accept](http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html) header to ‘application/json’.
## Response Values
When all is peachy, you’ll get a 200 OK HTTP response code and JSON with a `results` field that contains the function’s return value.
```default
GET https://services.adroll.com/api/v1/ad/get?apikey=MYAPIKEY&ad=XJCACTZQ2RHKRHU34YPFXQ
```
```default
//Server says
200 OK
//JSON Response
{
'results': {
'ad': 'XJCACTZQ2RHKRHU34YPFXQ',
...
}
}
```
## Errors
In the event of an error, the API will return an appropriate HTTP response code and an `errors` field in place of the `results` field. The API’s HTTP response codes are unsurprising:
| HTTP Response Code | What Happened |
|----------------------|-----------------------------------|
| 200 | Good to go |
| 400 | Validation error or missing input |
| 401/403 | You do not have access |
| 404 | We couldn’t find the object |
| 405 | HTTP method not allowed |
| 500 | You broke our service |
The response’s `errors` field will be a list of error objects. Each error object will have a `message` field and either a `code` field or a `field` field. Occasionally, an error object will have both a `code` field and a `field` field, but this is rare. Field errors are returned in response to an error with one of the input fields, and errors without a `field` field are more generic errors.
In the case of a 405 response code, the allowed HTTP methods are listed as a comma-separated list in the `Allow` header of the response.
Let’s see what a grand failure looks like. What if we wanted to create an ad but didn’t specify any parameters except for an uploaded text file? We would have validation (field) errors and errors with a code field.
```default
POST https://services.adroll.com/api/v1/ad/create?apikey=MYAPIKEY
```
```default
//Server says
400 Bad Request
//JSON Response
{
'errors': [{
message: 'No Advertisable found',
field: 'name',
code: 16
},{
message: 'Please enter a name for your ad',
field: 'name'
},{
message: 'Please enter a destination url',
field: 'destination_url'
},{
message: 'File is an invalid image',
field: 'ad_file',
code: 1
}]
}
```
The code field is an enum with the following values:
| code value | What it means |
|--------------|-----------------|
| 1 | INVALID |
| 2 | MISMATCH |
| 4 | NO_DEFAULT |
| 8 | FAIL |
| 16 | NOT_FOUND |
| 32 | UNSET |
| 64 | INCOMPLETE |
| 128 | EXTERNAL |
| 256 | DUPLICATE |
| 512 | FORBIDDEN |
### Data Types
Throughout this documentation, we will be referring to a number of data
types.
| Data Type | Description | Example |
|-------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-----------------------------------------------|
| String | A string | “My cat’s breath smells like cat food.” |
| Integer | An integer | 42 |
| Float | A real number | 123.127 |
| Boolean | true or false | true |
| List | As input this means a comma-separated list of values in string form. This is often a list of object (e.g. Campaign) EIDs. As output from a service’s method, List will mean a JSON list. | WPCWFT43KVFN3JKKZD2EYO,JXZWV4IW4RDALBFJIE3UPL |
| Binary | A binary stream, like a file. | 1010100101011110101010101010010 |
| DateTime | A date string in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format, with or without the time. | 2009-03-23 19:00 |
## Statuses
Campaign and ad objects have a `status` attribute.
These statuses may have different meanings depending on the type of object.
In addition, campaign and ad objects have an `is_active` attribute, which indicates whether or not the object has been deleted, and is independent of the object’s `status` attribute.
**Campaign Statuses**
| Status | Description |
|----------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `approved` | The campaign has been approved by an admin and submitted to the appropriate network(s). |
| `paused` | The campaign has been paused by a user or an admin, and is not serving any ads. |
| `admin_review` | The campaign is undergoing review by an admin and has not been approved or rejected yet. |
| `completed` | The campaign’s end date has elapsed and the campaign is no longer eligible to serve ads. |
| `draft` | The campaign is in draft state and has not yet been launched. |
| `admin_paused` | The campaign has been suspended by the review team, sometimes due to conflicts with creative requirements. See [Creative Requirements](https://help.adroll.com/hc/en-us/articles/214806408-Ad-Content-and-Format-Guidelines) for details on creative requirements. |
| `cancelled` | The campaign has been cancelled by an admin. |
| `rejected` | The campaign is not compliant with site policy or requirements. See [Website Content](https://help.adroll.com/hc/en-us/articles/213099348-Website-Content) for details on site policy and requirements. |
**Ad Statuses**
| Status | Description |
|----------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `approved` | The ad has been approved by an admin. If it is included as active in any currently running adgroups, it is serving impressions in those adgroups. An “approved” ad can be marked as “paused” in a specific adgroup, in which case, it will not serve impressions in that adgroup. |
| `paused` | The ad has been paused by a user or an admin. If it is included in any adgroups, it is not serving impressions in those adgroups. |
| `admin_review` | The ad is undergoing review from an admin. If it is included in any adgroups, it will not serve impressions in those adgroups until it is approved. |
| `admin_paused` | The ad has been paused by an admin. If it is included in any adgroups, it is not serving impressions in those adgroups. This is sometimes due to conflicts with creative requirements. See [Creative Requirements](https://help.adroll.com/hc/en-us/articles/214806408-Ad-Content-and-Format-Guidelines) for details on creative requirements. |
| `kicked` | The ad has been rejected by a network or removed by a user or an admin. If it is included in any adgroups, it is not serving impressions in those adgroups. |
# audience-sharing.html.md
# Share Audiences
#### NOTE
Audience Sharing is an upcoming feature and isn’t available to everyone
Audience Sharing enables you to share an Audience you’ve created with another NextRoll customer. Once shared, you can attach the shared audience to Web Retargeting campaigns.
For another Advertisable to use a shared segment, there are a few steps:
1. [Create a share invitation](#guide-audience-sharing-create)
2. [Fetch share invitations](#guide-audience-sharing-fetch)
3. [Accept a share invitation](#guide-audience-sharing-accept)
4. [Attach a shared audience to a campaign](#guide-audience-sharing-attach)
If you have seconds thoughts about sharing segments, you can [revoke the shared audience](#guide-audience-sharing-revoke).
Currently, only the following segment types can be shared:
- URL (`url`)
- External data (`arbitrary_data`)
- Pages viewed (`pages_viewed`)
## Create a share invitation
The first step in sharing an audience is to send a share invitation. This is done by making a request to [`POST /audience/v1/sharing/invitation`](../audience-api/reference.md#post--audience-v1-sharing-invitation). You’ll need to specify the segment EID you want to share and the Advertisable EID that you want to send the invitation. This request needs to be done using the credentials of the Advertisable that owns the segment.
```shell
curl -H 'Authorization: Token YOUR_TOKEN' \
--request POST \
'https://services.adroll.com/audience/v1/sharing/invitation?apikey=MYAPIKEY&advertisable_eid=TARGET_ADV_EID&segment_eid=SEGMENT_EID'
```
```json
{
"eid": "1DE62679ADA5EEA4EEE6B2",
"source_segment_eid": "01C8D357DCE0384FB23B7F",
"created_at": "2021-01-19T15:36:28.052968+00:00",
"is_active": true,
"source_user_eid": "A2B5747D084B7072BEFDF9",
"updated_at": "2021-01-19T15:36:28.051623+00:00",
"accepted": false,
"segment_source": "adroll",
"target_advertisable_eid": "6E1140DFF2B8FA0AC6EEAF",
"source_advertisable_eid": "EA1704974734327A383B01"
}
```
## Fetch share invitations
You can view the list of outstanding share invitations you’ve been sent by calling [`GET /audience/v1/sharing/invitation`](../audience-api/reference.md#get--audience-v1-sharing-invitation) and specifying the Advertisable EID that received the request.
```shell
curl -H 'Authorization: Token YOUR_TOKEN' \
'https://services.adroll.com/audience/v1/sharing/invitation?apikey=MYAPIKEY&target_advertisable_eid=TARGET_ADV_EID'
```
```json
[
{
"eid": "1DE62679ADA5EEA4EEE6B2",
"source_segment_eid": "01C8D357DCE0384FB23B7F",
"created_at": "2021-01-19T15:36:28.052968+00:00",
"is_active": true,
"source_user_eid": "A2B5747D084B7072BEFDF9",
"updated_at": "2021-01-19T15:36:28.051623+00:00",
"accepted": false,
"segment_source": "adroll",
"target_advertisable_eid": "6E1140DFF2B8FA0AC6EEAF",
"source_advertisable_eid": "EA1704974734327A383B01"
}
]
```
## Accept a share invitation
After you’ve created a sharing invitation, the receiving Advertisable needs to accept the invitation. This is done using the [`POST /audience/v1/sharing/segment`](../audience-api/reference.md#post--audience-v1-sharing-segment) endpoint. This request needs to be done using the credentials of the receiving Advertisable.
Once accepted, a new segment of type `mirror` can be found in the receiving Advertisable when retrieving a list of segments owned by that Advertisable. You’ll also see the new segment when browsing the dashboard.
```shell
curl -H 'Authorization: Token YOUR_TOKEN' \
--request POST \
'https://services.adroll.com/audience/v1/sharing/segment?apikey=MYAPIKEY&invitation_eid=YOUR_INVITATION_EID'
```
```json
{
"abm_tags": null,
"advertiser_id": "D5A1ED3325E61E27C9FF07",
"conversion_value": null,
"created_date": 1610998568758,
"currency_code": null,
"duration": 90,
"is_active": true,
"is_conversion": false,
"is_lead": false,
"lead_type": null,
"name": "Visitors to Unsegmented Pages",
"product": null,
"segment_id": "F71A58D5EAD767722199DA",
"source": "slargma",
"source_segment": {
"advertiser_id": "03865DAF43940F1D726995",
"conversion_value": null,
"created_date": 1414594022000,
"duration": 90,
"int_id": 601911,
"is_active": true,
"is_conversion": false,
"name": "Visitors to Unsegmented Pages",
"parent_segment_eid": "7B4B0BA630B4B903E9AF09",
"pattern": "",
"product": null,
"segment_id": "585F5A39D83FC5353F16FC",
"source": "adroll",
"tags": "p",
"type": "url",
"url_match_id": "all_prodo"
},
"source_segment_eid": "585F5A39D83FC5353F16FC",
"tags": "s",
"type": "mirror"
}
```
## Attach a shared audience to a campaign
Once you’ve accepted the share invitation, the segment is available when retrieving the list of segments for the Advertisable.
You can attach it to Web Retargeting campaigns just like any other segment.
## Revoke a shared audience
If you no longer wish to share a segment, you can call the [`DELETE /audience/v1/sharing/invitation`](../audience-api/reference.md#delete--audience-v1-sharing-invitation) endpoint. Once revoked, you’ll see that the is_active field is now false.
```shell
curl -H 'Authorization: Token YOUR_TOKEN' \
--request DELETE \
'https://services.adroll.com/audience/v1/sharing/invitation?apikey=MYAPIKEY&invitation_eid=YOUR_INVITATION_EID'
```
```json
{
"eid": "8DE426B5BB2EDFB9210895",
"created_at": "2021-01-19T15:36:28.052968+00:00",
"accepted": true,
"is_active": false,
"updated_at": "2021-01-19T17:49:53.447559+00:00",
"source_segment_eid": "048234E69DE8DA46FB9E61",
"segment_source": "adroll",
"target_advertisable_eid": "E5BA939587DA06A7FD846D",
"source_user_eid": "J7UHJLT7MVFIFK2STSXHVT",
"source_advertisable_eid": "DEB21215BEEC304325CB50"
}
```
# create-audiences.html.md
# Creating Audiences
> ##### Audience Types
>
> * [URL](#url)
> * [CRM](#crm)
> * [Partner](#partner)
> * [External Data](#external-data)
> * [Attribute](#attribute)
> * [Composite](#composite)
> * [CrossChannel Lookalike](#crosschannel-lookalike)
## URL
Type: `url`
To create a URL Audience, you’ll need to create a rule on the Pixel. To create a rule on a Pixel, you call [`POST /api/v1/rule/create`](../crud-api/reference.md#post--api-v1-rule-create) with the following parameters:
`pixel`
: Pixel EID to create the rule on. You can retrieve the Pixel EID by calling [`GET /api/v1/advertisable/get_pixel`](../crud-api/reference.md#get--api-v1-advertisable-get_pixel).
`type`
: The type of the rule being created. You can’t change this later. One of:
- `c` — Conversion
- `b` — Visited their cart
- `l` — Viewed a list of products
- `u` — Viewed a single product
- `s` — Segment. Use this if a one of the previous doesn’t fit your situation
`match_method`
: Set to `url_match` when creating a URL Audience
`pattern`
: Pattern expression that matches your URL. You can specify [wildcards](https://help.adroll.com/hc/en-us/articles/215785058) in the pattern. Max length of 255.
`name`
: Name for this rule. This must be unique within each Pixel. Max 128 characters. Alphanumeric with `-`, `_`, `(`, `)`, `[`, `]`, `<`, `>`.
`display_name` (Optional)
: Display name for reporting. Names cannot contain `<`, `>`, `'`, or `"`. Max 128 characters.
`order`
: Priority order in which this rule needs to be applied among the others. Must be unique in the Pixel. The lower the number, the higher the priority. Highest priority is `0`.
For example, to create an audience of people who have visited a cart page:
```shell
curl -H 'Authorization: Token YOUR_TOKEN' \
-F pixel=MY_PIXEL_EID \
-F type=b \
-F match_method=url_match \
-F pattern='*/cart/' \
-F name=shopping_cart \
-F order=3 \
https://services.adroll.com/api/v1/rule/create?apikey=MYAPIKEY
```
## CRM
Type: `crm`
Target your users by email address by creating a CRM Audience.
To create a CRM Audience, call [`POST /audience/v1/segments`](../audience-api/reference.md#post--audience-v1-segments) with the following body:
```json
{
"advertiser_id": "MY_ADVERTISALE_EID",
"name": "Newsletter subscribers",
"type": "crm",
"data": [
{
"email": "test1@example.com"
},
{
"email": "test2@example.com"
}
]
}
```
Emails need to be either:
- [RFC 5322](http://tools.ietf.org/html/rfc5322#section-3.4) emails, e.g. `test1@example.com`
- MD5 hashes of [RFC 5322](http://tools.ietf.org/html/rfc5322#section-3.4) emails, e.g. `aa99b351245441b8ca95d54a52d2998c` (MD5 hash of “[test1@example.com](mailto:test1@example.com)”)
You can optionally specify a timestamp, `ts`, to indicate when a user entered a Audience (the default timestamp is *now*). Timestamps can be up to 540 days old or up to 7 days in the future. Timestamps are specified as seconds since epoch.
## Partner
Type: `custom`
Target people using your custom user identifiers. These identifiers must have been previously matched to cookies using a cookie-match.
To create a Partner Audience, call [`POST /audience/v1/segments`](../audience-api/reference.md#post--audience-v1-segments) with the following body:
```json
{
"advertiser_id": "MY_ADVERTISABLE_EID",
"name": "Downloaded whitepaper",
"type": "custom",
"duration": 30,
"data": [
{
"id": "MY_USER_ID_1"
},
{
"id": "MY_USER_ID_2"
}
]
}
```
The `duration` parameter, controls the number of days that a user will remain in the defined segment. After that period, the identifiers in the segment should be refreshed in order to repopulate the segment with up-to-date profiles. We recommend a duration of 90 days. Longer durations expose the same ads to the same audience for an extended period of time and can lead to ad fatigue.
You can optionally specify a timestamp, `ts`, to indicate when a user entered a segment (the default timestamp is *now*). Timestamps can be up to 540 days old or up to 7 days in the future. Timestamps are specified as seconds since epoch.
There are not limits on the number of identifiers that can be added to a segment. However, our APIs limits the size of the body request up to 20MB. If you require to append identifiers to an existing segment you should call [`POST /audience/v1/segments/(segment_id)`](../audience-api/reference.md#post--audience-v1-segments-(segment_id)) with the following body:
```json
{
"name": "Downloaded whitepaper",
"type": "custom",
"data": [
{
"id": "MY_USER_ID_3"
},
{
"id": "MY_USER_ID_4"
}
]
}
```
## External Data
Type: `arbitrary_data`
See [Manage External Data Segments](external-segments.md#guide-external-segments).
## Attribute
Type: `user_attributes`
Attribute Audiences target users based on data from third party sources.
#### NOTE
Access to Attribute Audiences is not available to everyone. Contact your Account Manager if you’re interested in Attribute Audiences.
To create an Attribute Audience, you specify one or more attributes. You can retrieve a list of available attribute names and values for your Advertisable by calling [`GET /audience/v1/user_attribute_names/(advertisable_eid)`](../audience-api/reference.md#get--audience-v1-user_attribute_names-(advertisable_eid)).
`type`
: Set to `user_attributes` to create an Attribute Audience
`attributes`
: Array of attributes that define the Audience
`use_first_party_data` (Optional)
: If `true`, use first-party data sources. Defaults to `true`.
`use_third_party_data` (Optional)
: If `true`, use third-party data sources. Defaults to `true`.
Each object in the `attributes` array consists of:
`name`
: Name of the attribute
`values`
: Array of target values for the named attribute. Case sensitive.
`comparator`
: Operator to use when comparing a user to an attribute value. Possible values include:
- `in` — Attribute matches any value in the list
- `not_in` — Attribute does not match any value in the list
#### NOTE
If `values` is `null` then `comparator` must also be `null` and that means that membership to the audience is defined as the *existence* of `name`.
For example, to create an Attribute Audience that targets managers at `example.com`, call [`POST /audience/v1/segments`](../audience-api/reference.md#post--audience-v1-segments) with the following body:
```json
{
"advertiser_id": "MY_ADVERTISABLE_EID",
"name": "Management at example.com",
"type": "user_attributes",
"attributes": [
{
"name" : "ccm_seniority",
"values" : ["Management"],
"comparator" : "in",
},
{
"name" : "domain",
"values" : ["example.com"],
"comparator" : "in",
}
]
}
```
## Composite
Type: `composite`
Composite Audiences apply a set union relationship between two or more Audiences. A composite audience can narrow down Audiences to a more precise target audience. E.g. usage can be all audiences who viewed pages at least 5 times and are interested in snowboarding.
To create a Composite Audience, call [`POST /audience/v1/segments`](../audience-api/reference.md#post--audience-v1-segments) with the following body:
```json
{
"advertiser_id": "MY_ADVERTISABLE_EID",
"name": "Managers at example.com who have downloaded a whitepaper",
"type": "composite",
"duration": 30,
"components": [
"MY_SEGMENT_EID_1",
"MY_SEGMENT_EID_2"
]
}
```
`components` is a list of two or more audiences specified by their Segment EID. All components must be valid existing audiences and must not be another composite audience. You cannot have multiple Attribute Audiences in a Composite Audience.
## CrossChannel Lookalike
Type: `crosschannel_lal`
CrossChannel Lookalike Audiences gives you the ability to run campaigns seamlessly across inventory sources (Web Prospecting campaigns).
To create a CrossChannel Lookalike audience, call [`POST /audience/v1/segments`](../audience-api/reference.md#post--audience-v1-segments) with the following body:
```json
{
"advertiser_id": "MY_ADVERTISABLE_EID",
"name": "Test CrossChannel Lookalike audience",
"type": "crosschannel_lal",
"source_segment_eid": "SOURCESEGMENT_EID",
"duration": 30,
"size": 6,
"countries": [
{
"country_code": "CL",
"include": "True"
}
],
"allow_international_seeds": "True"
}
```
`countries` (Optional)
: List of countries to target the audience. The actual limit is just 1 country.
`source_segment_eid`
: Source segment eid to created the audience. The current restrictions for the source segment are:
- The source segment must be of type CRM, pages viewed or arbitrary data.
- The source segment size must be of at least 100 total visitors.
`size`
: A choice between broadness and narrowness on a 1-10 scale.
`allow_international_seeds`
: Boolean indicating if allow or not international seeds.
# create-prospecting-campaign.html.md
# Create Your First Prospecting Campaign
#### NOTE
In this page we will use `0000000ADVERTISABLEEID` as an example of an advertisable EID. You should use an
advertisable from your organization as ownership privileges are enforced.
## Create a campaign
The first step is creating your campaign. This is done by making a request to
[`POST /prospecting/api/v2/advertisables/(adv)/campaigns`](../prospecting-api/reference.md#post--prospecting-api-v2-advertisables-(adv)-campaigns):
```shell
curl -H 'Authorization: Token YOUR_TOKEN' \
-H "Content-Type: application/json" \
-d '{"name":"Example Campaign","weekly_budget":"30","currency_code":"USD"}' \
https://services.adroll.com/prospecting/api/v2/advertisables/0000000ADVERTISABLEEID/campaigns?apikey=MYAPIKEY
```
```javascript
{
"results": {
"status": "active",
"created_at": "2017-02-13T15:32:57+00:00",
"advertisable": "0000000ADVERTISABLEEID",
"name": "Example Campaign",
"end_date": null,
"kpi_goal": null,
"weekly_budget": 30,
"is_active": true,
"updated_at": "2017-02-13T15:32:57+00:00",
"frequency_cap": null,
"source": "49er",
"admin_status": "active",
"eid": "0000000CAMPAIGNEID",
"adgroups": [],
"kpi_metric": null,
"start_date": "2017-02-13T15:32:57+00:00",
"currency_code": "USD"
}
}
```
## Add AdGroups to your campaign
Now you’ll need to create the desired AdGroups for your campaign. This is done by making a request to
[`POST /prospecting/api/v2/campaigns/(campaign)/adgroups`](../prospecting-api/reference.md#post--prospecting-api-v2-campaigns-(campaign)-adgroups):
```shell
curl -H 'Authorization: Token YOUR_TOKEN' \
-H "Content-Type: application/json" \
-d '{"name":"Example AdGroup","auto_audience":"true","auto_geo_targets":"true","ads":[{"ad":"0000000ADEID","is_active":"true","status":"active"}]}' \
https://services.adroll.com/prospecting/api/v2/campaigns/0000000CAMPAIGNEID/adgroups?apikey=MYAPIKEY
```
```javascript
{
"results": {
"status": "active",
"campaign": "0000000CAMPAIGNEID",
"is_active": true,
"updated_at": "2017-02-13T15:42:28+00:00",
"auto_audience": true,
"ads": [
{
"status": "active",
"ad_eid": "0000000ADEID",
"is_active": true,
"eid": "0000000PROSPECTINGADEID"
}
],
"created_at": "2017-02-13T15:42:28+00:00",
"name": "Example AdGroup",
"audience": null,
"eid": "0000000ADGROUPEID",
"auto_geo_targets": false,
"geo_targets": [
{
"eid": "XSTN6R5HH5FJ5MAS5W8GEO",
"operation": "include"
}
]
}
}
```
#### NOTE
You must always send `auto_geo_targets` as `false` here, and send a list of `geo_targets` that
can be queried using the [Geotargeting API](../geotargeting-api/examples.md#geotargeting-examples).
## Add an audience to your AdGroups (Optional)
In the previous step, notice how we set `auto_audience` to `true` in the request to create the AdGroup. This means
that an audience of potential new customers will be created automatically for that AdGroup. However, if you wish to
specify a particular audience for an existing AdGroup, you can do that by making a request to
[`POST /prospecting/api/v2/adgroups/(adgroup)/audience`](../prospecting-api/reference.md#post--prospecting-api-v2-adgroups-(adgroup)-audience):
```shell
curl -H 'Authorization: Token YOUR_TOKEN' \
-H "Content-Type: application/json" \
-d '{"source_segment_eid":"0000000SOURCESEGMENTEID","size":200000}' \
https://services.adroll.com/prospecting/api/v2/adgroups/0000000ADGROUPEID/audience?apikey=MYAPIKEY
```
```javascript
{
"results": {
"eid": "0000000AUDIENCEEID"
"adgroup_eid": "0000000ADGROUPEID",
"target_segment_eid": "0000000TARGETSEGMENTEID",
"source_segment_eid": "0000000SOURCESEGMENTEID",
"size": 200000,
"created_at": "2017-02-13T16:25:37+00:00",
"updated_at": "2017-02-13T16:25:37+00:00",
}
}
```
## Add flights to your AdGroups (Optional)
Once your AdGroups are set, your campaign is ready to serve. By default, all AdGroups will serve their ads during the
same period of time determined by the campaign’s start and end date. However, you can specify time periods during which
an individual AdGroup should serve by creating flights. This is done by making a request to
[`POST /prospecting/api/v2/adgroups/(adgroup)/flights`](../prospecting-api/reference.md#post--prospecting-api-v2-adgroups-(adgroup)-flights):
```shell
curl -H 'Authorization: Token YOUR_TOKEN' \
-H "Content-Type: application/json" \
-d '{"start_date":"2017-02-15T00:00:00+00:00","end_date":"2017-02-20T00:00:00+00:00"}' \
https://services.adroll.com/prospecting/api/v2/adgroups/0000000ADGROUPEID/flights?apikey=MYAPIKEY
```
```javascript
{
"results": {
"adgroup": "0000000ADGROUPEID",
"end_date": "2017-02-20T00:00:00+00:00",
"created_at": "2017-02-13T16:25:37+00:00",
"updated_at": "2017-02-13T16:25:37+00:00",
"eid": "0000000FLIGHTEID",
"start_date": "2017-02-15T00:00:00+00:00"
}
}
```
# create-web-ads.html.md
# Creating Web Ads
## Static Web Ads
To create a static web ad, you need to specify:
- Advertisable EID to add the advertisement to
- Destination URL where to send the user when the ad is clicked
- Image file to upload
**Request**:
```shell
curl -H 'Authorization: Token YOUR_TOKEN' \
-F advertisable=8597013E81481B0FE28772 \
-F name="Test Ad 300x250" \
-F destination_url=https://developers.nextroll.com \
-F file=@300x250.png \
https://services.adroll.com/api/v1/ad/create?apikey=MYAPIKEY
```
**Response**:
```javascript
{
"results": {
"eid": "2A842B75A34EF695A5AA9D",
"name": "Test Ad 300x250",
// ...
}
}
```
## Native Ads
To create Native Ads, you’ll need to specify `type=native` and `inventory_type=iab` when calling [`POST /api/v1/ad/create`](../crud-api/reference.md#post--api-v1-ad-create). For the list of supported image sizes, please refer to the [Ad Format Guidelines](https://help.adroll.com/hc/en-us/articles/214806408-Ad-Format-Guidelines).
**Request**:
```shell
curl -H 'Authorization: Token YOUR_TOKEN' \
-F advertisable=8597013E81481B0FE28772 \
-F type=native \
-F inventory_type=iab \
-F name="Test Native Ad" \
-F body="This is the description" \
-F destination_url=https://www.example.com/ \
-F file=@600x500.png \
'https://services.adroll.com/api/v1/ad/create?apikey=MYAPIKEY'
```
**Response**:
```javascript
{
"results": {
"eid": "EABF2CB2DEED8B777E8306",
"name": "Test Native Ad",
"type": "native",
// ...
}
}
```
## Dynamic Native Ads
To create Dynamic Native Ads, you’ll need to specify several parameters:
`advertisable`
: Advertisable EID to create the native ad in
`name`
: Name of the ad when shown in the dashboard and in reports
`type`
: Always `native`
`inventory_type`
: Always `iab`
`is_liquid`
: Always `true`
`format`
: Always `33` (600x315)
`headline`
: Called *Title* in the dashboard. When rendered, the value may be truncated after 25 characters.
`message`
: Called *Description* in the dashboard. When rendered, the value may be truncated after 125 characters.
`brand_name`
: Called *Brand Name* in the dashboard. When rendered, the value may be truncated after 30 characters.
`destination_url`
: Fallback destination URL. When the ad is rendered, the product’s URL will be used.
`file`
: Fallback image. When the ad is rendered, the product’s image will be used. Pass a base64-encoded string or use the *multipart/form-data* content-type.
The `headline`, `message`, and `brand_name` parameters support the following macros that pull values from your product feed. These macros must be mapped to fields in the product feed to be useable.
`%%title%%`
: Title of the product
`%%description%%`
: Description of the product
`%%price%%`
: Price of the product
`%%brand%%`
: Brand name of the product
**Request**:
```shell
curl -H 'Authorization: Token YOUR_TOKEN' \
-F advertisable=8597013E81481B0FE28772 \
-F type=native \
-F inventory_type=iab \
-F is_liquid=true \
-F name="Test Dynamic Native Ad" \
-F headline="%%title%%" \
-F message="%%description%%" \
-F brand_name="%%brand%%" \
-F destination_url=https://www.example.com/ \
-F file=@600x315.png \
'https://services.adroll.com/api/v1/ad/create?apikey=MYAPIKEY'
```
**Response**:
```javascript
{
"results": {
"eid": "EABF2CB2DEED8B777E8306",
"name": "Test Native Ad",
"type": "native",
// ...
}
}
```
## Dynamic Web Ads
To create [Dynamic Web Ads](https://www.adroll.com/platform/dynamic-ads), you first need to ensure you’ve uploaded a logo for your Advertisable.
### Upload a Logo
You can upload a logo for an advertisable by calling [`/api/v1/advertisable_logo/create`](../crud-api/reference.md#post--api-v1-advertisable_logo-create). You only need to do this once or if you want to change the logo.
The endpoint expects the logo to be passed as a base64-encoded data. Here’s an example of base64-encoding an image on the command line using Python:
```shell
python -m base64 < 320x50.png > 320x50.png.txt
```
**Request**:
This example uses the `name@filename` syntax for the `--data-urlencode` cURL parameter which will URL-encode the contents of the file before sending it.
```shell
curl -H 'Authorization: Token YOUR_TOKEN' \
-d advertisable=8597013E81481B0FE28772 \
--data-urlencode logo_file@320x50.png.txt \
https://services.adroll.com/api/v1/advertisable_logo/create?apikey=MYAPIKEY
```
**Response**:
```javascript
{
"results": {
"id": 1234,
"advertisable_id": 1234,
"s3_logo_path": "https://s.adroll.com/logos/8597013E81481B0FE28772/CS5ETCEWB5GQRHCJ3ANOG5",
"width": 200,
"height": 31
}
}
```
### Create the Dynamic Web Ads
You create a set of Dynamic Web Ads by calling [`/api/v1/ad/create_templated_web_ads`](../crud-api/reference.md#post--api-v1-ad-create_templated_web_ads). When calling the method, you need to specify the ID of the template you’d like to use. The table below provides the IDs and examples. The endpoint returns a list of ads created, which you can then add to your campaigns.
| Template ID | Theme name |
|---------------|-------------------------------------------------------------------|
| 0 | [Classic spotlight](#dc-theme-spotlight) |
| 1 | [Classic carousel](#dc-classic-carousel) |
| 2 | [Duotone carousel](#dc-duotone-carousel) |
| 3 | [Holiday spotlight](#dc-holiday-spotlight) |
| 4 | [Holiday carousel](#dc-holiday-carousel) |
| 10 | [Valentine spotlight](#dc-valentines-spotlight) |
| 13 | [Valentine carousel](#dc-valentines-carousel) |
| 21 | [Fall carousel](#dc-fall-spotlight) |
| 22 | [Fall spotlight](#dc-fall-carousel) |
| 28 | [Black Friday carousel](#dc-black-friday-carousel) |
| 29 | [Cyber Monday carousel](#dc-cyber-monday-carousel) |
| 33 | [Holiday Bow carousel](#dc-holiday-bow-spotlight) |
| 36 | [Holiday Sparkle carousel](#dc-holiday-sparkle-carousel) |
| 45 | [Valentine 2018 spotlight](#dc-holiday-valentines-2018-spotlight) |
| 47 | [Valentine 2018 carousel](#dc-holiday-valentines-2018-carousel) |
| 64 | [Product Gladiator](#dc-product-gladiator) |
| 72 | [Spring Stripes](#dc-spring-stripes) |
| 80 | [Summer Polka Dots](#dc-summer-polka-dots) |
| 83 | [Summer Beach](#dc-summer-beach) |
**Request**:
```shell
curl -H 'Authorization: Token YOUR_TOKEN' \
-d advertisable=8597013E81481B0FE28772 \
-d name='test' \
-d theme_color='#FFFFFF' \
-d text_cta='Shop Now' \
-d dynamic_template_id=1 \
https://services.adroll.com/api/v1/ad/create_templated_web_ads?apikey=MYAPIKEY
```
**Response**:
```javascript
{
"results": [
{
"eid": "05995D19B6B19DD08AAF00",
"name": "Dynamic_728x90_3/3/2017_1_test",
// ...
}
]
}
```
### Retrieve List of Dynamic Web Templates
Call [`GET /api/v1/dynamic_template/get_all_for_advertisable`](../crud-api/reference.md#get--api-v1-dynamic_template-get_all_for_advertisable) to retrieve the list of available templates. To create ads, use the value of the `id` field from the template as the `dynamic_tempalte_id` parameter in [`POST /api/v1/ad/create_templated_web_ads`](../crud-api/reference.md#post--api-v1-ad-create_templated_web_ads). See [Create the Dynamic Web Ads](#dc-create-ads) for more on creating ads.
The response includes a list of capabilities. You can use the `capabilities` list to decide what fields to prompt the user for. For example, if you see the `salePrice` capability, then you’ll know you can use the `sale_price_option` field when calling [`POST /api/v1/ad/create_templated_web_ads`](../crud-api/reference.md#post--api-v1-ad-create_templated_web_ads). Note that capabilities are optional.
**Request**:
```shell
curl -H 'Authorization: Token YOUR_TOKEN' \
'https://services.adroll.com/api/v1/dynamic_template/get_all_for_advertisable?advertisable=8597013E81481B0FE28772&apikey=MYAPIKEY'
```
**Response**:
```javascript
{
"results": [
{
"id": 33,
"eid": "6SJ2LVKKLZHNFCBGRZLPXA",
"category": null,
"in_testing": false,
"is_private": false,
"is_published": true,
"is_visible": true,
"name": "Holiday Bow NEW!",
"capabilities": [
{
"id": 2,
"eid": "RJTMLC5L4ZDVFJSGV3EMOJ",
"name": "salePrice",
"description": "Sale price",
"is_enabled": true,
"type": null
}
],
"allowed_advertisables": []
}
]
}
```
### Retrieve List of Dynamic Web Templates Capabilities
Call [`GET /api/v1/dynamic_template_capability_description/get_all`](../crud-api/reference.md#get--api-v1-dynamic_template_capability_description-get_all) to query the full list of capabilities that might appear in templates.
**Request**:
```shell
curl -H 'Authorization: Token YOUR_TOKEN' \
'https://services.adroll.com/api/v1/dynamic_template_capability_description/get_all?apikey=MYAPIKEY'
```
**Response**:
```javascript
{
"results": [{
"id": 1,
"eid": "CHU4RLZSVJCVNG6ZELX2RM",
"name": "promoText",
"description": "Promo text",
"is_enabled": true,
"type": null
}, {
"id": 2,
"eid": "RJTMLC5L4ZDVFJSGV3EMOJ",
"name": "salePrice",
"description": "Sale price",
"is_enabled": true,
"type": null
}]
}
```
### Dynamic Web Templates
#### Classic Spotlight
#### Classic carousel
#### Duotone carousel
#### Holiday spotlight
#### Holiday carousel
#### Valentine carousel
#### Valentine spotlight
#### Fall carousel
#### Fall spotlight
#### Black Friday carousel
#### Cyber Monday carousel
#### Holiday Bow carousel
#### Holiday Sparkle carousel
#### Valentine 2018 spotlight
#### Valentine 2018 carousel
#### Product Gladiator
#### Spring Stripes
#### Summer Polka Dots
#### Summer Beach
# developer-site-migration.html.md
# Developer Site Migration
At the end of August 2020, we’re launching a redesign of the NextRoll developer portal, [developers.nextroll.com](https://developers.nextroll.com/). To continue managing your existing applications, you’ll need to re-register using the same email address you created your application with.
## How to access your existing applications
To regain access to your existing applications, follow these simple steps:
1. Visit the developer portal to [register an account](https://developers.nextroll.com/accounts/create).
#### NOTE
Make sure to use the same email address you used before to regain access to your existing applications
2. Click the activation link in the validation email sent to you
3. [Sign into the developer portal](https://developers.nextroll.com/login) and [find your applications](https://developers.nextroll.com/my-apps)
## Common questions
### I don’t know which email address my application belongs to
You can [send us a message](../support.md#support) with your API key and we can help you identify the owning email address. We also sent a notification email to every registered email address.
### What should I do if I no longer have access to the email that owns my application?
The simplest method would be to simply create a new account and application. If that doesn’t work for you, you can [contact us](../support.md#support).
### I’ve got a question that isn’t answered here
You can [create a support ticket](../support.md#support) making sure to specify *API Issue* in the Issue drop-down.
# ecommerce-integration.html.md
# Integration guide for E-commerce Platforms
This guide is intended for e-commerce platforms that are interested in automating the setup for their users. In this guide, you’ll learn how to use the NextRoll API to access your store owner’s account and place their Pixel. Properly placing the Pixel can be a hurdle for users and must be done properly to ensure optimal performance. High performing campaigns means more revenue for your platform.
## Get to know the NextRoll API
Before you start building your integration, it helps to have a basic understanding of the NextRoll API:
[Get Started with the NextRoll API](get-started.md#guide-get-started) will help you make your first API call.
[Get to know NextRoll](object-structure.md#guides-object-structure) provides an overview of the object structure and defines common terminology.
## Overview
For every store that wants to set up, you’ll need to do the following steps:
1. [Connect using OAuth](#guides-ecommerce-oauth)
2. [Retrieve the Pixel](#guides-ecommerce-get-pixel)
3. [Place the Pixel](#guides-ecommerce-place-pixel)
4. [Link to Onboarding Flow](#guides-ecommerce-buy-flow)
If the user wants to disconnect the integration from their store, you can simplify remove the Pixel from their website.
## Connect using OAuth
The NextRoll API uses OAuth 2.0 to allow users to grant you access to their accounts. Our OAuth 2.0 implementation works with most OAuth 2.0 libraries. We recommend using the Authorization Code Grant.
For the technical details see [Get Started with OAuth 2.0](oauth.md#guide-oauth).
## Retrieve the Pixel
The Pixel is a JavaScript snippet that you place on every page of the store’s website.
To retrieve a Pixel:
1. Call [`GET /api/v1/organization/get_advertisables`](../crud-api/reference.md#get--api-v1-organization-get_advertisables) to retrieve the list of Advertisables (there should be only one at this point). You’ll need the value of the `eid` field for the next step
2. Call [`GET /api/v1/advertisable/get_pixel`](../crud-api/reference.md#get--api-v1-advertisable-get_pixel) and specify the `advertisable` parameter.
The `code` field of the returned JSON object will contain the HTML to embed on the user’s website. The HTML snippet consists of a `
```
In addition to sending this data via the Pixel, users will need to set up a conversion segment for the page that this code is rendered on. You should tell the user which URLs to set up as conversion segments when you [Link to Onboarding Flow](#guides-ecommerce-buy-flow).
See also: [Setting Up Enhanced Conversion Tracking](https://help.adroll.com/hc/en-us/articles/212629938-Setting-Up-Enhanced-Conversion-Tracking).
### Cross Device Targeting
**Optional**
We can recognize visitors across devices. When you provide a cross-device ID to us, ads will display on other devices that your visitors use.
To enable cross-device targeting, set `adroll_email`, `adroll_user_identifier`, or both when calling the Pixel.
The value of `adroll_email` is the plaintext or MD5 hashed email address for the user (if you have one).
The value of `adroll_user_identifier` is your custom identifier for the user (if you have one).
For example:
```html
```
## Link to Onboarding Flow
Once you’ve configured the user’s store, you can deep-link the user to the dashboard onboarding flow. The onboarding flow will walk the user through completing setup and launch campaigns.
Here’s the link you should use:
```text
https://app.adroll.com/activate/getting-started/
```
In addition to linking the user, you should also provide to the user the conversion URL so that they can set up the conversion segment. This URL should be the same page that you render the [Enhanced Conversion Tracking](#guides-ecommerce-track-conversions) on.
## Conclusion
That’s all that’s needed for a basic setup. This gets users over the first hurdle of Pixel placement that is often done wrong when placed manually.
A deeper integration would automatically setup conversion Audiences and product feed of their store items. If that sounds interesting to you, [send us a note](https://www.adroll.com/partners/technology) about partnering.
# events.html.md
# Server-to-Server (S2S) API Events
#### NOTE
The S2S event API is under active development. Although the API is generally stable, it may change. Event processing is not yet fully complete. [Send us a message](../support.md#support) if you have questions.
## Event format
Below is an event’s JSON structure. You can send more than one event per request, but please limit it to no more than one hundred events. For additional properties and examples, please review the following event-specific sections.
```json
[{
"advertisable_eid": "",
"pixel_eid": "",
"event_name": "",
"event_attributes": "",
"external_data": "",
"ip": "",
"user_agent": "",
"conversion_value": "",
"currency": "",
"page_location": "",
"device_os": "",
"device_type": "",
"package_app_name": "",
"package_app_version": "",
"timestamp": "",
"identifiers": {
"adct": "",
"email": "",
"email_sha256": "",
"email_md5": "",
"device_id": "",
"first_party_cookie": "",
"user_id": ""
}
}]
```
### Required Fields
`advertisable_eid`
: The unique identifier for your AdRoll advertisable.
`pixel_eid`
: The pixel identifier associated with your AdRoll advertisable.
`event_name`
: Event type. One of the following:
- `pageView`: See [Page view event](#s2s-api-event-pageview).
- `homeView`: See [Home view event](#s2s-api-event-homeview).
- `productSearch`: See [Product search event](#s2s-api-event-productsearch).
- `addToCart`: See [Add to cart event](#s2s-api-event-addtocart).
- `purchase`: See [Purchase event](#s2s-api-event-purchase).
- `highValuePage`: See [High-value page event](#s2s-api-event-highvaluepage).
- `gatedContent`: See [Gated content event](#s2s-api-event-gatedcontent).
- `demoRequest`: See [Demo request event](#s2s-api-event-demorequest).
- `signupPlan`: See [Signup plan event](#s2s-api-event-signupplan).
- `signupTrial`: See [Signup trial event](#s2s-api-event-signuptrial).
- `contactSales`: See [Contact sales event](#s2s-api-event-contactsales).
- `liveChat`: See [Live chat event](#s2s-api-event-livechat).
- `formFill`: See [Form fill event](#s2s-api-event-formfill).
`page_location`
: The full URL where the event occurred. When using a mobile app, you should build a “fake” URL using the format mentioned in [Mobile app URLs](#s2s-api-mobile-app-urls).
`ip`
: IPv4 or IPv6 user address.
`identifiers`
: You must provide at least one of `first_party_cookie` or `adct`. Additional identifiers are recommended.
- `adct`: Ad Click Token parameter retrieved after an ad click. See [Click ID (adct)](overview.md#s2s-api-id-click).
- `email`: Email address in clear text. See [Email](overview.md#s2s-api-id-email).
- `email_sha256`: Email address hashed using SHA-256. See [Email](overview.md#s2s-api-id-email).
- `email_md5`: Email address hashed using MD5. See [Email](overview.md#s2s-api-id-email).
- `device_id`: mobile device ID. See [Mobile device ID](overview.md#s2s-api-id-mobile).
- `first_party_cookie`: First-party cookie retrieved from AdRoll pixel or generated. See [First-Party Cookie](overview.md#s2s-api-id-fpc).
- `user_id`: Custom user ID. See [Custom user ID](overview.md#s2s-api-id-custom).
### Optional Fields
`event_attributes`
: See the [Event types](#s2s-api-event-types) for the format of this field.
`user_agent`
: Optional for requests originating from a mobile app. When the journey begins on the web, capture and send the browser’s user agent.
`conversion_value`
: Monetary value of the event (e.g., purchase amount).
`currency`
: The currency of the `conversion_value` (e.g., `USD`). Supports three-letter ISO 4217 currency codes.
`timestamp`
: UTC timestamp in seconds of when the event should be considered to have taken place. The current time will be used if omitted. You can use a decimal point if you want to specify milliseconds.
`device_os`
: The operating system of the user’s device for mobile events.
`device_type`
: The user’s device type for mobile events.
`package_app_name`
: Your application’s package name for mobile events.
`package_app_version`
: Your application’s package version for mobile events.
`external_data`
: JSON string containing any additional event data that is useful to your application.
### Specifying products
Most events let you specify a list of products relevant to the event. Each product can contain the following fields:
`product_id`
: The ID of the product on your site
`product_group`
: The group or department of the product on your site
`price`
: The price of the product added. The currency must match what is specified in the event-level `currency` field.
`quantity`
: Quantity of this product added to cart or purchased
`category`
: Other categorization for product on your site
### Mobile app URLs
When sending mobile app events, you can create a fake URL for the `page_location` field. This allows you to use URL audiences for campaign targeting. This URL should simulate a web-like structure using key app-related fields. Start with a domain you manage (the domain doesn’t need to be reachable), and append query parameters derived from the mobile app data. Include the following optional event fields:
- `device_os`
- `device_type`
- `package_app_name`
- `package_app_version`
For example, a valid mobile app URL could look like this:
```default
https://app.example.com?device_os=iOS&device_type=phone&package_app_name=com.example.TradingApp&package_app_version=14.1.3
```
## Event types
The following sections describe the purpose and format for supported events. Please let us know if you need additional events to better represent your needs.
## B2C event types
### Page view event
Event name: `pageView`
This event means a user has viewed a page on your website or app. It serves as the default event type when a more specific event (such as “add to cart” or “purchase”) isn’t available. Tracking page views provides insights into user behavior, popular content, and overall engagement.
#### NOTE
If the AdRoll pixel is already installed on a page, do not send an S2S `pageView` event for that same page. Sending both can lead to double counting in traffic metrics.
Required attributes:
- None
Optional attributes:
`event_attributes.products`
: An array of products shown on the page. See [Specifying products](#s2s-api-specify-products).
Below is an example event:
```json
{
"advertisable_eid": "",
"pixel_eid": "",
"page_location": "",
"ip": "",
"identifiers": {
"first_party_cookie": ""
},
"event_name": "pageView",
"event_attributes": {
"products": [
{
"product_id": "ABCDEF-12345",
"product_group": "womens-fashion",
"quantity": 1,
"price": "56.78",
"category": "top-sellers"
}
]
}
}
```
### Home view event
Event name: `homeView`
This event means a user has viewed the homepage of your website or app. It indicates an initial entry point or a return to the main landing page, providing insight into user engagement at the most general level.
Required attributes:
- None
Optional attributes:
- None
Below is an example event:
```json
{
"advertisable_eid": "",
"pixel_eid": "",
"page_location": "",
"ip": "",
"identifiers": {
"first_party_cookie": ""
},
"event_name": "homeView"
}
```
### Product search event
Event name: `productSearch`
This event means a user has searched for products on your website or app. It indicates active engagement and a potential interest in making a purchase.
Required attributes:
- None
Optional attributes:
`event_attributes.keywords`
: Search terms entered by the user
`event_attributes.products`
: An array of products returned as results. See [Specifying products](#s2s-api-specify-products).
Below is an example event:
```json
{
"advertisable_eid": "",
"pixel_eid": "",
"page_location": "",
"ip": "",
"identifiers": {
"first_party_cookie": ""
},
"event_name": "productSearch",
"event_attributes": {
"keywords": "shoes",
"products": [
{
"product_id": "ABCDEF-12345",
"product_group": "womens-fashion",
"price": "56.78",
"category": "top-sellers"
},
{
"product_id": "GHIJKL-67890",
"product_group": "womens-fashion",
"price": "61.23",
"category": "new-items"
},
{
"product_id": "MNOPQR-98765",
"product_group": "womens-fashion",
"price": "57.89"
},
{
"product_id": "STUVWX-43210",
"product_group": "womens-fashion",
"price": "63.45",
"category": "new-items"
}
]
}
}
```
### Add to cart event
Event name: `addToCart`
This event means a user has added a product to their shopping cart.
Required attributes:
- None
Optional attributes:
`currency`
: Currency of the conversion value
`event_attributes.products`
: An array of products added to the cart. See [Specifying products](#s2s-api-specify-products).
Below is an example event:
```json
{
"advertisable_eid": "",
"pixel_eid": "",
"page_location": "",
"ip": "",
"identifiers": {
"first_party_cookie": ""
},
"event_name": "addToCart",
"currency": "USD",
"event_attributes": {
"products": [
{
"product_id": "ABCDEF-12345",
"product_group": "womens-fashion",
"quantity": 2,
"price": "56.78",
"category": "top-sellers"
},
{
"product_id": "UVWXYZ-98765",
"product_group": "electronics",
"quantity": 1,
"price": "123.45",
"category": "new-items"
}
]
}
}
```
### Purchase event
Event name: `purchase`
This event means a user has completed a purchase.
Required attributes:
- None
Optional attributes:
`conversion_value`
: The total conversion value of this purchase
`currency`
: Currency of the conversion value
`event_attributes.order_id`
: ID of the order on your site
`event_attributes.products`
: An array of purchased products. See [Specifying products](#s2s-api-specify-products).
`external_data`
: JSON string containing for any additional conversion data that is useful to your needs. It’s value is available in Granular Conversion Reports.
Below is an example event:
```json
{
"advertisable_eid": "",
"pixel_eid": "",
"page_location": "",
"ip": "",
"identifiers": {
"first_party_cookie": ""
},
"event_name": "purchase",
"conversion_value": "113.56",
"currency": "USD",
"event_attributes": {
"order_id": "ABCDEFGH-1234-5678-9012-IJKLMNOPQRST",
"products": [
{
"product_id": "ABCDEF-12345",
"product_group": "womens-fashion",
"quantity": 2,
"price": "56.78",
"category": "top-sellers"
}
]
},
"external_data": "{\"foo\": \"bar\"}"
}
```
## B2B/ABM event types
### High-value page event
Event name: `highValuePage`
This event signifies a user has visited a page deemed to be of high value. This could be a pricing page, a key feature page, or any other page that indicates strong user interest or intent.
Required attributes:
- None
Optional attributes:
- None
Below is an example event:
```json
{
"advertisable_eid": "",
"pixel_eid": "",
"page_location": "",
"ip": "",
"identifiers": {
"first_party_cookie": ""
},
"event_name": "highValuePage"
}
```
### Gated content event
Event name: `gatedContent`
This event indicates a user has accessed gated content, such as a whitepaper, ebook, or exclusive article, typically after providing their information (e.g., email address).
Required attributes:
- None
Optional attributes:
- None
Below is an example event:
```json
{
"advertisable_eid": "",
"pixel_eid": "",
"page_location": "",
"ip": "",
"identifiers": {
"first_party_cookie": ""
},
"event_name": "gatedContent"
}
```
### Demo request event
Event name: `demoRequest`
This event means a user has requested a product demonstration. This is a strong indicator of interest and a high-intent action.
Required attributes:
- None
Optional attributes:
- None
Below is an example event:
```json
{
"advertisable_eid": "",
"pixel_eid": "",
"page_location": "",
"ip": "",
"identifiers": {
"first_party_cookie": ""
},
"event_name": "demoRequest"
}
```
### Signup plan event
Event name: `signupPlan`
This event signifies a user has completed a signup process for a specific plan or subscription.
Required attributes:
- None
Optional attributes:
- None
Below is an example event:
```json
{
"advertisable_eid": "",
"pixel_eid": "",
"page_location": "",
"ip": "",
"identifiers": {
"first_party_cookie": ""
},
"event_name": "signupPlan"
}
```
### Signup trial event
Event name: `signupTrial`
This event indicates a user has signed up for a free trial of your product or service.
Required attributes:
- None
Optional attributes:
- None
Below is an example event:
```json
{
"advertisable_eid": "",
"pixel_eid": "",
"page_location": "",
"ip": "",
"identifiers": {
"first_party_cookie": ""
},
"event_name": "signupTrial"
}
```
### Contact sales event
Event name: `contactSales`
This event means a user has initiated contact with your sales team, typically through a form submission or a direct click-to-call/email.
Required attributes:
- None
Optional attributes:
- None
Below is an example event:
```json
{
"advertisable_eid": "",
"pixel_eid": "",
"page_location": "",
"ip": "",
"identifiers": {
"first_party_cookie": ""
},
"event_name": "contactSales"
}
```
### Live chat event
Event name: `liveChat`
This event signifies a user has engaged in a live chat session.
Required attributes:
- None
Optional attributes:
- None
Below is an example event:
```json
{
"advertisable_eid": "",
"pixel_eid": "",
"page_location": "",
"ip": "",
"identifiers": {
"first_party_cookie": ""
},
"event_name": "liveChat"
}
```
### Form fill event
Event name: `formFill`
This event indicates a user has completed a form, excluding those covered by more specific events like demo requests or contact sales.
Required attributes:
- None
Optional attributes:
- None
Below is an example event:
```json
{
"advertisable_eid": "",
"pixel_eid": "",
"page_location": "",
"ip": "",
"identifiers": {
"first_party_cookie": ""
},
"event_name": "formFill"
}
```
# examples.html.md
# Automated Campaigns API Examples
#### WARNING
The Automated Campaigns API will be retired April 2025.
#### NOTE
In this documentation page we will use `MY_ADVERTISABLE_EID` as an example of an Advertisable EID.
To try the calls, use an Advertisable from your organization as ownership privileges are enforced.
> ##### Examples on this page
>
> * [Create a Strategy](#create-a-strategy)
> * [Fetch a Strategy](#fetch-a-strategy)
> * [Fetch Campaigns for a Strategy](#fetch-campaigns-for-a-strategy)
## Create a Strategy
Create a strategy with a set of campaigns under one goal and one budget.
```shell
curl -H 'Authorization: Token YOUR_TOKEN' \
-H "Content-Type: application/json" \
-d '{ "budget": 1000, "currency": "USD", "kpi_goal": 2.00, "kpi_metric": "CPC", "products": "web" }' \
"https://services.adroll.com/activate/api/v1/strategy?apikey=MYAPIKEY&advertisable_eid=MY_ADVERTISABLE_EID"
```
```shell
{
"data": [
{
"advertisable_eid": "MY_ADVERTISABLE_EID",
"budget": 1000.0,
"created_at": "2017-03-13T23:08:33.198960",
"currency": "USD",
"end_date": null,
"start_date": "2017-03-13T23:08:33.184906",
"status": "live",
"strategy_eid": "0000000STRATEGYEID8VOL"
}
],
"message": "",
"status": 200
}
```
## Fetch a Strategy
Fetch strategy data
```shell
curl -H 'Authorization: Token YOUR_TOKEN' \
https://services.adroll.com/activate/api/v1/strategy?apikey=MYAPIKEY&advertisable_eid=MY_ADVERTISABLE_EID&strategy_eid=0000000STRATEGYEID8VOL
```
```shell
{
"data": [
{
"advertisable_eid": "MY_ADVERTISABLE_EID",
"budget": 1000.0,
"created_at": "2017-03-13T23:08:33.198960",
"currency": "USD",
"end_date": null,
"start_date": "2017-03-13T23:08:33.184906",
"status": "live",
"strategy_eid": "0000000STRATEGYEID8VOL"
}
],
"mesage": "",
"status": 200
}
```
## Fetch Campaigns for a Strategy
Get all campaigns under a strategy
```shell
curl -H 'Authorization: Token YOUR_TOKEN' \
https://services.adroll.com/activate/api/v1/campaign?apikey=MYAPIKEY&advertisable_eid=MY_ADVERTISABLE_EID&strategy_eid=0000000STRATEGYEID8VOL
```
```shell
{
"data": [
{
"budget": 1000,
"campaign_eid": "RDEMJY2RF5CGZLRIGYIZ2U",
"created_at": "2017-03-13T23:35:56.805483",
"product": "retargeting",
"strategy_eid": "RYULGPREKBA6LIVBWU8VOL",
"updated_at": "2017-03-13T23:36:00.460571"
}
],
"message": "",
"status": 200
}
```
# examples.html.md
# CRUD API Examples
The following examples use the tool [cURL](https://curl.haxx.se/) 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)](#get-info-for-your-organization-including-eid)
> * [Create an advertisable](#create-an-advertisable)
> * [Get the info for the newly created pixel (created along with the advertisable)](#get-the-info-for-the-newly-created-pixel-created-along-with-the-advertisable)
> * [Get the new segment (created by the advertisable)](#get-the-new-segment-created-by-the-advertisable)
> * [Create an additional rule to match users against](#create-an-additional-rule-to-match-users-against)
> * [Create a conversion rule to match users against](#create-a-conversion-rule-to-match-users-against)
> * [Create a new retargeting campaign](#create-a-new-retargeting-campaign)
> * [Create a new AdGroup for the campaign](#create-a-new-adgroup-for-the-campaign)
> * [Upload an ad](#upload-an-ad)
> * [Upload another ad](#upload-another-ad)
> * [Attach both image ads to the new AdGroup](#attach-both-image-ads-to-the-new-adgroup)
> * [Attach a retargeting segment to the new AdGroup](#attach-a-retargeting-segment-to-the-new-adgroup)
> * [Exclude a converted segment from the new AdGroup](#exclude-a-converted-segment-from-the-new-adgroup)
> * [Fetch a report for the campaign](#fetch-a-report-for-the-campaign)
> * [Create a new run-of-network campaign with DMA geotargets](#create-a-new-run-of-network-campaign-with-dma-geotargets)
> * [Enable Dynamic Creative for your Advertisable (Advanced)](#enable-dynamic-creative-for-your-advertisable-advanced)
## Get info for your organization (including EID)
```shell
curl -H 'Authorization: Token YOUR_TOKEN' \
https://services.adroll.com/api/v1/organization/get?apikey=MYAPIKEY
```
```shell
{"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
```shell
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
```
```shell
{"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)
```shell
curl -H 'Authorization: Token YOUR_TOKEN' \
"https://services.adroll.com/api/v1/advertisable/get_pixel?apikey=MYAPIKEY&advertisable=MY_ADVERTISALE_EID"
```
```shell
{"results": {"code": "\n",
"eid": "XCOW5YUNQFGR5J5VSDITAX",
"status": "pending"}}
```
## Get the new segment (created by the advertisable)
```shell
curl -H 'Authorization: Token YOUR_TOKEN' \
"https://services.adroll.com/api/v1/pixel/get_segments?apikey=MYAPIKEY&pixel=MY_ADVERTISALE_EID"
```
```shell
{"results": [{"duration_sec": 7776000,
"eid": "TJ5XB3USVBBMDCRNFBU2H3",
"conversion_value": null}]}
```
## Create an additional rule to match users against
```shell
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
```
```shell
{"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
```shell
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
```
```shell
{"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
```shell
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
```
```shell
{"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
```shell
curl -H 'Authorization: Token YOUR_TOKEN' \
https://services.adroll.com/api/v1/adgroup/create?apikey=MYAPIKEY \
-F campaign=ZO245MTLPFGJ3E3CDJLCK4 \
-F name="Test AdGroup"
```
```shell
{"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
```shell
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
```
```shell
{"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
```shell
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
```
```shell
{"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
```shell
curl -H 'Authorization: Token YOUR_TOKEN' \
https://services.adroll.com/api/v1/adgroup/select_ads?apikey=MYAPIKEY \
-F adgroup=RUXJF6GPBZDQLAUFVL7MII \
-F ads=FBUD7AQR7ZBNHHWQ7IOMWA,OAX4PI4NWZBYHHEWI4TUJU
```
```shell
{"results": [{"ad": "FBUD7AQR7ZBNHHWQ7IOMWA", "errors": []},
{"ad": "OAX4PI4NWZBYHHEWI4TUJU", "errors": []}]}
```
## Attach a retargeting segment to the new AdGroup
```shell
curl -H 'Authorization: Token YOUR_TOKEN' \
https://services.adroll.com/api/v1/adgroup/add_segments?apikey=MYAPIKEY \
-F adgroup=RUXJF6GPBZDQLAUFVL7MII \
-F segments=TJ5XB3USVBBMDCRNFBU2H3
```
```shell
{"results": true}
```
## Exclude a converted segment from the new AdGroup
```shell
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
```
```shell
{"results": true}
```
## Fetch a report for the campaign
```shell
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
```
```shell
{"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
```shell
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
```
```shell
{"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
```shell
curl -H 'Authorization: Token YOUR_TOKEN' \
https://services.adroll.com/api/v1/adgroup/create?apikey=MYAPIKEY \
-F campaign=PFL30SXLKA033IOPFHDJ9SAX \
-F name="Test AdGroup"
```
```shell
{"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
```shell
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"
```
```shell
{"results":true}
```
## Enable Dynamic Creative for your Advertisable (Advanced)
Dynamic Creative is an effective way to produce personalized ads dynamically for General Web.
```shell
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"
```
```shell
{"results": true}
```
# examples.html.md
# Geotargeting API Examples
> ##### Examples on this page
>
> * [Search for a geotarget](#search-for-a-geotarget)
> * [Attach a GeoTarget to an AdGroup](#attach-a-geotarget-to-an-adgroup)
## Search for a geotarget
To search for a geotarget by name, you can use the [`GET /geo/api/search/v2/geo`](reference.md#get--geo-api-search-v2-geo) endpoint.
Specify:
`geo_types`
: Type of geopgrahic area you are searching for:
- `country`
- `metro`
- `region`
- `city`
- `postal_code`
`starts_with`
: Segment that you want to query
For example, to search for a city named Austin:
**Request**:
```shell
curl -H 'Authorization: Token YOUR_TOKEN' \
"https://services.adroll.com/geo/api/search/v2/geo?apikey=MYAPIKEY&geo_types=city&starts_with=austin"
```
**Response**:
```javascript
{
"results": [
{
"country": {
"iso2": "US",
"name": "United States"
},
"eid": "PVVKZWCOHFH3XNYZKX8GEO",
"name": "Austin",
"name_localized": null,
"type": "city"
}
]
}
```
## Attach a GeoTarget to an AdGroup
```shell
curl --location --request POST 'https://services.adroll.com/api/v1/adgroup/create?apikey=MYAPIKEY' \
-H 'Authorization: Token YOUR_TOKEN' \
--form 'advertisable="ADVERTISABLE_EID"' \
--form 'name="OI"' \
--form 'campaign="CAMPAIGN_EID"' \
--form 'geo_targets="[{\"eid\": \"PVVKZWCOHFH3XNYZKX8GEO\", \"is_negative\": false}]"'
```
**Response**:
```javascript
{
"results": {
"status": "approved",
"updated_date": "2021-01-25 14:42:40",
"coops": [],
"ad_optimization": "",
"campaign": "CAMPAIGN_EID",
"site_exclusions": [],
"platform_targets": [],
"type": "sites",
"segments": [],
"ads": [],
"geo_targets": [],
"placement_targets": [],
"eid": "ADGROUP_EID",
"is_cats4gold": false,
"created_date": "2021-01-25 14:42:40",
"demographic_targets": [],
"space_optimization": "",
"flight_timezone": "UTC",
"name": "OI"
}
}
```
Then you can check if the GeoTargets were correctly attached with the following API call:
```shell
curl --location \
--request GET \
-H 'Authorization: Token YOUR_TOKEN' \
'https://services.adroll.com/geo/api/targets/v1/target/ADGROUP_EID?apikey=MYAPIKEY'
```
**Response**:
```javascript
{
"data": [
{
"city": {
"country_code": "US",
"eid": "PVVKZWCOHFH3XNYZKX8GEO",
"id": 315714,
"is_facebook_target": false,
"name": "Austin",
"name_localized": null,
"region_code": "PA",
"region_name": "Pennsylvania",
"type": "city"
},
"country": {
"code": "US",
"country": "US",
"eid": "TTWGSKZDVNAVNKJ7GJ8GEO",
"id": 232,
"is_facebook_target": true,
"name": "United States",
"server_id": 232,
"type": "country"
},
"geo_eid": "PVVKZWCOHFH3XNYZKX8GEO",
"metro": {
"boundaries": "NY-PA",
"country": "US",
"country_code": "US",
"eid": "LPU5NINNNJHI3H72QS8GEO",
"id": 514,
"is_facebook_target": null,
"name": "Buffalo, NY",
"server_id": 514,
"type": "metro"
},
"name": "Austin",
"operation": "include",
"postalcode": null,
"region": {
"country": "US",
"eid": "O5OINHGRIVHJ5GTZAJ8GEO",
"id": "USPA",
"is_facebook_target": true,
"name": "Pennsylvania",
"name_localized": null,
"region": "PA",
"type": "region"
},
"type": "city"
}
],
"eid": "ADGROUP_EID"
}
```
# examples.html.md
# GraphQL Reporting API Examples
The examples on this page contain GraphQL queries. For how to run these queries, see [Your First Query](overview.md#your-first-graphql-query).
> ##### Examples on this page
>
> * [List of Advertisables for your Organization](#list-of-advertisables-for-your-organization)
> * [List of Campaigns for an Advertisable](#list-of-campaigns-for-an-advertisable)
> * [Delivery and Attribution data for all Campaigns](#delivery-and-attribution-data-for-all-campaigns)
> * [Delivery and Attribution data for a Campaign](#delivery-and-attribution-data-for-a-campaign)
> * [Delivery and Attribution data for an AdGroup](#delivery-and-attribution-data-for-an-adgroup)
> * [Delivery and Attribution data for an Ad](#delivery-and-attribution-data-for-an-ad)
> * [Connected TV Campaign Metrics](#connected-tv-campaign-metrics)
> * [Granular Conversions for an Advertisable](#granular-conversions-for-an-advertisable)
## List of Advertisables for your Organization
```graphql
{
organization {
current {
advertisables {
eid
name
}
}
}
}
```
## List of Campaigns for an Advertisable
```graphql
{
advertisable {
byEID(advertisable: "MY_ADVERTISABLE_EID") {
eid
name
campaigns {
eid
name
}
}
}
}
```
## Delivery and Attribution data for all Campaigns
```graphql
{
advertisable {
byEID(advertisable: "MY_ADVERTISABLE_EID") {
eid
name
campaigns {
eid
name
channel
metrics(start: "2017-06-01", end: "2017-06-02", currency: "USD") {
byDate {
# Deliveries
impressions
clicks
cost
# Attribution
viewThroughs
clickThroughs
viewRevenue
clickRevenue
}
}
}
}
}
}
```
## Delivery and Attribution data for a Campaign
```graphql
{
campaign {
byEID(campaign: "MY_CAMPAIGN_EID") {
eid
name
metrics(start: "2017-06-01", end: "2017-06-02", currency: "USD") {
byDate {
impressions
clicks
cost
viewThroughs
clickThroughs
viewRevenue
clickRevenue
}
}
}
}
}
```
## Delivery and Attribution data for an AdGroup
```graphql
{
adgroup {
byEID(adgroup: "MY_ADGROUP_EID") {
eid
name
status
metrics(start: "2017-06-01", end: "2017-06-02", currency: "USD") {
byDate {
# Deliveries
impressions
clicks
cost
# Attribution
viewThroughs
clickThroughs
viewRevenue
clickRevenue
}
}
}
}
}
```
## Delivery and Attribution data for an Ad
```graphql
{
ad {
byEID(ad: "MY_AD_EID") {
eid
name
adFormatName
metrics(start: "2017-06-01", end: "2017-06-02", currency: "USD") {
byDate {
impressions
clicks
cost
viewThroughs
clickThroughs
viewRevenue
clickRevenue
}
}
}
}
}
```
## Connected TV Campaign Metrics
To retrieve metrics for Connected TV (CTV) campaigns, you must include the `enableConnectedTVCampaigns:true` flag in your query. This enables access to video-specific metrics.
```graphql
query ($advertisable_eid: String!, $start_date: Date!, $end_date: Date!) {
flags(enableConnectedTVCampaigns:true)
advertisable {
byEID(advertisable: $advertisable_eid) {
eid
name
campaigns {
eid
name
channel
metrics(start: $start_date, end: $end_date, currency: "USD") {
summary {
impressions
clicks
cost
viewThroughs
clickThroughs
viewRevenue
clickRevenue
videoImpressions
videoViews
videoTwentyFivePercent
videoFiftyPercent
videoSeventyFivePercent
videoHundredPercent
}
}
adgroups {
eid
name
metrics(start: $start_date, end: $end_date, currency: "USD") {
summary {
impressions
clicks
cost
viewThroughs
clickThroughs
viewRevenue
clickRevenue
videoImpressions
videoViews
videoTwentyFivePercent
videoFiftyPercent
videoSeventyFivePercent
videoHundredPercent
}
}
}
}
}
}
}
```
**Query Variables:**
```json
{
"advertisable_eid": "MY_ADVERTISABLE_EID",
"start_date": "2025-08-01",
"end_date": "2025-08-28"
}
```
## Granular Conversions for an Advertisable
You can use this query to replicate the Granular Conversion Report (GCR) that is generated in the dashboard. Note that this API does not support the converted user’s email. If you need an email address, you’ll have to use the GCR genreated by the dashboard.
```graphql
{
advertisable {
byEID(advertisable: "MY_ADVERTISABLE_EID") {
granularConversions(start: "2020-06-01", end: "2020-07-01") {
time
type
attributionModel
attributionCredit
adrollConversionId
touchpointTimestamp
attributedConversions
lastTouchAttribution
channel
campaignEID
campaignType
campaignName
adgroupEID
adgroupName
adEID
adName
adSize
segmentEID
segmentName
attributedRevenue
externalData
device
country
city
firstTouchTimestamp
lastTouchTimestamp
daysToConversionFirstTouch
daysToConversionLastTouch
referrerURL
}
}
}
}
```
# examples.html.md
# Prospecting API Examples
#### NOTE
In this page we will use `0000000ADVERTISABLEEID` as an example of an advertisable EID. You should use an
advertisable from your organization as ownership privileges are enforced.
# examples.html.md
# Site Traffic Revealer Examples
> ##### Examples on this page
>
> * [Get Visitor Attributes](#get-visitor-attributes)
> * [Data Dictionary](#data-dictionary)
## Get Visitor Attributes
The Site Traffic Revealer JavaScript interface provides a callback called B2BPersonalizationData which returns an array of five (5) firmographic attributes pertaining to the visitor: `domain`, `company_name`, `company_industry`, `company_revenue`, and `company_size`. The following JavaScript code will set variables with the available firmographic data of the current web visitor for use on-site or to make available as data with other applications and pixels.
```shell
window.onB2BPersonalizationDataReady = (function(personalizationData) {
var companyDomain = personalizationData["domain"];
var companyName = personalizationData["company_name"];
var companyIndustry = personalizationData["company_industry"];
var companyRevenue = personalizationData["company_revenue"];
var companySize = personalizationData["company_size"];
var accountLists = personalizationData["account_lists"];
var journeyStage = personalizationData["journey_stage"];
});
```
**Example Response**:
| Description | Variable | Value |
|----------------------------------------------------------|-----------------|------------------------------------------------------------------------------------------------------------------------------------------|
| Company domain of the site visitor | companyDomain | adroll.com |
| Company name of the site visitor based on the domain | companyName | AdRoll |
| Company industry of the site visitor based on the domain | companyIndustry | Marketing and Advertising |
| Company revenue of the site visitor based on the domain | companyRevenue | Medium-Small ($10MM-$50MM) |
| Company size of the site visitor based on the domain | companySize | Medium-Large (500 - 999 Employees) |
| Account Lists that include the site visitor | accountLists | `[ {accountList: "US East High Intent", accountGroup: "A accounts"}, {accountList: "US West High Intent", accountGroup: "B accounts"} ]` |
| Journey Stage of the site Visitor | journeyStage | Unaware |
## Data Dictionary
Company Revenue - a value from one of the following (7) options:
| Micro ($0-$1MM) |
|-----------------------------|
| Small ($1MM-$10MM) |
| Medium-Small ($10MM-$50MM) |
| Medium-Large ($50MM-$100MM) |
| Large ($100MM-$200MM) |
| XLarge ($200MM-$1B) |
| XXLarge ($1B+) |
Company Size - a value from one of the following (8) options:
| Micro (1 - 9 Employees) |
|------------------------------------|
| Small (10 - 49 Employees) |
| Medium-Small (50 - 199 Employees) |
| Medium (200 - 499 Employees) |
| Medium-Large (500 - 999 Employees) |
| Large (1,000 - 4,999 Employees) |
| XLarge (5,000 - 10,000 Employees) |
| XXLarge (10,000+ Employees) |
Industry - a value from one of the following (150) options:
| Accounting |
|--------------------------------------|
| Agriculture |
| Airlines/Aviation |
| Alternative Dispute Resolution |
| Alternative Medicine |
| Animation |
| Apparel & Fashion |
| Architecture & Planning |
| Arts and Crafts |
| Automotive |
| Aviation & Aerospace |
| Banking |
| Biotechnology |
| Broadcast Media |
| Building Materials |
| Business Services |
| Business Supplies and Equipment |
| Capital Markets |
| Chemicals |
| Civic & Social Organization |
| Civil Engineering |
| Commercial Real Estate |
| Computer & Network Security |
| Computer Games |
| Computer Hardware |
| Computer Networking |
| Construction |
| Consumer Electronics |
| Consumer Goods |
| Consumer Services |
| Cosmetics |
| Dairy |
| Defense & Space |
| Dentistry |
| Design |
| E-Learning |
| Education Management |
| Electrical/Electronic Manufacturing |
| Entertainment |
| Environmental Services |
| Events Services |
| Executive Office |
| Facilities Services |
| Financial Services |
| Fine Art |
| Fishery |
| Food & Beverages |
| Food Production |
| Fund-Raising |
| Furniture |
| Gambling & Casinos |
| Glass, Ceramics & Concrete |
| Government Administration |
| Graphic Design |
| Health, Wellness and Fitness |
| Higher Education |
| Hospital & Health Care |
| Hospitality |
| Human Resources |
| Import and Export |
| Individual & Family Services |
| Industrial Automation |
| Industrial Engineering |
| Information Services |
| Insurance |
| International Affairs |
| International Trade and Development |
| Internet |
| Investment Banking |
| Investment Management |
| Judiciary |
| Law Enforcement |
| Law Practice |
| Legal Services |
| Legislative Office |
| Leisure, Travel & Tourism |
| Libraries |
| Local Business |
| Logistics and Supply Chain |
| Luxury Goods & Jewelry |
| Machinery |
| Management Consulting |
| Manufacturing |
| Maritime |
| Market Research |
| Marketing and Advertising |
| Mechanical or Industrial Engineering |
| Media Production |
| Medical Devices |
| Medical Practice |
| Mental Health Care |
| Military |
| Mining & Metals |
| Motion Pictures and Film |
| Museums and Institutions |
| Music |
| Nanotechnology |
| Newspapers |
| Non-Profit Organization Management |
| Oil & Energy |
| Online Media |
| Outsourcing/Offshoring |
| Package/Freight Delivery |
| Packaging and Containers |
| Paper & Forest Products |
| Performing Arts |
| Pharmaceuticals |
| Philanthropy |
| Photography |
| Plastics |
| Political Organization |
| Primary/Secondary Education |
| Printing |
| Professional Training & Coaching |
| Program Development |
| Public Policy |
| Public Relations and Communications |
| Public Safety |
| Publishing |
| Railroad Manufacture |
| Ranching |
| Real Estate |
| Recreational Facilities and Services |
| Religious Institutions |
| Renewables & Environment |
| Research |
| Restaurants |
| Retail |
| Security and Investigations |
| Semiconductors |
| Shipbuilding |
| Software / Information Technology |
| Sporting Goods |
| Sports |
| Staffing and Recruiting |
| Supermarkets |
| Telecommunications |
| Textiles |
| Think Tanks |
| Tobacco |
| Translation and Localization |
| Transportation/Trucking/Railroad |
| Utilities |
| Venture Capital & Private Equity |
| Veterinary |
| Warehousing |
| Wholesale |
| Wine and Spirits |
| Wireless |
| Writing and Editing |
# examples.html.md
# Universal Campaigns API Examples
#### WARNING
The Universal Campaigns API will be retired April 2025.
> ##### Examples on this page
>
> * [Create a Universal Campaign](#create-a-universal-campaign)
> * [Create a Universal AdGroup](#create-a-universal-adgroup)
> * [Fetch a Universal Campaign](#fetch-a-universal-campaign)
## Create a Universal Campaign
Create a Universal Campaign that can serve web retargeting ads. This campaign will not have any ads or
AdGroups yet. Those can be included in the request to set up the campaign via the `adgroups` parameter, or created
separately (see below). A Universal Campaign governs the budget, which is shared among its AdGroups. See also [`CampaignCreate`](reference.md#AdRoll Universal Campaigns API (v2) CampaignCreate)
```shell
curl -H 'Authorization: Token YOUR_TOKEN' \
-H "Content-Type: application/json" \
-d ' { "advertisable_eid": "MY_ADVERTISABLE_EID", "name": "My First Campaign", "budget_settings": { "budget_type": "daily", "goal": 200.00, } }' \
"https://services.adroll.com/activate/api/v2/campaign?apikey=MYAPIKEY&advertisable_eid=MY_ADVERTISABLE_EID"
```
```shell
{
"data": [
{
"advertisable_eid": "MY_ADVERTISABLE_EID",
"budget": 1000.0,
"created_at": "2017-03-13T23:08:33.198960",
"currency": "USD",
"end_date": null,
"start_date": "2017-03-13T23:08:33.184906",
"status": "live",
"strategy_eid": "MY_UNI_CAMPAIGN_EID"
}
]
}
```
## Create a Universal AdGroup
Create an AdGroup as part of an existing Universal Campaign. The Universal AdGroup is where you specify start and end
dates, KPI goal and metric, a set of ads, and targeting parameters. In order to create a new AdGroup within a campaign, the
Universal Campaign must have a budget of at least `5 * ([number of current AdGroups] + [number of AdGroups being created])` (in USD), otherwise the AdGroup will be rejected. AdGroups should only contain either all static or all dynamic ads, and the ad types should match the value of the ad_type parameter. See also [`AdGroupCreate`](reference.md#AdRoll Universal Campaigns API (v2) AdGroupCreate)
```shell
curl -H 'Authorization: Token YOUR_TOKEN' \
-H "Content-Type: application/json" \
-d '{ "ad_type": "static", "ads": [{"eid": STATIC_AD_EID, "status": "live"}], "name": "My Adgroup", "kpi_metric": "CPC", "kpi_goal": 3}' \
"https://services.adroll.com/activate/api/v2/adgroup?apikey=MYAPIKEY&campaign_eid=MY_UNI_CAMPAIGN_EID"
```
```shell
{
"data": {
"ad_type": "static",
"ads": [{"eid": "STATIC_AD_EID", "status": "live"}],
"campaign_eid": "MY_UNI_CAMPAIGN_EID",
"created_at": "2017-03-13T23:08:33.198960",
"eid": "NEW_ADGROUP_EID",
"email": null,
"kpi_goal": 3.0,
"kpi_metric": "CPC",
"name": "My Adgroup",
"start_date": "2017-03-13T23:08:33.184906",
"end_date": null,
"status": "live",
"targeting_features": {
"geotargets": [],
"negative_segment_eids": [],
"positive_segment_eids": []
}
}
}
```
## Fetch a Universal Campaign
```shell
curl -H 'Authorization: Token YOUR_TOKEN' \
"https://services.adroll.com/activate/api/v2/campaign?apikey=MYAPIKEY&advertisable_eid=MY_ADVERTISABLE_EID&eid=MY_UNI_CAMPAIGN_EID"
```
```shell
{
"data": [
{
"advertisable_eid": "MY_ADVERTISABLE_EID",
"budget": 1000.0,
"created_at": "2017-03-13T23:08:33.198960",
"currency": "USD",
"end_date": null,
"start_date": "2017-03-13T23:08:33.184906",
"status": "live",
"strategy_eid": "MY_UNI_CAMPAIGN_EID"
}
]
}
```
# examples.html.md
# User Lists API Examples
> ##### Examples on this page
>
> * [Retrieve the size of a segment](#retrieve-the-size-of-a-segment)
## Retrieve the size of a segment
To retrieve a summary of the size of a segment, you can use the [`GET /user-lists/api/v1/userlists/segment`](reference.md#get--user-lists-api-v1-userlists-segment) endpoint.
Specify:
`advertisable_eid`
: Advertisable that owns the segment
`segment_eids`
: Segment that you want to query
`breakdowns`
: How to group the data, for example `summary` or `date`
`start_date`
: First day to retreive data for
`end_date`
: Last day to retrieve data for
**Request**:
```shell
curl -H 'Authorization: Token YOUR_TOKEN' \
"https://services.adroll.com/user-lists/api/v1/userlists/segment?apikey=MYAPIKEY&advertisable_eid=MY_ADVERTISABLE_EID&segment_eids=MY_SEGMENT_EID&breakdowns=summary&start_date=2019-08-21&end_date=2019-09-26"
```
**Response**:
```javascript
{
"results": {
"summary": {
"current_visitors": 1613519,
"current_visitors_in_date_range": 781266,
"new_visitors": 781266,
"total_visitors": 781266
}
}
}
```
# external-segments.html.md
# Manage External Data Segments
The guide shows you how to create and manage external data segments using the [Audience API](../audience-api/index.md#audience-api-index).
## Create the segment
**Request Arguments**
| Key | Data Type | Description | Example |
|---------------|-------------|--------------------------------------------------------------------------------------------|-------------------------------|
| advertiser_id | string | ID of the advertiser to create a new segment for | `MOCQ3OFYHRA4PGY6VCZYRT` |
| type | string | Type of the segment, in this case `arbitrary_data` | `arbitrary_data` |
| name | string | Name of the segment | `Entertainment Segment` |
| url | string | The URL pattern you want to apply your external data filter against | `/checkout/cart*` |
| expression | string | The external data expression - see [External Data Expressions](#external-data-expressions) | `category == "entertainment"` |
| duration | integer | Number of days users are in the segment | `90` |
**Request Format**:
```shell
curl -H 'Authorization: Token YOUR_TOKEN' \
-H "Content-Type: application/json" \
-d '{
"name": "{segment_name}",
"advertiser_id": "{advertiser_id}",
"type": "arbitrary_data",
"url": "{url_pattern}",
"expression": "{external_data_expression}",
"duration": {duration}
}' \
"https://services.adroll.com/audience/v1/segments?apikey=MYAPIKEY"
```
**Example Request**:
```shell
curl -H 'Authorization: Token YOUR_TOKEN' \
-H "Content-Type: application/json"
-d '{
"name": "Your External Data Segment",
"advertiser_id": "MOCQ3OFYHRA4PGY6VCZYRT",
"type": "arbitrary_data",
"url": "cart*",
"expression": "category == \"hotels\" && [\"hilton\", \"westin\", \"sheraton\"] contains refererDomain",
"duration": 90
}' \
"https://services.adroll.com/audience/v1/segments?apikey=MYAPIKEY"
```
**Example Response**:
```json
{
"result": "success",
"segment": {
"advertiser_id": "MOCQ3OFYHRA4PGY6VCZYRT",
"conversion_value": null,
"created_date": 1486523382000,
"duration": 90,
"expression": "category == \"Hotels\" && [\"hilton\", \"westin\", \"sheraton\"] contains refererDomain",
"is_active": true,
"is_conversion": false,
"name": "Your External Data Segment",
"segment_id": "IIEBKZ5R7BAADIF3BVVY7T",
"source": "slargma",
"tags": "s",
"type": "arbitrary_data",
"url": "cart*"
}
}
```
## Retrieve the segment
**Request Format**:
```shell
curl -H 'Authorization: Token YOUR_TOKEN' \
"https://services.adroll.com/audience/v1/segments/{segment_id}?apikey=MYAPIKEY"
```
**Example Request**:
```shell
curl -H 'Authorization: Token YOUR_TOKEN' \
"https://services.adroll.com/audience/v1/segments/IIEBKZ5R7BAADIF3BVVY7T?apikey=MYAPIKEY"
```
**Example Response**:
```json
{
"advertiser_id": "MOCQ3OFYHRA4PGY6VCZYRT",
"conversion_value": null,
"created_date": 1486523382000,
"duration": 90,
"expression": "category == \"Hotels\" && [\"hilton\", \"westin\", \"sheraton\"] contains refererDomain",
"is_active": true,
"is_conversion": false,
"name": "Your External Data Segment",
"segment_id": "IIEBKZ5R7BAADIF3BVVY7T",
"source": "slargma",
"tags": "s",
"type": "arbitrary_data",
"url": "cart*"
}
```
## Update the segment
**Request Arguments**
You can choose to edit the name, url, or duration of the segment.
| Key | Data Type | Description | Example |
|----------|-------------|---------------------------------------------------------------------|-------------------|
| name | string | Name of the segment | `Fashion Segment` |
| url | string | The URL pattern you want to apply your external data filter against | `/women/shoes*` |
| duration | integer | Number of days users are in the segment | `90` |
**Request Format**:
```shell
curl -H 'Authorization: Token YOUR_TOKEN' \
-H "Content-Type: application/json" \
-d '{
"name": "{segment_name}",
"url": "{url_pattern}",
"duration": "{duration}"
}' \
"https://services.adroll.com/audience/v1/segments/{segment_id}?apikey=MYAPIKEY"
```
**Example Request**:
```shell
curl -H 'Authorization: Token YOUR_TOKEN' \
-H "Content-Type: application/json" \
-d '{
"name": "Your Edited External Data Segment",
"url": "buy*",
}' \
"https://services.adroll.com/audience/v1/segments/IIEBKZ5R7BAADIF3BVVY7T?apikey=MYAPIKEY"
```
**Example Response**:
```json
{
"result": "success",
"segment": {
"advertiser_id": "MOCQ3OFYHRA4PGY6VCZYRT",
"conversion_value": null,
"created_date": 1486523382000,
"duration": 90,
"expression": "category == \"Hotels\" && [\"hilton\", \"westin\", \"sheraton\"] contains refererDomain",
"is_active": true,
"is_conversion": false,
"name": "Your Edited External Data Segment",
"segment_id": "IIEBKZ5R7BAADIF3BVVY7T",
"source": "slargma",
"tags": "s",
"type": "arbitrary_data",
"url": "buy*"
}
}
```
## Delete the segment
**Request Format**:
```shell
curl -H 'Authorization: Token YOUR_TOKEN' \
-X DELETE \
"https://services.adroll.com/audience/v1/segments/{segment_id}?apikey=MYAPIKEY"
```
**Example Request**:
```shell
curl -H 'Authorization: Token YOUR_TOKEN' \
-X DELETE \
"https://services.adroll.com/audience/v1/segments/IIEBKZ5R7BAADIF3BVVY7T?apikey=MYAPIKEY"
```
**Example Response**:
```json
{
"result": "success",
"segment_id": "IIEBKZ5R7BAADIF3BVVY7T"
}
```
## External Data Expressions
You may use the expressions to target your Segment audiences based on data passed in through the pixel.
**It supports the following operators**
| Operator | Description | Example |
|------------|--------------------------------|----------------------------------------------------------------------|
| == | equals (case sensitive) | `category == "entertainment"` |
| > | greater than | `age > 21` |
| < | less than | `age < 21` |
| >= | greater than or equal to | `age >= 21` |
| <= | less than or equal to | `age <= 21` |
| && | and | `category == "contractors" && vertical contains "construction"` |
| || | or | `category == "contractors" || vertical contains "construction"` |
| contains | string or array contains value | `category contains "contractors" || [94102, 94115] contains zipcode` |
| ~= | regex match | `category ~= ".*education.*"` |
**Additional Notes**
- You can use single quotes `'` for strings instead of double quotes (`"`). For example: `category == 'foobar'`.
- You can use brackets to specify order of operations. For example, `"a > 1 && (b > 2 || c < 3)"`.
# faq.html.md
# Frequently Asked Questions
> ##### Questions on this page
>
> * [When does reporting data become available?](#when-does-reporting-data-become-available)
> * [How to use display_url_override parameter?](#how-to-use-display-url-override-parameter)
> * [How can I tell if an ad has been deleted?](#how-can-i-tell-if-an-ad-has-been-deleted)
> * [Is there a limit to the size of GraphQL queries?](#is-there-a-limit-to-the-size-of-graphql-queries)
## When does reporting data become available?
We provide approximate real-time reporting data throughout the day. The numbers for a day are typically available within twelve hours after the day finishes. However, that data is not considered finalized until 48 hours after the start of the current UTC day. All of our dates and times are in UTC.
## How to use display_url_override parameter?
For web campaigns, display_url_override parameter is deprecated. If the destination URL is a redirect, you will need to specify the final destination URL in the display_url_override parameter as this is needed to pass ad review.
## How can I tell if an ad has been deleted?
Ads are never really ‘deleted’, we just set the ads `is_active` flag to `false`.
## Is there a limit to the size of GraphQL queries?
There is no limit to the size of GraphQL queries. Behind the scenes, the GraphQL Reporting API queries multiple services to retrieve your data. These requests are done in parallel and in bulk. It is more efficient to request all of the data you need in a single query than to create multiple queries.
# get-started-rollworks.html.md
# AdRoll ABM API Documentation
AdRoll ABM (formerly RollWorks) offers a host of APIs for many use cases — from pushing ad performance data into your system of record to pushing target account lists into other platforms.
The NextRoll API can be used by AdRoll ABM customers.
To make your first API call, see [Get Started with the NextRoll API](get-started.md#guide-get-started)
## Available APIs
Here are some of our most popular APIs and their use cases.
### [Site Traffic Revealer](../site-traffic-revealer/index.md#site-traffic-revealer-index)
The Site Traffic Revealer helps marketers better understand their website traffic in real time to create a more tailored experience for their website visitors and analyze trends in their visitor data. The benefits of the Site Traffic Revealer are:
- Provide site visitor analytics in your source of truth to inform business decisions (e.g., content strategy)
- Enable personalization of website,chat, and other content. AdRoll ABM has direct integrations with Google Analytics, Uberflip, Hushly, Folloze, and [more](https://www.rollworks.com/partners/)
- Provide site visitor data for engagement modeling
### [Reporting API](../graphql-reporting-api/index.md#graphql-reporting-api-index)
Whether you want to export data into data visualization tools (Tableau, Datorama, Looker, Domo, etc.) or create custom CSV reports, our reporting API can fit your needs.
AdRoll ABM customers most commonly use our GraphQL Reporting API because of its flexibility and ability to surface many different metrics. We also offer a [GraphQL query builder](https://app.adroll.com/reporting/graphiql), which customers can use to help build their reporting queries. The most common data our customers query are spend, impressions, clicks by account, ad unit, and campaign.
For examples on querying for metrics for Playbooks, see [Playbook reporting](rollworks-playbooks.md#guide-playbooks-reporting). For further examples, see [GraphQL Reporting API Examples](../graphql-reporting-api/examples.md#graphql-reporting-api-examples).
### [Playbooks API](rollworks-playbooks.md#guide-playbooks)
Playbooks are a simple user experience for running B2B advertising campaigns based on the best practices AdRoll ABM Customer Success organization has developed over the past several years. You can use our APIs to report on and manipulate Playbooks.
### [Target Account List API](target-account-lists.md#guide-target-account-lists)
Our Target Account List API grow our customers’ cross-channel orchestration capabilities by enabling them to sync target account data across their tech stack.
Here’s how AdRoll ABM customers and partners most commonly use this API:
- Fetch accounts on their target account lists to build a similar, personalized experience with users at those target accounts across different channels.
- Push a dynamic list of accounts into the AdRoll ABM platform when they’re showing high levels of intent and/or engagement in order to automatically activate ads against them.
### [Account Metrics API](account-metrics.md#guide-account-metrics)
You can access AdRoll ABM account metrics like unique visitors and page views using the [GraphQL Reporting API](../graphql-reporting-api/index.md#graphql-reporting-api-index). Metrics are available per account for a list of campaigns in an Advertisable. You can specify any date range as long as it doesn’t exceed thirty days. If you need more than thirty days of data, you can make multiple queries and iterate on the date range.
### [Email Contact List API](../audience-api/index.md#audience-api-index)
Sync email contact lists to reach contacts with ad campaigns and/or gather firmographic and technographic insights about those contacts. AdRoll ABM customers and partners most commonly use the Email Contact List API when they’re unable to integrate their CRM or MAP.
# get-started.html.md
# Get Started with the NextRoll API
The NextRoll API is divided into [several services](../index.md#api-list), each with its own focus. Every API uses a common base URL and the authentication method. API parameters and responses can vary with each service, however we try to use consistent terminology across services. If you have any questions, you can [contact the API team](../support.md#support).
For a high-level overview of the object structure, see [Get to know NextRoll](object-structure.md#guides-object-structure).
## Register as a Developer
To make API calls, you’ll need to register as developer and create an application:
1. [Create a developer account](https://developers.nextroll.com/accounts/create)
2. [Create an application](https://developers.nextroll.com/my-apps/new-app)
It is recommended that you create an application for production and one for testing. This allows you to have a separate OAuth 2.0 redirect URI for each of your development environments.
The default quota is 100 API requests per service per day. If you think you need your limit increased, [send us a message](../support.md#support).
#### NOTE
Be sure to give your application a meaningful name. Users will see the name on the OAuth consent page and it helps us when reviewing usage for quota increases.
#### NOTE
Once you’ve registered your application, you’ll see both a consumer key and secret. You’ll only use the consumer key when making API calls using Personal Access Tokens. You’ll use both key and secret when authenticating with OAuth 2.0.
## Base URL
The base URL for all API calls is:
```text
https://services.adroll.com
```
HTTPS is the only supported protocol.
## Authentication
### OAuth 2.0
All API calls are authenticated using [**OAuth 2.0**](https://datatracker.ietf.org/doc/html/rfc6749.html). For information on how to use OAuth 2.0 see [Get Started with OAuth 2.0](oauth.md#guide-oauth).
### Personal Access Tokens
Personal Access Tokens (PAT) are a simple way for developers to make API calls. Developers use them in simple API integrations and scripts where OAuth is not practical. If you’re building an application where you need to ask your users for their Personal Access Token, you should instead use [OAuth](oauth.md#guide-oauth).
To get started, first visit the [your settings page in the dashboard](https://app.adroll.com/settings/personal-access-tokens). From this page, you’ll be able to create and revoke Personal Access Tokens.
To make a request using a Personal Access Token, you need to include two things: your Personal Access Token and your application’s client ID. The Personal Access Token identifies the AdRoll user. The client ID identifies the application making the API call.
The Personal Access Token is sent via the `Authorization` header with the Token scheme. For example: `Authorization: Token MYTOKEN`
You’ll also need to pass your application’s client ID in the `apikey` query parameter. The `apikey` parameter is always sent in the URL query string, regardless of the HTTP method used. The `apikey` parameter should not be included in the body of the request for POST, PUT, or PATCH calls.
A complete request would look something like:
```shell
curl --header 'Authorization: Token MYTOKEN' \
'https://services.adroll.com/api/v1/organization/get_advertisables?apikey=MYAPIKEY'
```
## Your First API Call
The Advertisable is commonly used object in user accounts. Since the Advertisable EID will be used for most API calls, it is recommended to retrieve the Advertisable EID as your first API call.
Using cURL:
```shell
curl -H 'Authorization: Token YOUR_TOKEN' \
'https://services.adroll.com/api/v1/organization/get_advertisables?apikey=MYAPIKEY'
```
Using the [Requests](https://2.python-requests.org/en/master/) library in Python:
```python
r = requests.get(
'https://services.adroll.com/api/v1/organization/get_advertisables?apikey=MYAPIKEY',
headers={
'Authorization': 'Token MY_TOKEN'
}
)
```
Using PHP:
```php
{
const data = await res.json();
if (res.ok) {
console.log(data);
} else {
console.error(data);
}
})
.catch(console.error);
```
## Next Steps
Check out one of our [API guides](index.md#guides-index) or jump straight to our [list of services](../index.md#api-list).
- [Creating Audiences](create-audiences.md#guide-audiences)
- [Automated Campaigns API Examples](../automated-campaigns-api/examples.md#automated-campaigns-examples)
- [CRUD API Examples](../crud-api/examples.md#examples)
- [Prospecting API Examples](../prospecting-api/examples.md#prospecting-examples)
# guides.html.md
# Guides
The following guides use the Audience API:
- [Creating Audiences](../../guides/create-audiences.md#guide-audiences)
- [Manage External Data Segments](../../guides/external-segments.md#guide-external-segments)
# marketing-platforms.html.md
# Marketing Platforms Guide
This guide is intended for marketing platforms that are interested in expanding their current solutions to new channels and inventory sources. In this guide, you’ll learn how to use the NextRoll API to easily onboard your customers.
## Getting to know the NextRoll API
Before you start building your integration, it helps to have a basic understanding of the NextRoll API:
[Get Started with the NextRoll API](get-started.md#guide-get-started) will help you make your first API call.
[Get to know NextRoll](object-structure.md#guides-object-structure) provides an overview of the object structure and defines common terminology.
## Overview
A single Organization contains all of your customer’s accounts, also known as Advertisables. When onboarding a customer, you will create a new Advertisable for them.
To begin, you’ll start the initial setup:
1. [Organization Setup](#guides-marketing-platform-create-org)
After that, your customers will go through the following lifecycle:
1. [Onboarding a Customer](#guides-marketing-platform-on-board)
2. [Campaign Management](#guides-marketing-platform-manage)
3. [Offboarding a Customer](#guides-marketing-platform-off-board)
## Organization Setup
After you successfully [create a user account](https://app.adroll.com/onboarding/register) an Organization and Advertisable are automatically generated for you.
To create accounts for your customers, therefore generate customer-specific Advertisables, you’ll need your Organization EID. This can be found in the `eid` field returned by [`GET /api/v1/organization/get`](../crud-api/reference.md#get--api-v1-organization-get).
## Onboarding a Customer
The following steps are needed to onboard a new customer.
### Creating an Advertisable
First, you’ll create an Advertisable for the customer. This establishes an Advertisable EID that will be used for subsequent API calls.
Call [`POST /api/v1/advertisable/create`](../crud-api/reference.md#post--api-v1-advertisable-create) with the following parameters:
- `organization` — EID for your Organization
- `name` — Name of the customer. This can be returned in the GraphQL Reporting API when generating reports
- `country_code` - ISO-3166 2-Letter country code the Advertisable is registered in
### Pixel Setup
The Pixel is a snippet of JavaScript that you place on all of your customer’s webpages and can be configured by setting JavaScript variables.
You can retrieve the Pixel using the API call [`GET /api/v1/advertisable/get_pixel`](../crud-api/reference.md#get--api-v1-advertisable-get_pixel) and specify the `advertisable` parameter using the EID returned when creating the Advertisable.
The JavaScript snippet should be placed right before the closing `` HTML tag.
#### Enhanced Conversion Tracking
**Optional**
To enable revenue tracking or the tracking of custom values such as order IDs, user IDs, and more please review [Setting Up Enhanced Conversion Tracking](https://help.adroll.com/hc/en-us/articles/212629938-Setting-Up-Enhanced-Conversion-Tracking).
For example:
```html