openapi: 3.0.1 info: title: Sitecore CDP Audience export REST 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. To authorize your requests: 1. Create an API key. 2. Request an access token using the API key. 3. Include the access token in the request header. ### 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: Sitecore CDP security: - BearerToken: [] servers: - url: https://api-engage-ap.sitecorecloud.io description: Production server AP variables: {} - url: https://api-engage-eu.sitecorecloud.io description: Production server EU variables: {} - url: https://api-engage-jpe.sitecorecloud.io description: Production server JP variables: {} - url: https://api-engage-us.sitecorecloud.io description: Production server US variables: {} 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