REST Resource: buyers.userLists

  • A UserList represents an Authorized Buyers user list that can be created, updated, and listed.

  • Users can be added to a user list using the bulk uploader API or by hosting a tag on the advertiser's page.

  • The status of a user list can be OPEN (new users can be added) or CLOSED (new users cannot be added).

  • The urlRestriction field and the getRemarketingTag method have been deprecated and will be removed in October 2023.

  • The membershipDurationDays field specifies how long a user's cookie stays on the user list, with a range of 0 to 540 days.

Resource: UserList

Represents an Authorized Buyers user list. Authorized Buyers can create/update/list user lists. Once a user list is created in the system, Authorized Buyers can add users to the user list using the bulk uploader API. Alternatively, users can be added by hosting a tag on the advertiser's page.

JSON representation 
{
  "name": string,
  "displayName": string,
  "description": string,
  "status": enum (Status),
  "urlRestriction": {
    object (UrlRestriction)
  },
  "membershipDurationDays": string
}
Fields
name

string

Output only. Name of the user list that must follow the pattern buyers/{buyer}/userLists/{userList}, where {buyer} represents the account ID of the buyer who owns the user list. For a bidder accessing user lists on behalf of a child seat buyer, {buyer} represents the account ID of the child seat buyer. {userList} is an int64 identifier assigned by Google to uniquely identify a user list.
displayName

string

Required. Display name of the user list. This must be unique across all user lists for a given account.
description

string

The description for the user list.
status

enum (Status)

Output only. The status of the user list. A new user list starts out as open.
urlRestriction

object (UrlRestriction)

Required. Deprecated. This will be removed in October 2023.

For more information, see the release notes: https://developers.google.com/authorized-buyers/apis/relnotes#real-time-bidding-api The URL restriction for the user list.
membershipDurationDays

string (int64 format)

Required. The number of days a user's cookie stays on the user list. The field must be between 0 and 540 inclusive.

Status

User list status

Enums
STATUS_UNSPECIFIED Default value that should never be used.
OPEN New users can be added to the user list.
CLOSED New users cannot be added to the user list.

UrlRestriction

Deprecated. This will be removed in October 2023.

For more information, see the release notes: https://developers.google.com/authorized-buyers/apis/relnotes#real-time-bidding-api Represents the URL restriction (for the URL captured by the pixel callback) for a user list.

JSON representation 
{
  "url": string,
  "restrictionType": enum (RestrictionType),
  "startDate": {
    object (Date)
  },
  "endDate": {
    object (Date)
  }
}
Fields
url

string

Required. The URL to use for applying the restriction on the user list.
restrictionType

enum (RestrictionType)

The restriction type for the specified URL.
startDate

object (Date)

Start date (if specified) of the URL restriction.
endDate

object (Date)

End date (if specified) of the URL restriction. End date should be later than the start date for the date range to be valid.

RestrictionType

URL restriction type

Enums
RESTRICTION_TYPE_UNSPECIFIED Default value that should never be used.
CONTAINS The tag URL (as recorded by the pixel callback) contains the specified URL.
EQUALS The tag URL (as recorded by the pixel callback) exactly matches the specified URL.
STARTS_WITH The tag URL (as recorded by the pixel callback) starts with the specified URL.
ENDS_WITH The tag URL (as recorded by the pixel callback) ends with the specified URL.
DOES_NOT_EQUAL The tag URL (as recorded by the pixel callback) does not equal the specified URL.
DOES_NOT_CONTAIN The tag URL (as recorded by the pixel callback) does not contain the specified URL.
DOES_NOT_START_WITH The tag URL (as recorded by the pixel callback) does not start with the specified URL.
DOES_NOT_END_WITH The tag URL (as recorded by the pixel callback) does not end with the specified URL.

Date

Represents a whole or partial calendar date, such as a birthday. The time of day and time zone are either specified elsewhere or are insignificant. The date is relative to the Gregorian Calendar. This can represent one of the following:

  • A full date, with non-zero year, month, and day values.
  • A month and day, with a zero year (for example, an anniversary).
  • A year on its own, with a zero month and a zero day.
  • A year and month, with a zero day (for example, a credit card expiration date).

Related types:

JSON representation 
{
  "year": integer,
  "month": integer,
  "day": integer
}
Fields
year

integer

Year of the date. Must be from 1 to 9999, or 0 to specify a date without a year.
month

integer

Month of a year. Must be from 1 to 12, or 0 to specify a year without a month and day.
day

integer

Day of a month. Must be from 1 to 31 and valid for the year and month, or 0 to specify a year by itself or a year and month where the day isn't significant.

Methods

close

 Changes the status of a user list to CLOSED.

create

 Creates a new user list.

get

 Gets a user list by its name.

getRemarketingTag

 This has been sunset as of October 2023, and will return an error response if called.

list

 Lists the user lists visible to the current user.

open

 Changes the status of a user list to OPEN.

update

 Updates the given user list.