# REST Resource: buyers.userLists

- [Resource: UserList](https://developers.google.com/authorized-buyers/apis/realtimebidding/reference/rest/v1/buyers.userLists#UserList)
  - [JSON representation](https://developers.google.com/authorized-buyers/apis/realtimebidding/reference/rest/v1/buyers.userLists#UserList.SCHEMA_REPRESENTATION)
- [Status](https://developers.google.com/authorized-buyers/apis/realtimebidding/reference/rest/v1/buyers.userLists#Status)
- [UrlRestriction](https://developers.google.com/authorized-buyers/apis/realtimebidding/reference/rest/v1/buyers.userLists#UrlRestriction)
  - [JSON representation](https://developers.google.com/authorized-buyers/apis/realtimebidding/reference/rest/v1/buyers.userLists#UrlRestriction.SCHEMA_REPRESENTATION)
- [RestrictionType](https://developers.google.com/authorized-buyers/apis/realtimebidding/reference/rest/v1/buyers.userLists#RestrictionType)
- [Date](https://developers.google.com/authorized-buyers/apis/realtimebidding/reference/rest/v1/buyers.userLists#Date)
  - [JSON representation](https://developers.google.com/authorized-buyers/apis/realtimebidding/reference/rest/v1/buyers.userLists#Date.SCHEMA_REPRESENTATION)
- [Methods](https://developers.google.com/authorized-buyers/apis/realtimebidding/reference/rest/v1/buyers.userLists#METHODS_SUMMARY)

## 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 (`https://developers.google.com/authorized-buyers/apis/realtimebidding/reference/rest/v1/buyers.userLists#Status`), "urlRestriction": { object (`https://developers.google.com/authorized-buyers/apis/realtimebidding/reference/rest/v1/buyers.userLists#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 (`https://developers.google.com/authorized-buyers/apis/realtimebidding/reference/rest/v1/buyers.userLists#Status`)`` Output only. The status of the user list. A new user list starts out as open. |
| `urlRestriction` | ``object (`https://developers.google.com/authorized-buyers/apis/realtimebidding/reference/rest/v1/buyers.userLists#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 (https://developers.google.com/discovery/v1/type-format 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 (`https://developers.google.com/authorized-buyers/apis/realtimebidding/reference/rest/v1/buyers.userLists#RestrictionType`), "startDate": { object (`https://developers.google.com/authorized-buyers/apis/realtimebidding/reference/rest/v1/buyers.userLists#Date`) }, "endDate": { object (`https://developers.google.com/authorized-buyers/apis/realtimebidding/reference/rest/v1/buyers.userLists#Date`) } } ``` |

| Fields ||
|---|---|
| `url` | `string` Required. The URL to use for applying the restriction on the user list. |
| `restrictionType` | ``enum (`https://developers.google.com/authorized-buyers/apis/realtimebidding/reference/rest/v1/buyers.userLists#RestrictionType`)`` The restriction type for the specified URL. |
| `startDate` | ``object (`https://developers.google.com/authorized-buyers/apis/realtimebidding/reference/rest/v1/buyers.userLists#Date`)`` Start date (if specified) of the URL restriction. |
| `endDate` | ``object (`https://developers.google.com/authorized-buyers/apis/realtimebidding/reference/rest/v1/buyers.userLists#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:

- `google.type.TimeOfDay`
- `google.type.DateTime`
- `https://protobuf.dev/reference/protobuf/google.protobuf#timestamp`

| 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 ||
|---|---|
| ### `https://developers.google.com/authorized-buyers/apis/realtimebidding/reference/rest/v1/buyers.userLists/close` | Changes the status of a user list to CLOSED. |
| ### `https://developers.google.com/authorized-buyers/apis/realtimebidding/reference/rest/v1/buyers.userLists/create` | Creates a new user list. |
| ### `https://developers.google.com/authorized-buyers/apis/realtimebidding/reference/rest/v1/buyers.userLists/get` | Gets a user list by its name. |
| ### `https://developers.google.com/authorized-buyers/apis/realtimebidding/reference/rest/v1/buyers.userLists/getRemarketingTag` | This has been sunset as of October 2023, and will return an error response if called. |
| ### `https://developers.google.com/authorized-buyers/apis/realtimebidding/reference/rest/v1/buyers.userLists/list` | Lists the user lists visible to the current user. |
| ### `https://developers.google.com/authorized-buyers/apis/realtimebidding/reference/rest/v1/buyers.userLists/open` | Changes the status of a user list to OPEN. |
| ### `https://developers.google.com/authorized-buyers/apis/realtimebidding/reference/rest/v1/buyers.userLists/update` | Updates the given user list. |