openapi: 3.0.1
info:
  title: Audience export API
  description: >
    Use the Audience export REST API to access the output of an [audience
    export](https://doc.sitecore.com/cdp/en/users/sitecore-cdp/audience-export.html)
    job.


    After an export job finishes running, its
    [output](https://doc.sitecore.com/cdp/en/users/sitecore-cdp/the-output-of-an-export.html)
    becomes available at presigned URLs. You can download the output of the
    export job by opening the URLs.

    You can access output URLs in two ways:
       - Retrieve the output URLs for the most recently finished export job.
       - First retrieve a list of all finished export jobs of the export, then retrieve the output URLs for any finished export job of your choice.

    Note the following:
       - To use this REST API, you must authorize your API requests.
       - All API requests are made in your production environment. 

     For more information, see the [official Sitecore CDP developer documentation](https://doc.sitecore.com/cdp/en/developers/api/index-en.html).

    # Authorization

    The Audience export REST API uses the OAuth 2.0 standard with JSON web
    tokens to authorize REST API requests.

    ### Create an API key
      1. In the Sitecore Cloud Portal, open Sitecore CDP.
      2. Click **Developer center** > **API keys** > **Create**.
      3. Name your API key and select a feature. Then, click **Save**. The API key and the API secret display.
      4. Copy the API key and the API secret because you won't be able to view them again in Sitecore CDP. You'll use them to request an access token.

    ### Request an access token

    Run the following cURL command to request an access token. Replace the
    placeholder values with your API key and API secret.

    ```curl
      curl -X POST 'https://auth.sitecorecloud.io/oauth/token' \
      --header 'Content-Type: application/x-www-form-urlencoded' \
      --data-urlencode 'client_id={YOUR_API_KEY}' \
      --data-urlencode 'client_secret={YOUR_API_SECRET}' \
      --data-urlencode 'grant_type=client_credentials' \
      --data-urlencode 'audience=https://api.sitecorecloud.io'
    ```

    In the response, the `access_token` key contains the access token:

    ```json
      {
        "access_token": "{YOUR_ACCESS_TOKEN}",
        "scope": "cdp.audience_exports:r",
        "expires_in": 86400,
        "token_type": "Bearer"
      }
    ```

    Access tokens expire in 24 hours. If your requests unexpectedly return a
    response with status `401 Unauthorized`, request a new access token by
    repeating this `POST` request.


    We recommend that you cache the access token for 24 hours to avoid repeating
    this `POST` request while the access token is still valid.

    ### Include the access token in the request header

    You can now start making REST API requests. You must include the access
    token in the request header of every request. For example:

      ```curl
      curl -X GET '{YOUR_BASE_URL}/v2/...' \
      -H 'Authorization: Bearer {YOUR_ACCESS_TOKEN}' \
      -H 'Accept: application/json'
      ```
  contact:
    name: Sitecore Corporation A/S
  license:
    name: Apache 2.0
    url: https://www.apache.org/licenses/LICENSE-2.0
  version: v2
  x-metadata:
    product: CDP
security:
  - BearerToken: []
servers:
  - url: https://api-engage-ap.sitecorecloud.io
    description: Production server AP
  - url: https://api-engage-eu.sitecorecloud.io
    description: Production server EU
  - url: https://api-engage-jpe.sitecorecloud.io
    description: Production server JP
  - url: https://api-engage-us.sitecorecloud.io
    description: Production server US
tags:
  - name: Most recent export job
    description: Access output URLs for the most recently finished export job.
  - name: Any export job
    description: >-
      You can access output URLs for any finished export job by making two API
      requests. First retrieve a list of all finished export jobs of an audience
      export, then retrieve the output URLs for the finished export job of your
      choice.
paths:
  /v2/audienceExports/definitions/{audienceExportRef}/reports:
    get:
      tags:
        - Any export job
      summary: Retrieve a list of all finished export jobs
      description: >-
        Retrieves a list of all finished export jobs of an audience export.


        In the response, in every object in the array, the `executionRef` key
        contains the export job reference. You use the export job reference to
        retrieve the output URLs for that specific export job.
      operationId: RetrieveFinishedExportJobs
      parameters:
        - name: audienceExportRef
          in: path
          required: true
          schema:
            type: string
            description: >-
              The audience export reference.

              Set this value either to the friendly ID or the UUID reference of
              the audience export.


              To find these values in Sitecore CDP, click **Audience export** >
              **Audience export**, then the export you want to work with. The
              friendly ID is on the **Details** pane. The UUID reference is a
              36-character string in the web browser's address bar, starting
              after `audience-export/`.


              Example friendly ID: `daily_loyalty_members`

              Example UUID reference: `d6c5335a-4028-49c0-8d55-a534e89127c9` 
            example: daily_loyalty_members
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ExecutionReportName'
        '401':
          description: Unauthorized request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthorizedResponse'
  /v2/audienceExports/definitions/{audienceExportRef}/latestExport:
    get:
      tags:
        - Most recent export job
      summary: Retrieve output URLs for the most recent export job
      description: >-
        Retrieves the presigned URLs where you can download the outputs of the
        most recently finished export job.


        In the response, in every object in the `exports` array, the `url` key
        contains the output URL.


        The URLs expire after a limited time. In the response, the `expireAt`
        key contains the expiration time. If you don't download the output
        before the URLs expire, you have to repeat this request to renew the
        URLs.
      operationId: RetrieveURLsOfMostRecentExportJob
      parameters:
        - name: audienceExportRef
          in: path
          required: true
          schema:
            type: string
            description: >-
              The audience export reference.

              Set this value either to the friendly ID or the UUID reference of
              the audience export.


              To find these values in Sitecore CDP, click **Audience export** >
              **Audience export**, then the export you want to work with. The
              friendly ID is on the **Details** pane. The UUID reference is a
              36-character string in the web browser's address bar, starting
              after `audience-export/`.


              Example friendly ID: `daily_loyalty_members`

               Example UUID reference: `d6c5335a-4028-49c0-8d55-a534e89127c9` 
            example: daily_loyalty_members
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExportFileListingName'
        '401':
          description: Unauthorized request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthorizedResponse'
  /v2/audienceExports/executions/{jobExecutionRef}/export:
    get:
      tags:
        - Any export job
      summary: Retrieve output URLs for a specific export job
      description: >-
        Retrieves the presigned URLs where you can download the outputs of the
        export job of your choice.


        In the response, in every object in the `exports` array, the `url` key
        contains the output URL.


        The URLs expire after a limited time. In the response, the `expireAt`
        key contains the expiration time. If you don't download the output
        before the URLs expire, you have to repeat this request to renew the
        URLs.
      operationId: RetrieveURLsOfSpecificExportJob
      parameters:
        - name: jobExecutionRef
          in: path
          required: true
          schema:
            type: string
            description: >-
              The export job reference.


              If you don't know the export job reference, first retrieve a list
              of all finished export jobs. In the response, the `executionRef`
              key contains the export job reference.
            example: fe351e84-3504-4668-8e5f-574d320b9679
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExportFileListingName'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BadRequestResponse'
        '401':
          description: Unauthorized request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthorizedResponse'
components:
  schemas:
    ExecutionReportName:
      type: object
      properties:
        clientKey:
          type: string
          description: Your organization's unique and public identifier.
          example: pqsPERS3lw12v5a9rrHPW1c4hET73GxQ
        executionRef:
          type: string
          description: >-
            The export job reference.


            Use this as the `jobExecutionRef` path parameter when you retrieve
            output URLs for a specific export job.
          format: uuid
          example: fe351e84-3504-4668-8e5f-574d320b9679
        definitionRef:
          type: string
          description: The UUID reference of the audience export.
          format: uuid
          example: d6c5335a-4028-49c0-8d55-a534e89127c9
        friendlyId:
          type: string
          description: |-
            The unique ID of the audience export.

            Only lowercase alphanumeric characters and underscores are allowed.
          example: daily_loyalty_members
        executionType:
          type: string
          description: Whether the audience export runs instantly or on a schedule.
          example: INSTANT_RUN
          enum:
            - INSTANT_RUN
            - SCHEDULED
        status:
          type: string
          description: The status of the export job.
          example: SUCCESS
          enum:
            - PENDING_GUEST_CONTEXT
            - PENDING_SEGMENTATION
            - PENDING_EMR_SUBMIT
            - PENDING_EMR_JOB
            - SUCCESS
            - FAILED
            - ALERT
        definitionType:
          type: string
          description: Whether the audience export is a full or a delta export.
          example: FULL_SYNC
          enum:
            - DELTA
            - FULL_SYNC
        segmentExecutionType:
          type: string
          description: Whether the segment in the audience export is scheduled or live.
          example: LIVE
          enum:
            - ON_DEMAND
            - LIVE
        total:
          type: integer
          description: The number of guests in the segment selected for the export.
          format: int32
          example: 101308
        filterMatchedGuests:
          type: integer
          description: >-
            The number of guests matched by the filter. These guests are
            included in the export. If no filter was used, the value is 0.
          format: int32
          example: 97466
        filterNotMatchedGuests:
          type: integer
          description: >-
            The number of guests not matched by the filter. These guests are
            excluded from the export. If no filter was used, the value is 0.
          format: int32
          example: 3842
        filterFailures:
          type: integer
          description: >-
            The number of guests that filtering failed for. If no filter was
            used, the value is 0.
          format: int32
          example: 16
        successes:
          type: integer
          description: The number of guests the export succeeded for.
          format: int32
          example: 97466
        failures:
          type: integer
          description: The number of guests the export failed for.
          format: int32
          example: 0
        programmableErrors:
          type: array
          description: >-
            A list of errors related to the JavaScript in the export and the
            attribute values in the output structure.
          items:
            $ref: '#/components/schemas/Errors'
        filterErrors:
          type: array
          description: >-
            A list of errors related to conditions, for example, errors with the
            JavaScript in a condition.
          items:
            $ref: '#/components/schemas/Errors'
        errorLogs:
          type: array
          description: A list of all errors.
          example: '[TypeError: Cannot read property ''length'' of undefined]'
          items:
            type: string
            description: A list of all errors.
            example: '[TypeError: Cannot read property ''length'' of undefined]'
        datasetDate:
          type: string
          description: The date the export job started running.
          example: 2024/10/16
        startTime:
          type: string
          description: The UTC time the export job started running.
          format: date-time
          example: '2024-10-16T06:00:01.122Z'
        endTime:
          type: string
          description: The UTC time the export job finished running.
          format: date-time
          example: '2024-10-16T06:40:45.794Z'
        successAdd:
          type: integer
          description: >-
            Guests added to the segment after the export job ran. This attribute
            is only present in delta exports.
          format: int32
          example: 0
        successRemove:
          type: integer
          description: >-
            Guests removed from the segment after the export job ran. This
            attribute is only present in delta exports.
          format: int32
          example: 0
      description: ExecutionReportDescription
    Errors:
      type: object
      properties:
        description:
          type: string
          description: Error description.
          example: 'TypeError: Cannot read property ''length'' of undefined'
        count:
          type: integer
          description: The number of times this error occurred.
          format: int32
          example: 16
      description: A list of errors.
    BadRequestResponse:
      type: object
      properties:
        status:
          type: integer
          description: The HTTP request status.
          format: int32
          example: 400
        code:
          type: integer
          description: The HTTP response status code.
          format: int32
          example: 400
        message:
          type: string
          description: Error description.
          example: Bad request.
        developerMessage:
          type: string
          description: Error description for developers.
          example: Attribute path param ref not a valid UUID.
        moreInfoUrl:
          type: string
          description: URL to get more information about the error.
          example: 'Contact Sitecore support here: https://support.sitecore.com'
    UnauthorizedResponse:
      type: object
      properties:
        status:
          type: string
          description: The HTTP request status.
          format: uppercase
          example: UNAUTHORIZED
        code:
          type: integer
          description: The HTTP response status code.
          format: int32
          example: 401
        message:
          type: string
          description: Error description.
          example: >-
            Authentication credentials are required to access the resource. All
            requests must be authenticated.
        moreInfoUrl:
          type: string
          description: URL to get more information about the error.
          example: 'Contact Sitecore support here: https://support.sitecore.com'
    ExportFileListingName:
      type: object
      properties:
        executionRef:
          type: string
          description: >-
            The export job reference.


            Use this as the `jobExecutionRef` path parameter when you retrieve
            output URLs for a specific export job.
          format: uuid
          example: fe351e84-3504-4668-8e5f-574d320b9679
        definitionRef:
          type: string
          description: The UUID reference of the audience export.
          format: uuid
          example: d6c5335a-4028-49c0-8d55-a534e89127c9
        friendlyId:
          type: string
          description: |-
            The unique ID of the audience export.

            Only lowercase alphanumeric characters and underscores are allowed.
          example: daily_loyalty_members
        clientKey:
          type: string
          description: Your organization's unique and public identifier.
          example: pqsPERS3lw12v5a9rrHPW1c4hET73GxQ
        expireAt:
          type: string
          description: The UTC date and time the output URLs expire.
          format: date-time
          example: '2024-11-05T12:08:00.145Z'
        numberOfFiles:
          type: integer
          description: The total number of files included in the output.
          format: int32
          example: 2
        totalSizeKB:
          type: integer
          description: The total size of all the output files in kilobytes.
          format: int64
          example: 54
        exports:
          type: array
          description: A list of all the presigned output URLs for the export job.
          items:
            $ref: '#/components/schemas/exports'
      description: ExportFileListing
    exports:
      type: object
      properties:
        url:
          type: string
          description: The presigned output URL for the export job.
          example: https://sitecore-cdp-...
        sizeKB:
          type: integer
          description: The size of the output file in kilobytes.
          format: int64
          example: 52
        deltaAction:
          type: string
          description: >-
            Whether the presigned output URL of a delta export contains the
            added guests or the removed guests.


            This attribute is only present in delta exports.
          example: add
          enum:
            - add
            - remove
      description: A list of all the presigned output URLs for the export job.
  securitySchemes:
    BearerToken:
      type: http
      scheme: bearer
      bearerFormat: JWT
x-logo:
  altText: Audience export REST API
  url: https://content-search-api-doc.rfksrv.com/logo.png
