openapi: 3.2.0
info:
  title: Segmentation Service Audiences API
  description: "\nAdobe Experience Platform Segmentation Service provides a user interface and RESTful API that allows you to create audiences through segment definitions or other sources from your Real-Time Customer Profile data. These audiences are centrally configured and maintained on Platform, and are readily accessible by any Adobe solution. Use the Segmentation Service API to programmatically integrate the service's various functionalities into your experience application, providing RESTful endpoints for managing audiences, segment definitions, segment jobs, exports, schedules, and more.\n- **Related documentation**:\n    - [Segmentation Service documentation](https://www.adobe.com/go/segmentation-overview-en)\n\n- **Visualize API calls with Postman (a free, third-party software)**:\n    - [Segmentation Service API Postman collection on GitHub](https://github.com/adobe/experience-platform-postman-samples/blob/master/apis/experience-platform/Segmentation%20Service%20API.postman_collection.json)\n    - [Video guide for creating the Postman environment](https://video.tv.adobe.com/v/28832)\n    - [Steps for importing environments and collections in Postman](https://learning.getpostman.com/docs/postman/collection_runs/using_environments_in_collection_runs/)\n\n- **API paths**: \n  - PLATFORM Gateway URL: https://<span>platform.adobe.io/\n  - Base path for this API: /data/core/ups\n  - Example of a complete path: https://<span>platform.adobe.io/data/core/ups/segment/definitions\n\n- **Required headers**:\n  - All calls require the headers `Authorization`, `x-gw-ims-org-id`, and `x-api-key`. For more information on how to obtain these values, see the [authentication tutorial](https://www.adobe.com/go/platform-api-authentication-en).\n  - All resources in Experience Platform are isolated to specific virtual sandboxes. All requests to Platform APIs require the header `x-sandbox-name` whose value is the all-lowercase name of the sandbox the operation will take place in (for example, \\\"prod\\\"). See the [sandboxes overview](https://adobe.com/go/sandbox-overview-en)for more information.    \n  - All requests with a payload in the request body(such as POST, PUT, and PATCH calls) must include the header `Content-Type` with a value of `application/json`.\n\n- **API error handling**:\n  - Refer to the Experience Platform API troubleshooting guide for [FAQs](https://experienceleague.adobe.com/docs/experience-platform/landing/troubleshooting.html#faq), [API status codes](https://experienceleague.adobe.com/docs/experience-platform/landing/troubleshooting.html#api-status-codes), and [request header errors](https://experienceleague.adobe.com/docs/experience-platform/landing/troubleshooting.html#request-header-errors)."
  version: '1.0'
servers:
- url: //{environment}.adobe.io/data/core/ups
  variables:
    environment:
      default: platform
      enum:
      - platform
      - platform-stage
tags:
- name: Audiences
  description: Audiences are a set of people, accounts, households, or other entities that share common characteristics and behaviors. This set can be generated either by using Platform or from external sources. More information about using this set of endpoints can be found in the [audiences endpoint guide](https://experienceleague.adobe.com/docs/experience-platform/segmentation/api/audiences.html).
paths:
  /audiences:
    get:
      tags:
      - Audiences
      summary: List audiences
      operationId: listAudiences
      parameters:
      - $ref: '#/components/parameters/authorization'
      - $ref: '#/components/parameters/x-api-key'
      - $ref: '#/components/parameters/x-gw-ims-org-id'
      - $ref: '#/components/parameters/x-sandbox-name'
      - name: start
        in: query
        description: A query parameter that specifies the starting offset for the audiences returned.
        required: false
        schema:
          type: integer
        example: 4
      - name: limit
        in: query
        description: A query parameter that specifies the total number of audiences returned per page.
        required: false
        schema:
          type: integer
        example: 20
      - name: sort
        in: query
        description: A query parameter that specifies the field to sort the results by. This is written in the format `[attributeName]:[desc/asc]`
        required: false
        schema:
          type: string
        example: updateTime:desc
      - name: property
        in: query
        description: A query parameter that specifies which audiences to return. The audiences returned must **exactly** match the attribute value given. This is written in the format `property=[attributeName]==[attributeValue]`.
        required: false
        schema:
          type: string
        example: property=audienceId==test-audience-id
      - name: name
        in: query
        description: A query parameter that filters for audiences that contain the string in the name. This value is case **insensitive**.
        required: false
        schema:
          type: string
        example: Test
      - name: description
        in: query
        description: A query parameter that filters for audiences that contain the string in the description. This value is case **insensitive**.
        required: false
        schema:
          type: string
        example: Test description
      - name: entityType
        in: query
        description: A query parameter that lets you filter the type of audience you're looking for.
        required: false
        schema:
          type: string
        example: _xom.context.account
      responses:
        200:
          x-summary: Success
          description: A list of audiences is returned.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AudiencesList'
        403:
          x-summary: Missing access permissions
          description: Access is forbidden because the organization is **not** enabled for audiences.
          content:
            application/json:
              schema:
                type: object
              examples:
                Organization not enabled for audiences:
                  value:
                    requestId: dprgmrFdQgxPMLq5WxCRJsJUQcllxtHX
                    errors:
                      403:
                      - code: 403
                        message: The IMS Org is not enabled for External Segment.
                    type: https://ns.adobe.com/aep/errors/UPAPI-113740-403
                    title: The IMS Org is not enabled for External Segment
                    status: 403
                Attribute Based Access Control validation error:
                  value:
                    requestId: NvXUrBnbFxSQb00Uthy3rMIEFzNyRc2s
                    errors:
                      403:
                      - code: UPAPI-113752-403
                        message: Permission denied on some resources. errorMessage=[{\"resource\":{\"uri\":\"/orgs/{ORG_ID}/sandboxes/prod/segments\",\"labels\":[]},\"action\":\"READ\"}]
                      type: https://ns.adobe.com/aep/errors/UPAPI-113752-403
                      title: Permission denied on some resources. errorMessage=[{"resource":{"uri":"/orgs/{ORG_ID}/sandboxes/prod/segments","labels":[]},"action":"READ"}]
                      status: 403
    post:
      tags:
      - Audiences
      summary: Create an audience
      operationId: createAudience
      parameters:
      - $ref: '#/components/parameters/authorization'
      - $ref: '#/components/parameters/content-type'
      - $ref: '#/components/parameters/x-api-key'
      - $ref: '#/components/parameters/x-gw-ims-org-id'
      - $ref: '#/components/parameters/x-sandbox-name'
      requestBody:
        description: The request body for creating an audience.
        content:
          application/json:
            schema:
              oneOf:
              - $ref: '#/components/schemas/CreatePlatformAudienceRequestBody'
            examples:
              Platform-generated audience:
                $ref: '#/components/examples/CreatePlatformAudienceRequestBody'
      responses:
        201:
          x-summary: Success
          description: A new audience was successfully created.
          content:
            application/json:
              schema:
                oneOf:
                - $ref: '#/components/schemas/PlatformGeneratedAudience'
              examples:
                Platform-generated audience:
                  $ref: '#/components/examples/PlatformAudience'
        400:
          x-summary: Error
          description: The audience could not be created.
          content:
            application/json:
              schema:
                type: object
              examples:
                Validation error (Name is a mandatory field):
                  value:
                    requestId: fggdhzT89v3qlldeezJ9eVQtKiR51hkZ
                    errors:
                      400:
                      - code: 400
                        message: There is a problem extracting the user JSON, field(s) missing or invalid.  Correct and try again.
                      - code: 400
                        message: No usable value for name\nDid not find value which can be converted into java.lang.String
                      - code: 400
                        message: Did not find value which can be converted into java.lang.String
                    type: https://ns.adobe.com/aep/errors/UPLIB-101206-500
                    title: There is a problem extracting the user JSON, field(s) missing or invalid. Correct and try again.
                    status: 400
                Validation error (Cannot create audience where lifecycle state is deleted):
                  value:
                    requestId: 2wvHvngaq58nE1JyNFOJwQjIQJV2dePE
                    errors:
                      400:
                      - code: 400
                        message: There is a problem in audience validation. Cannot set lifecycleState as deleted
                    type: https://ns.adobe.com/aep/errors/UPAPI-113434-400
                    title: There is a problem in audience validation. Cannot set lifecycleState as deleted
                    status: 400
                Validation error (Dataset ID validation):
                  value:
                    requestId: dki6o4NeG6sUAYd80tIfNFnTTMzq9TWk
                    errors:
                      400:
                      - code: 400
                        message: Dataset 15b4657a-058a-47b0-a356-7b63328138c6 cannot be retrieved from Catalog https://platform.adobe.io/data/foundation/catalog/dataSets/15b4657a-058a-47b0-a356-7b63328138c6.
                      - code: 400
                        message: 'uri:PlatformUrl/data/foundation/catalog/dataSets/15b4657a-058a-47b0-a356-7b63328138c6 -> Status Code - 404 : message

                          {"type":"/placeholder/type/uri","status":404,"title":"NotFoundError","detail":"DataSet not found."}'
                    type: https://ns.adobe.com/aep/errors/UPLIB-101554-503
                    title: Dataset 15b4657a-058a-47b0-a356-7b63328138c6 cannot be retrieved from Catalog https://platform.adobe.io/data/foundation/catalog/dataSets/15b4657a-058a-47b0-a356-7b63328138c6.
                    status: 400
  /audiences/{AUDIENCE_ID}:
    get:
      tags:
      - Audiences
      summary: Retrieve an audience
      operationId: getAudience
      parameters:
      - $ref: '#/components/parameters/authorization'
      - $ref: '#/components/parameters/x-api-key'
      - $ref: '#/components/parameters/x-gw-ims-org-id'
      - $ref: '#/components/parameters/x-sandbox-name'
      - name: AUDIENCE_ID
        in: path
        description: The ID of the audience you want to retrieve.
        required: true
        schema:
          type: string
          example: 60ccea95-1435-4180-97a5-58af4aa285ab
      responses:
        200:
          x-summary: Success
          description: The specified audience was successfully retrieved.
          content:
            application/json:
              schema:
                oneOf:
                - $ref: '#/components/schemas/PlatformGeneratedAudience'
              examples:
                Platform-generated audience:
                  $ref: '#/components/examples/PlatformAudience'
        404:
          x-summary: Not found
          description: The audience was not found.
          content:
            application/json:
              schema:
                type: object
              examples:
                Audience not found:
                  value:
                    requestId: YrgXiqvCobA9neOmrzCP7kQLi4yIizoP
                    errors:
                      404:
                      - code: 404
                        message: The audience entity e65765df-adfa-4d4b-b31a-53c390a575c is not found. Use a valid entity and try again.
                    type: https://ns.adobe.com/aep/errors/UPAPI-113430-404
                    title: The audience entity e65765df-adfa-4d4b-b31a-53c390a575c is not found. Use a valid entity and try again.
                    status: 404
    delete:
      tags:
      - Audiences
      summary: Delete an audience
      operationId: deleteAudience
      parameters:
      - $ref: '#/components/parameters/authorization'
      - $ref: '#/components/parameters/x-api-key'
      - $ref: '#/components/parameters/x-gw-ims-org-id'
      - $ref: '#/components/parameters/x-sandbox-name'
      - name: AUDIENCE_ID
        in: path
        description: The ID of the audience you want to retrieve.
        required: true
        schema:
          type: string
          example: 60ccea95-1435-4180-97a5-58af4aa285ab
      responses:
        204:
          x-summary: Success
          description: The audience was successfully deleted. No message is returned upon a successful response.
          content:
            application/json:
              schema:
                type: object
        400:
          x-summary: Error
          description: The audience could not be deleted.
          content:
            application/json:
              schema:
                type: object
              examples:
                Validation error (Audience is dependent on other audiences):
                  value:
                    requestId: JG5rthQiyy8Ca0Y0WnCbhCu6Rh2PT6bg
                    errors:
                      400:
                      - code: 400
                        message: The audience cannot be deleted.
                    type: https://ns.adobe.com/aep/errors/UPAPI-113631-403
                    title: The audience cannot be deleted.
                    status: 400
        403:
          x-summary: Missing access permissions
          description: Attribute based access control error
          content:
            application/json:
              schema:
                type: object
              examples:
                Could not re-write audience status:
                  value:
                    requestId: NvXUrBnbFxSQb00Uthy3rMIEFzNyRc2s
                    errors:
                      403:
                      - code: UPAPI-113752-403
                        message: Permission denied on some resources. errorMessage=[{\"resource\":{\"uri\":\"/orgs/660932FC5AFCB4C50A494209@AdobeOrg/sandboxes/prod/segments/60ccea95-1435-4180-97a5-58af4aa285ab5\",\"labels\":[]},\"action\":\"WRITE\"}]
                    type: https://ns.adobe.com/aep/errors/UPAPI-113752-403
                    title: Permission denied on some resources. errorMessage=[{\"resource\":{\"uri\":\"/orgs/660932FC5AFCB4C50A494209@AdobeOrg/sandboxes/prod/segments/60ccea95-1435-4180-97a5-58af4aa285ab5\",\"labels\":[]},\"action\":\"WRITE\"}]
                    status: 403
        404:
          x-summary: Not found
          description: The audience could not be found.
          content:
            application/json:
              schema:
                type: object
              examples:
                Audience not found:
                  value:
                    requestId: YrgXiqvCobA9neOmrzCP7kQLi4yIizoP
                    errors:
                      404:
                      - code: 404
                        message: The audience entity 60ccea95-1435-4180-97a5-58af4aa285ab5 is not found. Use a valid entity and try again.
                    type: https://ns.adobe.com/aep/errors/UPAPI-113430-404
                    title: The audience entity 60ccea95-1435-4180-97a5-58af4aa285ab5 is not found. Use a valid entity and try again.
                    status: 404
    patch:
      tags:
      - Audiences
      summary: Update one or more attributes of an audience
      operationId: patchAudience
      parameters:
      - $ref: '#/components/parameters/authorization'
      - $ref: '#/components/parameters/content-type'
      - $ref: '#/components/parameters/x-api-key'
      - $ref: '#/components/parameters/x-gw-ims-org-id'
      - $ref: '#/components/parameters/x-sandbox-name'
      - name: AUDIENCE_ID
        in: path
        description: The ID of the audience you want to patch.
        required: true
        schema:
          type: string
          example: 60ccea95-1435-4180-97a5-58af4aa285ab
      requestBody:
        description: A sample request body to update the PQL expression of the audience.
        content:
          application/json:
            schema:
              type: array
              items:
                type: object
                properties:
                  op:
                    type: string
                    example: add
                  path:
                    type: string
                    example: /expression
                  value:
                    type: object
                    properties:
                      type:
                        type: string
                        example: PQL
                      format:
                        type: string
                        example: pql/text
                      value:
                        type: string
                        example: workAddress.country = "CA"
            examples:
              Update the PQL:
                description: The following PATCH request will update the audience's workAddress.country to US.
                value:
                - op: add
                  path: /expression
                  value:
                    type: PQL
                    format: pql/text
                    value: workAddress.country= "US"
      responses:
        201:
          x-summary: Success
          description: Details of your newly updated audience are returned.
          content:
            application/json:
              schema:
                oneOf:
                - $ref: '#/components/schemas/PlatformGeneratedAudience'
              examples:
                Update the PQL:
                  $ref: '#/components/examples/PlatformAudience'
        400:
          x-summary: Error
          description: The audience could not be updated.
          content:
            application/json:
              schema:
                type: object
              examples:
                Validation error (Lifecycle status cannot be modified to Delete):
                  value:
                    requestId: rxFGviFDXAfpH2qTzDta41sWoXHsuQpU
                    errors:
                      400:
                      - code: 400
                        message: There is a problem in audience validation. lifecycle field can not be modified to Delete using Patch operation
                    type: https://ns.adobe.com/aep/errors/UPAPI-113434-400
                    title: There is a problem in audience validation. lifecycle field can not be modified to Delete using Patch operation
                    status: 400
        404:
          x-summary: Not found
          description: The audience could not be found.
          content:
            application/json:
              schema:
                type: object
              examples:
                Audience not found:
                  value:
                    requestId: YrgXiqvCobA9neOmrzCP7kQLi4yIizoP
                    errors:
                      404:
                      - code: 404
                        message: The audience entity 4afe34ae-8c98-4513-8a1d-67ccaa54bc05 is not found. Use a valid entity and try again.
                    type: https://ns.adobe.com/aep/errors/UPAPI-113430-404
                    title: The audience entity 4afe34ae-8c98-4513-8a1d-67ccaa54bc05 is not found. Use a valid entity and try again.
                    status: 404
    put:
      tags:
      - Audiences
      summary: Update an audience
      operationId: updateAudience
      parameters:
      - $ref: '#/components/parameters/authorization'
      - $ref: '#/components/parameters/content-type'
      - $ref: '#/components/parameters/x-api-key'
      - $ref: '#/components/parameters/x-gw-ims-org-id'
      - $ref: '#/components/parameters/x-sandbox-name'
      - name: AUDIENCE_ID
        in: path
        description: The ID of the audience you want to overwrite.
        required: true
        schema:
          type: string
          example: 60ccea95-1435-4180-97a5-58af4aa285ab
      responses:
        201:
          x-summary: Success
          description: The audience was successfully updated.
          content:
            application/json:
              schema:
                oneOf:
                - $ref: '#/components/schemas/PlatformGeneratedAudience'
              examples:
                Update audience PQL expression:
                  $ref: '#/components/examples/PlatformAudience'
        400:
          x-summary: Error
          description: The audience could not be updated.
          content:
            application/json:
              schema:
                type: object
              examples:
                Validation error (Namepsace is immutable):
                  value:
                    requestId: LBGnewEg2iOcx6TcTVEIy1e6fE6zAlHh
                    errors:
                      400:
                      - code: 400
                        message: There is a problem in audience validation. Namespace is immutable field.
                    type: https://ns.adobe.com/aep/errors/UPAPI-113434-400
                    title: There is a problem in audience validation. Namespace is immutable field
                    status: 400
        404:
          x-summary: Not found
          description: The audience was not found.
          content:
            application/json:
              schema:
                type: object
              examples:
                Audience not found:
                  value:
                    requestId: YrgXiqvCobA9neOmrzCP7kQLi4yIizoP
                    errors:
                      404:
                      - code: 404
                        message: The audience entity 4afe34ae-8c98-4513-8a1d-67ccaa54bc05 is not found. Use a valid entity and try again.
                    type: https://ns.adobe.com/aep/errors/UPAPI-113430-404
                    title: The audience entity 4afe34ae-8c98-4513-8a1d-67ccaa54bc05 is not found. Use a valid entity and try again.
                    status: 404
        500:
          x-summary: Access control validation error
          description: An attribute based access control validation error ocurred.
          content:
            application/json:
              schema:
                type: object
              examples:
                Validation error:
                  value:
                    requestId: oeoKKxNTV4HAUcTPfhWoz6nDYmghjIIu
                    errors:
                      500:
                      - code: UPAPI-113751-500
                        message: There is a problem validating Field Level Access Control.
                      - code: 500
                        message: '{"type":"http://ns.adobe.com/aep/errors/PDP-4041-403","title":"The user is not entitled to the specified organization. Please try again with a valid user.","status":403,"report":{"tenantInfo":{"sandboxName":"N/A","sandboxId":"N/A","imsOrgId":"745F37C35E4B776E0A49421B@AdobeOrg"},"additionalContext":{"request-id":"oeoKKxNTV4HAUcTPfhWoz6nDYmghjIIu"}},"error-chain":[{"serviceId":"Policy Decision Point","errorCode":"PDP-4041-403","invokingServiceId":"acp_core_unifiedProfile_feeds","unixTimeStampMs":1660925698164}]}'
                    type: https://ns.adobe.com/aep/errors/UPAPI-113751-500
                    title: here is a problem validating Field Level Access Control."
                    status: 500
      requestBody:
        description: The request body to update the audience.
        content:
          application/json:
            schema:
              oneOf:
              - $ref: '#/components/schemas/UpdateAudienceName'
              - $ref: '#/components/schemas/UpdateAudiencePQL'
            examples:
              Update the audience name:
                $ref: '#/components/examples/UpdateAudienceName'
              Update the audience PQL:
                $ref: '#/components/examples/UpdateAudiencePQL'
  /audiences/bulk-get:
    post:
      tags:
      - Audiences
      summary: Retrieve multiple audiences
      operationId: bulkGetAudiences
      parameters:
      - $ref: '#/components/parameters/authorization'
      - $ref: '#/components/parameters/content-type'
      - $ref: '#/components/parameters/x-api-key'
      - $ref: '#/components/parameters/x-gw-ims-org-id'
      - $ref: '#/components/parameters/x-sandbox-name'
      requestBody:
        description: A sample request body to retrieve multiple audiences.
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                ids:
                  type: array
                  items:
                    type: object
                    properties:
                      id:
                        type: string
                        example: 72c393ea-caed-441a-9eb6-5f66bb1bd6cd
            example:
              ids:
              - id: 72c393ea-caed-441a-9eb6-5f66bb1bd6cd
              - id: QU9fLTEzOTgzNTE0MzY0NzY0NDg5NzkyOTkx_6ed34f6f-fe21-4a30-934f-6ffe21fa3075
      responses:
        207:
          x-summary: Success
          description: The audiences were successfully retrieved.
          content:
            application/json:
              schema:
                type: object
              examples:
                All the audiences were successfully retrieved:
                  value:
                    results:
                      72c393ea-caed-441a-9eb6-5f66bb1bd6cd:
                        id: 72c393ea-caed-441a-9eb6-5f66bb1bd6cd
                        audienceId: 72c393ea-caed-441a-9eb6-5f66bb1bd6cd
                        schema:
                          name: _xdm.context.profile
                        imsOrgId: '{ORG_ID}'
                        sandbox:
                          sandboxId: 6ed34f6f-fe21-4a30-934f-6ffe21fa3075
                          sandboxName: prod
                          type: production
                          default: true
                        name: Sample Audience
                        expression:
                          type: pql
                          format: pql/text
                          value: _id = \"abc\"
                        mergePolicyId: 87c94d51-239c-4391-932c-29c2412100e5
                        evaluationInfo:
                          batch:
                            enabled: false
                          continuous:
                            enabled: true
                          synchronous:
                            enabled: false
                        ansibleUiEnabled: false
                        dataGovernancePolicy:
                          excludeOptOut: true
                        creationTime: 1623889553000
                        createEpoch: 1623889553
                        updateTime: 1674646369000
                        updateEpoch: 1674646369
                        _etag: \"61030ec7-0000-0200-0000-63d113610000\"
                        dependents: []
                        definedOn:
                        - meta:resourceType: unions
                          meta:containerId: tenant
                          $ref: https://ns.adobe.com/xdm/context/profile__union
                        dependencies: []
                        type: SegmentDefinition
                        state: enabled
                        overridePerformanceWarnings: false
                        lastModifiedBy: '{USER_ID}'
                        lifecycleState: published
                        namespace: AEPSegments
                        isSystem: false
                        saveSegmentMembership: true
                        originName: REAL_TIME_CUSTOMER_PROFILE
                      QU9fLTEzOTgzNTE0MzY0NzY0NDg5NzkyOTkx_6ed34f6f-fe21-4a30-934f-6ffe21fa3075:
                        id: QU9fLTEzOTgzNTE0MzY0NzY0NDg5NzkyOTkx_6ed34f6f-fe21-4a30-934f-6ffe21fa3075
                        name: External Audience
                        namespace: AO
                        imsOrgId: '{ORG_ID}'
                        sandbox:
                          sandboxId: 6ed34f6f-fe21-4a30-934f-6ffe21fa3075
                          sandboxName: prod
                          type: production
                          default: true
                        type: ExternalSegment
                        lifecycleState: published
                        sourceId: source-id
                        createdBy: '{USER_ID}'
                        datasetId: 62bf31a105e9891b63525c92
                        _etag: \"3100da6d-0000-0200-0000-62bf31a10000\"
                        creationTime: 1656697249000
                        createEpoch: 1656697249
                        updateTime: 1656697249000
                        updateEpoch: 1656697249
                        audienceId: external-audience-id
                        isSystem: false
                        saveSegmentMembership: true
                        linkedAudienceRef:
                          aoWorkflowId: 62bf31858e87e34c8364befa
                        originName: AUDIENCE_ORCHESTRATION
                One audience was not found:
                  value:
                    results:
                      QU9fLTEzOTgzNTE0MzY0NzY0NDg5NzkyOTkx_6ed34f6f-fe21-4a30-934f-6ffe21fa3075:
                        id: QU9fLTEzOTgzNTE0MzY0NzY0NDg5NzkyOTkx_6ed34f6f-fe21-4a30-934f-6ffe21fa3075
                        name: External Audience
                        namespace: AO
                        imsOrgId: '{ORG_ID}'
                        sandbox:
                          sandboxId: 6ed34f6f-fe21-4a30-934f-6ffe21fa3075
                          sandboxName: prod
                          type: production
                          default: true
                        type: ExternalSegment
                        lifecycleStatus: published
                        sourceId: source-id
                        createdBy: '{USER_ID}'
                        datasetId: 62bf31a105e9891b63525c92
                        _etag: \"3100da6d-0000-0200-0000-62bf31a10000\"
                        creationTime: 1656697249000
                        createEpoch: 1656697249
                        updateTime: 1656697249000
                        updateEpoch: 1656697249
                        audienceId: test-audience-id
                        isSystem: false
                        saveSegmentMembership: true
                        linkedAudienceRef:
                          aoWorkflowId: 62bf31858e87e34c8364befa
                        originName: AUDIENCE_ORCHESTRATION
                      missing-audience:
                        requestId: BNcYkjG1BCnhQ51uToeSdY5D5fQOKcSe
                        errors:
                          404:
                          - code: 404
                            message: Not found.
        400:
          x-summary: Error
          description: An invalid number of IDs was requested. This value **must** be greater than 100 and less than 1000.
          content:
            application/json:
              schema:
                type: object
              examples:
                No IDs were provided:
                  value:
                    requestId: 6qtdW3er5YruNle8CfFa050FlIuKsEZb
                    errors:
                      400:
                      - code: UPAPI-113015-400
                        message: The number of requested IDs is invalid. Cannot be 0 or exceed 100.
                    type: https://ns.adobe.com/aep/errors/UPAPI-113015-400
                    title: The number of requested IDs is invalid. Cannot be 0 or exceed 100.
                    status: 400
        404:
          x-summary: Not found
          description: None of the requested audiences could be found.
          content:
            application/json:
              schema:
                type: object
              examples:
                All audiences were not found:
                  value:
                    requestId: Vrxt59wqKLr5OlpnclFc2kMGAVwZQIT2
                    errors:
                      404:
                      - code: UPAPI-113000-404
                        message: The entity missing-audience-1,missing-audience-2 is not found.
                    type: https://ns.adobe.com/aep/errors/UPAPI-113000-404
                    title: The entity missing-audience-1,missing-audience-2 is not found.
                    status: 404
components:
  schemas:
    AudiencesList:
      type: object
      properties:
        children:
          type: array
          description: A list of audiences.
          items:
            oneOf:
            - $ref: '#/components/schemas/PlatformGeneratedAudience'
            - $ref: '#/components/schemas/ExternallyGeneratedAudience'
        _page:
          type: object
          description: An object that shows what page the list is on.
          properties:
            totalCount:
              type: integer
              example: 111
              description: The total number of audiences.
            totalPages:
              type: integer
              example: 21
              description: The total number of pages.
            sortField:
              type: string
              example: name
              description: The name of the field that the audiences are sorted by.
            sort:
              type: string
              example: asc
              description: The sort direction of the audiences.
            pageSize:
              type: integer
              example: 2
              description: The number of results contained on this page.
            limit:
              type: integer
              example: 5
            start:
              type: integer
              example: 0
            next:
              type: integer
              example: 1
              description: The value needed for `start` to show the next page of results.
        _links:
          type: object
          properties:
            next:
              type: object
              properties:
                href:
                  type: string
                  example: '@/audiences?start=1&limit=2&totalCount=111'
                  description: A URI that can be used to access the next page.
          description: An object that contains useful links for the audiences.
    UpdateAudiencePQL:
      type: object
      properties:
        audienceId:
          type: string
          example: 60ccea95-1435-4180-97a5-58af4aa285ab
          description: The ID of the audience.
        name:
          type: string
          example: People who ordered in the last 30 days
          description: The name of the audience.
        profileInstanceId:
          type: string
          example: ups
          description: A field that contains the value passed in by the `x-profile-instance-id` header. However, this field is currently **not** used.
        description:
          type: string
          example: This audience is generated to see people who ordered in the last 30 days.
          description: A description of the audience.
        type:
          type: string
          example: SegmentDefinition
          description: A system-generated field that displays whether the audience is Platform-generated or is an externally generated audience. Possible values include `SegmentDefinition` and `ExternalAudience`.
        expression:
          type: object
          properties:
            type:
              type: string
              example: PQL
            format:
              type: string
              example: pql/text
            value:
              type: string
              example: workAddress.country = "US"
          description: The PQL expression for the audience.
        schema:
          type: object
          properties:
            name:
              type: string
              example: _xdm.context.profile
          description: The Experience Data Model (XDM) schema class name.
        labels:
          type: array
          items:
            type: string
            example:
            - core/C1
          description: Object-level data usage and attribute-based access control labels that are relevant to the audience.
    ExternallyGeneratedAudience:
      type: object
      properties:
        id:
          type: string
          example: 32a83b5d-a118-4bd6-b3cb-3aee2f4c30a1
          description: The ID of the audience.
        audienceId:
          type: string
          example: test-external-audience-id
          description: The ID of the audience. For an externally-generated audience, this value is client-generated and can be different than the `id` value.
        name:
          type: string
          example: externalAudience1
          description: The name of the audience.
        namespace:
          type: string
          example: aam
          description: The namespace of the audience.
          enum:
          - AAM
          - AAMSegments
          - AAMTraits
          - AEPSegments
        imsOrgId:
          type: string
          example: 1BD6382559DF0C130A49422D@AdobeOrg
          description: The ID of the audience's organization.
        sandbox:
          type: object
          description: Details about the sandbox the audience belongs to. More information about sandboxes can be found in the [sandbox overview]((https://adobe.com/go/sandbox-overview-en)).
          properties:
            sandboxId:
              type: string
              example: 6ed34f6f-fe21-4a30-934f-6ffe21fa3075
              description: The ID of the sandbox.
            sandboxName:
              type: string
              example: prod
              description: The name of the sandbox.
            type:
              type: string
              example: production
              description: The type of the sandbox. Possible values include `production` and `development`.
            default:
              type: boolean
              example: true
              description: A boolean value that states whether or not this sandbox is the default sandbox.
        isSystem:
          type: boolean
          example: false
          description: A property that shows if the audience is system-generated. If the audience is system-generated, it will not be included in any results by default.
        description:
          type: string
          example: Last 30 days
          description: A description of the audience.
        type:
          type: string
          example: ExternalSegment
          description: A value that shows whether the audience is Platform-generated (`SegmentDefinition`) or externally-generated (`ExternalAudience`).
          enum:
          - SegmentDefinition
          - ExternalAudience
        originName:
          type: string
          example: CUSTOM_UPLOAD
          description: 'The name of the audience''s origin. Can be one of the following values: `REAL_TIME_CUSTOMER_PROFILE`, `CUSTOM_UPLOAD`, `AUDIENCE_ORCHESTRATION`, `AUDIENCE_MANAGER`'
        lifecycleState:
          type: string
          example: published
          enum:
          - draft
          - published
          - inactive
          - archived
          description: 'The status of the audience. <ul><li>`draft`: The audience is created</li><li>`published`: The audience is published</li><li>`inactive`: The audience is no longer active</li><li>`archived`: The audience is deleted.</li></ul>'
        createdBy:
          type: string
          example: externalAudience@AdobeID
          description: The ID of the user who created the audience.
        datasetId:
          type: string
          example: 6254cf3c97f8e31b639fb14d
          description: The ID of the dataset where the external audience data was ingested into.
        labels:
          type: array
          items:
            type: string
          example:
          - core/C1
          description: Object-level data usage and attribute-based access control labels that are relevant to the audience.
        linkedAudienceRef:
          type: object
          properties:
            flowId:
              type: string
              example: 4685ea90-d2b6-11ec-9d64-0242ac120002
          description: Identifiers that point to metadata in other audience-related systems.
        creationTime:
          type: integer
          example: 1642745034000000
          description: A UTC timestamp for when the audience was created, in milliseconds.
        updateEpoch:
          type: integer
          example: 1649926314
          description: A UTC timestamp for when the audience was updated, in seconds.
        updateTime:
          type: integer
          example: 1649926314000
          description: A UTC timestamp for when the audience was updated, in milliseconds.
        createEpoch:
          type: integer
          example: 1642745034
          description: A UTC timestamp for when the audience was created, in seconds.
    PlatformGeneratedAudience:
      type: object
      properties:
        id:
          type: string
          example: 60ccea95-1435-4180-97a5-58af4aa285ab
          description: The ID of the audience.
        audienceId:
          type: string
          example: 60ccea95-1435-4180-97a5-58af4aa285ab
          description: The ID of the audience. For a Platform-generated audience, this will be the same as `id`.
        schema:
          type: object
          properties:
            name:
              type: string
              example: _xdm.context.profile
          description: The Experience Data Model (XDM) schema class name.
        profileInstanceId:
          type: string
          example: ups
          description: A field that contains the value passed in by the `x-profile-instance-id` header. However, this field is currently **not** used.
        imsOrgId:
          type: string
          example: 1BD6382559DF0C130A49422D@AdobeOrg
          description: The ID of the audience's organization.
        sandbox:
          type: object
          description: Details about the sandbox the audience belongs to. More information about sandboxes can be found in the [sandbox overview]((https://adobe.com/go/sandbox-overview-en)).
          properties:
            sandboxId:
              type: string
              example: 6ed34f6f-fe21-4a30-934f-6ffe21fa3075
              description: The ID of the sandbox.
            sandboxName:
              type: string
              example: prod
              description: The name of the sandbox.
            type:
              type: string
              example: production
              description: The type of the sandbox. Possible values include `production` and `development`.
            default:
              type: boolean
              example: true
              description: A boolean value that states whether or not this sandbox is the default sandbox.
        name:
          type: string
          example: People who ordered in the last 30 days
          description: The name of the audience.
        description:
          type: string
          example: Last 30 days
          description: A description of the audience.
        expression:
          type: object
          properties:
            type:
              type: string
              example: PQL
            format:
              type: string
              example: pql/text
            value:
              type: string
              example: workAddress.country="US"
          description: The PQL expression for the audience.
        mergePolicyId:
          type: string
          example: ef006bbe-750e-4e81-85f0-0c6902192dcc
          description: The ID of the merge policy the audience belongs to.
        evaluationInfo:
          type: object
          properties:
            batch:
              type: object
              properties:
                enabled:
                  type: boolean
                  example: false
              description: If this property is marked as enabled, the audience will be evaluated using batch segmentation.
            continuous:
              type: object
              properties:
                enabled:
                  type: boolean
                  example: true
              description: If this property is marked as enabled, the audience will be evaluated using streaming segmentation.
            synchronous:
              type: object
              properties:
                enabled:
                  type: boolean
                  example: false
              description: If this property is marked as enabled, the audience will be evaluated using edge segmentation.
          description: An object that describes how the audience is evaluated.
        dataGovernancePolicy:
          type: object
          properties:
            excludeOptOut:
              type: boolean
              example: true
          description: Information about the audience's data governance policy.
        isSystem:
          type: boolean
          example: false
          description: A property that shows if the audience is system-generated. If the audience is system-generated, it will not be included in any results by default.
        creationTime:
          type: integer
          example: 1650374572000
          description: A UTC timestamp for when the audience was created, in milliseconds.
        updateEpoch:
          type: integer
          example: 1650374573
          description: A UTC timestamp for when the audience was updated, in seconds.
        updateTime:
          type: integer
          example: 1650374573000
          description: A UTC timestamp for when the audience was updated, in milliseconds.
        createEpoch:
          type: integer
          example: 1650374572
          description: A UTC timestamp for when the audience was created, in seconds.
        _etag:
          type: string
          example: '"33120d7c-0000-0200-0000-625eb7ad0000"'
          description: A field used for tagging Platform-generated audiences for data usage enforcement. This value is **not** used for externally-generated audiences.
        dependents:
          type: array
          items:
            type: string
          example: []
          description: An array of audience IDs that the audience is dependent on. This value is used for audiences which are part of a segment of segments query.
        definedOn:
          type: array
          items:
            type: object
            properties:
              meta:resourceType:
                type: string
                example: unions
              meta:containerId:
                type: string
                example: tenant
              $ref:
                type: string
                example: https://ns.adobe.com/xdm/context/profile__union
          description: This value is only used on Platform-generated audiences.
        dependencies:
          type: array
          items:
            type: string
          example: []
          description: An array of IDs that depend on the audience. This value is used for audiences which are part of a segment of segments query.
        type:
          type: string
          example: SegmentDefinition
          description: A value that shows whether the audience is Platform-generated (`SegmentDefinition`) or externally-generated (`ExternalAudience`).
          enum:
          - SegmentDefinition
          - ExternalAudience
        originName:
          type: string
          example: REAL_TIME_CUSTOMER_PROFILE
          description: 'The name of the audience''s origin. Can be one of the following values: `REAL_TIME_CUSTOMER_PROFILE`, `CUSTOM_UPLOAD`, `AUDIENCE_ORCHESTRATION`, `AUDIENCE_MANAGER`'
        overridePerformanceWarnings:
          type: boolean
          example: false
          description: A boolean that lets you override the performance warnings.
        createdBy:
          type: string
          example: audiences@AdobeId
          description: The ID of the user who created the audience.
        lifecycleState:
          type: string
          enum:
          - draft
          - published
          - inactive
          - archived
          example: published
          description: 'The status of the audience. <ul><li>`draft`: The audience is created</li><li>`published`: The audience is published</li><li>`inactive`: The audience is no longer active</li><li>`archived`: The audience is deleted.</li></ul>'
        labels:
          type: array
          items:
            type: string
          example:
          - core/C1
          description: Object-level data usage and attribute-based access control labels that are relevant to the audience.
        namespace:
          type: string
          example: AEPSegments
          description: The namespace of the audience.
          enum:
          - AAM
          - AAMSegments
          - AAMTraits
          - AEPSegments
    UpdateAudienceName:
      type: object
      properties:
        audienceId:
          type: string
          example: test-external-audience-id
          description: The ID of the audience.
        name:
          type: string
          example: externalAudience1
          description: The name of the audience.
        namespace:
          type: string
          example: aam
          description: The namespace that the audience belongs to. Possible values include `AAM`, `AAMSegments`, `AAMTraits`, and `AEPSegments`.
        description:
          type: string
          example: People who ordered in the last 30 days.
          description: A description of the audience.
        type:
          type: string
          example: ExternalAudience
          description: A system-generated field that displays whether the audience is Platform-generated or is an externally generated audience. Possible values include `SegmentDefinition` and `ExternalAudience`.
        lifecycleState:
          type: string
          example: published
          description: A Platform-maintained status to show the status of the audience. Possible values include `draft`, `published`, `inactive`, and `archived`.
        datasetId:
          type: string
          example: 6254cf3c97f8e31b639fb14d
          description: The dataset where the audience data can be found.
        expression:
          type: object
          properties:
            type:
              type: string
              example: PQL
            format:
              type: string
              example: pql/text
            value:
              type: string
              example: workAddress.country = "US"
          description: The PQL expression for the audience.
        labels:
          type: array
          items:
            type: string
          example:
          - core/C1
          description: Object-level data usage and attribute-based access control labels that are relevant to the audience.
    CreatePlatformAudienceRequestBody:
      type: object
      properties:
        name:
          type: string
          example: People who ordered in the last 30 days
          description: The ID of the audience.
        profileInstanceId:
          type: string
          example: ups
        description:
          type: string
          example: This audience is generated to see people who ordered in the last 30 days.
          description: A description of the audience.
        type:
          type: string
          example: SegmentDefinition
          description: A field that displays whether the audience is Platform-generated or is an externally generated audience. Possible values include `SegmentDefinition` and `ExternalAudience`.
        expression:
          type: object
          properties:
            type:
              type: string
              example: PQL
            format:
              type: string
              example: pql/text
            value:
              type: string
              example: workAddress.country = "US"
          description: The PQL expression for the audience.
        schema:
          type: object
          properties:
            name:
              type: string
              example: _xdm.context.profile
          description: The Experience Data Model (XDM) schema class name.
        labels:
          type: array
          items:
            type: string
          example:
          - core/C1
          description: Object-level data usage and attribute-based access control labels that are relevant to the audience.
  examples:
    CreatePlatformAudienceRequestBody:
      description: A sample body for creating an audience.
      value:
        name: People who ordered in the last 30 days
        profileInstanceId: ups
        description: This audience is generated to see people who ordered in the last 30 days.
        type: SegmentDefinition
        expression:
          type: PQL
          format: pql/text
          value: workAddress.country = "US"
        schema:
          name: _xdm.context.profile
        labels:
        - core/C1
    PlatformAudience:
      description: A sample Platform-generated audience.
      value:
        id: 60ccea95-1435-4180-97a5-58af4aa285ab
        audienceId: 60ccea95-1435-4180-97a5-58af4aa285ab
        schema:
          name: _xdm.context.profile
        profileInstanceId: ups
        imsOrgId: 1BD6382559DF0C130A49422D@AdobeOrg
        sandbox:
          sandboxId: 6ed34f6f-fe21-4a30-934f-6ffe21fa3075
          sandboxName: prod
          type: production
          default: true
        isSystem: false
        name: People who ordered in the last 30 days
        description: This audience is generated to see people who ordered in the last 30 days.
        expression:
          type: PQL
          format: pql/text
          value: workAddress.country = "US"
        mergePolicyId: ef006bbe-750e-4e81-85f0-0c6902192dcc
        evaluationInfo:
          batch:
            enabled: false
          continuous:
            enabled: true
          synchronous:
            enabled: false
        dataGovernancePolicy:
          excludeOptOut: true
        creationTime: 1650374572000
        updateEpoch: 1650374573
        updateTime: 1650374573000
        createEpoch: 1650374572
        _etag: '"33120d7c-0000-0200-0000-625eb7ad0000"'
        dependents: []
        definedOn:
        - meta:resourceType: unions
          meta:containerId: tenant
          $ref: https://ns.adobe.com/xdm/context/profile__union
        dependencies: []
        type: SegmentDefinition
        overridePerformanceWarnings: false
        createdBy: audiences@AdobeId
        lifecycle: active
        labels:
        - core/C1
        namespace: AEPSegments
    UpdateAudienceName:
      description: A sample request body for updating an audience's name.
      value:
        audienceId: test-external-audience-id
        name: New externalSegment
        namespace: aam
        description: This audience is generated to see people who ordered in the last 30 days.
        type: ExternalSegment
        lifecycleState: published
        datasetId: 6254cf3c97f8e31b639fb14d
        labels:
        - core/c1
    UpdateAudiencePQL:
      description: A sample request body for updating an audience's PQL expression.
      value:
        audienceId: 60ccea95-1435-4180-97a5-58af4aa285ab
        name: People who ordered in the last 30 days
        profileInstanceId: ups
        description: This audience is generated to see people who ordered in the last 30 days.
        type: SegmentDefinition
        expression:
          type: PQL
          format: pql/text
          value: workAddress.country = "US"
        schema:
          name: _xdm.context.profile
        labels:
        - core/C1
  parameters:
    authorization:
      name: Authorization
      in: header
      description: The access token which can be copied from your Experience Platform integration, prefixed with "Bearer ". For more information on how to obtain this value, visit the [authentication tutorial](http://www.adobe.com/go/platform-api-authentication-en).
      required: true
      schema:
        type: string
    content-type:
      name: Content-Type
      in: header
      description: The type of content being sent in the body of the request. Should be 'application/json'.
      required: true
      schema:
        type: string
    x-api-key:
      name: x-api-key
      in: header
      description: The API key which can be copied from your Experience Platform integration. For more information on how to obtain this value, visit the [authentication tutorial](http://www.adobe.com/go/platform-api-authentication-en).
      required: true
      schema:
        type: string
    x-gw-ims-org-id:
      name: x-gw-ims-org-id
      in: header
      description: The Organization ID which can be copied from your Experience Platform integration. For more information on how to obtain this value, visit the [authentication tutorial](http://www.adobe.com/go/platform-api-authentication-en).
      required: true
      schema:
        type: string
    x-sandbox-name:
      name: x-sandbox-name
      in: header
      description: All resources in Experience Platform are isolated to specific virtual sandboxes. Requests to Platform APIs require a header that specifies the name of the sandbox in which the operation will take place. See the [sandboxes overview](https://adobe.com/go/sandbox-overview-en) for more information.
      required: true
      schema:
        type: string