Send conversion events to 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.

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.

Add orchestration

An orchestration defines the relationship between query results and a destination, including the destination and the frequency at which an orchestration runs.

To add an orchestration

1. Open the Activations page, select the Orchestrations tab, and then click the Add orchestration button. This opens the Add orchestration dialog box.

2. From the Object type dropdown, select Query.

3. From the Object dropdown, select the query for which results is sent to Microsoft Advertising.

4. From the Destination dropdown, select a destination that is configured for sending data to Microsoft Advertising.

5. Verify all settings.

6. Set the workflow to Manual. You can change this to automatic later, after verifying the end-to-end workflow.

7. Click Save.

Run orchestration

Run the orchestration manually to validate that it works.

To run the orchestration

1. Open the Activations page, select the Orchestrations tab, and then open the menu for the Microsoft Advertising orchestration. Select Run.

2. The Status column for the orchestration updates to say “Waiting to start”, after which the notifications pane updates to include a notification that shows the current status.

3. When the orchestration has run successfully, the status is updated to “Completed”.

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.