Caution: You are viewing documentation for the API's REST interface. Most of our official client libraries use gRPC. See the REST Introduction for details.

UserList

Stay organized with collections Save and categorize content based on your preferences.

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)
  }
  // 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/{user_list_id}

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. A flag 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 (e.g. 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.

It'll be ignored for logicalUserList.

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.

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.

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.