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 \
              --url 'https://api.impact.com/Agencies/{AccountSID}/ReportExport/{ReportId}' \
              --user '{AccountSID}:{AuthToken}' \
              --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 \
              --url 'https://api.impact.com/Agencies/{AccountSID}/Reports' \
              --user '{AccountSID}:{AuthToken}' \
              --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 \
              --url 'https://api.impact.com/Agencies/{AccountSID}/Reports/{ReportId}' \
              --user '{AccountSID}:{AuthToken}' \
              --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 \
              --url 'https://api.impact.com/Agencies/{AccountSID}/Reports/{ReportId}/MetaData' \
              --user '{AccountSID}:{AuthToken}' \
              --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
