> ## Documentation Index
> Fetch the complete documentation index at: https://doc.extole.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Update audience

> Updates an existing audience. Only fields supplied in the body are changed; omitted fields are left untouched. Sending `null` for `name` returns `400 invalid_null` because `name` is a required attribute on the audience. Returns the updated audience.



## OpenAPI

````yaml /api-reference/management.json put /v1/audiences/{audience_id}
openapi: 3.0.1
info:
  description: >-
    Configuration endpoints for the Extole platform: campaigns, components,
    audiences, persons, rewards, reporting, integrations setup, and
    administrative tooling.
  title: Management API
  version: '1.0'
servers:
  - description: Production
    url: https://api.extole.io
security:
  - HEADER: []
  - QUERY: []
  - COOKIE: []
tags:
  - name: Audiences
  - name: Authentication
  - name: Batch Jobs
  - name: Blocks
  - name: Campaigns
  - name: Components
  - name: Components Settings
  - name: Domains
  - name: Email
  - name: Erasure
  - name: Event Streams
  - name: File Validation Monitors
  - name: Optout
  - name: Profiles
  - name: Promotion Links
  - name: Report Schedules
  - name: Report Types
  - name: Reports
  - name: Reward Suppliers
  - name: Security Keys
  - name: Settings
  - name: User Notifications
  - name: User Subscriptions
  - name: Users
  - name: Webhooks
paths:
  /v1/audiences/{audience_id}:
    put:
      tags:
        - Audiences
      summary: Update audience
      description: >-
        Updates an existing audience. Only fields supplied in the body are
        changed; omitted fields are left untouched. Sending `null` for `name`
        returns `400 invalid_null` because `name` is a required attribute on the
        audience. Returns the updated audience.
      operationId: updateAudience
      parameters:
        - in: path
          name: audience_id
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            example:
              component_ids:
                - component_id
              component_references:
                - component_id: component_id
                  socket_names:
                    - socket_name
              enabled: true
              name: name
              tags:
                - tag
            schema:
              $ref: '#/components/schemas/AudienceUpdateRequest'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AudienceResponse'
          description: Updated audience.
        '400':
          content:
            application/json:
              examples:
                audience_not_found:
                  $ref: '#/components/examples/audience_not_found'
                invalid_audience_name:
                  $ref: '#/components/examples/invalid_audience_name'
                invalid_audience_tag:
                  $ref: '#/components/examples/invalid_audience_tag'
              schema:
                $ref: '#/components/schemas/RestExceptionResponse'
          description: >-
            Bad request. The named examples below cover the validation errors
            that are specific to this operation. Other 400 causes include
            malformed JSON, an empty request body, and an invalid `Time-Zone`
            header - inspect the response `code` field for the specific error.
        '401':
          content:
            application/json:
              examples:
                method_unauthorized:
                  $ref: '#/components/examples/method_unauthorized'
              schema:
                $ref: '#/components/schemas/RestExceptionResponse'
          description: Unauthorized
        '402':
          content:
            application/json:
              examples:
                payment_required:
                  $ref: '#/components/examples/payment_required'
              schema:
                $ref: '#/components/schemas/RestExceptionResponse'
          description: Payment Required
        '403':
          content:
            application/json:
              examples:
                access_denied:
                  $ref: '#/components/examples/access_denied'
                method_unauthorized:
                  $ref: '#/components/examples/method_unauthorized'
                missing_access_token:
                  $ref: '#/components/examples/missing_access_token'
              schema:
                $ref: '#/components/schemas/RestExceptionResponse'
          description: Forbidden
        '415':
          content:
            application/json:
              examples:
                unsupported_media_type:
                  $ref: '#/components/examples/unsupported_media_type'
              schema:
                $ref: '#/components/schemas/RestExceptionResponse'
          description: Unsupported Media Type
        '429':
          content:
            application/json:
              examples:
                too_many_requests:
                  $ref: '#/components/examples/too_many_requests'
              schema:
                $ref: '#/components/schemas/RestExceptionResponse'
          description: Too Many Requests
components:
  schemas:
    AudienceUpdateRequest:
      description: Body of a `PUT /v1/audiences/{audience_id}` request.
      properties:
        component_ids:
          items:
            type: string
          type: array
        component_references:
          items:
            $ref: '#/components/schemas/ComponentReferenceRequest'
          type: array
        enabled:
          $ref: '#/components/schemas/EnabledInAudienceUpdateRequest'
        name:
          $ref: '#/components/schemas/NameInAudienceUpdateRequest'
        tags:
          description: >-
            Replaces the audience's tag set with the supplied set. Pass an empty
            set to clear all tags. Each tag must be 255 characters or fewer.
          items:
            type: string
          type: array
      type: object
    AudienceResponse:
      description: >-
        Stored audience definition. Fields `name` and `enabled` are unevaluated
        and appear in buildtime-evaluatable form.
      properties:
        component_ids:
          items:
            type: string
          type: array
        component_references:
          items:
            $ref: '#/components/schemas/ComponentReferenceResponse'
          type: array
        enabled:
          $ref: '#/components/schemas/EnabledInAudienceResponse'
        id:
          description: Stable Extole identifier for the audience.
          readOnly: true
          type: string
        name:
          $ref: '#/components/schemas/NameInAudienceResponse'
        tags:
          description: Free-form tags applied to the audience.
          items:
            type: string
          type: array
      required:
        - component_ids
        - component_references
        - enabled
        - id
        - name
        - tags
      type: object
    RestExceptionResponse:
      description: Represents the API error response
      properties:
        code:
          description: Specific error code for this error type, documented per endpoint
          type: string
        http_status_code:
          description: >-
            HTTP status code that was returned with this error, useful if client
            get response code
          format: int32
          type: integer
        message:
          description: User readable English description of the error
          type: string
        parameters:
          additionalProperties:
            description: >-
              Attributes related to the error, varies be error code, documented
              per endpoint
            type: object
          description: >-
            Attributes related to the error, varies be error code, documented
            per endpoint
          type: object
        unique_id:
          description: >-
            Unique id associated with this error, useful for discussions with
            Extole
          type: string
      required:
        - code
        - http_status_code
        - message
        - parameters
        - unique_id
      type: object
    ComponentReferenceRequest:
      properties:
        component_id:
          type: string
        socket_names:
          items:
            type: string
          type: array
      type: object
    EnabledInAudienceUpdateRequest:
      description: >-
        New enabled flag. Disabling an audience leaves the definition in place
        but prevents the runtime from evaluating it.
      oneOf:
        - description: Static enabled
          title: Static Value
          type: boolean
        - description: >-
            Handlebars expression with
            [AudienceBuildtimeContext](https://github.com/extole/extole-specification/blob/main/openapi/expression-context/com/extole/api/audience/AudienceBuildtimeContext.d.ts).
          example: handlebars@buildtime:{{enabled}}
          externalDocs:
            description: AudienceBuildtimeContext
            url: >-
              https://github.com/extole/extole-specification/blob/main/openapi/expression-context/com/extole/api/audience/AudienceBuildtimeContext.d.ts
          pattern: ^handlebars@buildtime:.*
          title: Buildtime - Handlebars
          type: string
        - description: >-
            Javascript expression with
            [AudienceBuildtimeContext](https://github.com/extole/extole-specification/blob/main/openapi/expression-context/com/extole/api/audience/AudienceBuildtimeContext.d.ts).
          example: >-
            javascript@buildtime:function() { return
            context.getVariableContext().get('enabled');}
          externalDocs:
            description: AudienceBuildtimeContext
            url: >-
              https://github.com/extole/extole-specification/blob/main/openapi/expression-context/com/extole/api/audience/AudienceBuildtimeContext.d.ts
          pattern: ^javascript@buildtime:.*
          title: Buildtime - Javascript
          type: string
    NameInAudienceUpdateRequest:
      description: >-
        New display name. Same shape and 255-character cap as on `POST
        /v1/audiences`. Sending `null` returns `400 invalid_null` because `name`
        is required on the audience.
      oneOf:
        - allOf:
            - type: string
            - not:
                anyOf:
                  - pattern: ^handlebars@buildtime:.*
                    type: string
                  - pattern: ^javascript@buildtime:.*
                    type: string
              type: string
          description: Static name
          title: Static Value
        - description: >-
            Handlebars expression with
            [AudienceBuildtimeContext](https://github.com/extole/extole-specification/blob/main/openapi/expression-context/com/extole/api/audience/AudienceBuildtimeContext.d.ts).
          example: handlebars@buildtime:{{name}}
          externalDocs:
            description: AudienceBuildtimeContext
            url: >-
              https://github.com/extole/extole-specification/blob/main/openapi/expression-context/com/extole/api/audience/AudienceBuildtimeContext.d.ts
          pattern: ^handlebars@buildtime:.*
          title: Buildtime - Handlebars
          type: string
        - description: >-
            Javascript expression with
            [AudienceBuildtimeContext](https://github.com/extole/extole-specification/blob/main/openapi/expression-context/com/extole/api/audience/AudienceBuildtimeContext.d.ts).
          example: >-
            javascript@buildtime:function() { return
            context.getVariableContext().get('name');}
          externalDocs:
            description: AudienceBuildtimeContext
            url: >-
              https://github.com/extole/extole-specification/blob/main/openapi/expression-context/com/extole/api/audience/AudienceBuildtimeContext.d.ts
          pattern: ^javascript@buildtime:.*
          title: Buildtime - Javascript
          type: string
    ComponentReferenceResponse:
      properties:
        component_id:
          type: string
        socket_names:
          items:
            type: string
          type: array
      type: object
    EnabledInAudienceResponse:
      description: Whether the audience is currently evaluated at runtime.
      oneOf:
        - description: Literal enabled
          title: Static Value
          type: boolean
        - description: >-
            Handlebars expression with
            [AudienceBuildtimeContext](https://github.com/extole/extole-specification/blob/main/openapi/expression-context/com/extole/api/audience/AudienceBuildtimeContext.d.ts).
          example: handlebars@buildtime:{{enabled}}
          externalDocs:
            description: AudienceBuildtimeContext
            url: >-
              https://github.com/extole/extole-specification/blob/main/openapi/expression-context/com/extole/api/audience/AudienceBuildtimeContext.d.ts
          pattern: ^handlebars@buildtime:.*
          title: Buildtime - Handlebars
          type: string
        - description: >-
            Javascript expression with
            [AudienceBuildtimeContext](https://github.com/extole/extole-specification/blob/main/openapi/expression-context/com/extole/api/audience/AudienceBuildtimeContext.d.ts).
          example: >-
            javascript@buildtime:function() { return
            context.getVariableContext().get('enabled');}
          externalDocs:
            description: AudienceBuildtimeContext
            url: >-
              https://github.com/extole/extole-specification/blob/main/openapi/expression-context/com/extole/api/audience/AudienceBuildtimeContext.d.ts
          pattern: ^javascript@buildtime:.*
          title: Buildtime - Javascript
          type: string
    NameInAudienceResponse:
      description: >-
        Display name for the audience, in the same buildtime-evaluatable form
        that was supplied on create or update.
      oneOf:
        - allOf:
            - type: string
            - not:
                anyOf:
                  - pattern: ^handlebars@buildtime:.*
                    type: string
                  - pattern: ^javascript@buildtime:.*
                    type: string
              type: string
          description: Literal name
          title: Static Value
        - description: >-
            Handlebars expression with
            [AudienceBuildtimeContext](https://github.com/extole/extole-specification/blob/main/openapi/expression-context/com/extole/api/audience/AudienceBuildtimeContext.d.ts).
          example: handlebars@buildtime:{{name}}
          externalDocs:
            description: AudienceBuildtimeContext
            url: >-
              https://github.com/extole/extole-specification/blob/main/openapi/expression-context/com/extole/api/audience/AudienceBuildtimeContext.d.ts
          pattern: ^handlebars@buildtime:.*
          title: Buildtime - Handlebars
          type: string
        - description: >-
            Javascript expression with
            [AudienceBuildtimeContext](https://github.com/extole/extole-specification/blob/main/openapi/expression-context/com/extole/api/audience/AudienceBuildtimeContext.d.ts).
          example: >-
            javascript@buildtime:function() { return
            context.getVariableContext().get('name');}
          externalDocs:
            description: AudienceBuildtimeContext
            url: >-
              https://github.com/extole/extole-specification/blob/main/openapi/expression-context/com/extole/api/audience/AudienceBuildtimeContext.d.ts
          pattern: ^javascript@buildtime:.*
          title: Buildtime - Javascript
          type: string
  examples:
    audience_not_found:
      summary: audience_not_found
      value:
        code: audience_not_found
        http_status_code: 400
        message: Audience was not found
        parameters: {}
        unique_id: 00000000-0000-0000-0000-000000000000
    invalid_audience_name:
      summary: invalid_audience_name
      value:
        code: invalid_audience_name
        http_status_code: 400
        message: Invalid audience name
        parameters: {}
        unique_id: 00000000-0000-0000-0000-000000000000
    invalid_audience_tag:
      summary: invalid_audience_tag
      value:
        code: invalid_audience_tag
        http_status_code: 400
        message: Invalid audience tag
        parameters: {}
        unique_id: 00000000-0000-0000-0000-000000000000
    method_unauthorized:
      summary: method_unauthorized
      value:
        code: method_unauthorized
        http_status_code: 401
        message: Unauthorized access to this endpoint
        parameters: {}
        unique_id: 00000000-0000-0000-0000-000000000000
    payment_required:
      summary: payment_required
      value:
        code: payment_required
        http_status_code: 402
        message: The access_token provided is associated with an unpaid account.
        parameters: {}
        unique_id: 00000000-0000-0000-0000-000000000000
    access_denied:
      summary: access_denied
      value:
        code: access_denied
        http_status_code: 403
        message: >-
          The access_token provided is not permitted to access the specified
          resource.
        parameters: {}
        unique_id: 00000000-0000-0000-0000-000000000000
    missing_access_token:
      summary: missing_access_token
      value:
        code: missing_access_token
        http_status_code: 403
        message: No access_token was provided with this request.
        parameters: {}
        unique_id: 00000000-0000-0000-0000-000000000000
    unsupported_media_type:
      summary: unsupported_media_type
      value:
        code: unsupported_media_type
        http_status_code: 415
        message: Request had an unsupported or no media type
        parameters: {}
        unique_id: 00000000-0000-0000-0000-000000000000
    too_many_requests:
      summary: too_many_requests
      value:
        code: too_many_requests
        http_status_code: 429
        message: >-
          The server is unable to process your request at the moment, please
          retry later.
        parameters: {}
        unique_id: 00000000-0000-0000-0000-000000000000
  securitySchemes:
    HEADER:
      in: header
      name: Authorization
      type: apiKey
      x-bearer-format: bearer
    QUERY:
      in: query
      name: access_token
      type: apiKey
    COOKIE:
      in: cookie
      name: extole_token
      type: apiKey

````