REST Resource: customers.userLists

Resource: UserList

Defines an Ads Data Hub-managed user list.

JSON representation 
{
  "name": string,
  "userListId": string,
  "adsDataCustomerId": string,
  "title": string,
  "description": string,
  "type": enum (UserListType),
  "createEmail": string,
  "listSize": string,
  "populateTime": string,
  "recipientAdsDataLinks": [
    string
  ],
  "state": enum (State),

  // Union field user_list can be only one of the following:
  "frequencyList": {
    object (FrequencyBasedListInfo)
  },
  "remarketingList": {
    object (RemarketingListInfo)
  },
  "crmList": {
    object (CrmBasedListInfo)
  }
  // End of list of possible types for union field user_list.
}
Fields
name

string

Output only. Immutable. Name that uniquely identifies an Ads Data Hub user list. It has the form customers/[customerId]/userLists/[userListId]
userListId

string (int64 format)

Output only. Immutable. User list ID. This field is generated by the service and is used to populate the UserList.
adsDataCustomerId

string (int64 format)

Immutable. Linked Ads Data Hub customer ID associated with this user list. This ID must be specified as the adsDataCustomerId when running UserListQuery jobs using this user list. If absent, the parent customer will be used. This cannot be changed after the list is created.
title

string

Required. User list title, which is unique for the specified adsDataCustomerId.
description

string

Required. User list description.
type

enum (UserListType)

Output only. UserList type values should be consistent with the userList. This value is Read Only and will accessible on get/list requests.
createEmail

string

Output only. Immutable. Email address of the user that created this user list.
listSize

string (int64 format)

Output only. The number of users on the user list. List size update may be delayed.
populateTime

string (Timestamp format)

Output only. Time the list was last populated.

A timestamp in RFC3339 UTC "Zulu" format, with nanosecond resolution and up to nine fractional digits. Examples: "2014-10-02T15:01:23Z" and "2014-10-02T15:01:23.045123456Z".
state

enum (State)

Output only. State of the user list (Active/Deleted). This value is Read Only and will accessible on get/list requests.

Union field user_list. Further configuration depending on the type of the user list.

Exactly one must be set. user_list can be only one of the following:
frequencyList
(deprecated)

object (FrequencyBasedListInfo)

User list for frequency capping.
remarketingList

object (RemarketingListInfo)

Remarketing list.
crmList

object (CrmBasedListInfo)

Customer Matching user list.

UserListType

User List kind. User list construction and usage at targeting time depends on this enum. List can not have its type switched after creation.

Enums
USER_LIST_TYPE_UNSPECIFIED Default value: should not be used.
REMARKETING Remarketing Audiences created with SQL queries on ADH. Remarketing list can be used for positive and negative targeting.
FREQUENCY_BASED

Frequency limited audiences. Audiences of this kind are restricted to negative targeting.
CRM_BASED Customer Matching Audiences created with SQL queries on ADH. Customer Matching list can be used for positive and negative targeting.

FrequencyBasedListInfo

Metadata for frequency-based User List.

JSON representation 
{
  "dv360LineitemIds": [
    string
  ],
  "cmCampaignIds": [
    string
  ],
  "googleAdsCampaignIds": [
    string
  ],
  "eventMatchers": [
    {
      object (EventMatcher)
    }
  ],
  "frequencyConstraint": {
    object (FrequencyConstraint)
  },
  "slidingWindowDays": integer
}
Fields
dv360LineitemIds[]
(deprecated)

string (int64 format)

Ids for DV360 line items that contribute to the frequency.
cmCampaignIds[]
(deprecated)

string (int64 format)

Ids for CM campaigns that contribute to the frequency.
googleAdsCampaignIds[]
(deprecated)

string (int64 format)

Ids for Google Ads campaigns that contribute to the frequency.
eventMatchers[]

object (EventMatcher)

Which events contribute to the frequency. When creating frequency-based user lists, eventMatchers is preferred for specifying events contributing to the frequency. dv360LineitemIds, cmCampaignIds, and googleAdsCampaignIds are used if eventMatchers is empty.
frequencyConstraint

object (FrequencyConstraint)

Describes when a user gets added to the list.
slidingWindowDays

integer

Required. Time window size used when calculating the frequency of each event. This is measure in days

EventMatcher

Generic event that contributes to the frequency.

JSON representation 
{
  "matchType": enum (MatchType),
  "value": string
}
Fields
matchType

enum (MatchType)

The type of the constraint that will be included in the frequency count.
value

string

Value of the constraint. For example, for specifying a Google Ads campaign ID = 1234, matchType would be GOOGLE_ADS_CAMPAIGN_ID and value would be '1234'. Events that have this value for the respective MatchType will be included in the frequency count.

MatchType

Types of constraints supported for frequency count. More types may get added to this enum in future to support additional constraints. You can specify a filter on the MatchType in the DescribeValidFrequencyLimitingEventMatchersRequest to restrict the event matchers returned in the results to only those that are supported by your API. For example, setting the filter as "eventMatcher.match_type= CM_CAMPAIGN_ID OR eventMatcher.match_type=GOOGLE_ADS_CAMPAIGN_ID" will return EventMatchers only of those two types.

Enums
MATCH_TYPE_UNSPECIFIED Default value. This value is unused.
CM_CAMPAIGN_ID Constraint type representing Campaign Manager Campaign ID.
DV360_INSERTION_ORDER_ID Constraint type representing DV360 Insertion Order ID.
DV360_LINE_ITEM_ID Constraint type representing DV360 Line Item ID.
GOOGLE_ADS_CAMPAIGN_ID Constraint type representing Google Ads Campaign ID.

FrequencyConstraint

Specify the minimum number of events for the cap.

JSON representation 
{
  "eventType": enum (EventType),
  "thresholdEventCount": string
}
Fields
eventType

enum (EventType)

Immutable. The type of event that will be counted against thresholdEventCount. For now we do not explicitly represent the comparison constraints assuming all are GREATER_OR_EQUAL.
thresholdEventCount

string (int64 format)

Required. Each user should appear in at least K events.

EventType

Types of events that can be used to count frequency.

Enums
EVENT_TYPE_UNSPECIFIED Default value: should not be used.
IMPRESSIONS Count all impressions.

RemarketingListInfo

Metadata for remarketing lists.

JSON representation 
{
  "userListQuery": string,
  "populatingUserListQueries": [
    string
  ]
}
Fields
userListQuery

string

Immutable. The Ads Data Hub user list query resource that specifies how users are added to this audience. Has the form of: customers/[customerId]/userListQueries/[query_resource_id]
populatingUserListQueries[]

string

Output only. The Ads Data Hub user list query resources that have populated this audience. This is intended as a legacy field to support userlists that were populated by multiple queries before 1:1 userlist:query restrictions went into effect. Has the form of: customers/[customerId]/userListQueries/[query_resource_id]

CrmBasedListInfo

Metadata for CRM based lists.

JSON representation 
{
  "crmBasedUserListQuery": string
}
Fields
crmBasedUserListQuery

string

Immutable. The Ads Data Hub CRM based query resource that specifies how users are added to this audience. Has the form of: customers/[customerId]/crmBasedUserListQueries/[query_resource_id]

State

State of user list.

Enums
STATE_UNSPECIFIED The default / unset value.
STATE_ACTIVE User list is still open and active.
STATE_DELETED User list is marked as deleted and should not be used for targeting any more

Methods

addEventMatchers
(deprecated)

 Adds event matchers to a frequency-based user list.

addRecipients

 Add entities to an Ads Data Hub-managed user list’s recipients.

create

 Creates an Ads Data Hub-managed user list.

delete

 Delete the requested Ads Data Hub-managed user list.

generateFrequencyListMemberships
(deprecated)

 Generate memberships for the UserList.

get

 Retrieves the requested Ads Data Hub-managed user list.

list

 Lists the user lists managed by the specified Ads Data Hub customer.

patch

 Updates the requested Ads Data Hub-managed user list.

removeRecipients

 Removes entities from an Ads Data Hub-managed user list’s recipients.

updateCrmBasedUserListMemberships

 Update memberships for the UserList.