openapi: 3.0.1
info:
  title: FirstPromoter Admin Commissions Reports API
  version: '2.0'
  description: REST API for managing affiliate programs, promoters, campaigns, referrals, rewards, and payouts in FirstPromoter. Supports pagination, filtering, and full CRUD operations across all affiliate program resources.
  contact:
    url: https://docs.firstpromoter.com
  license:
    name: Proprietary
    url: https://firstpromoter.com/terms
servers:
- url: https://api.firstpromoter.com/api/v2
  description: Production server
security:
- BearerAuth: []
tags:
- name: Reports
paths:
  /company/reports/overview:
    get:
      summary: Get reports for overview
      description: "Get reports for overview \n <Tip>**HTTP Request** <br/>`GET https://api.firstpromoter.com/api/v2/company/reports/overview`</Tip>"
      tags:
      - Reports
      parameters:
      - $ref: '#/components/parameters/AccountId'
      - name: columns
        in: query
        required: true
        schema:
          type: array
          items:
            type: string
            enum:
            - active_customers
            - monthly_churn
            - clicks_count
            - net_revenue_amount
            - revenue_amount
            - referrals_count
            - customers_count
            - sales_count
            - refunds_count
            - cancelled_customers_count
            - promoter_earnings_amount
            - non_link_customers
            - referrals_to_customers_cr
            - 3m_epc
            - 6m_epc
            - clicks_to_customers_cr
            - clicks_to_referrals_cr
            - promoter_paid_amount
            - signups_count
      - name: q
        in: query
        required: false
        schema:
          type: string
      - name: group_by
        in: query
        required: true
        schema:
          type: string
          enum:
          - day
          - week
          - month
          - year
      - name: start_date
        in: query
        required: true
        schema:
          type: string
          format: date-time
      - name: end_date
        in: query
        required: true
        schema:
          type: string
          format: date-time
      - name: sorting
        in: query
        required: false
        schema:
          type: object
          additionalProperties:
            type: string
            enum:
            - asc
            - desc
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    period:
                      type: string
                    id:
                      type: string
                    data:
                      type: object
                      properties:
                        revenue_amount:
                          type: number
                        net_revenue_amount:
                          type: number
                        promoter_earnings_amount:
                          type: number
                        customers_count:
                          type: integer
                        referrals_count:
                          type: integer
                        clicks_count:
                          type: integer
                        active_customers:
                          type: integer
                        3m_epc:
                          type: number
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                  code:
                    type: string
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                  code:
                    type: string
        '422':
          description: Unprocessable Entity
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                  code:
                    type: string
  /company/reports/campaigns:
    get:
      summary: Get reports for campaigns
      description: With this endpoint you can get the report data grouped by campaigns.<Tip>**HTTP Request** <br/>`GET https://api.firstpromoter.com/api/v2/company/reports/campaigns`</Tip>
      tags:
      - Reports
      parameters:
      - $ref: '#/components/parameters/AccountId'
      - name: columns
        in: query
        required: true
        schema:
          type: array
          items:
            type: string
            enum:
            - active_customers
            - monthly_churn
            - clicks_count
            - net_revenue_amount
            - revenue_amount
            - referrals_count
            - customers_count
            - sales_count
            - refunds_count
            - cancelled_customers_count
            - promoter_earnings_amount
            - non_link_customers
            - referrals_to_customers_cr
            - 3m_epc
            - 6m_epc
            - clicks_to_customers_cr
            - clicks_to_referrals_cr
            - promoter_paid_amount
            - signups_count
      - name: q
        in: query
        required: false
        schema:
          type: string
      - name: group_by
        in: query
        required: true
        schema:
          type: string
          enum:
          - day
          - week
          - month
          - year
      - name: start_date
        in: query
        required: true
        schema:
          type: string
          format: date-time
      - name: end_date
        in: query
        required: true
        schema:
          type: string
          format: date-time
      - name: sorting
        in: query
        required: false
        schema:
          type: object
          additionalProperties:
            type: string
            enum:
            - asc
            - desc
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    campaign:
                      type: object
                      properties:
                        id:
                          type: integer
                        name:
                          type: string
                        color:
                          type: string
                    id:
                      type: integer
                    data:
                      type: object
                      properties:
                        revenue_amount:
                          type: number
                        net_revenue_amount:
                          type: number
                        promoter_earnings_amount:
                          type: number
                        customers_count:
                          type: integer
                        referrals_count:
                          type: integer
                        clicks_count:
                          type: integer
                        active_customers:
                          type: integer
                        3m_epc:
                          type: number
                    sub_data:
                      type: array
                      items:
                        type: object
                        properties:
                          period:
                            type: string
                          id:
                            type: string
                          data:
                            type: object
                            properties:
                              revenue_amount:
                                type: number
                              net_revenue_amount:
                                type: number
                              promoter_earnings_amount:
                                type: number
                              customers_count:
                                type: integer
                              referrals_count:
                                type: integer
                              clicks_count:
                                type: integer
                              active_customers:
                                type: integer
                              3m_epc:
                                type: number
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                  code:
                    type: string
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                  code:
                    type: string
  /company/reports/promoters:
    get:
      summary: Get reports for promoters
      description: ' With this endpoint you can get the report data grouped by promoters.<Tip>**HTTP Request** <br/>`GET https://api.firstpromoter.com/api/v2/company/reports/promoters`</Tip>'
      tags:
      - Reports
      parameters:
      - $ref: '#/components/parameters/AccountId'
      - name: columns
        in: query
        required: true
        schema:
          type: array
          items:
            type: string
            enum:
            - active_customers
            - monthly_churn
            - clicks_count
            - net_revenue_amount
            - revenue_amount
            - referrals_count
            - customers_count
            - sales_count
            - refunds_count
            - cancelled_customers_count
            - promoter_earnings_amount
            - non_link_customers
            - referrals_to_customers_cr
            - 3m_epc
            - 6m_epc
            - clicks_to_customers_cr
            - clicks_to_referrals_cr
            - promoter_paid_amount
            - signups_count
        description: Fields to be included in the report
      - name: q
        in: query
        required: false
        schema:
          type: string
        description: Search query string
      - name: group_by
        in: query
        required: true
        schema:
          type: string
          enum:
          - day
          - week
          - month
          - year
        description: Time period grouping
      - name: start_date
        in: query
        required: true
        schema:
          type: string
          format: date-time
        description: Start date for the report period
      - name: end_date
        in: query
        required: true
        schema:
          type: string
          format: date-time
        description: End date for the report period
      - name: sorting
        in: query
        required: false
        schema:
          type: object
          additionalProperties:
            type: string
            enum:
            - asc
            - desc
        description: Sorting parameters
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    promoter:
                      type: object
                      properties:
                        id:
                          type: integer
                        email:
                          type: string
                          format: email
                        name:
                          type: string
                      required:
                      - id
                      - email
                      - name
                    id:
                      type: integer
                    data:
                      type: object
                      properties:
                        revenue_amount:
                          type: number
                        net_revenue_amount:
                          type: number
                        promoter_earnings_amount:
                          type: number
                        customers_count:
                          type: integer
                        referrals_count:
                          type: integer
                        clicks_count:
                          type: integer
                        active_customers:
                          type: integer
                        3m_epc:
                          type: number
                    sub_data:
                      type: array
                      items:
                        type: object
                        properties:
                          period:
                            type: string
                          id:
                            type: string
                          data:
                            type: object
                            properties:
                              revenue_amount:
                                type: number
                              net_revenue_amount:
                                type: number
                              promoter_earnings_amount:
                                type: number
                              customers_count:
                                type: integer
                              referrals_count:
                                type: integer
                              clicks_count:
                                type: integer
                              active_customers:
                                type: integer
                              3m_epc:
                                type: number
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Unauthorized
                  code:
                    type: string
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Invalid user type
                  code:
                    type: string
                    example: forbidden
        '422':
          description: Unprocessable Entity
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: 'param is missing or the value is empty: columns'
                  code:
                    type: string
                    example: invalid_params
  /company/reports/traffic_sources:
    get:
      summary: Get reports for traffic sources
      description: "With this endpoint you can get the report data grouped by traffic sources. \n <Tip>**HTTP Request** <br/>`GET https://api.firstpromoter.com/api/v2/company/reports/traffic_sources`</Tip>"
      tags:
      - Reports
      parameters:
      - $ref: '#/components/parameters/AccountId'
      - name: columns
        in: query
        required: true
        schema:
          type: array
          items:
            type: string
            enum:
            - clicks_count
            - revenue_amount
            - promoter_earnings_amount
            - referrals_count
            - customers_count
            - sales_count
            - refunds_count
            - cancelled_customers_count
            - referrals_to_customers_cr
            - clicks_to_customers_cr
            - clicks_to_referrals_cr
        description: Fields to be included in the report
      - name: q
        in: query
        required: false
        schema:
          type: string
        description: Search query string
      - name: group_by
        in: query
        required: true
        schema:
          type: string
          enum:
          - day
          - week
          - month
          - year
        description: Time period grouping
      - name: start_date
        in: query
        required: true
        schema:
          type: string
          format: date-time
        description: Start date for the report period
      - name: end_date
        in: query
        required: true
        schema:
          type: string
          format: date-time
        description: End date for the report period
      - name: sorting
        in: query
        required: false
        schema:
          type: object
          additionalProperties:
            type: string
            enum:
            - asc
            - desc
        description: Sorting parameters
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    source:
                      type: string
                    id:
                      type: string
                    data:
                      type: object
                      properties:
                        clicks_count:
                          type: integer
                        revenue_amount:
                          type: number
                        promoter_earnings_amount:
                          type: number
                        referrals_count:
                          type: integer
                        customers_count:
                          type: integer
                        sales_count:
                          type: integer
                        refunds_count:
                          type: integer
                        cancelled_customers_count:
                          type: integer
                        referrals_to_customers_cr:
                          type: number
                        clicks_to_customers_cr:
                          type: number
                        clicks_to_referrals_cr:
                          type: number
                    sub_data:
                      type: array
                      items:
                        type: object
                        properties:
                          period:
                            type: string
                          id:
                            type: string
                          data:
                            type: object
                            properties:
                              clicks_count:
                                type: integer
                              revenue_amount:
                                type: number
                              promoter_earnings_amount:
                                type: number
                              referrals_count:
                                type: integer
                              customers_count:
                                type: integer
                              sales_count:
                                type: integer
                              refunds_count:
                                type: integer
                              cancelled_customers_count:
                                type: integer
                              referrals_to_customers_cr:
                                type: number
                              clicks_to_customers_cr:
                                type: number
                              clicks_to_referrals_cr:
                                type: number
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Unauthorized
                  code:
                    type: string
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Invalid user type
                  code:
                    type: string
                    example: forbidden
        '422':
          description: Unprocessable Entity
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: 'param is missing or the value is empty: columns'
                  code:
                    type: string
                    example: invalid_params
  /company/reports/urls:
    get:
      summary: Get reports for URLs
      description: With this endpoint you can get the report data grouped by URLs.<Tip>**HTTP Request** <br/>`GET https://api.firstpromoter.com/api/v2/company/reports/urls`</Tip>
      tags:
      - Reports
      parameters:
      - $ref: '#/components/parameters/AccountId'
      - name: columns
        in: query
        required: true
        schema:
          type: array
          items:
            type: string
            enum:
            - clicks_count
            - revenue_amount
            - promoter_earnings_amount
            - referrals_count
            - customers_count
            - sales_count
            - refunds_count
            - cancelled_customers_count
            - referrals_to_customers_cr
            - clicks_to_customers_cr
            - clicks_to_referrals_cr
            - url
      - name: q
        in: query
        required: false
        schema:
          type: string
      - name: group_by
        in: query
        required: true
        schema:
          type: string
          enum:
          - day
          - week
          - month
          - year
      - name: start_date
        in: query
        required: true
        schema:
          type: string
          format: date-time
      - name: end_date
        in: query
        required: true
        schema:
          type: string
          format: date-time
      - name: sorting
        in: query
        required: false
        schema:
          type: object
          additionalProperties:
            type: string
            enum:
            - asc
            - desc
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/URLsResponse'
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        '422':
          description: Unprocessable Entity
  /company/reports/download:
    get:
      summary: Download reports
      description: With this endpoint you can download reports.<Tip>**HTTP Request** <br/>`GET https://api.firstpromoter.com/api/v2/company/reports/download`</Tip>
      tags:
      - Reports
      parameters:
      - $ref: '#/components/parameters/AccountId'
      - name: report_type
        in: query
        required: true
        schema:
          type: string
          enum:
          - overview
          - campaigns
          - promoters
          - traffic_sources
          - urls
      - name: totals
        in: query
        required: false
        schema:
          type: boolean
      - name: columns
        in: query
        required: true
        schema:
          type: array
          items:
            type: string
      - name: group_by
        in: query
        required: true
        schema:
          type: string
          enum:
          - day
          - week
          - month
          - year
      - name: start_date
        in: query
        required: true
        schema:
          type: string
          format: date-time
      - name: end_date
        in: query
        required: true
        schema:
          type: string
          format: date-time
      responses:
        '200':
          description: CSV file download
          content:
            text/csv:
              schema:
                type: string
                format: binary
        '202':
          description: Accepted - async processing started
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        '422':
          description: Unprocessable Entity
components:
  schemas:
    URLsResponse:
      type: array
      items:
        type: object
        properties:
          url:
            type: string
          id:
            type: string
          data:
            type: object
            properties:
              clicks_count:
                type: integer
              revenue_amount:
                type: number
              promoter_earnings_amount:
                type: number
              referrals_count:
                type: integer
              customers_count:
                type: integer
              sales_count:
                type: integer
              refunds_count:
                type: integer
              cancelled_customers_count:
                type: integer
              referrals_to_customers_cr:
                type: number
              clicks_to_customers_cr:
                type: number
              clicks_to_referrals_cr:
                type: number
  parameters:
    AccountId:
      name: Account-ID
      in: header
      required: true
      description: Account ID. You can find your Account ID on Your FirstPromoter Dashboard. Navigate to Settings → Integrations
      schema:
        type: string
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      description: API key passed as Bearer token