Google Ads V25:list Plannable User Lists API

openapi: 3.2.0
info:
  title: Google Ads V25:list Plannable User Lists API
  description: Manage your Google Ads accounts, campaigns, and reports with this API.
  version: v25
  x-discovery-revision: '20260721'
  contact:
    name: Google
    url: https://developers.google.com/google-ads/api/
  termsOfService: https://developers.google.com/terms
servers:
- url: https://googleads.googleapis.com
  description: Google Ads API production server
security:
- oauth2:
  - https://www.googleapis.com/auth/adwords
tags:
- name: V25:listPlannableUserLists
paths:
  /v25:listPlannableUserLists:
    parameters:
    - name: upload_protocol
      in: query
      required: false
      schema:
        type: string
      description: Upload protocol for media (e.g. "raw", "multipart").
    - name: quotaUser
      in: query
      required: false
      schema:
        type: string
      description: Available to use for quota purposes for server-side applications. Can be any arbitrary string assigned to a user, but should not exceed 40 characters.
    - name: fields
      in: query
      required: false
      schema:
        type: string
      description: Selector specifying which fields to include in a partial response.
    - name: $.xgafv
      in: query
      required: false
      schema:
        type: string
        enum:
        - '1'
        - '2'
        x-enumDescriptions:
        - v1 error format
        - v2 error format
      description: V1 error format.
    - name: callback
      in: query
      required: false
      schema:
        type: string
      description: JSONP
    - name: prettyPrint
      in: query
      required: false
      schema:
        type: boolean
        default: 'true'
      description: Returns response with indentations and line breaks.
    - name: access_token
      in: query
      required: false
      schema:
        type: string
      description: OAuth access token.
    - name: uploadType
      in: query
      required: false
      schema:
        type: string
      description: Legacy upload protocol for media (e.g. "media", "multipart").
    - name: key
      in: query
      required: false
      schema:
        type: string
      description: API key. Your API key identifies your project and provides you with API access, quota, and reports. Required unless you provide an OAuth 2.0 token.
    - name: oauth_token
      in: query
      required: false
      schema:
        type: string
      description: OAuth 2.0 token for the current user.
    - name: alt
      in: query
      required: false
      schema:
        x-enumDescriptions:
        - Responses with Content-Type of application/json
        - Media download with context-dependent Content-Type
        - Responses with Content-Type of application/x-protobuf
        type: string
        default: json
        enum:
        - json
        - media
        - proto
      description: Data format for response.
    post:
      operationId: googleads_listPlannableUserLists
      summary: Returns the list of plannable user lists with their plannable status
      tags:
      - V25:listPlannableUserLists
      description: 'Returns the list of plannable user lists with their plannable status. User lists may not be plannable for a number of reasons, including: - They are less than 10 days old. - They have a membership lifespan that is less than 30 days - They have less than 10,000 or more than 700,000 users. List of thrown errors: AuthenticationError AuthorizationError FieldError HeaderError InternalError QuotaError RangeError ReachPlanError RequestError'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GoogleAdsGoogleadsV25Services__ListPlannableUserListsRequest'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GoogleAdsGoogleadsV25Services__ListPlannableUserListsResponse'
      security:
      - oauth2:
        - https://www.googleapis.com/auth/adwords
components:
  schemas:
    GoogleAdsGoogleadsV25Services__PlannableUserList:
      description: A plannable user list.
      type: object
      properties:
        userListInfo:
          description: The user list ID.
          $ref: '#/components/schemas/GoogleAdsGoogleadsV25Common__UserListInfo'
        userListType:
          type: string
          description: The user list type.
          x-enumDescriptions:
          - Not specified.
          - Used for return value only. Represents value unknown in this version.
          - UserList represented as a collection of conversion types.
          - UserList represented as a combination of other user lists/interests.
          - UserList created in the Google Ad Manager platform.
          - UserList associated with a rule.
          - UserList with users similar to users of another UserList.
          - UserList of first-party CRM data provided by advertiser in the form of emails or other formats.
          - LookalikeUserlist, composed of users similar to those of a configurable seed (set of UserLists)
          enum:
          - UNSPECIFIED
          - UNKNOWN
          - REMARKETING
          - LOGICAL
          - EXTERNAL_REMARKETING
          - RULE_BASED
          - SIMILAR
          - CRM_BASED
          - LOOKALIKE
        plannableStatus:
          type: string
          description: The plannable status of the user list.
          x-enumDescriptions:
          - Not specified.
          - Used for return value only. Represents value unknown in this version.
          - The user list is plannable.
          - The user list is not plannable.
          enum:
          - UNSPECIFIED
          - UNKNOWN
          - PLANNABLE
          - UNPLANNABLE
        displayName:
          type: string
          description: The name of the user list.
        plannableUserListMetadata:
          $ref: '#/components/schemas/GoogleAdsGoogleadsV25Services__PlannableUserListMetadata'
          description: The relevant metadata for this user list.
    GoogleAdsGoogleadsV25Services__PlannableUserListMetadata:
      type: object
      properties:
        userListCrmDataSourceType:
          description: The data source type of a CRM based user list.
          type: string
          x-enumDescriptions:
          - Not specified.
          - Used for return value only. Represents value unknown in this version.
          - The uploaded data is first-party data.
          - The uploaded data is from a third-party credit bureau.
          - The uploaded data is from a third-party voter file.
          - The uploaded data is third party partner data.
          enum:
          - UNSPECIFIED
          - UNKNOWN
          - FIRST_PARTY
          - THIRD_PARTY_CREDIT_BUREAU
          - THIRD_PARTY_VOTER_FILE
          - THIRD_PARTY_PARTNER_DATA
      description: The metadata associated with a plannable user list.
    GoogleAdsGoogleadsV25Services__ListPlannableUserListsRequest:
      type: object
      properties:
        reachApplicationInfo:
          description: Optional. Additional information on the application issuing the request.
          $ref: '#/components/schemas/GoogleAdsGoogleadsV25Common__AdditionalApplicationInfo'
        customerId:
          type: string
          description: Required. The ID of the customer.
        customerReachGroup:
          type: string
          description: The name of the customer being planned for. This is a user-defined value.
      description: Request message for ReachPlanService.ListPlannableUserLists that lists the available user lists for a customer.
    GoogleAdsGoogleadsV25Common__AdditionalApplicationInfo:
      description: Additional information about the application/tool issuing the request. This field is only used by ContentCreatorInsightsService, AudienceInsightsService, and ReachPlanService APIs.
      type: object
      properties:
        applicationId:
          description: The unique identifier of the agency proprietary application. This identifier is generated by Google. Reach out to your Google representative to request an application_id for each new application being integrated.
          type: string
        applicationInstance:
          description: The instance type of the application sending the request.
          type: string
          x-enumDescriptions:
          - Not specified.
          - The value is unknown in this version.
          - The instance is for development and testing purposes.
          - The instance is for production purposes.
          enum:
          - UNSPECIFIED
          - UNKNOWN
          - DEVELOPMENT_AND_TESTING
          - PRODUCTION
    GoogleAdsGoogleadsV25Common__UserListInfo:
      type: object
      properties:
        userList:
          type: string
          description: The User List resource name.
      description: A User List criterion. Represents a user list that is defined by the advertiser to be targeted.
    GoogleAdsGoogleadsV25Services__ListPlannableUserListsResponse:
      description: A response with all available user lists with their plannable status.
      type: object
      properties:
        plannableUserLists:
          type: array
          description: The list of user lists available for planning and related targeting metadata.
          items:
            $ref: '#/components/schemas/GoogleAdsGoogleadsV25Services__PlannableUserList'
  securitySchemes:
    oauth2:
      type: oauth2
      description: Google OAuth 2.0. Google Ads API additionally requires a developer token in the developer-token header.
      flows:
        authorizationCode:
          authorizationUrl: https://accounts.google.com/o/oauth2/auth
          tokenUrl: https://oauth2.googleapis.com/token
          scopes:
            https://www.googleapis.com/auth/adwords: See, edit, create, and delete your Google Ads accounts and data.
externalDocs:
  url: https://developers.google.com/google-ads/api/
x-source: https://googleads.googleapis.com/$discovery/rest?version=v25
x-generated-by: API Evangelist enrichment pipeline — mechanical conversion of the first-party Google API Discovery Document