Configure the Microsoft Ads Conversions API

The Microsoft Advertising Conversions API (CAPI) lets your brand send server-side conversion events — such as purchases, leads, sign-ups, and other actions that happen away from the browser — to Microsoft Advertising. Microsoft Advertising uses these events to attribute conversions to your campaigns, improve measurement accuracy, and build audiences for remarketing. Amperity identifies each event by a hashed email address or phone number, a Microsoft click ID (msclkid), or another customer identifier, and hashes email and phone values before sending them.

Send conversion events to Microsoft Advertising using the Conversions API (CAPI) to attribute conversions that happen away from the browser — in-store purchases, CRM events, phone orders, and other server-side transactions — back to your Microsoft Advertising campaigns, and to build audiences for remarketing. Each row returned by your query is sent as a single custom conversion event, carrying an event name, an event time, and at least one customer identifier.

Amperity hashes email and phone identifiers with SHA-256 before sending them; raw email and phone values never leave Amperity. Other identifiers — an anonymous ID, external ID, Microsoft click ID (msclkid), or mobile advertising ID — are sent as provided. See the Conversions API (CAPI) guide for more information.

Beta

The Microsoft Ads Conversions API connector is currently in beta. Contact your Amperity representative to learn more.

Caution

The values for email and phone sent to Microsoft Advertising are SHA-256 hashed automatically by Amperity before sending. Do not use the TO_HEX() function with the email and phone fields for queries that return results for Microsoft Advertising.

Get details

Review the following details before configuring credentials for Microsoft Advertising and before configuring Amperity to send conversion events to Microsoft Advertising.

	Credential settings API token Required The API token that authorizes Amperity to send conversion events to the Microsoft Advertising Conversions API. This is a bearer token scoped to a single UET tag; it must be authorized for the UET Tag ID configured in this destination. Obtain the token in the Microsoft Advertising UI: open the UET section, edit the UET tag, select Use Conversions API, and copy the token. Contact your Amperity representative if you need help obtaining a token.
	Microsoft Advertising settings UET Tag ID Required The Microsoft Advertising UET tag ID that receives these events. Amperity includes it in the Conversions API request path, and the API token configured for this destination must be authorized for this tag. Find it in the UET section of your Microsoft Advertising account. A destination sends events for a single UET tag.
	Request properties A query must return event_name and event_time, plus at least one identifier column — anonymous_id, external_id, email, phone, msclkid, idfa, or gaid. All other columns are optional. See Conversion event fields for the full list of columns your query may return.

Configure credentials

Configure credentials for Microsoft Advertising before adding a destination.

An individual with access to Microsoft Advertising should use SnapPass to securely share “API token” details with the individual who configures Amperity.

To configure credentials for the Microsoft Ads Conversions API

	From the Settings page, select the Credentials tab, and then click the Add credential button.
	In the Credentials settings dialog box, do the following: From the Plugin dropdown, select Microsoft Ads Conversions API. Note Amperity provides three Microsoft Advertising connectors. Select Microsoft Ads Conversions API to send conversion events through Microsoft Advertising’s Conversions API. Microsoft Ads Offline Events sends offline conversions through the older offline-conversions API, and Microsoft Ads sends customer profiles for audience targeting. Assign the credential a name and description that ensures other users of Amperity can recognize when to use this destination.
	The settings that are available for a credential vary by credential type. For the “Microsoft Ads Conversions API” credential type, configure settings, and then click Save. API token Required The API token that authorizes Amperity to send conversion events to the Microsoft Advertising Conversions API. This is a bearer token scoped to a single UET tag; it must be authorized for the UET Tag ID configured in this destination. Obtain the token in the Microsoft Advertising UI: open the UET section, edit the UET tag, select Use Conversions API, and copy the token. Contact your Amperity representative if you need help obtaining a token.

Add destination

Use a sandbox to configure a destination for Microsoft Advertising. Before promoting your changes, send a sample audience, and then verify the results in Microsoft Advertising. After verifying the end-to-end workflow, push the destination from the sandbox to production.

To add a destination

	Open the Destinations tab to configure a destination for Microsoft Advertising. Click the Add Destination button to open the Destination dialog box. Enter the name of the destination and a description. For example: “Microsoft Advertising conversion events” and “Send conversion events to Microsoft Advertising.”.
	Credentials allow Amperity to connect to Microsoft Advertising. The credential type is set automatically. You may use an existing credential or you may add a new one. Select an existing credential from the Credential dropdown. – or – Select Create a new credential from the Credential dropdown. This opens the Credential dialog box.
	In the “Destination settings” dialog box, assign the destination a name and description that ensures other users of Amperity can recognize when to use this destination. Configure business user access By default a destination is available to all users who have permission to view personally identifiable information (PII). Enable the Admin only checkbox to restrict access to only users assigned to the Datagrid Operator and Datagrid Administrator policies. Enable the PII setting checkbox to allow limited access to PII for this destination. Use the Restrict PII access policy option to prevent users from viewing data marked as PII anywhere in Amperity and from sending data to downstream workflows.
	Configure the following settings, and then click “Save”. UET Tag ID Required The Microsoft Advertising UET tag ID that receives these events. Amperity includes it in the Conversions API request path, and the API token configured for this destination must be authorized for this tag. Find it in the UET section of your Microsoft Advertising account. A destination sends events for a single UET tag.
	After configuring this destination users may use orchestrations to send query results Microsoft Advertising.
	Validate the audience with Microsoft Advertising by using a sample audience with a very small membership. For example: 10 or 100 members or the minimum audience size recommended by Microsoft Advertising. Send the sample audience to Microsoft Advertising and verify the sample audience is correct in Microsoft Advertising. Make adjustments if necessary. Only send full audiences after validation is complete.

Build a query

Use a query to build a combination of data — typically from the Unified Transactions and Customer 360 tables — that returns one row per conversion event to send to Microsoft Advertising. Each row must include an event name and an event time, plus at least one customer identifier — an email address, phone number, Microsoft click ID, anonymous ID, external ID, or mobile advertising ID. Adding more identifiers can improve the match rate. You can also include a conversion value and currency, and a transaction ID, which Amperity sends with each event.

Review the Conversion event fields section for the columns your query must and may return.

Note

Microsoft Advertising deduplicates events by event_id. If your query does not return event_id, Amperity generates a stable one from the event’s name, time, transaction ID, and first identifier, so that retries of the same event do not create duplicate conversions.

Note

For an event to be attributed to a conversion goal, its event_name must match the event action of a custom conversion goal configured in Microsoft Advertising. Events are still accepted — and can contribute to audiences and measurement — when no matching goal exists, so confirm your goal setup in Microsoft Advertising if accepted events are not appearing as conversions.

Bound the query to recent conversions — Microsoft Advertising accepts events with an event_time within the last 7 days — so each orchestration sends new events instead of re-sending history. A query that returns a collection of recent purchase events for use in Microsoft Advertising is similar to:

SELECT
  'purchase' AS event_name
  ,ut.order_datetime AS event_time
  ,ut.order_id AS transaction_id
  ,c360.email AS email
  ,c360.phone AS phone
  ,ut.order_revenue AS value
  ,ut.currency AS currency
FROM Unified_Transactions ut
LEFT JOIN Customer_360 c360 ON ut.amperity_id = c360.amperity_id
WHERE ut.order_datetime > (CURRENT_DATE - interval '7' day)
AND (c360.email IS NOT NULL OR c360.phone IS NOT NULL)

Data validation

Amperity validates each row before sending and drops rows that Microsoft Advertising would reject, so that one invalid row does not cause an entire batch of events to be rejected. Dropped rows are reported as failed with the reason. A row is dropped when:

• event_name or event_time is missing.

• event_time cannot be parsed as UNIX epoch seconds or an ISO 8601 instant, is more than 7 days in the past, or is in the future.

• the row has no identifier — anonymous_id, external_id, email, phone, msclkid, idfa, and gaid are all empty.

• every identifier the row provides is unusable — for example, the only identifier is an email address that cannot be validated — leaving no identifier after normalization.

An individual identifier that cannot be used — an email without an @, or a phone number that cannot be normalized — is dropped from that row; the rest of the event is still sent when another identifier remains. A non-numeric value (and its currency) is omitted the same way, and an ad_storage_consent value other than G or D is omitted.

Conversion event fields

The following table describes each column Amperity sends to Microsoft Advertising. A query must return columns with the same name as listed in the “Amperity name” column; Amperity maps them to the Microsoft Advertising Conversions API field names automatically.

Important

A query must return event_name and event_time, plus at least one identifier column — anonymous_id, external_id, email, phone, msclkid, idfa, or gaid. All other columns are optional.

Amperity name	Microsoft Advertising field	Description
event_name	eventName	Required A name for the conversion event. To deduplicate an event that is also sent by Universal Event Tracking (UET), use the same event name in both systems.
event_time	eventTime	Required When the event occurred, as UNIX epoch seconds (for example, 1710438591) or a full ISO 8601 instant (for example, 2026-07-10T12:00:00Z). Must be within the last 7 days; values older than 7 days or in the future are dropped.
event_id	eventId	Optional A unique identifier for the event, used to deduplicate an event sent by both UET and the Conversions API. If omitted, Amperity generates a stable value so retries do not create duplicate conversions.
anonymous_id	userData.anonymousId	Optional A guest (non-authenticated) visitor ID, sent as provided. At least one identifier — anonymous_id, external_id, email, phone, msclkid, idfa, or gaid — is required per row.
external_id	userData.externalId	Optional An authenticated user ID, sent as provided.
email	userData.em	Optional An email address. Amperity normalizes and SHA-256 hashes the value following Microsoft’s hashing rules before sending.
phone	userData.ph	Optional A phone number. Amperity normalizes the number to E.164 format using the US region and applies SHA-256 hashing before sending.
msclkid	userData.msclkid	Optional The Microsoft click ID captured from the ad click.
idfa	userData.idfa	Optional An Apple mobile advertising ID (Identifier for Advertisers), sent as provided.
gaid	userData.gaid	Optional A Google (Android) advertising ID, sent as provided.
client_user_agent	userData.clientUserAgent	Optional The user agent of the customer’s browser, sent as provided.
client_ip_address	userData.clientIpAddress	Optional The IP address of the customer, sent as provided.
ad_storage_consent	adStorageConsent	Optional The customer’s advertising-storage consent. Must be G (granted) or D (denied); any other value is omitted. An event with no value defaults to granted.
transaction_id	customData.transactionId	Optional Your identifier for the transaction, sent as provided.
value	customData.value	Optional A numeric conversion value for the event.
currency	customData.currency	Optional The currency for value. Sent only when value is also present.

Note

ad_storage_consent controls how Microsoft Advertising may use an event. Send G (granted) or D (denied) per row; an event with no value is processed as granted. If you send Microsoft Advertising conversion data for customers in the EEA, the UK, or Switzerland, populate ad_storage_consent from your own consent records for those rows rather than relying on the default.

Workflow actions

A workflow will occasionally show an error that describes what prevented a workflow from completing successfully. These first appear as alerts in the notifications pane. The alert describes the error, and then links to the Workflows tab.

Open the Workflows page to review a list of workflow actions, choose an action to resolve the workflow error, and then follow the steps that are shown.

	You may receive a notifications error for a configured Microsoft Advertising destination. This appears as an alert in the notifications pane on the Destinations tab. If you receive a notification error, review the details, and then click the View Workflow link to open this notification error in the Workflows page.
	On the Workflows page, review the individual steps to determine which steps have errors that require your attention, and then click Show Resolutions to review the list of workflow actions generated for this error.
	A list of individual workflow actions are shown. Review the list to identify which action you should take. Some workflow actions are common across workflows and will often be available, such as retrying a specific task within a workflow or restarting a workflow. These types of actions can often resolve an error. In certain cases, actions are specific and are shown when certain conditions exist in your tenant. These types of actions typically must be resolved and may require steps that must be done upstream or downstream from your Amperity workflow. Amperity provides a series of workflow actions that can help resolve specific issues that may arise with Microsoft Advertising, including: Invalid credentials
	Select a workflow action from the list of actions, and then review the steps for resolving that error. After you have completed the steps in the workflow action, click Continue to rerun the workflow.

Note

If Microsoft Advertising rejects an event, the workflow reports Microsoft’s field-level validation message (up to 10 per batch) — review the values returned by your query. A batch is rejected in full only when every event in it is invalid; otherwise the valid events are still sent. If sends are rate limited, Amperity retries automatically.

Invalid credentials

The credentials that are defined in Amperity are invalid.

To resolve this error, verify that the credentials required by this workflow are valid.

1. Open the Credentials page.

2. Review the details for the credentials used with this workflow. Update the credentials for Microsoft Advertising if required.

3. Return to the workflow action, and then click Resolve to retry this workflow.

Note

A 401 response from Microsoft Advertising means the API token is missing, expired, or not authorized for the configured UET Tag ID. Obtain a new token from the Microsoft Advertising UI for the correct tag, and then update the credential in Amperity.