openapi: 3.2.0
info:
  title: Agency API — Reports Report Export API
  version: '3.0'
  description: Asynchronously export reports through impact.com's Jobs system. Recommended for all report downloads.
servers:
- url: https://api.impact.com
  description: Production
tags:
- name: ReportExport
  description: Asynchronously export reports through impact.com's Jobs system. Recommended for all report downloads.
paths:
  /Agencies/{AccountSID}/ReportExport/{ReportId}:
    get:
      operationId: exportReport
      summary: Export a report
      description: 'Schedules a report to be exported asynchronously through impact.com''s Jobs system. Returns immediately with the initial job status and three URIs to interact with the job.


        Use the returned `QueuedUri` to poll job status, `ResultUri` to download the result file once the job has completed, and `ReplayUri` to re-run the same job.


        ## Available query parameters


        - `ResultFormat` — output file format (universal).

        - Report-specific filters — every report accepts its own set of filter parameters (`START_DATE`, `END_DATE`, `SUBAID`, `Advertiser`, etc.). Call `GET /Reports/{ReportId}/MetaData` first to discover which filters a given report supports.


        ## Error handling


        Invalid input is returned as **HTTP 200** with an error envelope in the body — for example, an unknown `ReportId` returns `{"Status":"ERROR","Message":"Not permitted to run report ..."}`. Always check the `Status` field before treating the response as a queued job.'
      tags:
      - ReportExport
      parameters:
      - name: AccountSID
        in: path
        required: true
        description: Your Agency Account SID.
        schema:
          type: string
        example: IRq8mWJybvoQ1020978kbj7am8zzM2dBL1
      - name: ReportId
        in: path
        required: true
        description: The unique ID of the report to export. Use `GET /Reports` to list all reports and find each report's `Id`.
        schema:
          type: string
        example: agency_action_listing
      - name: ResultFormat
        in: query
        required: false
        description: The file format the exported report should be returned in.
        schema:
          type: string
          enum:
          - CSV
          - JSON
          - XML
          default: CSV
        example: CSV
      - name: START_DATE
        in: query
        required: false
        description: The start date (inclusive) for the report data, in `YYYY-MM-DD` format. Required by most reports — check the report's `MetaData` to confirm.
        schema:
          type: string
          format: date
        example: '2026-05-01'
      - name: END_DATE
        in: query
        required: false
        description: The end date (inclusive) for the report data, in `YYYY-MM-DD` format. Required by most reports — check the report's `MetaData` to confirm.
        schema:
          type: string
          format: date
        example: '2026-05-29'
      - name: SUBAID
        in: query
        required: false
        description: A program (campaign) ID to refine the report to data from a single program. Required for some reports.
        schema:
          type: string
        example: '12345'
      responses:
        '200':
          description: '**Success** — the export job was queued. Response includes URIs for polling and downloading the result.


            **Error** — invalid input (e.g., bad `ReportId`, unrecognised `ResultFormat`, invalid date) returns the same HTTP 200 status with an error envelope. See the `ErrorResponse` schema and the operation description.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReportExportResponse'
              example:
                Status: QUEUED
                QueuedUri: /Agencies/IRq8mWJybvoQ1020978kbj7am8zzM2dBL1/Jobs/8ef45463-8b0b-499f-8cdc-8d6e4c2a8c12
                ResultUri: /Agencies/IRq8mWJybvoQ1020978kbj7am8zzM2dBL1/Jobs/8ef45463-8b0b-499f-8cdc-8d6e4c2a8c12/Download
                ReplayUri: /Agencies/IRq8mWJybvoQ1020978kbj7am8zzM2dBL1/Jobs/8ef45463-8b0b-499f-8cdc-8d6e4c2a8c12/Replay
        '401':
          description: Unauthorized. Check that your Account SID and Auth Token are correct.
      x-codeSamples:
      - lang: Shell
        label: curl
        source: "curl -L \\\n  --url 'https://api.impact.com/Agencies/{AccountSID}/ReportExport/{ReportId}' \\\n  --user '{AccountSID}:{AuthToken}' \\\n  --header 'Accept: */*'"
components:
  schemas:
    ReportExportResponse:
      type: object
      description: 'Job-handle response returned from the ReportExport endpoint. The export runs asynchronously through impact.com''s Jobs system; use the URIs in this response to track and retrieve the result.


        On invalid input the API returns the same HTTP 200 with an `ErrorResponse` envelope instead — check the `Status` field.'
      properties:
        Status:
          type: string
          description: The initial status of the export job. Returns `QUEUED` on successful submission, or `ERROR` if the request was invalid (in which case a `Message` field will be populated instead of the URIs).
          enum:
          - QUEUED
          - ERROR
          example: QUEUED
        QueuedUri:
          type: string
          format: uri-reference
          description: The relative URI of the underlying job. Use it (or its trailing job ID) with the Jobs API to poll for status updates.
          example: /Agencies/IRq8mWJybvoQ1020978kbj7am8zzM2dBL1/Jobs/8ef45463-8b0b-499f-8cdc-8d6e4c2a8c12
        ResultUri:
          type: string
          format: uri-reference
          description: The relative URI to download the exported result file. Available once the job completes — calling it before completion returns the job status, not the file.
          example: /Agencies/IRq8mWJybvoQ1020978kbj7am8zzM2dBL1/Jobs/8ef45463-8b0b-499f-8cdc-8d6e4c2a8c12/Download
        ReplayUri:
          type: string
          format: uri-reference
          description: The relative URI to re-run the same export with the same parameters. Useful for retrying failed jobs without re-specifying inputs.
          example: /Agencies/IRq8mWJybvoQ1020978kbj7am8zzM2dBL1/Jobs/8ef45463-8b0b-499f-8cdc-8d6e4c2a8c12/Replay
        Message:
          type: string
          description: A human-readable error description. Only present when `Status` is `ERROR`.
          example: Not permitted to run report nonexistent_report
x-default-client: cURL