Choozle Reports API

openapi: 3.0.3
info:
  title: Choozle Reporting Reports API
  description: 'REST API for retrieving Choozle advertising account structure (accounts, campaigns, ad
    groups) and daily campaign performance reports. Authentication is an HMAC-SHA256 signed exchange at
    POST /api/auth that returns a token valid for two hours; the token is then sent as a `token` request
    header on every reporting call.


    This document is transcribed from Choozle''s own published apiDoc dataset at https://app.choozle.com/apidoc/api_data.json
    (saved verbatim alongside this file as choozle-apidoc-api_data.json) and verified against live unauthenticated
    probes of the production host on 2026-08-13.

    '
  version: 1.0.0
  contact:
    name: Choozle Support
    url: https://help.choozle.com/
  termsOfService: https://choozle.com/terms-of-service/
externalDocs:
  description: Choozle API Docs (apiDoc)
  url: https://app.choozle.com/apidoc/
servers:
- url: https://app.choozle.com/api
  description: Choozle production API
security:
- tokenHeader: []
tags:
- name: Reports
paths:
  /reports:
    get:
      operationId: getReports
      summary: Get Reports
      description: 'Returns an array of reports for the given filters. There is one report per active
        ad group per day; if no reports were recorded for an ad group on a particular day, that report
        is omitted.


        `campaign_id` cannot be combined with `campaign_status`. `ad_group_id` cannot be combined with
        `campaign_id` or `campaign_status`, and accepts one or more comma-separated ids.

        '
      tags:
      - Reports
      parameters:
      - $ref: '#/components/parameters/TokenHeader'
      - name: account_id
        in: query
        required: true
        description: The account to report on.
        schema:
          type: integer
          example: 8737
      - name: date_start
        in: query
        required: false
        description: 'Beginning of the date range (inclusive), ISO 8601 date, e.g. 2015-05-04. If used
          without date_end, returns valid reports after and including date_start.

          '
        schema:
          type: string
          format: date
          example: '2017-12-11'
      - name: date_end
        in: query
        required: false
        description: 'End of the date range (inclusive), ISO 8601 date, e.g. 2015-05-04. If used without
          date_start, returns valid reports before and including date_end.

          '
        schema:
          type: string
          format: date
          example: '2017-12-11'
      - name: campaign_id
        in: query
        required: false
        description: Filter to one campaign. Cannot be combined with campaign_status.
        schema:
          type: integer
          example: 15
      - name: campaign_status
        in: query
        required: false
        description: Filter by campaign status. Cannot be combined with campaign_id.
        schema:
          type: string
          enum:
          - all
          - active
          - inactive
          - archived
      - name: ad_group_id
        in: query
        required: false
        description: 'Filter to one or more ad groups, comma separated. Cannot be combined with campaign_id
          or campaign_status.

          '
        schema:
          type: string
          example: 42506,42507,42508,41194
      responses:
        '200':
          description: Daily per-ad-group performance rows for the requested filters.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ReportRow'
              example:
              - date: '2014-12-02'
                account_id: '1'
                account_name: Acme
                campaign_id: '15'
                campaign_name: Campaign 1
                ad_group_id: '154'
                ad_group_name: Ad Group 1
                advertiser_cost: 0
                impressions_won: 3
                win: 0
                cpm: 0
                cpc: 0
                ctr: 0
                cpa: 0
                clicks: 0
                impressions_bid_on: 0
                conversions: 0
        '401':
          description: Unauthorized — no token found in the request, or the request token is expired.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error: Unauthorized - Request token is expired.
components:
  parameters:
    TokenHeader:
      name: token
      in: header
      required: true
      description: Authentication token generated from the /api/auth endpoint.
      schema:
        type: string
  schemas:
    Error:
      type: object
      description: 'Choozle''s error envelope. A single `error` string; not RFC 9457 problem+json.

        '
      properties:
        error:
          type: string
          example: Unauthorized - No Token Found in request
    ReportRow:
      type: object
      description: One day of performance for one ad group.
      properties:
        date:
          type: string
          format: date
          example: '2014-12-02'
        account_id:
          type: string
          example: '1'
        account_name:
          type: string
          example: Acme
        campaign_id:
          type: string
          example: '15'
        campaign_name:
          type: string
          example: Campaign 1
        ad_group_id:
          type: string
          example: '154'
        ad_group_name:
          type: string
          example: Ad Group 1
        advertiser_cost:
          type: number
          description: Advertiser cost for the day.
        impressions_won:
          type: integer
          description: Impressions won.
        win:
          type: number
          description: Win rate.
        cpm:
          type: number
        cpc:
          type: number
        ctr:
          type: number
        cpa:
          type: number
        clicks:
          type: integer
        impressions_bid_on:
          type: integer
        conversions:
          type: integer
  securitySchemes:
    tokenHeader:
      type: apiKey
      in: header
      name: token
      description: 'Authentication token generated from the /api/auth endpoint. Valid for two hours from
        creation. Pass the token value as the `token` request header on every reporting call.

        '