openapi: 3.1.0
info:
  title: Reach API
  description: >
    API for accessing financial data and reporting for financing companies.
    Provides access to 

    financial statements, chart of accounts, budgets, and operational metrics.
  version: 1.0.3
security:
  - OAuth2: []
servers:
  - url: http://localhost:{port}
    variables:
      port:
        default: '3000'
  - url: https://{baseUrl}
    description: API Base URL
    variables:
      baseUrl:
        default: example.com
        description: Enter the base URL for API calls
tags:
  - name: Authentication
    description: >
      Endpoints for OAuth 2.0 authentication and authorization. These endpoints
      handle the OAuth 

      discovery document, authorization flow, token exchange, and user
      information retrieval.
  - name: Company Information
    description: >
      Endpoints for retrieving basic company information such as company name
      and fiscal month end.
  - name: Reference Data
    description: >
      Endpoints for accessing reference data including chart of accounts,
      budgets, classes, 

      departments, and non-financial metrics. These endpoints provide the
      foundational data 

      structures used throughout the API.
  - name: Metrics
    description: >
      Endpoints for retrieving non-financial metrics and KPIs over specified
      date ranges.
  - name: Financial Statements
    description: >
      Endpoints for retrieving financial statements including Profit and Loss,
      Balance Sheet, 

      and Cash Flow Statement. These endpoints support filtering by date range,
      accounting basis, 

      budget, class, and department.
paths:
  /auth/oauth-discovery:
    get:
      tags:
        - Authentication
      summary: OAuth discovery document
      description: >-
        Retrieves OAuth 2.0 discovery document with authorization server
        configuration.
      security: []
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                type: object
                properties:
                  issuer:
                    type: string
                    description: The issuer URL of the authorization server
                    example: https://reachreporting.com
                  authorization_endpoint:
                    type: string
                    description: The URL of the authorization endpoint
                    example: https://reachreporting.com/oauth2/authorize
                  token_endpoint:
                    type: string
                    description: The URL of the token endpoint
                    example: https://reachreporting.com/oauth2/token
                  grant_types_supported:
                    type: array
                    items:
                      type: string
                    example:
                      - authorization_code
                      - refresh_token
                    description: >-
                      The OAuth 2.0 grant types supported by the authorization
                      server
                  response_types_supported:
                    type: array
                    items:
                      type: string
                    example:
                      - code
                    description: The response types supported by the authorization server
                  scopes_supported:
                    type: array
                    items:
                      type: string
                    example:
                      - openid
                      - profile
                      - email
                      - phone
                      - read:company
                    description: The OAuth 2.0 scopes supported by the authorization server
                  token_endpoint_auth_methods_supported:
                    type: array
                    items:
                      type: string
                    example:
                      - client_secret_post
                    description: >-
                      The client authentication methods supported by the token
                      endpoint
  /oauth2/authorize:
    get:
      tags:
        - Authentication
      summary: OAuth Authorization Endpoint
      description: >
        Initiates the OAuth authorization flow. This endpoint redirects the user
        to an authorization page 

        where they can grant or deny access. After user interaction, they are
        redirected back to the 

        client's redirect_uri with an authorization code in the URL parameters.
      security: []
      parameters:
        - name: response_type
          in: query
          required: true
          schema:
            type: string
            enum:
              - code
          description: The response type, must be "code" for authorization code flow
        - name: client_id
          in: query
          required: true
          schema:
            type: string
          description: The client identifier
        - name: redirect_uri
          in: query
          required: true
          schema:
            type: string
            format: uri
          description: The redirect URI where the authorization code will be sent
        - name: scope
          in: query
          required: false
          schema:
            type: string
          description: |
            Space-separated list of OAuth scopes.
            - openid: Required for OpenID Connect
            - profile: Access to user profile information
            - email: Access to user email address
            - phone: Access to user phone number
            - read:company: Access to company information
        - name: state
          in: query
          required: false
          schema:
            type: string
          description: >
            State parameter should be a JSON object stringified, then base64
            encoded, then URI encoded.

            Contains any application-specific data.
      responses:
        '200':
          description: Successful authorization
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: string
                    description: Authorization code
                  state:
                    type: string
                    description: State parameter returned from request
  /oauth2/token:
    post:
      tags:
        - Authentication
      summary: OAuth Token Endpoint
      description: Exchanges authorization code for access and refresh tokens.
      security: []
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              properties:
                grant_type:
                  type: string
                  enum:
                    - authorization_code
                    - refresh_token
                  description: The grant type
                code:
                  type: string
                  description: >-
                    The authorization code received from the authorization
                    endpoint (required when grant_type is authorization_code)
                redirect_uri:
                  type: string
                  format: uri
                  description: >-
                    The same redirect URI used in the authorization request
                    (required when grant_type is authorization_code)
                client_id:
                  type: string
                  description: The client identifier
                client_secret:
                  type: string
                  description: The client secret
                refresh_token:
                  type: string
                  description: >-
                    The refresh token (required when grant_type is
                    refresh_token)
              required:
                - grant_type
                - client_id
                - client_secret
      responses:
        '200':
          description: Successful token exchange
          content:
            application/json:
              schema:
                type: object
                properties:
                  access_token:
                    type: string
                    description: The access token
                  token_type:
                    type: string
                    enum:
                      - Bearer
                    description: The token type
                  expires_in:
                    type: integer
                    description: Token expiration time in seconds
                  scope:
                    type: string
                    description: Space-separated list of granted OAuth scopes
                  refresh_token:
                    type: string
                    description: Refresh token for obtaining new access tokens
  /oauth2/user-info:
    get:
      tags:
        - Authentication
      summary: Get User Information
      description: >-
        Retrieves authenticated user information and list of accessible
        companies.
      security: []
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserDetail'
  /companies/{CompanyId}/info:
    get:
      tags:
        - Company Information
      summary: Get Company Info
      description: Retrieves basic company information including name and fiscal month end.
      parameters:
        - name: CompanyId
          in: path
          required: true
          schema:
            type: string
          description: The ID of the company.
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                type: object
                properties:
                  CompanyId:
                    type: string
                    example: '12345'
                  Name:
                    type: string
                    example: ABC Corp
                  FiscalMonth:
                    $ref: '#/components/schemas/Month'
  /companies/{CompanyId}/chart-of-accounts:
    get:
      tags:
        - Reference Data
      summary: List Chart of Accounts
      description: >-
        Retrieves the complete chart of accounts with account details and
        hierarchy. A balance sheet account that also exists on the cash flow
        statement must only be one entry.
      parameters:
        - name: CompanyId
          in: path
          required: true
          schema:
            type: string
          description: The ID of the company.
        - $ref: '#/components/parameters/Offset'
        - $ref: '#/components/parameters/Limit'
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                type: object
                properties:
                  Data:
                    type: array
                    items:
                      type: object
                      properties:
                        AccountId:
                          type: string
                        Name:
                          type: string
                        AccountNumber:
                          type: string
                        AccountType:
                          $ref: '#/components/schemas/AccountType'
                        AccountSubtype:
                          $ref: '#/components/schemas/AccountSubtype'
                        ParentAccountId:
                          type: string
                        Inactive:
                          type: boolean
                        CashFlowSection:
                          $ref: '#/components/schemas/CashFlowSection'
                  Pagination:
                    $ref: '#/components/schemas/PaginationMetadata'
  /companies/{CompanyId}/budgets:
    get:
      tags:
        - Reference Data
      summary: List Budgets
      description: Retrieves all budgets configured for the company.
      parameters:
        - name: CompanyId
          in: path
          required: true
          schema:
            type: string
          description: The ID of the company.
        - $ref: '#/components/parameters/Offset'
        - $ref: '#/components/parameters/Limit'
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                type: object
                properties:
                  Data:
                    type: array
                    items:
                      type: object
                      properties:
                        BudgetId:
                          type: string
                        Name:
                          type: string
                        StartDate:
                          type: string
                          format: date
                          description: Start date in YYYY-MM-DD format (e.g., 2025-01-31)
                          example: '2025-01-31'
                        EndDate:
                          type: string
                          format: date
                          description: End date in YYYY-MM-DD format (e.g., 2025-01-31)
                          example: '2025-01-31'
                        ClassIds:
                          type: array
                          items:
                            type: string
                        DepartmentIds:
                          type: array
                          items:
                            type: string
                  Pagination:
                    $ref: '#/components/schemas/PaginationMetadata'
  /companies/{CompanyId}/classes:
    get:
      tags:
        - Reference Data
      summary: List Classes
      description: >-
        Retrieves all classes (cost centers or segments) for financial
        segmentation.
      parameters:
        - name: CompanyId
          in: path
          required: true
          schema:
            type: string
          description: The ID of the company.
        - $ref: '#/components/parameters/Offset'
        - $ref: '#/components/parameters/Limit'
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                type: object
                properties:
                  Data:
                    type: array
                    items:
                      type: object
                      properties:
                        ClassId:
                          type: string
                        Name:
                          type: string
                        ParentId:
                          type: string
                  Pagination:
                    $ref: '#/components/schemas/PaginationMetadata'
  /companies/{CompanyId}/departments:
    get:
      tags:
        - Reference Data
      summary: List Departments
      description: Retrieves all departments for organizational segmentation and reporting.
      parameters:
        - name: CompanyId
          in: path
          required: true
          schema:
            type: string
          description: The ID of the company.
        - $ref: '#/components/parameters/Offset'
        - $ref: '#/components/parameters/Limit'
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                type: object
                properties:
                  Data:
                    type: array
                    items:
                      type: object
                      properties:
                        DepartmentId:
                          type: string
                        Name:
                          type: string
                        ParentId:
                          type: string
                  Pagination:
                    $ref: '#/components/schemas/PaginationMetadata'
  /companies/{CompanyId}/non-financial-list:
    get:
      tags:
        - Reference Data
      summary: List Non-Financial Items
      description: Retrieves all available non-financial metrics and KPIs.
      parameters:
        - name: CompanyId
          in: path
          required: true
          schema:
            type: string
          description: The ID of the company.
        - $ref: '#/components/parameters/Offset'
        - $ref: '#/components/parameters/Limit'
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                type: object
                properties:
                  Data:
                    type: array
                    items:
                      type: object
                      properties:
                        NonFinancialId:
                          type: string
                        Name:
                          type: string
                        Group:
                          type: string
                  Pagination:
                    $ref: '#/components/schemas/PaginationMetadata'
  /companies/{CompanyId}/non-financial:
    post:
      tags:
        - Metrics
      summary: Get non-financial data
      description: >-
        Retrieves historical values for specified non-financial metrics over a
        date range.
      parameters:
        - name: CompanyId
          in: path
          required: true
          schema:
            type: string
          description: The ID of the company.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - NonFinancialIds
                - StartDate
                - EndDate
              properties:
                NonFinancialIds:
                  type: array
                  items:
                    type: string
                StartDate:
                  type: string
                  format: date
                  description: Start date in YYYY-MM-DD format (e.g., 2025-01-01)
                  example: '2025-01-01'
                EndDate:
                  type: string
                  format: date
                  description: End date in YYYY-MM-DD format (e.g., 2025-01-31)
                  example: '2025-01-31'
                BudgetId:
                  type: string
                  description: Optional budget identifier. When omitted, returns actuals.
                ClassId:
                  type: string
                  description: Optional class identifier to filter by class.
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                type: object
                properties:
                  Data:
                    type: array
                    items:
                      type: object
                      properties:
                        NonFinancialId:
                          type: string
                          example: 90dcbc1e-05f3-11ea-82c7-96c172b25530
                        Values:
                          type: array
                          items:
                            type: object
                            description: Each index represents month in range
                            properties:
                              Value:
                                type: string
  /companies/{CompanyId}/profit-loss:
    get:
      tags:
        - Financial Statements
      summary: Profit and Loss
      description: >-
        Retrieves the Profit and Loss statement showing revenues, expenses, and
        net income.
      parameters:
        - name: CompanyId
          in: path
          required: true
          schema:
            type: string
        - name: StartDate
          in: query
          required: true
          schema:
            type: string
            format: date
          description: Start date in YYYY-MM-DD format (e.g., 2025-01-01)
          example: '2025-01-01'
        - name: EndDate
          in: query
          required: true
          schema:
            type: string
            format: date
          description: End date in YYYY-MM-DD format (e.g., 2025-01-31)
          example: '2025-01-31'
        - name: AccountingBasis
          in: query
          required: true
          schema:
            $ref: '#/components/schemas/AccountingBasis'
          description: 'Accounting method: CASH or ACCRUAL'
        - name: BudgetId
          in: query
          required: false
          schema:
            type: string
          description: Optional budget identifier. When omitted, returns actuals.
        - name: ClassId
          in: query
          required: false
          schema:
            type: string
          description: Optional class identifier to filter by class.
        - name: DepartmentId
          in: query
          required: false
          schema:
            type: string
          description: Optional department identifier to filter by department.
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                type: object
                properties:
                  Data:
                    type: array
                    items:
                      type: object
                      properties:
                        AccountId:
                          type: string
                          example: 90dcbc1e-05f3-11ea-82c7-96c172b25530
                        Values:
                          type: array
                          items:
                            type: object
                            description: Each index represents month in range
                            properties:
                              Value:
                                type: string
  /companies/{CompanyId}/cash-flow-statement:
    get:
      tags:
        - Financial Statements
      summary: Cash Flow Statement
      description: >-
        Retrieves the Cash Flow Statement showing cash movements by activity
        type.
      parameters:
        - name: CompanyId
          in: path
          required: true
          schema:
            type: string
        - name: StartDate
          in: query
          required: true
          schema:
            type: string
            format: date
          description: Start date in YYYY-MM-DD format (e.g., 2025-01-01)
          example: '2025-01-01'
        - name: EndDate
          in: query
          required: true
          schema:
            type: string
            format: date
          description: End date in YYYY-MM-DD format (e.g., 2025-01-31)
          example: '2025-01-31'
        - name: BudgetId
          in: query
          required: false
          schema:
            type: string
          description: Optional budget identifier. When omitted, returns actuals.
        - name: ClassId
          in: query
          required: false
          schema:
            type: string
          description: Optional class identifier to filter by class.
        - name: DepartmentId
          in: query
          required: false
          schema:
            type: string
          description: Optional department identifier to filter by department.
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                type: object
                properties:
                  Data:
                    type: array
                    items:
                      type: object
                      properties:
                        AccountId:
                          type: string
                          example: defaa768-34e9-11e3-827d-af4343366b37
                          description: >-
                            This account id must be the same as the
                            corresponding account id on the Balance Sheet
                            statement.
                        Values:
                          type: array
                          items:
                            type: object
                            description: Each index represents month in range
                            properties:
                              Value:
                                type: string
  /companies/{CompanyId}/balance-sheet:
    get:
      tags:
        - Financial Statements
      summary: Balance Sheet
      description: Retrieves the Balance Sheet showing assets, liabilities, and equity.
      parameters:
        - name: CompanyId
          in: path
          required: true
          schema:
            type: string
        - name: StartDate
          in: query
          required: true
          schema:
            type: string
            format: date
          description: Start date in YYYY-MM-DD format (e.g., 2025-01-01)
          example: '2025-01-01'
        - name: EndDate
          in: query
          required: true
          schema:
            type: string
            format: date
          description: End date in YYYY-MM-DD format (e.g., 2025-01-31)
          example: '2025-01-31'
        - name: AccountingBasis
          in: query
          required: true
          schema:
            $ref: '#/components/schemas/AccountingBasis'
          description: 'Accounting method: CASH or ACCRUAL'
        - name: BudgetId
          in: query
          required: false
          schema:
            type: string
          description: Optional budget identifier. When omitted, returns actuals.
        - name: ClassId
          in: query
          required: false
          schema:
            type: string
          description: Optional class identifier to filter by class.
        - name: DepartmentId
          in: query
          required: false
          schema:
            type: string
          description: Optional department identifier to filter by department.
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                type: object
                properties:
                  Data:
                    type: array
                    items:
                      type: object
                      properties:
                        AccountId:
                          type: string
                          example: 4f455bf6-34fe-11e3-827d-af4343366b37
                        Values:
                          type: array
                          items:
                            type: object
                            description: Each index represents month in range
                            properties:
                              Value:
                                type: string
components:
  securitySchemes:
    OAuth2:
      type: oauth2
      description: >-
        OAuth 2.0 authorization code flow. Use the authorization endpoint to
        initiate the flow, then exchange the authorization code for tokens at
        the token endpoint.
      flows:
        authorizationCode:
          authorizationUrl: /oauth2/authorize
          tokenUrl: /oauth2/token
          refreshUrl: /oauth2/token
          scopes:
            openid: Required for OpenID Connect
            profile: Access to user profile information
            email: Access to user email address
            phone: Access to user phone number
            read:company: Access to company information
  parameters:
    Offset:
      name: offset
      in: query
      required: false
      schema:
        type: integer
        minimum: 0
        default: 0
      description: Number of records to skip for pagination
    Limit:
      name: limit
      in: query
      required: false
      schema:
        type: integer
        minimum: 1
        maximum: 1000
        default: 100
      description: Maximum number of records to return
  schemas:
    PaginationMetadata:
      type: object
      properties:
        offset:
          type: integer
          description: The number of records skipped
          example: 0
        limit:
          type: integer
          description: The maximum number of records requested
          example: 100
        total:
          type: integer
          description: The total number of records available
          example: 250
    AccountingBasis:
      type: string
      enum:
        - CASH
        - ACCRUAL
    AccountType:
      type: string
      enum:
        - BANK
        - OTHER_CURRENT_ASSET
        - FIXED_ASSET
        - OTHER_ASSET
        - ACCOUNTS_RECEIVABLE
        - EQUITY
        - EXPENSE
        - OTHER_EXPENSE
        - COST_OF_GOODS_SOLD
        - ACCOUNTS_PAYABLE
        - CREDIT_CARD
        - LONG_TERM_LIABILITY
        - OTHER_CURRENT_LIABILITY
        - INCOME
        - OTHER_INCOME
    AccountSubtype:
      type: string
      enum:
        - UNDEPOSITED_FUNDS
        - RETAINED_EARNINGS
        - ADJUSTMENT_RETAINED_EARNINGS
        - ACCRUALS_AND_DEFERRED_INCOME
        - PREPAYMENTS_AND_ACCRUED_INCOME
        - ACCUMULATED_DEPRECIATION
        - ACCUMULATED_AMORTIZATION
        - ACCUMULATED_DEPLETION
        - ACCUMULATED_AMORTIZATION_OF_OTHER_ASSETS
        - INVENTORY
        - NET_PROFIT_EQUITY
    Month:
      type: string
      enum:
        - JAN
        - FEB
        - MAR
        - APR
        - MAY
        - JUN
        - JUL
        - AUG
        - SEP
        - OCT
        - NOV
        - DEC
    CashFlowSection:
      type: string
      enum:
        - OPERATING_ACTIVITIES
        - INVESTING_ACTIVITIES
        - FINANCING_ACTIVITIES
    CompanyDetails:
      type: object
      properties:
        CompanyId:
          type: integer
        Name:
          type: string
    UserDetail:
      type: object
      properties:
        Id:
          type: string
        Email:
          type: string
        FirstName:
          type: string
        LastName:
          type: string
        CompanyDetails:
          type: array
          items:
            $ref: '#/components/schemas/CompanyDetails'
