UserList

A user list. This is a list of users a customer may target.

JSON representation 
{
  "resourceName": string,
  "membershipStatus": enum (UserListMembershipStatus),
  "sizeRangeForDisplay": enum (UserListSizeRange),
  "sizeRangeForSearch": enum (UserListSizeRange),
  "type": enum (UserListType),
  "closingReason": enum (UserListClosingReason),
  "accessReason": enum (AccessReason),
  "accountUserListStatus": enum (UserListAccessStatus),
  "id": string,
  "readOnly": boolean,
  "name": string,
  "description": string,
  "integrationCode": string,
  "membershipLifeSpan": string,
  "sizeForDisplay": string,
  "sizeForSearch": string,
  "eligibleForSearch": boolean,
  "eligibleForDisplay": boolean,
  "matchRatePercentage": integer,

  // Union field user_list can be only one of the following:
  "crmBasedUserList": {
    object (CrmBasedUserListInfo)
  },
  "similarUserList": {
    object (SimilarUserListInfo)
  },
  "ruleBasedUserList": {
    object (RuleBasedUserListInfo)
  },
  "logicalUserList": {
    object (LogicalUserListInfo)
  },
  "basicUserList": {
    object (BasicUserListInfo)
  },
  "lookalikeUserList": {
    object (LookalikeUserListInfo)
  }
  // End of list of possible types for union field user_list.
}
Fields
resourceName

string

Immutable. The resource name of the user list. User list resource names have the form:

customers/{customerId}/userLists/{userListId}
membershipStatus

enum (UserListMembershipStatus)

Membership status of this user list. Indicates whether a user list is open or active. Only open user lists can accumulate more users and can be targeted to.
sizeRangeForDisplay

enum (UserListSizeRange)

Output only. Size range in terms of number of users of the UserList, on the Google Display Network.

This field is read-only.
type

enum (UserListType)

Output only. Type of this list.

This field is read-only.
closingReason

enum (UserListClosingReason)

Indicating the reason why this user list membership status is closed. It is only populated on lists that were automatically closed due to inactivity, and will be cleared once the list membership status becomes open.
accessReason

enum (AccessReason)

Output only. Indicates the reason this account has been granted access to the list. The reason can be SHARED, OWNED, LICENSED or SUBSCRIBED.

This field is read-only.
accountUserListStatus

enum (UserListAccessStatus)

Indicates if this share is still enabled. When a UserList is shared with the user this field is set to ENABLED. Later the userList owner can decide to revoke the share and make it DISABLED. The default value of this field is set to ENABLED.
id

string (int64 format)

Output only. Id of the user list.
readOnly

boolean

Output only. An option that indicates if a user may edit a list. Depends on the list ownership and list type. For example, external remarketing user lists are not editable.

This field is read-only.
name

string

Name of this user list. Depending on its accessReason, the user list name may not be unique (for example, if accessReason=SHARED)
description

string

Description of this user list.
integrationCode

string

An ID from external system. It is used by user list sellers to correlate IDs on their systems.
membershipLifeSpan

string (int64 format)

Number of days a user's cookie stays on your list since its most recent addition to the list. This field must be between 0 and 540 inclusive. However, for CRM based userlists, this field can be set to 10000 which means no expiration.

This field is ignored for logicalUserList and ruleBasedUserList types. Membership to lists of these types depends on the rules defined by the lists.
sizeForDisplay

string (int64 format)

Output only. Estimated number of users in this user list, on the Google Display Network. This value is null if the number of users has not yet been determined.

This field is read-only.
eligibleForDisplay

boolean

Output only. Indicates this user list is eligible for Google Display Network.

This field is read-only.
matchRatePercentage

integer

Output only. Indicates match rate for Customer Match lists. The range of this field is [0-100]. This will be null for other list types or when it's not possible to calculate the match rate.

This field is read-only.

Union field user_list. The user list.

Exactly one must be set. user_list can be only one of the following:
crmBasedUserList

object (CrmBasedUserListInfo)

User list of CRM users provided by the advertiser.
similarUserList

object (SimilarUserListInfo)

Output only. User list which are similar to users from another UserList. These lists are readonly and automatically created by google.
ruleBasedUserList

object (RuleBasedUserListInfo)

User list generated by a rule.
logicalUserList

object (LogicalUserListInfo)

User list that is a custom combination of user lists and user interests.
basicUserList

object (BasicUserListInfo)

User list targeting as a collection of conversion or remarketing actions.
lookalikeUserList

object (LookalikeUserListInfo)

Immutable. Lookalike User List.

UserListMembershipStatus

Enum containing possible user list membership statuses.

Enums
UNSPECIFIED Not specified.
UNKNOWN Used for return value only. Represents value unknown in this version.
OPEN Open status - List is accruing members and can be targeted to.
CLOSED Closed status - No new members being added. Cannot be used for targeting.

UserListSizeRange

Enum containing possible user list size ranges.

Enums
UNSPECIFIED Not specified.
UNKNOWN Used for return value only. Represents value unknown in this version.
LESS_THAN_FIVE_HUNDRED User list has less than 500 users.
LESS_THAN_ONE_THOUSAND User list has number of users in range of 500 to 1000.
ONE_THOUSAND_TO_TEN_THOUSAND User list has number of users in range of 1000 to 10000.
TEN_THOUSAND_TO_FIFTY_THOUSAND User list has number of users in range of 10000 to 50000.
FIFTY_THOUSAND_TO_ONE_HUNDRED_THOUSAND User list has number of users in range of 50000 to 100000.
ONE_HUNDRED_THOUSAND_TO_THREE_HUNDRED_THOUSAND User list has number of users in range of 100000 to 300000.
THREE_HUNDRED_THOUSAND_TO_FIVE_HUNDRED_THOUSAND User list has number of users in range of 300000 to 500000.
FIVE_HUNDRED_THOUSAND_TO_ONE_MILLION User list has number of users in range of 500000 to 1 million.
ONE_MILLION_TO_TWO_MILLION User list has number of users in range of 1 to 2 millions.
TWO_MILLION_TO_THREE_MILLION User list has number of users in range of 2 to 3 millions.
THREE_MILLION_TO_FIVE_MILLION User list has number of users in range of 3 to 5 millions.
FIVE_MILLION_TO_TEN_MILLION User list has number of users in range of 5 to 10 millions.
TEN_MILLION_TO_TWENTY_MILLION User list has number of users in range of 10 to 20 millions.
TWENTY_MILLION_TO_THIRTY_MILLION User list has number of users in range of 20 to 30 millions.
THIRTY_MILLION_TO_FIFTY_MILLION User list has number of users in range of 30 to 50 millions.
OVER_FIFTY_MILLION User list has over 50 million users.

UserListType

Enum containing possible user list types.

Enums
UNSPECIFIED Not specified.
UNKNOWN Used for return value only. Represents value unknown in this version.
REMARKETING UserList represented as a collection of conversion types.
LOGICAL UserList represented as a combination of other user lists/interests.
EXTERNAL_REMARKETING UserList created in the Google Ad Manager platform.
RULE_BASED UserList associated with a rule.
SIMILAR UserList with users similar to users of another UserList.
CRM_BASED UserList of first-party CRM data provided by advertiser in the form of emails or other formats.
LOOKALIKE LookalikeUserlist, composed of users similar to those of a configurable seed (set of UserLists)

UserListClosingReason

Enum describing possible user list closing reasons.

Enums
UNSPECIFIED Not specified.
UNKNOWN Used for return value only. Represents value unknown in this version.
UNUSED The userlist was closed because of not being used for over one year.

AccessReason

Enum describing possible access reasons.

Enums
UNSPECIFIED Not specified.
UNKNOWN Used for return value only. Represents value unknown in this version.
OWNED The resource is owned by the user.
SHARED The resource is shared to the user.
LICENSED The resource is licensed to the user.
SUBSCRIBED The user subscribed to the resource.
AFFILIATED The resource is accessible to the user.

UserListAccessStatus

Enum containing possible user list access statuses.

Enums
UNSPECIFIED Not specified.
UNKNOWN Used for return value only. Represents value unknown in this version.
ENABLED The access is enabled.
DISABLED The access is disabled.

CrmBasedUserListInfo

UserList of CRM users provided by the advertiser.

JSON representation 
{
  "uploadKeyType": enum (CustomerMatchUploadKeyType),
  "dataSourceType": enum (UserListCrmDataSourceType),
  "appId": string
}
Fields
uploadKeyType

enum (CustomerMatchUploadKeyType)

Matching key type of the list. Mixed data types are not allowed on the same list. This field is required for an ADD operation.
dataSourceType

enum (UserListCrmDataSourceType)

Data source of the list. Default value is FIRST_PARTY. Only customers on the allow-list can create third-party sourced CRM lists.
appId

string

A string that uniquely identifies a mobile application from which the data was collected. For iOS, the ID string is the 9 digit string that appears at the end of an App Store URL (for example, "476943146" for "Flood-It! 2" whose App Store link is http://itunes.apple.com/us/app/flood-it!-2/id476943146). For Android, the ID string is the application's package name (for example, "com.labpixies.colordrips" for "Color Drips" given Google Play link https://play.google.com/store/apps/details?id=com.labpixies.colordrips). Required when creating CrmBasedUserList for uploading mobile advertising IDs.

CustomerMatchUploadKeyType

Enum describing possible customer match upload key types.

Enums
UNSPECIFIED Not specified.
UNKNOWN Used for return value only. Represents value unknown in this version.
CONTACT_INFO Members are matched from customer info such as email address, phone number or physical address.
CRM_ID Members are matched from a user id generated and assigned by the advertiser.
MOBILE_ADVERTISING_ID Members are matched from mobile advertising ids.

UserListCrmDataSourceType

Enum describing possible user list crm data source type.

Enums
UNSPECIFIED Not specified.
UNKNOWN Used for return value only. Represents value unknown in this version.
FIRST_PARTY The uploaded data is first-party data.
THIRD_PARTY_CREDIT_BUREAU The uploaded data is from a third-party credit bureau.
THIRD_PARTY_VOTER_FILE The uploaded data is from a third-party voter file.

SimilarUserListInfo

SimilarUserList is a list of users which are similar to users from another UserList. These lists are read-only and automatically created by Google.

JSON representation 
{
  "seedUserList": string
}
Fields
seedUserList

string

Seed UserList from which this list is derived.

RuleBasedUserListInfo

Representation of a userlist that is generated by a rule.

JSON representation 
{
  "prepopulationStatus": enum (UserListPrepopulationStatus),
  "flexibleRuleUserList": {
    object (FlexibleRuleUserListInfo)
  }
}
Fields
prepopulationStatus

enum (UserListPrepopulationStatus)

The status of pre-population. The field is default to NONE if not set which means the previous users will not be considered. If set to REQUESTED, past site visitors or app users who match the list definition will be included in the list (works on the Display Network only). This will only add past users from within the last 30 days, depending on the list's membership duration and the date when the remarketing tag is added. The status will be updated to FINISHED once request is processed, or FAILED if the request fails.
flexibleRuleUserList

object (FlexibleRuleUserListInfo)

Flexible rule representation of visitors with one or multiple actions. The flexible user list is defined by two lists of operands – inclusiveOperands and exclusiveOperands; each operand represents a set of users based on actions they took in a given timeframe. These lists of operands are combined with the AND_NOT operator, so that users represented by the inclusive operands are included in the user list, minus the users represented by the exclusive operands.

UserListPrepopulationStatus

Enum describing possible user list prepopulation status.

Enums
UNSPECIFIED Not specified.
UNKNOWN Used for return value only. Represents value unknown in this version.
REQUESTED Prepopoulation is being requested.
FINISHED Prepopulation is finished.
FAILED Prepopulation failed.

FlexibleRuleUserListInfo

Flexible rule representation of visitors with one or multiple actions. The flexible user list is defined by two lists of operands – inclusiveOperands and exclusiveOperands; each operand represents a set of users based on actions they took in a given timeframe. These lists of operands are combined with the AND_NOT operator, so that users represented by the inclusive operands are included in the user list, minus the users represented by the exclusive operands.

JSON representation 
{
  "inclusiveRuleOperator": enum (UserListFlexibleRuleOperator),
  "inclusiveOperands": [
    {
      object (FlexibleRuleOperandInfo)
    }
  ],
  "exclusiveOperands": [
    {
      object (FlexibleRuleOperandInfo)
    }
  ]
}
Fields
inclusiveRuleOperator

enum (UserListFlexibleRuleOperator)

Operator that defines how the inclusive operands are combined.
inclusiveOperands[]

object (FlexibleRuleOperandInfo)

Rules representing users that should be included in the user list. These are located on the left side of the AND_NOT operator, and joined together by either AND/OR as specified by the inclusiveRuleOperator.
exclusiveOperands[]

object (FlexibleRuleOperandInfo)

Rules representing users that should be excluded from the user list. These are located on the right side of the AND_NOT operator, and joined together by OR.

UserListFlexibleRuleOperator

Enum describing possible user list combined rule operators.

Enums
UNSPECIFIED Not specified.
UNKNOWN Used for return value only. Represents value unknown in this version.
AND A AND B.
OR A OR B.

FlexibleRuleOperandInfo

Flexible rule that wraps the common rule and a lookback window.

JSON representation 
{
  "rule": {
    object (UserListRuleInfo)
  },
  "lookbackWindowDays": string
}
Fields
rule

object (UserListRuleInfo)

List of rule item groups that defines this rule. Rule item groups are grouped together.
lookbackWindowDays

string (int64 format)

Lookback window for this rule in days. From now until X days ago.

UserListRuleInfo

A client defined rule based on custom parameters sent by web sites or uploaded by the advertiser.

JSON representation 
{
  "ruleType": enum (UserListRuleType),
  "ruleItemGroups": [
    {
      object (UserListRuleItemGroupInfo)
    }
  ]
}
Fields
ruleType

enum (UserListRuleType)

Rule type is used to determine how to group rule items.

The default is OR of ANDs (disjunctive normal form). That is, rule items will be ANDed together within rule item groups and the groups themselves will be ORed together.

OR of ANDs is the only supported type for FlexibleRuleUserList.
ruleItemGroups[]

object (UserListRuleItemGroupInfo)

List of rule item groups that defines this rule. Rule item groups are grouped together based on ruleType.

UserListRuleType

Enum describing possible user list rule types.

Enums
UNSPECIFIED Not specified.
UNKNOWN Used for return value only. Represents value unknown in this version.
AND_OF_ORS Conjunctive normal form.
OR_OF_ANDS Disjunctive normal form.

UserListRuleItemGroupInfo

A group of rule items.

JSON representation 
{
  "ruleItems": [
    {
      object (UserListRuleItemInfo)
    }
  ]
}
Fields
ruleItems[]

object (UserListRuleItemInfo)

Rule items that will be grouped together based on ruleType.

UserListRuleItemInfo

An atomic rule item.

JSON representation 
{
  "name": string,

  // Union field rule_item can be only one of the following:
  "numberRuleItem": {
    object (UserListNumberRuleItemInfo)
  },
  "stringRuleItem": {
    object (UserListStringRuleItemInfo)
  },
  "dateRuleItem": {
    object (UserListDateRuleItemInfo)
  }
  // End of list of possible types for union field rule_item.
}
Fields
name

string

Rule variable name. It should match the corresponding key name fired by the pixel. A name must begin with US-ascii letters or underscore or UTF8 code that is greater than 127 and consist of US-ascii letters or digits or underscore or UTF8 code that is greater than 127. For websites, there are two built-in variable URL (name = 'url__') and referrer URL (name = 'ref_url__'). This field must be populated when creating a new rule item.
Union field rule_item. An atomic rule item. rule_item can be only one of the following:
numberRuleItem

object (UserListNumberRuleItemInfo)

An atomic rule item composed of a number operation.
stringRuleItem

object (UserListStringRuleItemInfo)

An atomic rule item composed of a string operation.
dateRuleItem

object (UserListDateRuleItemInfo)

An atomic rule item composed of a date operation.

UserListNumberRuleItemInfo

A rule item composed of a number operation.

JSON representation 
{
  "operator": enum (UserListNumberRuleItemOperator),
  "value": number
}
Fields
operator

enum (UserListNumberRuleItemOperator)

Number comparison operator. This field is required and must be populated when creating a new number rule item.
value

number

Number value to be compared with the variable. This field is required and must be populated when creating a new number rule item.

UserListNumberRuleItemOperator

Enum describing possible user list number rule item operators.

Enums
UNSPECIFIED Not specified.
UNKNOWN Used for return value only. Represents value unknown in this version.
GREATER_THAN Greater than.
GREATER_THAN_OR_EQUAL Greater than or equal.
EQUALS Equals.
NOT_EQUALS Not equals.
LESS_THAN Less than.
LESS_THAN_OR_EQUAL Less than or equal.

UserListStringRuleItemInfo

A rule item composed of a string operation.

JSON representation 
{
  "operator": enum (UserListStringRuleItemOperator),
  "value": string
}
Fields
operator

enum (UserListStringRuleItemOperator)

String comparison operator. This field is required and must be populated when creating a new string rule item.
value

string

The right hand side of the string rule item. For URLs or referrer URLs, the value can not contain illegal URL chars such as newlines, quotes, tabs, or parentheses. This field is required and must be populated when creating a new string rule item.

UserListStringRuleItemOperator

Enum describing possible user list string rule item operators.

Enums
UNSPECIFIED Not specified.
UNKNOWN Used for return value only. Represents value unknown in this version.
CONTAINS Contains.
EQUALS Equals.
STARTS_WITH Starts with.
ENDS_WITH Ends with.
NOT_EQUALS Not equals.
NOT_CONTAINS Not contains.
NOT_STARTS_WITH Not starts with.
NOT_ENDS_WITH Not ends with.

UserListDateRuleItemInfo

A rule item composed of a date operation.

JSON representation 
{
  "operator": enum (UserListDateRuleItemOperator),
  "value": string,
  "offsetInDays": string
}
Fields
operator

enum (UserListDateRuleItemOperator)

Date comparison operator. This field is required and must be populated when creating new date rule item.
value

string

String representing date value to be compared with the rule variable. Supported date format is YYYY-MM-DD. Times are reported in the customer's time zone.
offsetInDays

string (int64 format)

The relative date value of the right hand side denoted by number of days offset from now. The value field will override this field when both are present.

UserListDateRuleItemOperator

Enum describing possible user list date rule item operators.

Enums
UNSPECIFIED Not specified.
UNKNOWN Used for return value only. Represents value unknown in this version.
EQUALS Equals.
NOT_EQUALS Not Equals.
BEFORE Before.
AFTER After.

LogicalUserListInfo

Represents a user list that is a custom combination of user lists.

JSON representation 
{
  "rules": [
    {
      object (UserListLogicalRuleInfo)
    }
  ]
}
Fields
rules[]

object (UserListLogicalRuleInfo)

Logical list rules that define this user list. The rules are defined as a logical operator (ALL/ANY/NONE) and a list of user lists. All the rules are ANDed when they are evaluated.

Required for creating a logical user list.

UserListLogicalRuleInfo

A user list logical rule. A rule has a logical operator (and/or/not) and a list of user lists as operands.

JSON representation 
{
  "operator": enum (UserListLogicalRuleOperator),
  "ruleOperands": [
    {
      object (LogicalUserListOperandInfo)
    }
  ]
}
Fields
operator

enum (UserListLogicalRuleOperator)

The logical operator of the rule.
ruleOperands[]

object (LogicalUserListOperandInfo)

The list of operands of the rule.

UserListLogicalRuleOperator

Enum describing possible user list logical rule operators.

Enums
UNSPECIFIED Not specified.
UNKNOWN Used for return value only. Represents value unknown in this version.
ALL And - all of the operands.
ANY Or - at least one of the operands.
NONE Not - none of the operands.

LogicalUserListOperandInfo

Operand of logical user list that consists of a user list.

JSON representation 
{
  "userList": string
}
Fields
userList

string

Resource name of a user list as an operand.

BasicUserListInfo

User list targeting as a collection of conversions or remarketing actions.

JSON representation 
{
  "actions": [
    {
      object (UserListActionInfo)
    }
  ]
}
Fields
actions[]

object (UserListActionInfo)

Actions associated with this user list.

UserListActionInfo

Represents an action type used for building remarketing user lists.

JSON representation 
{

  // Union field user_list_action can be only one of the following:
  "conversionAction": string,
  "remarketingAction": string
  // End of list of possible types for union field user_list_action.
}
Fields
Union field user_list_action. Subtypes of user list action. user_list_action can be only one of the following:
conversionAction

string

A conversion action that's not generated from remarketing.
remarketingAction

string

A remarketing action.

LookalikeUserListInfo

LookalikeUserlist, composed of users similar to those of a configurable seed (set of UserLists)

JSON representation 
{
  "seedUserListIds": [
    string
  ],
  "expansionLevel": enum (LookalikeExpansionLevel),
  "countryCodes": [
    string
  ]
}
Fields
seedUserListIds[]

string (int64 format)

Seed UserList ID from which this list is derived, provided by user.
expansionLevel

enum (LookalikeExpansionLevel)

Expansion level, reflecting the size of the lookalike audience
countryCodes[]

string

Countries targeted by the Lookalike. Two-letter country code as defined by ISO-3166

LookalikeExpansionLevel

Expansion level, reflecting the size of the lookalike audience

Enums
UNSPECIFIED Not specified.
UNKNOWN Invalid expansion level.
NARROW Expansion to a small set of users that are similar to the seed lists
BALANCED Expansion to a medium set of users that are similar to the seed lists. Includes all users of EXPANSION_LEVEL_NARROW, and more.
BROAD Expansion to a large set of users that are similar to the seed lists. Includes all users of EXPANSION_LEVEL_BALANCED, and more.