Google Ads Customers.custom Audiences API

openapi: 3.2.0
info:
  title: Google Ads Customers.custom Audiences 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: customers.customAudiences
paths:
  /v25/customers/{customersId}/customAudiences:mutate:
    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_customers_customAudiences_mutate
      summary: Creates or updates custom audiences
      tags:
      - customers.customAudiences
      description: 'Creates or updates custom audiences. Operation statuses are returned. List of thrown errors: [AuthenticationError]() [AuthorizationError]() [CustomAudienceError]() [CustomInterestError]() [FieldError]() [FieldMaskError]() [HeaderError]() [InternalError]() [MutateError]() [OperationAccessDeniedError]() [PolicyViolationError]() [QuotaError]() [RequestError]()'
      parameters:
      - name: customerId
        in: path
        required: true
        schema:
          type: string
          pattern: ^[^/]+$
        description: Required. The ID of the customer whose custom audiences are being modified.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GoogleAdsGoogleadsV25Services__MutateCustomAudiencesRequest'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GoogleAdsGoogleadsV25Services__MutateCustomAudiencesResponse'
      security:
      - oauth2:
        - https://www.googleapis.com/auth/adwords
components:
  schemas:
    GoogleAdsGoogleadsV25Resources__CustomAudience:
      description: 'A custom audience. This is a list of users by interest. The unique key of a custom audience consists of the following fields: name. Violating the unique key constraint produces error: CustomAudienceError.NAME_ALREADY_USED'
      type: object
      properties:
        type:
          type: string
          description: Type of the custom audience. ("INTEREST" OR "PURCHASE_INTENT" is not allowed for newly created custom audience but kept for existing audiences)
          x-enumDescriptions:
          - Not specified.
          - Used for return value only. Represents value unknown in this version.
          - Google Ads will auto-select the best interpretation at serving time.
          - Matches users by their interests.
          - Matches users by topics they are researching or products they are considering for purchase.
          - Matches users by what they searched on Google Search.
          enum:
          - UNSPECIFIED
          - UNKNOWN
          - AUTO
          - INTEREST
          - PURCHASE_INTENT
          - SEARCH
        id:
          description: Output only. ID of the custom audience.
          type: string
          format: int64
        status:
          x-enumDescriptions:
          - Not specified.
          - Used for return value only. Represents value unknown in this version.
          - Enabled status - custom audience is enabled and can be targeted.
          - Removed status - custom audience is removed and cannot be used for targeting.
          enum:
          - UNSPECIFIED
          - UNKNOWN
          - ENABLED
          - REMOVED
          type: string
          description: Output only. Status of this custom audience. Indicates whether the custom audience is enabled or removed.
        description:
          type: string
          description: Description of this custom audience.
        members:
          description: List of custom audience members that this custom audience is composed of. Members can be added during CustomAudience creation. If members are presented in UPDATE operation, existing members will be overridden.
          items:
            $ref: '#/components/schemas/GoogleAdsGoogleadsV25Resources__CustomAudienceMember'
          type: array
        name:
          description: Name of the custom audience. It should be unique for all custom audiences created by a customer. This field is required for creating operations.
          type: string
        resourceName:
          type: string
          description: 'Immutable. The resource name of the custom audience. Custom audience resource names have the form: `customers/{customer_id}/customAudiences/{custom_audience_id}`'
    GoogleAdsGoogleadsV25Services__MutateCustomAudienceResult:
      type: object
      properties:
        resourceName:
          description: Returned for successful operations.
          type: string
      description: The result for the custom audience mutate.
    GoogleAdsGoogleadsV25Services__MutateCustomAudiencesResponse:
      description: Response message for custom audience mutate.
      type: object
      properties:
        results:
          description: All results for the mutate.
          items:
            $ref: '#/components/schemas/GoogleAdsGoogleadsV25Services__MutateCustomAudienceResult'
          type: array
    GoogleAdsGoogleadsV25Resources__CustomAudienceMember:
      description: A member of custom audience. A member can be a KEYWORD, URL, PLACE_CATEGORY or APP. It can only be created or removed but not changed.
      type: object
      properties:
        app:
          type: string
          description: A package name of Android apps which users installed such as com.google.example.
        keyword:
          description: A keyword or keyword phrase — at most 10 words and 80 characters. Languages with double-width characters such as Chinese, Japanese, or Korean, are allowed 40 characters, which describes the user's interests or actions.
          type: string
        memberType:
          type: string
          description: The type of custom audience member, KEYWORD, URL, PLACE_CATEGORY or APP.
          x-enumDescriptions:
          - Not specified.
          - Used for return value only. Represents value unknown in this version.
          - Users whose interests or actions are described by a keyword.
          - Users who have interests related to the website's content.
          - Users who visit place types described by a place category.
          - Users who have installed a mobile app.
          enum:
          - UNSPECIFIED
          - UNKNOWN
          - KEYWORD
          - URL
          - PLACE_CATEGORY
          - APP
        placeCategory:
          format: int64
          description: A place type described by a place category users visit.
          type: string
        url:
          type: string
          description: An HTTP URL, protocol-included — at most 2048 characters, which includes contents users have interests in.
    GoogleAdsGoogleadsV25Services__CustomAudienceOperation:
      description: A single operation (create, update) on a custom audience.
      type: object
      properties:
        remove:
          description: 'Remove operation: A resource name for the removed custom audience is expected, in this format: `customers/{customer_id}/customAudiences/{custom_audience_id}`'
          type: string
        update:
          description: 'Update operation: The custom audience is expected to have a valid resource name.'
          $ref: '#/components/schemas/GoogleAdsGoogleadsV25Resources__CustomAudience'
        updateMask:
          type: string
          description: FieldMask that determines which resource fields are modified in an update.
          format: google-fieldmask
        create:
          $ref: '#/components/schemas/GoogleAdsGoogleadsV25Resources__CustomAudience'
          description: 'Create operation: No resource name is expected for the new custom audience.'
    GoogleAdsGoogleadsV25Services__MutateCustomAudiencesRequest:
      description: Request message for CustomAudienceService.MutateCustomAudiences.
      type: object
      properties:
        operations:
          type: array
          description: Required. The list of operations to perform on individual custom audiences.
          items:
            $ref: '#/components/schemas/GoogleAdsGoogleadsV25Services__CustomAudienceOperation'
        validateOnly:
          type: boolean
          description: If true, the request is validated but not executed. Only errors are returned, not results.
  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