openapi: 3.1.0
info:
  title: Agency API — Reports
  version: '3.0'
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.
- name: Reports (Legacy)
  description: Legacy synchronous reports endpoint. Subject to pagination limits — prefer `ReportExport` for large datasets.
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: */*'"
  /Agencies/{AccountSID}/Reports:
    get:
      operationId: listAllReports
      summary: List all reports
      description: Returns the full catalog of reports available to your agency. Each report record indicates whether it is runnable via the API and exposes the URIs to run it synchronously (`ApiRunUri`), export it asynchronously (`DeferredApiRunUri`), or fetch its metadata (`MetaDataUri`).
      tags:
      - Reports (Legacy)
      parameters:
      - name: AccountSID
        in: path
        required: true
        description: Your Agency Account SID.
        schema:
          type: string
        example: IRq8mWJybvoQ1020978kbj7am8zzM2dBL1
      responses:
        '200':
          description: A list of report definitions.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Report'
              example:
              - Name: Action Listing
                Id: agency_action_listing
                Category: Performance
                Description: Displays data for each individual action that has been credited to your media.
                ApiAccessible: true
                ApiRunUri: /Agencies/IRq8mWJybvoQ1020978kbj7am8zzM2dBL1/Reports/agency_action_listing
                DeferredApiRunUri: /Agencies/IRq8mWJybvoQ1020978kbj7am8zzM2dBL1/ReportExport/agency_action_listing
                MetaDataUri: /Agencies/IRq8mWJybvoQ1020978kbj7am8zzM2dBL1/Reports/agency_action_listing/MetaData
        '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}/Reports' \\\n  --user '{AccountSID}:{AuthToken}' \\\n  --header 'Accept: */*'"
  /Agencies/{AccountSID}/Reports/{ReportId}:
    get:
      operationId: runReport
      summary: Run a report
      description: 'Runs a report and returns the records synchronously.


        > **Legacy endpoint.** This endpoint has pagination limits and may be rate-limited or capped on result size. For large datasets, use `GET /ReportExport/{ReportId}` instead, which schedules an asynchronous job and produces a downloadable result file.


        ## Page size is fixed


        As of October 2023, `/Reports` enforces a fixed `PageSize` of **20,000 records** per response. Any `PageSize` value you pass is silently overridden. For larger datasets, use `ReportExport`.


        ## Record values are returned as JSON strings


        All record field values are returned as JSON strings, even when the report''s metadata declares them as `Decimal`, `Integer`, `Boolean`, or `Date`. For example, a `Decimal` field returns `"5.000000000000000000"` (string), not `5.0` (number). Cast on the client side as needed — use `MetaData.Attributes[].DataType` to know the intended type.


        ## Filter parameters


        Filter parameters vary per report — call `GET /Reports/{ReportId}/MetaData` to discover which are supported. Convert each filter `Name` to uppercase with underscores (`"Start Date"` → `START_DATE`) when passing as a query parameter.'
      tags:
      - Reports (Legacy)
      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 run.
        schema:
          type: string
        example: agency_action_listing
      - 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.
        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.
        schema:
          type: string
          format: date
        example: '2026-05-29'
      - name: SUBAID
        in: query
        required: false
        description: A program (campaign) ID to refine the report.
        schema:
          type: string
      - name: RQueryIDx
        in: query
        required: false
        description: For reports with multiple result tables, selects which table to return (0-indexed).
        schema:
          type: integer
          default: 0
      responses:
        '200':
          description: '**Success** — a list of report record objects. Each record''s field set depends on the report — refer to `MetaData.Attributes` for column descriptions.


            **Error** — invalid input is returned as HTTP 200 with an error envelope (`{"Status":"ERROR","Message":"..."}`). Always check the `Status` field.'
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  additionalProperties: true
                  description: A single report record. Field names match the report's `MetaData.Attributes`.
        '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}/Reports/{ReportId}' \\\n  --user '{AccountSID}:{AuthToken}' \\\n  --header 'Accept: */*'"
  /Agencies/{AccountSID}/Reports/{ReportId}/MetaData:
    get:
      operationId: getReportMetadata
      summary: Get report metadata
      description: Returns the metadata for a single report — its filters (input parameters) and attributes (output columns). Use this to discover which query parameters a report accepts before running or exporting it.
      tags:
      - Reports (Legacy)
      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 whose metadata to retrieve.
        schema:
          type: string
        example: agency_action_listing
      responses:
        '200':
          description: The metadata object for the requested report.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReportMetadata'
        '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}/Reports/{ReportId}/MetaData' \\\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
    Report:
      type: object
      description: A single report definition in the report catalog.
      properties:
        Name:
          type: string
          description: The human-readable name of the report.
          example: Action Listing
        Id:
          type: string
          description: The unique identifier of the report on impact.com. Use this as the `ReportId` path parameter when running or exporting the report. May not be present for some web-only reports.
          example: agency_action_listing
        Category:
          type: string
          description: 'The category the report belongs to. Categories group reports by purpose in the impact.com UI.


            Additional categories may exist beyond the values listed below.'
          enum:
          - Admin
          - Beta
          - Compliance
          - Cross-Program
          - Custom
          - Finance
          - Insights
          - Listing
          - Operations
          - Partner
          - Performance
          example: Performance
        Description:
          type: string
          description: A short explanation of the data this report shows.
          example: Displays data for each individual action that has been credited to your media.
        ApiAccessible:
          type: boolean
          description: Whether this report can be run via the API. When `false`, only `RunUri` (web app URL) is populated; the report can only be run from the impact.com UI.
          example: true
        ApiRunUri:
          type: string
          format: uri-reference
          description: The relative URI to run the report synchronously via the legacy `GET /Reports/{ReportId}` endpoint. Present when `ApiAccessible` is `true`.
          example: /Agencies/IRq8mWJybvoQ1020978kbj7am8zzM2dBL1/Reports/agency_action_listing
        DeferredApiRunUri:
          type: string
          format: uri-reference
          description: 'The relative URI to export the report asynchronously via the `GET /ReportExport/{ReportId}` endpoint. Present when `ApiAccessible` is `true`.


            **Recommended** over `ApiRunUri` for any non-trivial report.'
          example: /Agencies/IRq8mWJybvoQ1020978kbj7am8zzM2dBL1/ReportExport/agency_action_listing
        MetaDataUri:
          type: string
          format: uri-reference
          description: The relative URI to retrieve the report's metadata (filters and attributes). Present when `ApiAccessible` is `true`.
          example: /Agencies/IRq8mWJybvoQ1020978kbj7am8zzM2dBL1/Reports/agency_action_listing/MetaData
        RunUri:
          type: string
          format: uri-reference
          description: The relative URI to run the report in the impact.com web app. Present when `ApiAccessible` is `false` — these reports cannot be run via API.
          example: /secure/agency/report/viewReport.report?id=8019
    ReportMetadata:
      type: object
      description: Metadata describing a single report's accepted filters (input parameters) and returned attributes (output columns).
      properties:
        Name:
          type: string
          description: The human-readable name of the report.
          example: Action Listing
        Id:
          type: string
          description: The unique identifier of the report on impact.com.
          example: agency_action_listing
        Description:
          type: string
          description: A short explanation of the data this report shows.
        Filters:
          type: array
          description: The filter parameters this report accepts as query parameters. Filter names from this list (uppercased with underscores, e.g., `Start Date` → `START_DATE`) are passed as query parameters to the `Reports/{ReportId}` or `ReportExport/{ReportId}` endpoints.
          items:
            $ref: '#/components/schemas/ReportFilter'
        Attributes:
          type: array
          description: The output columns this report returns. Each entry describes one field of each record in the report results.
          items:
            $ref: '#/components/schemas/ReportAttribute'
        RunUri:
          type: string
          format: uri-reference
          description: The relative URI to run the report.
        Uri:
          type: string
          format: uri-reference
          description: The relative URI of this metadata resource.
    ReportFilter:
      type: object
      description: A single filter parameter that a report accepts.
      properties:
        Name:
          type: string
          description: The display name of the filter as shown in the impact.com UI (e.g., `"Start Date"`). When passing the filter as a query parameter, convert it to uppercase with underscores in place of spaces — `"Start Date"` becomes `START_DATE`.
          example: Start Date
        DataType:
          type: string
          description: The data type the filter accepts.
          enum:
          - Boolean
          - Date (yyyy-MM-dd'T'HH:mm:ssZZ)
          - Decimal
          - Integer
          - String
          example: String
        Format:
          type: string
          description: An optional input format constraint. When empty, no specific format is enforced beyond the data type.
          enum:
          - yyyy-MM-dd
          - ''
          example: ''
    ReportAttribute:
      type: object
      description: A single output column that a report returns.
      properties:
        Name:
          type: string
          description: The field name as it appears in the report records.
          example: ActionId
        DataType:
          type: string
          description: The data type of this field.
          enum:
          - Boolean
          - Date (yyyy-MM-dd'T'HH:mm:ssZZ)
          - Decimal
          - Integer
          - String
          example: String
        Description:
          type: string
          description: A short description of what this field represents. May be empty.
          example: ''
    ErrorResponse:
      type: object
      description: Error envelope returned with HTTP 200 when a request is invalid. The Reports and ReportExport endpoints do not use 4xx status codes — always check the `Status` field on every response.
      properties:
        Status:
          type: string
          description: Returns `ERROR` on a failed request.
          enum:
          - ERROR
          example: ERROR
        Message:
          type: string
          description: Human-readable description of the error.
          example: Invalid result format. Must be one of CSV, JSON or XML
x-default-client: cURL