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,
  "conversionCount": 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.
conversionCount

number

Optional. The conversion quantity associated with the event, for counting-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,
  "dclid": string,
  "impressionId": string,
  "matchId": string,
  "encryptedUserIds": [
    {
      object (EncryptedUserId)
    }
  ]
}
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.
dclid

string

Optional. The display click ID associated with this event.
impressionId

string

Optional. The impression ID associated with this event.
matchId

string

Optional. The match ID field used to join this event with a previous event.
encryptedUserIds[]

object (EncryptedUserId)

Optional. Any number of encrypted user IDs.

EncryptedUserId

A user identifier issued to be used for attribution. All fields are required if this is used.

JSON representation 
{
  "encryptedId": string,
  "entityType": enum (EncryptionEntityType),
  "entityId": string,
  "source": enum (EncryptionSource)
}
Fields
encryptedId

string

Required. The alphanumeric encrypted id.
entityType

enum (EncryptionEntityType)

Required. The encryption entity type. This should match the encryption configuration for ad serving or Data Transfer.
entityId

string (int64 format)

Required. The encryption entity ID. This should match the encryption configuration for ad serving or Data Transfer.
source

enum (EncryptionSource)

Required. Describes whether the encrypted cookie was received from ad serving (the %m macro) or from Data Transfer.

EncryptionEntityType

The encryption entity type.

Enums
ENCRYPTION_ENTITY_TYPE_UNSPECIFIED Unspecified encryption entity type.
CAMPAIGN_MANAGER_ACCOUNT Campaign Manager 360 account.
CAMPAIGN_MANAGER_ADVERTISER Campaign Manager 360 advertiser.
DISPLAY_VIDEO_PARTNER Display & Video 360 partner.
DISPLAY_VIDEO_ADVERTISER Display & Video 360 advertiser.
GOOGLE_ADS_CUSTOMER Google Ads customer.
GOOGLE_AD_MANAGER_NETWORK_CODE Google Ad Manager network code.

EncryptionSource

The encryption source.

Enums
ENCRYPTION_SOURCE_UNSPECIFIED Unspecified encryption source.
AD_SERVING Ad serving encryption source.
DATA_TRANSFER Data transfer encryption source.

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.