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:

• Online events: Send event data 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 on an allowlist. Fill out the form if you're interested in adding your account.

• Offline events: Send event data for 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 a destination

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

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

      "productDestinationId": "CONVERSION_ACTION_1_ID"
    }

• Set the accountId of the operatingAccount to the Google Ads account ID that will receive the event data. The accountType of the operatingAccount must be GOOGLE_ADS.

• Set the productDestinationId to the ID of the conversion action for the events. For online events, the conversion action must be a Google Ads conversion action with type set to WEBPAGE. For offline events, the conversion action must be a Google Ads conversion action with type set to UPLOAD_CLICKS.

  This guide shows how to construct a request that sends every event to the same conversion action. If you want to send events for multiple conversion actions in the same request, see 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.

Here's the first event's data:

Here's the second event's data:

Format the data

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

Here's the second event's 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 first event's data after formatting, hashing, and encoding using hex encoding:

Here's the second event's data after formatting, hashing, and encoding using hex encoding:

Convert the data to an Event

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

• event_timestamp: The time the event occurred.
• event_source: The source of the event. Required for offline events. Optional for online events. If specified for an online event, must be WEB.
• ad_identifiers or user_data: The event must have either an ad identifier or user data. Send both if you have both for the event.

If you are sending offline conversions as an additional data source to boost performance and data strength, then transaction_id is required. Otherwise, transaction_id is optional but recommended.

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

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

{
   "adIdentifiers": {
      "gclid": "GCLID_2"
   },
   "conversionValue": 3.25,
   "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"
      }
   }
}

Build the request body

Combine the Destination and Events for the request body:

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

      "productDestinationId": "CONVERSION_ACTION_1_ID"
    }
  ],
  "encoding": "HEX",
  "events": [
     {
       "adIdentifiers": {
         "gclid": "GCLID_1"
       },
       "conversionValue": 1.99,
       "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"
       }
     },
     {
       "adIdentifiers": {
         "gclid": "GCLID_2"
       },
       "conversionValue": 3.25,
       "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"
       }
     }
  ],
  "validateOnly": true
}

1. Update the placeholders in the body, such as OPERATING_ACCOUNT_ID and CONVERSION_ACTION_1_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 email_address 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 email_address 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": "GOOGLE_ADS",
        "accountId": "OPERATING_ACCOUNT_ID"
      },

      "productDestinationId": "123456789",
      "reference": "conversion_action_1"
    },
    {
      "operatingAccount": {
        "accountType": "GOOGLE_ADS",
        "accountId": "OPERATING_ACCOUNT_ID"
      },

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

Set the destination_references 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 destination_references 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": [
      "conversion_action_1"
   ]
}

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

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.