AdRoll Conversions and Events API

The AdRoll Conversions and Events API, also known as a Conversions API (CAPI) or server-to-server tracking, allows you to send marketing and conversion events directly from your internal systems to AdRoll.

Unlike browser-based tracking, the API does not rely on JavaScript firing in a user’s browser. This allows you to capture events that occur in secure portals, logged-in environments, applications, backend systems, or anywhere else the AdRoll Pixel cannot reliably reach. For mobile applications, we recommend using a Mobile Measurement Provider (MMP), like Appsflyer, to ensure accurate attribution and event tracking across app environments.

Events sent through the API can support:

• Audience targeting and suppression
• Campaign attribution and reporting
• AdRoll BidIQ® bidding and optimization

Availability

The Conversions and Events API is available in open beta and supports server-to-server event ingestion for AdRoll customers. AdRoll continues to expand the API’s event processing, matching, reporting, and integration capabilities based on customer needs and feedback.

The API is designed for direct server-side implementation by a developer or technical team. To get started, you need:

• An existing AdRoll account
• An API key (see Authentication regarding Server Access Tokens in the API docs) provided by AdRoll. Note: this is different from the Personal Access Tokens for other AdRoll APIs.
• Technical resources to implement and maintain the integration

The Conversions and Events API is included with an existing AdRoll account during the open beta.

To request access, contact your Account Manager, Customer Onboarding Manager, or AdRoll Customer Support.

Review the Conversions and Events API documentation for authentication, endpoints, payload requirements, and other technical specifications.

Why use the Conversions and Events API?

Capture events that browsers miss

Ad blockers, browser privacy restrictions, script limitations, and secure environments can prevent browser pixels from capturing important customer activity.

The Conversions and Events API allows you to send events directly from your server so that meaningful conversions, behavioral signals, and offline actions can be used within AdRoll.

Examples include:

• Purchases completed in a secure checkout or account portal
• Account registrations or upgrades
• Qualified leads and completed consultations
• Contracts signed outside the browser
• Appointments or transactions recorded in a backend system
• Activity within a logged-in platform
• Offline or phone conversions

Improve campaign optimization

Server-side conversion events provide AdRoll with additional signals about the outcomes your campaigns are generating.

This allows campaigns to optimize using meaningful business events that may not be visible through browser-based tracking alone, rather than relying only on upstream actions such as clicks, page visits, or registrations.

Learn more about how AdRoll BidIQ supports campaign bidding and optimization.

Build more accurate audiences

Events sent through the API can populate User Event Audiences, including conversion audiences.

You can use these audiences to:

• Retarget users based on meaningful actions
• Suppress customers who have already converted
• Reach users who completed one step but not another
• Separate high-value converters from general website visitors
• Build audiences from activity occurring in secure or offline environments

Maintain greater control over tracking

Your organization controls which events are sent, how identifiers are captured, and how the integration fits into your internal systems.

This can make server-side tracking useful for secure or regulated environments where browser scripts are restricted, unreliable, or impractical.

How the API works

At a high level, the Conversions and Events API moves event collection from the user’s browser to your server.

1. A user interacts with an AdRoll ad.
   When the user clicks an eligible ad, an AdRoll Click ID is appended to the landing-page URL.
2. Your system captures an identifier.
   Your website or backend captures and stores the Click ID or a first-party cookie.
3. The user completes an event.
   The event might occur immediately or later within your website, account portal, application, CRM, or another internal system.
4. Your server sends the event to AdRoll.
   Your integration submits the event through the API with the relevant identifier and event information.
5. AdRoll processes the event.
   AdRoll uses the identifier to associate the event with the corresponding visitor or earlier ad interaction when possible.
6. The event is used across AdRoll.
   Depending on how the event and audience are configured, it can contribute to audience segmentation, targeting, suppression, attribution, campaign reporting, and BidIQ optimization.

How is this different from the AdRoll Pixel?

The AdRoll Pixel and the Conversions and Events API collect events in different ways.

The AdRoll Pixel uses JavaScript in a user’s browser. This makes it useful for collecting website activity, but it can be affected by:

• Ad blockers
• Browser privacy settings
• Cookie restrictions
• Secure or logged-in environments
• Pages where third-party scripts cannot be installed

The Conversions and Events API sends events directly from your server, without relying on the browser or client-side JavaScript.

For most advertisers, the API complements the AdRoll Pixel rather than replacing it. You can continue using the Pixel for standard website activity while using the API to capture events the Pixel cannot reliably reach.

Organizations that cannot use browser pixels may use the API as their primary event-tracking method.

Supported identifiers

Each event must include at least one identifier that AdRoll can use to process and match the event.

AdRoll Click ID (adct)

The AdRoll Click ID is a unique identifier appended to the landing-page URL after an AdRoll ad click.

Your system can capture and store the Click ID, associate it with the relevant user or transaction, and include it when sending a later event.

Click ID mapping supports a 30-day window. Events sent more than 30 days after the original click may not be attributed to that ad interaction.

First-party cookie

A first-party cookie can be used to associate server-side events with activity collected through your AdRoll implementation.

The first-party cookie can be retrieved from the AdRoll Pixel or generated by your system. Your implementation must retain the identifier and include it in the API request when the corresponding event occurs.

Refer to the Conversions and Events API documentation for current identifier requirements, collection methods, and formatting instructions.

Capturing the AdRoll Click ID

The AdRoll Click ID uses the query parameter adct.

When a user clicks an eligible AdRoll ad, the Click ID is appended to the landing-page URL. For example:

https://example.com?adct=click123

Your implementation should:

1. Read the adct value from the landing-page URL.
2. Store it in your backend or another persistent first-party system.
3. Associate it with the relevant user or transaction record.
4. Include it in the API request when the corresponding event occurs.

When using a third-party click tracker, make sure the tracker passes the adct parameter through to the final landing-page URL.

Supported event types

The Conversions and Events API supports a standard set of AdRoll event types. Custom event names are not currently supported.

Your internal business events should be mapped to the closest applicable AdRoll event type.

For example, events such as an account upgrade, completed consultation, signed contract, or qualified lead may be mapped to the appropriate conversion event based on your implementation and measurement goals.

Although the API event name must use AdRoll’s standard event taxonomy, the corresponding audience can be given a descriptive name that reflects your organization’s terminology.

See User Event Audience for the current list of supported event types and instructions for creating an audience from server-to-server events.

Create an audience from server-side events

To use an event for audience targeting or suppression, create a User Event Audience that corresponds to the event sent through the API.

To create a User Event Audience:

1. Sign in to AdRoll.
2. Navigate to Audiences > Website Audiences.
3. Select New Audience.
4. Select User Event as the audience type.
5. Enter a descriptive audience name.
6. Select the event that corresponds to the event_name sent through the API.
7. Choose whether the audience represents a conversion.
8. Set how long visitors should remain in the audience.

Once the audience is populated, it can be used to positively or negatively target visitors in your campaigns.

For complete setup instructions, see User Event Audience.

Reporting and attribution

Conversion events sent through the API are processed through AdRoll’s attribution systems and incorporated into standard campaign reporting alongside other attributed campaign activity.

When an event includes an eligible Click ID, AdRoll can associate the conversion with the earlier ad interaction within the supported 30-day mapping window.

Events that occur more than 30 days after the original click may still be received, but they may not be attributed to that ad interaction.

AdRoll is continuing to enhance reporting and analysis workflows for server-side events.

BidIQ optimization

Server-side conversion events provide BidIQ with additional signals about the business outcomes generated by your campaigns.

This is especially valuable when your most important conversions occur outside the browser. By sending those events to AdRoll, campaign optimization can account for outcomes that may otherwise be missing from browser-based tracking.

For example, instead of optimizing only toward page visits or account registrations, you can provide AdRoll with events representing downstream outcomes such as completed purchases, account upgrades, qualified leads, or other mapped conversions.

Learn more about AdRoll’s bidding and optimization engine in AdRoll BidIQ.

Important implementation considerations

Review the following requirements with your marketing, analytics, and technical teams before implementing the API.

Technical implementation

The API requires a direct server-side integration using the endpoints, authentication methods, and payload structure described in the API documentation.

A developer or technical team is needed to:

• Capture and retain identifiers
• Construct API requests
• Map internal events to AdRoll event types
• Handle API responses and errors
• Test the implementation
• Maintain the integration

Event taxonomy

Each event must use one of AdRoll’s supported event names. Map your internal business events to the closest applicable event type when constructing API requests.

Audience names can be customized to reflect your organization’s terminology.

Identifier collection

Capture and retain either the Click ID or first-party cookie needed to process each event.

Click ID window

Click IDs support a 30-day mapping window. We encourage customers to send us events as soon as possible so they can influence BidIQ and be included in attribution reporting more quickly. Events occurring outside that window may not be attributed to the original ad click.

Consider your typical sales cycle and time to conversion when deciding whether to use Click IDs, first-party cookies, or both.

Event deduplication

Do not send the same event through both the AdRoll Pixel and the Conversions and Events API.

For example, avoid submitting a pageView event through the API when the Pixel already collects the same page view. Sending the same event through both methods may result in duplicate activity.

Privacy and consent

Your organization is responsible for ensuring that its collection, storage, and transmission of event data complies with applicable privacy, data-protection, and consent requirements.

This includes determining:

• Which events and identifiers may be collected
• Whether user consent is required
• How long identifiers may be retained
• Which privacy disclosures are required
• How data-subject requests will be handled

How to get started

Implementing the Conversions and Events API typically requires coordination between your marketing, analytics, and engineering teams.

1. Request API access

Contact your Account Manager, Customer Onboarding Manager, or AdRoll Customer Support to request an Server Access Token (API key) and confirm that your account is ready for the integration.

2. Define the events you want to track

Identify the business events that are currently missing from your AdRoll tracking.

For each event, document:

• Where the event occurs
• When it should be sent
• Whether the AdRoll Pixel already captures it
• Which supported AdRoll event type it should use
• Whether it will be used for reporting, targeting, suppression, or optimization

3. Choose an identifier strategy

Determine whether your integration will use the AdRoll Click ID, a first-party cookie, or both.

Make sure the selected identifiers can be captured, stored, and associated with the relevant user or transaction until the event occurs.

4. Map your internal events

Map each internal business event to the closest supported AdRoll event type.

For example, your organization might map a completed subscription, approved application, or signed agreement to the purchase event when it represents the primary conversion outcome.

Review User Event Audience for the supported event names.

5. Implement the API request

Your engineering team sends events from your server to AdRoll using the required endpoint and payload structure.

Use the Conversions and Events API documentation for authentication, request formatting, supported fields, and error handling.

6. Validate your events

Test the integration to confirm that:

• Requests are accepted by the API
• A valid Click ID or first-party cookie is included
• Events use supported event names
• Event timestamps and values are formatted correctly
• Duplicate events are not being submitted
• Events are being received and processed as expected

Optionally, the dry_run=true parameter can be used to validate the payload without impacting audiences or attribution; in this mode, the request is validated and logged only

7. Create your User Event Audiences

Create a conversion audience for each event you intend to use for targeting, suppression, or conversion measurement. Note that for BidIQ optimization, events such as purchase must also be associated with a conversion audience; otherwise, even if the event is sent, it may not be used effectively for optimization.

Give each audience a descriptive name that clearly communicates the business action it represents.

8. Activate and optimize

Once the integration is validated, begin sending production events.

These events can then contribute to:

• Audience creation
• Targeting and suppression
• Campaign attribution
• Standard campaign reporting
• BidIQ optimization

Frequently asked questions