openapi: 3.2.0
info:
  title: Google Display & Video 360 Custom Lists API
  description: Display & Video 360 API allows users to automate complex Display & Video 360 workflows, such as creating insertion orders and setting targeting options for individual line items. Derived mechanically from the first-party Google API Discovery Document at https://displayvideo.googleapis.com/$discovery/rest?version=v4 (revision 20260813).
  version: v4
  contact:
    name: Google
    url: https://developers.google.com/display-video/
  license:
    name: Google APIs Terms of Service
    url: https://developers.google.com/terms
  termsOfService: https://developers.google.com/terms
  x-google-discovery-revision: '20260813'
  x-google-discovery-document: https://displayvideo.googleapis.com/$discovery/rest?version=v4
servers:
- url: https://displayvideo.googleapis.com
  description: Display & Video 360 API server
security:
- oauth2:
  - https://www.googleapis.com/auth/display-video
tags:
- name: Custom Lists
paths:
  /v4/customLists/{customListsId}:
    get:
      operationId: customListsGet
      summary: Gets a custom list.
      description: Gets a custom list.
      tags:
      - Custom Lists
      parameters:
      - name: customListId
        in: path
        schema:
          type: string
          format: int64
          pattern: ^[^/]+$
        description: Required. The ID of the custom list to fetch.
        required: true
      - name: advertiserId
        in: query
        schema:
          type: string
          format: int64
        description: The ID of the DV360 advertiser that has access to the fetched custom lists.
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CustomList'
      security:
      - oauth2:
        - https://www.googleapis.com/auth/display-video
      x-google-method-id: displayvideo.customLists.get
  /v4/customLists:
    get:
      operationId: customListsList
      summary: Lists custom lists.
      description: Lists custom lists. The order is defined by the order_by parameter.
      tags:
      - Custom Lists
      parameters:
      - name: filter
        in: query
        schema:
          type: string
        description: 'Allows filtering by custom list fields. Supported syntax: * Filter expressions for custom lists can only contain at most one restriction. * A restriction has the form of `{field} {operator} {value}`. * All fields must use the `HAS (:)` operator. Supported fields: * `displayName` Examples: * All custom lists for which the display name contains "Google": `displayName:"Google"`. The length of this field should be no more than 500 characters. Reference our [filter `LIST` requests](/display-video/api/guides/how-tos/filters) guide for more information.'
      - name: pageToken
        in: query
        schema:
          type: string
        description: A token identifying a page of results the server should return. Typically, this is the value of next_page_token returned from the previous call to `ListCustomLists` method. If not specified, the first page of results will be returned.
      - name: pageSize
        in: query
        schema:
          type: integer
          format: int32
        description: Requested page size. Must be between `1` and `200`. If unspecified will default to `100`. Returns error code `INVALID_ARGUMENT` if an invalid value is specified.
      - name: advertiserId
        in: query
        schema:
          type: string
          format: int64
        description: The ID of the DV360 advertiser that has access to the fetched custom lists.
      - name: orderBy
        in: query
        schema:
          type: string
        description: 'Field by which to sort the list. Acceptable values are: * `customListId` (default) * `displayName` The default sorting order is ascending. To specify descending order for a field, a suffix "desc" should be added to the field name. Example: `displayName desc`.'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListCustomListsResponse'
      security:
      - oauth2:
        - https://www.googleapis.com/auth/display-video
      x-google-method-id: displayvideo.customLists.list
components:
  schemas:
    CustomList:
      type: object
      description: Describes a custom list entity, such as a custom affinity or custom intent audience list.
      properties:
        name:
          type: string
          description: Output only. The resource name of the custom list.
          readOnly: true
        customListId:
          type: string
          format: int64
          description: Output only. The unique ID of the custom list. Assigned by the system.
          readOnly: true
        displayName:
          type: string
          description: Output only. The display name of the custom list. .
          readOnly: true
    ListCustomListsResponse:
      type: object
      properties:
        customLists:
          type: array
          description: The list of custom lists. This list will be absent if empty.
          items:
            $ref: '#/components/schemas/CustomList'
        nextPageToken:
          type: string
          description: A token to retrieve the next page of results. Pass this value in the page_token field in the subsequent call to `ListCustomLists` method to retrieve the next page of results.
  securitySchemes:
    oauth2:
      type: oauth2
      description: Google OAuth 2.0. Authorization and token endpoints read from https://accounts.google.com/.well-known/openid-configuration.
      flows:
        authorizationCode:
          authorizationUrl: https://accounts.google.com/o/oauth2/v2/auth
          tokenUrl: https://oauth2.googleapis.com/token
          refreshUrl: https://oauth2.googleapis.com/token
          scopes:
            https://www.googleapis.com/auth/doubleclickbidmanager: View and manage your reports in DoubleClick Bid Manager
            https://www.googleapis.com/auth/display-video-user-management: 'Private Service: https://www.googleapis.com/auth/display-video-user-management'
            https://www.googleapis.com/auth/display-video: Create, see, edit, and permanently delete your Display & Video 360 entities and reports
            https://www.googleapis.com/auth/display-video-mediaplanning: Create, see, and edit Display & Video 360 Campaign entities and see billing invoices