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,

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

string

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

userListId

string (int64 format)

Output only. 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.

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. 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, accurate to nanoseconds. Example: "2014-10-02T15:01:23.045123456Z".

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

object (FrequencyBasedListInfo)

User list for frequency limiting.

remarketingList

object (RemarketingListInfo)

Remarketing 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.

FrequencyBasedListInfo

Metadata for frequency based User List.

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

string (int64 format)

Ids for DV360 line items that contribute to the frequency.

cmCampaignIds[]

string (int64 format)

Ids for CM campaigns that contribute to the frequency.

googleAdsCampaignIds[]

string (int64 format)

Ids for Google Ads campaigns that contribute to the frequency.

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

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.

Methods

create

Creates an Ads Data Hub-managed user list.

generateFrequencyListMemberships

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.