openapi: 3.1.0
info:
  title: Brand API - Reports
  description: API for discovering available reports and exporting report data, either synchronously or asynchronously via the Jobs endpoint.
  version: v12
servers:
- url: https://api.impact.com
security:
- basicAuth: []
paths:
  /Advertisers/{AccountSID}/Reports:
    get:
      summary: List All Available Reports
      description: Retrieves a list of all reports available to your account, indicating whether they can be run via the API.
      operationId: listReports
      tags:
      - Reports
      parameters:
      - name: AccountSID
        in: path
        required: true
        schema:
          type: string
        description: Your unique Account SID.
      responses:
        '200':
          description: A paginated list of report metadata objects.
          content:
            application/json:
              schema:
                type: object
                properties:
                  Reports:
                    type: array
                    description: The list of report objects.
                    items:
                      $ref: '#/components/schemas/ReportInfo'
      x-codeSamples:
      - lang: cURL
        source: |-
          curl -L \
            --url 'https://api.impact.com/Advertisers/{AccountSID}/Reports' \
            --user '{AccountSID}:{AuthToken}' \
            --header 'Accept: */*'
  /Advertisers/{AccountSID}/Reports/{ReportId}:
    get:
      summary: Run a Report Synchronously
      description: |-
        Runs a report and returns the data directly in the response.
        The required filter parameters (like `SUBAID`, `StartDate`, `EndDate`) depend on the specific report being run.
        Retrieve the report's metadata to see all available filters.
      operationId: runReport
      tags:
      - Reports
      parameters:
      - name: AccountSID
        in: path
        required: true
        schema:
          type: string
      - name: ReportId
        in: path
        required: true
        schema:
          type: string
        description: The unique identifier of the report to run.
      - name: SUBAID
        in: query
        schema:
          type: integer
        description: Required for most reports. The ID of the program (campaign) to filter by.
      - name: StartDate
        in: query
        schema:
          type: string
          format: date
        description: Required for most reports. The start of the date range for the report data.
      - name: EndDate
        in: query
        schema:
          type: string
          format: date
        description: Required for most reports. The end of the date range for the report data.
      responses:
        '200':
          description: A paginated list of report records. The structure of each record depends on the report run.
          content:
            application/json:
              schema:
                type: object
                properties:
                  Records:
                    type: array
                    description: The records from the report.
                    items:
                      type: object
      x-codeSamples:
      - lang: cURL
        source: |-
          curl -L \
            --url 'https://api.impact.com/Advertisers/{AccountSID}/Reports/{ReportId}' \
            --user '{AccountSID}:{AuthToken}' \
            --header 'Accept: */*'
  /Advertisers/{AccountSID}/ReportExport/{ReportId}:
    get:
      summary: Export a Report Asynchronously
      description: |-
        Schedules a job to export a report as a file.
        Returns URIs to monitor the job's status and download the result.
      operationId: exportReport
      tags:
      - Reports
      parameters:
      - name: AccountSID
        in: path
        required: true
        schema:
          type: string
      - name: ReportId
        in: path
        required: true
        schema:
          type: string
        description: The unique identifier of the report to export.
      - name: SUBAID
        in: query
        schema:
          type: integer
        description: Required for most reports. The ID of the program (campaign).
      - name: StartDate
        in: query
        schema:
          type: string
          format: date-time
        description: Required for most reports. The start of the date range, as an ISO 8601 date-time (YYYY-MM-DDThh:mm:ssZ), e.g. 2026-01-15T00:00:00Z.
      - name: EndDate
        in: query
        schema:
          type: string
          format: date-time
        description: Required for most reports. The end of the date range, as an ISO 8601 date-time (YYYY-MM-DDThh:mm:ssZ), e.g. 2026-01-15T00:00:00Z.
      - name: ResultFormat
        in: query
        schema:
          type: string
          enum:
          - CSV
          - JSON
          - XML
          default: CSV
      responses:
        '200':
          description: The report export job was successfully queued.
          content:
            application/json:
              schema:
                type: object
                properties:
                  Status:
                    type: string
                    description: Indicates whether the job was queued successfully.
                    example: QUEUED
                  QueuedUri:
                    type: string
                    format: uri-reference
                    description: The URI to poll for the job's status.
                  ResultUri:
                    type: string
                    format: uri-reference
                    description: The URI to download the result file once the job completes.
      x-codeSamples:
      - lang: cURL
        source: |-
          curl -L \
            --url 'https://api.impact.com/Advertisers/{AccountSID}/ReportExport/{ReportId}' \
            --user '{AccountSID}:{AuthToken}' \
            --header 'Accept: */*'
  /Advertisers/{AccountSID}/Reports/{ReportId}/MetaData:
    get:
      summary: Retrieve Report Metadata
      description: Retrieves the dynamic documentation for a specific API-accessible report, including its available filters and attributes.
      operationId: getReportMetadata
      tags:
      - Reports
      parameters:
      - name: AccountSID
        in: path
        required: true
        schema:
          type: string
      - name: ReportId
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: A report metadata object.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReportMetadata'
      x-codeSamples:
      - lang: cURL
        source: |-
          curl -L \
            --url 'https://api.impact.com/Advertisers/{AccountSID}/Reports/{ReportId}/MetaData' \
            --user '{AccountSID}:{AuthToken}' \
            --header 'Accept: */*'
components:
  securitySchemes:
    basicAuth:
      type: http
      scheme: basic
      description: Use your AccountSID as the username and AuthToken as the password.
  schemas:
    ReportInfo:
      type: object
      description: General information about an available report.
      properties:
        Name:
          type: string
          description: The display name of the report.
          example: Action Listing
        Id:
          type: string
          description: The unique identifier or handle for the report.
          example: adv_action_listing_pm
        Category:
          type: string
          description: The category the report belongs to.
          example: Performance
        Description:
          type: string
          description: A description of what the report contains.
          example: Lists all actions for a date range.
        ApiAccessible:
          type: boolean
          description: Whether this report can be run via the API.
          example: true
        ApiRunUri:
          type: string
          format: uri-reference
          description: The URI to run this report synchronously.
          example: /Advertisers/<AccountSID>/Reports/adv_action_listing_pm
        DeferredApiRunUri:
          type: string
          format: uri-reference
          description: The URI to schedule this report as an asynchronous export job.
          example: /Advertisers/<AccountSID>/ReportExport/adv_action_listing_pm
        MetaDataUri:
          type: string
          format: uri-reference
          description: The URI to retrieve this report's metadata.
          example: /Advertisers/<AccountSID>/ReportsMetadata/adv_action_listing_pm
        RunUri:
          type: string
          format: uri-reference
          description: The URI to run this report in the impact.com platform.
          example: https://app.impact.com/secure/reports/run/adv_action_listing_pm
    ReportMetadata:
      type: object
      description: Dynamic documentation for a specific report, detailing its filters and attributes.
      properties:
        Name:
          type: string
          description: The display name of the report.
          example: Action Listing
        Id:
          type: string
          description: The unique identifier or handle for the report.
          example: adv_action_listing_pm
        Description:
          type: string
          description: A description of what the report contains.
          example: Lists all actions for a date range.
        Filters:
          type: array
          description: The filter parameters available when running the report.
          items:
            $ref: '#/components/schemas/ReportFilter'
        Attributes:
          type: array
          description: The attributes (columns) returned by the report.
          items:
            $ref: '#/components/schemas/ReportAttribute'
        RunUri:
          type: string
          format: uri-reference
          description: The URI to run this report.
          example: /Advertisers/<AccountSID>/Reports/adv_action_listing_pm
        Uri:
          type: string
          format: uri-reference
          description: The unique reference to this metadata object in the impact.com API.
          example: /Advertisers/<AccountSID>/ReportsMetadata/adv_action_listing_pm
    ReportFilter:
      type: object
      properties:
        Name:
          type: string
          description: The filter parameter name.
          example: DEFAULT_MODEL
        DataType:
          type: string
          description: The data type of the filter (e.g., String, Integer, Date).
          example: String
        Format:
          type: string
          description: The expected format of the filter value, if applicable.
          example: ''
    ReportAttribute:
      type: object
      properties:
        Name:
          type: string
          description: The attribute name.
          example: ActionDate
        DataType:
          type: string
          description: The data type of the attribute.
          example: DATETIME
        Description:
          type: string
          description: A description of the attribute.
          example: Date the action occurred.
x-default-client: cURL
