Send events

AI-generated Key Takeaways

outlined_flag

• Use the Data Manager API to send online or offline event data for conversion tracking and improved ad performance.

• To send event data, you need to prepare a Destination and format, hash, and encode your event data into an Event object.

• Combine the Destination and Events into a request body, updating placeholders with your account and destination details.

• Send the request using the Google APIs Explorer and review the response, which will include a requestId for successful requests or error details for failures.

• You can send events for multiple destinations in a single request by using destination references.

You can work through this quickstart to get familiar with sending event data.

Use the Data Manager API for either of the following scenarios:

• Send Google Ads tag conversions or Google Analytics key events as an additional data source for your tag conversions, to maximize ad interaction signals and strengthen your data and overall performance.

  This feature is only available to accounts an allowlist. Fill out the form if you're interested in adding your Google Ads account or Google Analytics property.

• Send event data for Google Ads offline conversions or enhanced conversions for leads.

Choose the version of the guide that you want to see:

Advertiser Data Partner

In this quickstart, you complete the following steps:

1. Prepare a Destination to receive event data.
2. Prepare event data to send.
3. Build an IngestionService request for events.
4. Send the request with the Google APIs Explorer.
5. Understand success and failure responses.

Prepare destinations

Before you can send data, you need to prepare at least one Destination for the data. Here's a sample Destination for you to use:

    {
      "operatingAccount": {
        "accountType": "OPERATING_ACCOUNT_TYPE",
        "accountId": "OPERATING_ACCOUNT_ID"
      },

      "loginAccount": {
        "accountType": "LOGIN_ACCOUNT_TYPE",
        "accountId": "LOGIN_ACCOUNT_ID"
      },

      "productDestinationId": "PRODUCT_DESTINATION_ID"
    }

Here are the fields of a Destination:

operatingAccount

The account that receives the events.

For events sent as an additional data source, the operating account can be either a Google Ads account or a Google Analytics property. Set the accountType to GOOGLE_ADS or GOOGLE_ANALYTICS_PROPERTY, and set the accountId to the Google Ads customer ID or Google Analytics property ID. If the accountType is GOOGLE_ANALYTICS_PROPERTY, the request's credentials must be for a Google Analytics user with the Editor or Administrator role for the property.

For offline conversions and enhanced conversions for leads, the operating account must be a Google Ads account, so set the accountType to GOOGLE_ADS and set the accountId to the Google Ads customer ID.

loginAccount

The account where the credential's user has access.

If your OAuth credentials are for a user with access to a Google Ads manager account that has the operatingAccount as one of its subaccounts, loginAccount is required. Set the accountId of the loginAccount to the ID of the manager account, and set the accountType of the loginAccount to GOOGLE_ADS.

If your OAuth credentials are for a user with direct access to the operatingAccount, you don't need to set loginAccount and it defaults to the operatingAccount. However, we recommend setting loginAccount to the same accountId and accountType as the operatingAccount. This helps avoid problems if the set of accounts the user can access changes.

productDestinationId

The ID of the entity in the operatingAccount that receives the events.

For events sent as an additional data source, the productDestinationId must be the ID of a Google Ads conversion with type set to WEBPAGE, or the measurement ID of a Google Analytics Web stream. You can't send events as an additional data source to a Google Analytics iOS app or Android app stream.

For offline conversions or enhanced conversions for leads, the productDestinationId must be the ID of a Google Ads conversion action with type set to UPLOAD_CLICKS.

The example in this guide shows how to construct a request that sends every event to the same destination. If you want to send events for multiple destinations in the same request, see send events for multiple destinations.

Prepare event data

Consider the following event data. Each table corresponds to one conversion event. Each conversion event has a timestamp of the event, its conversion action, and conversion value.

Each event might have ad identifiers, like gclid, or user identifiers, like email addresses, phone numbers, and address information. An event can also have:

• Information about the user assessed at the time of the event, like the value of the customer or whether they are a new, returning, or reengaged customer.
• Shopping cart data.
• Additional event parameters or user properties for a destination, such as client_id or user_id for Google Analytics.

Here's the event data:

Format the data

Format the fields according as specified in the formatting guide. Here's the event data after formatting:

Hash and encode the data

In addition, the formatted email addresses, given names, and family names must be hashed using the SHA-256 algorithm and encoded using either hex or Base64 encoding. Here's the event data after formatting, hashing, and encoding using hex encoding:

Convert the data to Event objects

Convert each event's formatted and hashed data to an Event. Populate the following fields as indicated:

1. Set eventTimestamp to the time the event occurred.

   Events for Google Analytics must have an eventTimestamp within the last 72 hours.

2. Set required fields for your use case.

   Use case	Identifiers	transactionId	eventSource
   Offline conversions or enhanced conversions for leads	Required. Set at least one of the following: adIdentifiers with at least one of gclid, gbraid, wbraid, or sessionAttributes set userData	Optional	Required. Set to one of the enum values for EventSource.
   Events sent as an additional data source to a Google Ads destination	Required. Set at least one of the following: adIdentifiers with at least one of gclid, gbraid, or wbraid set userData	Required	Optional. If set, must be WEB.
   Events sent as an additional data source to a Google Analytics destination	Required. Set at least one of the following: clientId adIdentifiers with gclid set userData	Required	Optional. If set, must be WEB.

3. Populate any other fields where you have a value for the event. Refer to the Event reference documentation for the complete list of available fields.

Add Google Analytics information

If the destinations for an event sent as an additional data source include a Google Analytics property, populate the following fields as indicated:

eventName

Required. The name of the Google Analytics event.

transactionId

Required . The unique identifier for the event.

At least one identifier

At least one of the following fields must be set:

• clientId: Unique identifier for a user instance of a web client. See Send event to the Measurement Protocol.

• adIdentifiers.gclid: A Google Click ID.

• userData: Identifiers for the user, such as email addresses, phone numbers, or address information.

destinationReferences

Required if the request-level destinations list contains more than one Google Analytics Destination. Add an entry to destinationReferences to specify which Google Analytics destination should receive the event. See send events to multiple destinations for more information about destination references.

If destinationReferences isn't set or has multiple entries that refer to Google Analytics destinations, the Data Manager API rejects the event with the error MULTIPLE_DESTINATIONS_FOR_GOOGLE_ANALYTICS_EVENT.

userId

Optional. The User-ID for the user.

additionalEventParameters

Optional, but recommended. Populate this list with any Google Analytics event parameters that aren't captured in the other Event fields. The parameters can include additional recommended parameters from the purchase event, or other parameters you want to capture. Use the Google Analytics parameter name for the parameterName of the EventParameter.

For example, if you have the taxes associated with a transaction, add an entry to additionalEventParameters with parameterName set to tax, and value set to the tax cost.

We don't recommend adding entries for the transactionId, currency, or value Google Analytics event parameters. Instead, populate the transactionId, currency, and conversionValue of the Event, which take precedence over any entries in additionalEventParameters.

Add cart data for purchase events

Populate the cartData field of the Event with information about the items purchased. For each item purchased, add an Item object to the items list of the CartData and populate the following fields as indicated:

itemId

Required. A unique identifier for the item.

unitPrice

Required. The unit price excluding tax, shipping, and event scoped (transaction-level) discounts.

If the item has an item scoped discount, use the discounted unit price. For example, if an item has a unit price of 27.67 and a unit discount of 6.66, then set unitPrice to 21.01.

quantity

Required. The quantity of units purchased for this particular item.

additionalItemParameters

Populate this list with any item scoped parameters that aren't captured in the other Item fields. Use the Google Analytics item parameter name for the parameterName of the ItemParameter.

For example, if you have the brand and category for an item, add an entry to the item's additionalItemParameters with parameterName set to item_brand and value set to the brand name, and another entry with parameterName set to item_category and the value set to the category of the item.

We don't recommend adding entries for the quantity, price, or item_id Google Analytics item parameters. Instead, populate the itemId, unitPrice, and quantity of the Item, which take precedence over any entries in additionalItemParameters.

Here's a sample Event for the formatted, hashed, and encoded data from the second event, with additional data for Google Analytics:

{
  "adIdentifiers": {
     "gclid": "GCLID_2"
  },
  "conversionValue": 42.02,
  "currency": "EUR",
  "eventTimestamp": "2025-06-10T23:42:33-05:00",
  "transactionId": "DEF999911111",
  "eventSource": "WEB",
  "userData": {
    "userIdentifiers": [
      {
        "emailAddress": "3E693CF7E5B67880BFF33B2D2626DADB7BF1D4BC737192E47CF8BAA89ACF2250"
      },
      {
        "emailAddress": "223EBDA6F6889B1494551BA902D9D381DAF2F642BAE055888E96343D53E9F9C4"
      },
      {
        "address": {
          "givenName": "2752B88686847FA5C86F47B94CE652B7B3F22A91C37617D451A4DB9AFA431450",
          "familyName": "6654977D57DDDD3C0329CA741B109EF6CD6430BEDD00008AAD213DF25683D77F",
          "regionCode": "PT",
          "postalCode": "1229-076"
        }
      }
    ],
  },
  "userProperties": {
    "customerType": "RETURNING"
  },
  "eventName": "purchase",
  "clientId": "9876543210.1761582117",
  "userId": "user_DEF9876",
  "additionalEventParameters": [
    {
      "parameterName": "ad_unit_name",
      "value": "Banner_02"
    }
  ],
  "cartData": {
    "transactionDiscount": 6.66,
    "items": [
      {
        "itemId": "SKU_12346",
        "quantity": 2,
        "unitPrice": 21.01,
        "additionalItemParameters": [
          {
            "parameterName": "item_name",
            "value": "Google Grey Women's Tee"
          },
          {
            "parameterName": "affiliation",
            "value": "Google Merchandise Store"
          },
          {
            "parameterName": "coupon",
            "value": "SUMMER_FUN"
          },
          {
            "parameterName": "discount",
            "value": "3.33"
          },
          {
            "parameterName": "index",
            "value": "1"
          },
          {
            "parameterName": "item_brand",
            "value": "Google"
          },
          {
            "parameterName": "item_category",
            "value": "Apparel"
          },
          {
            "parameterName": "item_category2",
            "value": "Adult"
          },
          {
            "parameterName": "item_category3",
            "value": "Shirts"
          },
          {
            "parameterName": "item_category4",
            "value": "Crew"
          },
          {
            "parameterName": "item_category5",
            "value": "Short sleeve"
          },
          {
            "parameterName": "item_list_id",
            "value": "related_products"
          },
          {
            "parameterName": "item_list_name",
            "value": "Related Products"
          }
        ]
      }
    ]
  }
}

Build the request body

Combine the Destination and Events for the request body:

{
  "destinations": [
    {
      "operatingAccount": {
        "accountType": "OPERATING_ACCOUNT_TYPE",
        "accountId": "OPERATING_ACCOUNT_ID"
      },

      "loginAccount": {
        "accountType": "LOGIN_ACCOUNT_TYPE",
        "accountId": "LOGIN_ACCOUNT_ID"
      },

      "productDestinationId": "CONVERSION_ACTION_1_ID"
    }
  ],
  "encoding": "HEX",
  "events": [
     {
       "adIdentifiers": {
         "gclid": "GCLID_1"
       },
       "conversionValue": 30.03,
       "currency": "USD",
       "eventTimestamp": "2025-06-10T20:07:01Z",
       "transactionId": "ABC798654321",
       "eventSource": "WEB",
       "userData": {
         "userIdentifiers": [
           {
             "address": {
               "givenName": "96D9632F363564CC3032521409CF22A852F2032EEC099ED5967C0D000CEC607A",
               "familyName": "DB98D2607EFFFA28AFF66975868BF54C075ECA7157E35064DCE08E20B85B1081",
               "regionCode": "US",
               "postalCode": "94045"
             }
           }
         ]
       },
       "userProperties": {
         "customerType": "NEW",
         "customerValueBucket": "HIGH"
       },
       "eventName": "purchase",
       "clientId": "1234567890.1761581763",
       "userId": "user_ABC12345",
       "additionalEventParameters": [
         {
           "parameterName": "ad_unit_name",
           "value": "Banner_01"
         }
       ],
       "cartData": {
         "transactionDiscount": 6.66,
         "items": [
           {
             "itemId": "SKU_12345",
             "quantity": 3,
             "unitPrice": 10.01,
             "additionalItemParameters": [
               {
                 "parameterName": "item_name",
                 "value": "Stan and Friends Tee"
               },
               {
                 "parameterName": "affiliation",
                 "value": "Google Merchandise Store"
               },
               {
                 "parameterName": "coupon",
                 "value": "SUMMER_FUN"
               },
               {
                 "parameterName": "discount",
                 "value": "2.22"
               },
               {
                 "parameterName": "index",
                 "value": "0"
               },
               {
                 "parameterName": "item_brand",
                 "value": "Google"
               },
               {
                 "parameterName": "item_category",
                 "value": "Apparel"
               },
               {
                 "parameterName": "item_category2",
                 "value": "Adult"
               },
               {
                 "parameterName": "item_category3",
                 "value": "Shirts"
               },
               {
                 "parameterName": "item_category4",
                 "value": "Crew"
               },
               {
                 "parameterName": "item_category5",
                 "value": "Short sleeve"
               },
               {
                 "parameterName": "item_list_id",
                 "value": "related_products"
               },
               {
                 "parameterName": "item_list_name",
                 "value": "Related Products"
               }
             ]
           }
         ]

       }
     },
     {
       "adIdentifiers": {
         "gclid": "GCLID_2"
       },
       "conversionValue": 42.02,
       "currency": "EUR",
       "eventTimestamp": "2025-06-11T04:42:33Z",
       "transactionId": "DEF999911111",
       "eventSource": "WEB",
       "userData": {
         "userIdentifiers": [
           {
             "emailAddress": "3E693CF7E5B67880BFF33B2D2626DADB7BF1D4BC737192E47CF8BAA89ACF2250"
           },
           {
             "emailAddress": "223EBDA6F6889B1494551BA902D9D381DAF2F642BAE055888E96343D53E9F9C4"
           },
           {
             "address": {
               "givenName": "2752B88686847FA5C86F47B94CE652B7B3F22A91C37617D451A4DB9AFA431450",
               "familyName": "6654977D57DDDD3C0329CA741B109EF6CD6430BEDD00008AAD213DF25683D77F",
               "regionCode": "PT",
               "postalCode": "1229-076"
             }
           }
         ]
       },
       "userProperties": {
         "customerType": "RETURNING"
       },
       "eventName": "purchase",
       "clientId": "9876543210.1761582117",
       "userId": "user_DEF9876",
       "additionalEventParameters": [
         {
           "parameterName": "ad_unit_name",
           "value": "Banner_02"
         }
       ],
       "cartData": {
         "transactionDiscount": 6.66,
         "items": [
           {
             "itemId": "SKU_12346",
             "quantity": 2,
             "unitPrice": 21.01,
             "additionalItemParameters": [
               {
                 "parameterName": "item_name",
                 "value": "Google Grey Women's Tee"
               },
               {
                 "parameterName": "affiliation",
                 "value": "Google Merchandise Store"
               },
               {
                 "parameterName": "coupon",
                 "value": "SUMMER_FUN"
               },
               {
                 "parameterName": "discount",
                 "value": "3.33"
               },
               {
                 "parameterName": "index",
                 "value": "1"
               },
               {
                 "parameterName": "item_brand",
                 "value": "Google"
               },
               {
                 "parameterName": "item_category",
                 "value": "Apparel"
               },
               {
                 "parameterName": "item_category2",
                 "value": "Adult"
               },
               {
                 "parameterName": "item_category3",
                 "value": "Shirts"
               },
               {
                 "parameterName": "item_category4",
                 "value": "Crew"
               },
               {
                 "parameterName": "item_category5",
                 "value": "Short sleeve"
               },
               {
                 "parameterName": "item_list_id",
                 "value": "related_products"
               },
               {
                 "parameterName": "item_list_name",
                 "value": "Related Products"
               }
             ]
           }
         ]
       }
     }
  ],
  "validateOnly": true
}

1. Update the placeholders in the body, such as OPERATING_ACCOUNT_ID and PRODUCT_DESTINATION_ID with the values for your account and destination.
2. Set validateOnly to true to validate the request without applying the changes. When you're ready to apply the changes, set validateOnly to false.
3. Note this example doesn't use encryption.

Send the request

1. Copy the request body using the copy button at the top right of the sample.
2. Click the API button in the toolbar.
3. Paste the copied request body into the Request body box.
4. Click the Execute button, complete the authorization prompts, and review the response.

Success responses

A successful request returns a response with an object containing a requestId.

{
  "requestId": "126365e1-16d0-4c81-9de9-f362711e250a"
}

Record the requestId returned so you can retrieve diagnostics as each destination in the request is processed.

Failure responses

A failed request results in an error response status code such as 400 Bad Request, and a response with error details.

For example, an emailAddress containing a plain text string instead of a hex encoded value produces the following response:

{
  "error": {
    "code": 400,
    "message": "There was a problem with the request.",
    "status": "INVALID_ARGUMENT",
    "details": [
      {
        "@type": "type.googleapis.com/google.rpc.ErrorInfo",
        "reason": "INVALID_ARGUMENT",
        "domain": "datamanager.googleapis.com"
      },
      {
        "@type": "type.googleapis.com/google.rpc.BadRequest",
        "fieldViolations": [
          {
            "field": "events.events[0].user_data.user_identifiers",
            "description": "Email is not hex encoded.",
            "reason": "INVALID_HEX_ENCODING"
          }
        ]
      }
    ]
  }
}

An emailAddress that isn't hashed and is only hex encoded produces the following response:

{
  "error": {
    "code": 400,
    "message": "There was a problem with the request.",
    "status": "INVALID_ARGUMENT",
    "details": [
      {
        "@type": "type.googleapis.com/google.rpc.ErrorInfo",
        "reason": "INVALID_ARGUMENT",
        "domain": "datamanager.googleapis.com"
      },
      {
        "@type": "type.googleapis.com/google.rpc.BadRequest",
        "fieldViolations": [
          {
            "field": "events.events[0]",
            "reason": "INVALID_SHA256_FORMAT"
          }
        ]
      }
    ]
  }
}

Send events for multiple destinations

If your data contains events for different destinations, you can send them in the same request by using destination references.

For example, if you have an event for conversion action ID 123456789 and another event for conversion action ID 777111122, send both events in a single request by setting the reference of each Destination. The reference is user-defined. The only requirement is that each Destination has a unique reference. Here's the modified destinations list for the request:

  "destinations": [
    {
      "operatingAccount": {
        "accountType": "OPERATING_ACCOUNT_TYPE",
        "accountId": "OPERATING_ACCOUNT_ID"
      },

      "loginAccount": {
        "accountType": "LOGIN_ACCOUNT_TYPE",
        "accountId": "LOGIN_ACCOUNT_ID"
      },

      "productDestinationId": "PRODUCT_DESTINATION_ID",
      "reference": "destination_a"
    },
    {
      "operatingAccount": {
        "accountType": "OPERATING_ACCOUNT_2_TYPE",
        "accountId": "OPERATING_ACCOUNT_2_ID"
      },

      "loginAccount": {
        "accountType": "LOGIN_ACCOUNT_2_TYPE",
        "accountId": "LOGIN_ACCOUNT_2_ID"
      },

      "productDestinationId": "777111122",
      "reference": "destination_b"
    }
  ]

Set the destinationReferences of each Event to send it to one or more specific destinations. For example, here's an Event that's only for the first Destination, so its destinationReferences list only contains the reference of the first Destination:

{
   "adIdentifiers": {
      "gclid": "GCLID_1"
   },
   "conversionValue": 1.99,
   "currency": "USD",
   "eventTimestamp": "2025-06-10T20:07:01Z",
   "transactionId": "ABC798654321",
   "eventSource": "WEB",
   "destinationReferences": [
      "destination_a"
   ]
}

The destinationReferences field is a list, so you can specify multiple destinations for an event. If you don't set the destinationReferences of an Event, the Data Manager API sends the event to all of the destinations in the request.

If an event has multiple destinations, the Data Manager API sends relevant fields to each destination. For example, if an event has a Google Ads destination and a Google Analytics destination, the API includes Google Analytics fields such as clientId or eventName when sending the event to the Google Analytics destination, and includes Google Ads fields such as customVariables when sending the event to the Google Ads destination.

Next steps

• Configure authentication and setup your environment with a client library.
• Learn about the formatting, hashing, and encoding requirements for each type of data.
• Learn how to encrypt user data.
• Learn how to retrieve diagnostics for your requests.
• Learn about best practices.
• Learn about limits and quotas.