Method: events.ingest

  • The content provides a reference for the IngestEvents method, which uploads a list of Event resources.

  • The HTTP request method is POST to https://datamanager.googleapis.com/v1/events:ingest.

  • The request body requires specifying the list of destinations and events.

  • The response body returns a requestId string if successful.

  • The API requires the https://www.googleapis.com/auth/datamanager authorization scope.

Uploads a list of Event resources from the provided Destination.

HTTP request

POST https://datamanager.googleapis.com/v1/events:ingest

The URL uses gRPC Transcoding syntax.

Request body

The request body contains data with the following structure:

JSON representation 
{
  "destinations": [
    {
      object (Destination)
    }
  ],
  "events": [
    {
      object (Event)
    }
  ],
  "consent": {
    object (Consent)
  },
  "validateOnly": boolean,
  "encoding": enum (Encoding),
  "encryptionInfo": {
    object (EncryptionInfo)
  }
}
Fields
destinations[]

object (Destination)

Required. The list of destinations to send the events to.
events[]

object (Event)

Required. The list of events to send to the specified destinations. At most 2000 Event resources can be sent in a single request.
consent

object (Consent)

Optional. Request-level consent to apply to all users in the request. User-level consent overrides request-level consent, and can be specified in each Event.
validateOnly

boolean

Optional. For testing purposes. If true, the request is validated but not executed. Only errors are returned, not results.
encoding

enum (Encoding)

Optional. Required for UserData uploads. The encoding type of the user identifiers. For hashed user identifiers, this is the encoding type of the hashed string. For encrypted hashed user identifiers, this is the encoding type of the outer encrypted string, but not necessarily the inner hashed string, meaning the inner hashed string could be encoded in a different way than the outer encrypted string. For non UserData uploads, this field is ignored.
encryptionInfo

object (EncryptionInfo)

Optional. Encryption information for UserData uploads. If not set, it's assumed that uploaded identifying information is hashed but not encrypted. For non UserData uploads, this field is ignored.

Response body

Response from the IngestEventsRequest.

If successful, the response body contains data with the following structure:

JSON representation 
{
  "requestId": string
}
Fields
requestId

string

The auto-generated ID of the request.

Authorization scopes

Requires the following OAuth scope:

  • https://www.googleapis.com/auth/datamanager

Event

An event representing a user interaction with an advertiser's website or app.

JSON representation 
{
  "destinationReferences": [
    string
  ],
  "transactionId": string,
  "eventTimestamp": string,
  "lastUpdatedTimestamp": string,
  "userData": {
    object (UserData)
  },
  "consent": {
    object (Consent)
  },
  "adIdentifiers": {
    object (AdIdentifiers)
  },
  "currency": string,
  "eventSource": enum (EventSource),
  "eventDeviceInfo": {
    object (DeviceInfo)
  },
  "cartData": {
    object (CartData)
  },
  "customVariables": [
    {
      object (CustomVariable)
    }
  ],
  "experimentalFields": [
    {
      object (ExperimentalField)
    }
  ],
  "userProperties": {
    object (UserProperties)
  },
  "eventName": string,
  "clientId": string,
  "userId": string,
  "additionalEventParameters": [
    {
      object (EventParameter)
    }
  ],
  "thirdPartyUserData": {
    object (UserData)
  },
  "eventLocation": {
    object (EventLocation)
  },
  "appInstanceId": string,
  "conversionValue": number
}
Fields
destinationReferences[]

string

Optional. Reference string used to determine the destination. If empty, the event will be sent to all destinations in the request.
transactionId

string

Optional. The unique identifier for this event. Required for events sent as an additional data source for tag conversions.
eventTimestamp

string (Timestamp format)

Required. The time the event occurred.

Uses RFC 3339, where generated output will always be Z-normalized and use 0, 3, 6 or 9 fractional digits. Offsets other than "Z" are also accepted. Examples: "2014-10-02T15:01:23Z", "2014-10-02T15:01:23.045123456Z" or "2014-10-02T15:01:23+05:30".
lastUpdatedTimestamp

string (Timestamp format)

Optional. The last time the event was updated.

Uses RFC 3339, where generated output will always be Z-normalized and use 0, 3, 6 or 9 fractional digits. Offsets other than "Z" are also accepted. Examples: "2014-10-02T15:01:23Z", "2014-10-02T15:01:23.045123456Z" or "2014-10-02T15:01:23+05:30".
userData

object (UserData)

Optional. Pieces of user provided data, representing the user the event is associated with.
consent

object (Consent)

Optional. Information about whether the associated user has provided different types of consent.
adIdentifiers

object (AdIdentifiers)

Optional. Identifiers and other information used to match the conversion event with other online activity (such as ad clicks).
currency

string

Optional. The currency code associated with all monetary values within this event.
eventSource

enum (EventSource)

Optional. Signal for where the event happened (web, app, in-store, etc.).
eventDeviceInfo

object (DeviceInfo)

Optional. Information gathered about the device being used (if any) when the event happened.
cartData

object (CartData)

Optional. Information about the transaction and items associated with the event.
customVariables[]

object (CustomVariable)

Optional. Additional key/value pair information to send to the conversion containers (conversion action or FL activity).
experimentalFields[]

object (ExperimentalField)

Optional. A list of key/value pairs for experimental fields that may eventually be promoted to be part of the API.
userProperties

object (UserProperties)

Optional. Advertiser-assessed information about the user at the time that the event happened.
eventName

string

Optional. The name of the event. Required for GA4 events.
clientId

string

Optional. A unique identifier for the user instance of a web client for this GA4 web stream.
userId

string

Optional. A unique identifier for a user, as defined by the advertiser.
additionalEventParameters[]

object (EventParameter)

Optional. A bucket of any event parameters to be included within the event that were not already specified using other structured fields.
thirdPartyUserData

object (UserData)

Optional. The same type of data provided in userData, but explicitly flagged as being provided as owned by a third-party and not first-party advertiser data.
eventLocation

object (EventLocation)

Optional. Information gathered about the location of the user when this event occurred.
appInstanceId

string

Optional. A unique identifier for the user instance of an app client for this GA4 app stream.
conversionValue

number

Optional. The conversion value associated with the event, for value-based conversions.

AdIdentifiers

Identifiers and other information used to match the conversion event with other online activity (such as ad clicks).

JSON representation 
{
  "sessionAttributes": string,
  "gclid": string,
  "gbraid": string,
  "wbraid": string,
  "landingPageDeviceInfo": {
    object (DeviceInfo)
  },
  "mobileDeviceId": string
}
Fields
sessionAttributes

string

Optional. Session attributes for event attribution and modeling.
gclid

string

Optional. The Google click ID (gclid) associated with this event.
gbraid

string

Optional. The click identifier for clicks associated with app events and originating from iOS devices starting with iOS14.
wbraid

string

Optional. The click identifier for clicks associated with web events and originating from iOS devices starting with iOS14.
landingPageDeviceInfo

object (DeviceInfo)

Optional. Information gathered about the device being used (if any) at the time of landing onto the advertiser’s site after interacting with the ad.
mobileDeviceId

string

Optional. The mobile identifier for advertisers. This would be IDFA on iOS, AdID on Android, or other platforms’ identifiers for advertisers.

DeviceInfo

Information about the device being used (if any) when the event happened.

JSON representation 
{
  "userAgent": string,
  "ipAddress": string,
  "category": string,
  "languageCode": string,
  "screenHeight": integer,
  "screenWidth": integer,
  "operatingSystem": string,
  "operatingSystemVersion": string,
  "model": string,
  "brand": string,
  "browser": string,
  "browserVersion": string
}
Fields
userAgent

string

Optional. The user-agent string of the device for the given context.
ipAddress

string

Optional. The IP address of the device for the given context.

Note: Google Ads does not support IP address matching for end users in the European Economic Area (EEA), United Kingdom (UK), or Switzerland (CH). Add logic to conditionally exclude sharing IP addresses from users from these regions and ensure that you provide users with clear and comprehensive information about the data you collect on your sites, apps, and other properties and get consent where required by law or any applicable Google policies. See the About offline conversion imports page for more details.
category

string

Optional. The category of device. For example, “desktop”, “tablet”, “mobile”, “smart TV”.
languageCode

string

Optional. The language the device uses in ISO 639-1 format.
screenHeight

integer

Optional. The height of the screen in pixels.
screenWidth

integer

Optional. The width of the screen in pixels.
operatingSystem

string

Optional. The operating system or platform of the device.
operatingSystemVersion

string

Optional. The version of the operating system or platform.
model

string

Optional. The model of the device.
brand

string

Optional. The brand of the device.
browser

string

Optional. The brand or type of the browser.
browserVersion

string

Optional. The version of the browser.

EventSource

The source of the event.

Enums
EVENT_SOURCE_UNSPECIFIED Unspecified EventSource. Should never be used.
WEB The event was generated from a web browser.
APP The event was generated from an app.
IN_STORE The event was generated from an in-store transaction.
PHONE The event was generated from a phone call.
MESSAGE The event was generated from a message.
OTHER The event was generated from other sources.

CartData

The cart data associated with the event.

JSON representation 
{
  "merchantId": string,
  "merchantFeedLabel": string,
  "merchantFeedLanguageCode": string,
  "transactionDiscount": number,
  "items": [
    {
      object (Item)
    }
  ],
  "couponCodes": [
    string
  ]
}
Fields
merchantId

string

Optional. The Merchant Center ID associated with the items.
merchantFeedLabel

string

Optional. The Merchant Center feed label associated with the feed of the items.
merchantFeedLanguageCode

string

Optional. The language code in ISO 639-1 associated with the Merchant Center feed of the items.where your items are uploaded.
transactionDiscount

number

Optional. The sum of all discounts associated with the transaction.
items[]

object (Item)

Optional. The list of items associated with the event.
couponCodes[]

string

Optional. The list of coupon codes that were applied to the cart. Cart-level and item-level coupon codes are independent.

If the event is for a Google Analytics destination, only provide a single coupon code. Google Analytics ignores additional coupon codes.

Item

Represents an item in the cart associated with the event.

JSON representation 
{
  "merchantProductId": string,
  "quantity": string,
  "unitPrice": number,
  "itemId": string,
  "additionalItemParameters": [
    {
      object (ItemParameter)
    }
  ],
  "merchantId": string,
  "merchantFeedLabel": string,
  "merchantFeedLanguageCode": string,
  "customVariables": [
    {
      object (ItemCustomVariable)
    }
  ],
  "conversionValue": number
}
Fields
merchantProductId

string

Optional. The product ID within the Merchant Center account.
quantity

string (int64 format)

Optional. The number of this item associated with the event.
unitPrice

number

Optional. The unit price excluding tax, shipping, and any transaction level discounts.
itemId

string

Optional. A unique identifier to reference the item.
additionalItemParameters[]

object (ItemParameter)

Optional. A bucket of any event parameters related to an item to be included within the event that were not already specified using other structured fields.
merchantId

string

Optional. The Merchant Center ID associated with the item. For Store Sales events this will override the value set at the cart level. This field is ignored for other events.
merchantFeedLabel

string

Optional. The feed label of the Merchant Center feed. If countries are still being used, the 2-letter country code in ISO-3166-1 alpha-2 can be used instead. For Store Sales events this will override the value set at the cart level. This field is ignored for other events.
merchantFeedLanguageCode

string

Optional. The language code in ISO 639-1 associated with the Merchant Center feed where your items are uploaded.
customVariables[]

object (ItemCustomVariable)

Optional. Additional key/value pair information to send to the conversion containers (conversion action or Floodlight activity), when tracking per-item conversions.
conversionValue

number

Optional. The conversion value associated with this item within the event, for cases where the conversion value is different for each item.

ItemParameter

A bucket of any event parameters related to an item to be included within the event that were not already specified using other structured fields.

JSON representation 
{
  "parameterName": string,
  "value": string
}
Fields
parameterName

string

Required. The name of the parameter to use.
value

string

Required. The string representation of the value of the parameter to set.

ItemCustomVariable

Item-level custom variable for ads conversions.

JSON representation 
{
  "variable": string,
  "value": string,
  "destinationReferences": [
    string
  ]
}
Fields
variable

string

Optional. The name of the custom variable to set. If the variable is not found for the given destination, it will be ignored.
value

string

Optional. The value to store for the custom variable.
destinationReferences[]

string

Optional. Reference string used to determine which of the Event.destination_references the custom variable should be sent to. If empty, the Event.destination_references will be used.

CustomVariable

Custom variable for ads conversions.

JSON representation 
{
  "variable": string,
  "value": string,
  "destinationReferences": [
    string
  ]
}
Fields
variable

string

Optional. The name of the custom variable to set. If the variable is not found for the given destination, it will be ignored.
value

string

Optional. The value to store for the custom variable.
destinationReferences[]

string

Optional. Reference string used to determine which of the Event.destination_references the custom variable should be sent to. If empty, the Event.destination_references will be used.

ExperimentalField

Experimental field representing unofficial fields.

JSON representation 
{
  "field": string,
  "value": string
}
Fields
field

string

Optional. The name of the field to use.
value

string

Optional. The value the field to set.

UserProperties

Advertiser-assessed information about the user at the time that the event happened. See https://support.google.com/google-ads/answer/14007601 for more details.

JSON representation 
{
  "customerType": enum (CustomerType),
  "customerValueBucket": enum (CustomerValueBucket),
  "additionalUserProperties": [
    {
      object (UserProperty)
    }
  ]
}
Fields
customerType

enum (CustomerType)

Optional. Type of the customer associated with the event.
customerValueBucket

enum (CustomerValueBucket)

Optional. The advertiser-assessed value of the customer.
additionalUserProperties[]

object (UserProperty)

Optional. A bucket of any additional user properties for the user associated with this event.

CustomerType

Type of the customer associated with the event.

Enums
CUSTOMER_TYPE_UNSPECIFIED Unspecified CustomerType. Should never be used.
NEW The customer is new to the advertiser.
RETURNING The customer is returning to the advertiser.
REENGAGED The customer has re-engaged with the advertiser.

CustomerValueBucket

The advertiser-assessed value of the customer.

Enums
CUSTOMER_VALUE_BUCKET_UNSPECIFIED Unspecified CustomerValueBucket. Should never be used.
LOW The customer is low value.
MEDIUM The customer is medium value.
HIGH The customer is high value.

UserProperty

A bucket of any additional user properties for the user associated with this event.

JSON representation 
{
  "propertyName": string,
  "value": string
}
Fields
propertyName

string

Required. The name of the user property to use.
value

string

Required. The string representation of the value of the user property to use.

EventParameter

Event parameter for GA4 events.

JSON representation 
{
  "parameterName": string,
  "value": string
}
Fields
parameterName

string

Required. The name of the parameter to use.
value

string

Required. The string representation of the value of the parameter to set.

EventLocation

The location where the event occurred.

JSON representation 
{
  "storeId": string,
  "city": string,
  "subdivisionCode": string,
  "regionCode": string,
  "subcontinentCode": string,
  "continentCode": string
}
Fields
storeId

string

Optional. Required for Store Sales. The identifier to represent a physical store where the event happened.
city

string

Optional. The name of the city where the event occurred.
subdivisionCode

string

Optional. The ISO 3166-2 subdivision code where the event occurred.
regionCode

string

Optional. The 2-letter CLDR region code of the user's address.
subcontinentCode

string

Optional. The subcontinent code in UN M49 format where the event occurred.
continentCode

string

Optional. The continent code in UN M49 format where the event occurred.