Embat Forecasts API

openapi: 3.1.0
info:
  title: Embat AccountingAccounts Forecasts API
  description: Embat API enables connections between any third party application and Embat. Is organized around REST principles, using HTTP responses code and returning data in JSON format. While testing the API, you have to request **sandbox credentials**.
  contact:
    name: API Support
    url: https://embat.io/
    email: tech@embat.io
  version: 2.120.3
  x-logo:
    url: https://storage.googleapis.com/embat-production.appspot.com/assets/embat_dark.svg
tags:
- name: Forecasts
  description: "`Forecast` represents a treasury cash flow projection generated by Embat for a given date, classified under a `Category` and grouped into a `Scenario` (e.g. a base case or a stress scenario). Each scenario has its own currency and periodicity — `daily`, `weekly`, `monthly` or `yearly` — that determines how forecasted periods are spaced.\n\nForecasts are generated in Embat; this API does not support creating or deleting them. Use it to read forecasted cash flows and, optionally, to mark them as synchronized with your own systems.\n\n**Typical flow:**\n\n1. **Read forecasts.** Pull the forecasted amounts for a company with `GET /forecasts/{companyId}`, optionally filtered by `scenarioId`, a date range, or synchronization status (`sync`).\n2. **Confirm them as synchronized.** Once you have processed a forecast on your side, mark it as synchronized with `PATCH /forecasts/{companyId}/{id}` (or the bulk variant `PATCH /forecasts/{companyId}`):\n\n```json\nPATCH /forecasts/{companyId}/{id}\n{\n  \"sync\": true\n}\n```\n"
paths:
  /forecasts/{companyId}:
    get:
      tags:
      - Forecasts
      summary: List forecasts
      description: 'Returns the treasury forecasts of a company. Results are paginated: use `limit` to control page size and pass the returned `nextPageToken` to fetch the next page. `startDate` is inclusive and `endDate` is exclusive; either bound can be used on its own to leave the other end of the range unbounded. Only forecasts linked to a scenario that is currently visible are returned.'
      operationId: list_forecasts_forecasts__companyId__get
      security:
      - HTTPBearer: []
      parameters:
      - name: companyId
        in: path
        required: true
        schema:
          type: string
          title: Companyid
      - name: scenarioId
        in: query
        required: false
        schema:
          type: string
          description: Filter forecasts belonging to a given scenario, by its Embat scenario ID.
          title: Scenarioid
        description: Filter forecasts belonging to a given scenario, by its Embat scenario ID.
      - name: sync
        in: query
        required: false
        schema:
          type: boolean
          description: Filter by synchronization status. `false` also matches forecasts where the value is not set.
          title: Sync
        description: Filter by synchronization status. `false` also matches forecasts where the value is not set.
      - name: operations
        in: query
        required: false
        schema:
          type: boolean
          description: Reserved for future use; currently has no effect on the results.
          default: false
          title: Operations
        description: Reserved for future use; currently has no effect on the results.
      - name: startDate
        in: query
        required: false
        schema:
          type: string
          format: date
          description: Only return forecasts dated on or after this date (inclusive).
          title: Startdate
        description: Only return forecasts dated on or after this date (inclusive).
      - name: endDate
        in: query
        required: false
        schema:
          type: string
          format: date
          description: Only return forecasts dated before this date (exclusive).
          title: Enddate
        description: Only return forecasts dated before this date (exclusive).
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          maximum: 2000
          title: Response length of objects limit
          description: Maximum number of objects to return in the response. Default 500, maximum 2000.
          default: 500
        description: Maximum number of objects to return in the response. Default 500, maximum 2000.
      - name: nextPageToken
        in: query
        required: false
        schema:
          type: string
          title: Pagination token
          description: Token to fetch the next page of results, taken from the `nextPageToken` returned by the previous request with the same filters. Omit it to fetch the first page. An invalid or malformed token is rejected with `404`.
        description: Token to fetch the next page of results, taken from the `nextPageToken` returned by the previous request with the same filters. Omit it to fetch the first page. An invalid or malformed token is rejected with `404`.
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListForecastsResponseSchema'
        '401':
          description: Unauthorized. The bearer token is missing, invalid or expired.
          content:
            application/json:
              example:
                detail: user not authorized
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Company not found, or invalid `nextPageToken`.
          content:
            application/json:
              example:
                detail: 0021 companyId not found
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    patch:
      tags:
      - Forecasts
      summary: Update forecasts in bulk
      description: 'Updates the synchronization status or additional info of several forecasts in a single call, identified by `id`. Follows the same rules as the single-forecast update endpoint: fields omitted from the request, or sent as `null`, are left unchanged, and entries whose `id` does not match any forecast are silently skipped — the call still returns `200` for the whole batch.'
      operationId: update_forecasts_bulk_forecasts__companyId__patch
      security:
      - HTTPBearer: []
      parameters:
      - name: companyId
        in: path
        required: true
        schema:
          type: string
          title: Companyid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BulkPatchForecastsRequestSchema'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BulkModifyForecastsResponseSchema'
        '401':
          description: Unauthorized. The bearer token is missing, invalid or expired.
          content:
            application/json:
              example:
                detail: user not authorized
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not found. The requested resource or `companyId` does not exist.
          content:
            application/json:
              example:
                detail: 0021 companyId not found
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Unexpected error. Contact support if it persists.
          content:
            application/json:
              example:
                detail: Internal server error
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /forecasts/{companyId}/{id}:
    get:
      tags:
      - Forecasts
      summary: Retrieve forecast
      description: Returns a single forecast by its Embat `id`. `accountingAmount` and `exchangeRate` are not computed for this endpoint and are returned as stored, typically `null` — use `GET /forecasts/{companyId}` to get them populated. If the forecast's scenario is no longer visible, this endpoint returns a response with every field set to `null` instead of the forecast data.
      operationId: retrieve_forecast_forecasts__companyId___id__get
      security:
      - HTTPBearer: []
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
          title: Id
      - name: companyId
        in: path
        required: true
        schema:
          type: string
          title: Companyid
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetForecastsResponseSchema'
        '401':
          description: Unauthorized. The bearer token is missing, invalid or expired.
          content:
            application/json:
              example:
                detail: user not authorized
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Company not found, or no forecast matches the given id.
          content:
            application/json:
              example:
                detail: 0021 companyId not found
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    patch:
      tags:
      - Forecasts
      summary: Update forecast
      description: Updates the synchronization status or additional info of a forecast identified by `id`. Fields omitted from the request, or sent as `null`, are left unchanged. Updating an `id` that does not match any forecast also returns `200` without applying any change — no `404` is raised.
      operationId: update_forecast_forecasts__companyId___id__patch
      security:
      - HTTPBearer: []
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
          title: Id
      - name: companyId
        in: path
        required: true
        schema:
          type: string
          title: Companyid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PatchForecastsRequestSchema'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ModifyForecastsResponseSchema'
        '401':
          description: Unauthorized. The bearer token is missing, invalid or expired.
          content:
            application/json:
              example:
                detail: user not authorized
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not found. The requested resource or `companyId` does not exist.
          content:
            application/json:
              example:
                detail: 0021 companyId not found
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Unexpected error. Contact support if it persists.
          content:
            application/json:
              example:
                detail: Internal server error
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
components:
  schemas:
    ModifyForecastsResponseSchema:
      properties:
        id:
          type: string
          title: Id
          description: Embat forecast ID.
          examples:
          - fct_00123
      type: object
      required:
      - id
      title: ModifyForecastsResponseSchema
    AuxBulkPatchForecastsRequestSchema:
      properties:
        additionalInfo:
          additionalProperties: true
          type: object
          title: Additionalinfo
          description: Free-form key/value metadata to attach to the forecast.
          default: {}
        sync:
          anyOf:
          - type: boolean
          - type: 'null'
          title: Sync
          description: Marks the forecast as synchronized with your systems. Fields omitted from the request, or sent as `null`, are left unchanged.
          examples:
          - true
        id:
          type: string
          title: Id
          description: Embat forecast ID to update.
          examples:
          - fct_00123
      type: object
      required:
      - id
      title: AuxBulkPatchForecastsRequestSchema
    CurrencyEnum:
      type: string
      enum:
      - AED
      - AFN
      - ALL
      - AMD
      - ANG
      - AOA
      - ARS
      - AUD
      - AWG
      - AZN
      - BAM
      - BBD
      - BDT
      - BGN
      - BHD
      - BIF
      - BMD
      - BND
      - BOB
      - BOV
      - BRL
      - BSD
      - BTC
      - BTN
      - BWP
      - BYN
      - BZD
      - CAD
      - CDF
      - CHE
      - CHF
      - CHW
      - CLF
      - CLP
      - CNH
      - CNY
      - COP
      - COU
      - CRC
      - CUP
      - CVE
      - CZK
      - DJF
      - DKK
      - DOP
      - DZD
      - EEK
      - EGP
      - ERN
      - ETB
      - ETH
      - EUR
      - FJD
      - FKP
      - GBP
      - GEL
      - GHS
      - GIP
      - GMD
      - GNF
      - GTQ
      - GYD
      - HKD
      - HNL
      - HRK
      - HTG
      - HUF
      - IDR
      - ILS
      - INR
      - IQD
      - IRR
      - ISK
      - JMD
      - JOD
      - JPY
      - KES
      - KGS
      - KHR
      - KMF
      - KPW
      - KRW
      - KWD
      - KYD
      - KZT
      - LAK
      - LBP
      - LKR
      - LRD
      - LSL
      - LTC
      - LTL
      - LVL
      - LYD
      - MAD
      - MDL
      - MGA
      - MKD
      - MMK
      - MNT
      - MOP
      - MRU
      - MUR
      - MVR
      - MWK
      - MXN
      - MXV
      - MYR
      - MZN
      - NAD
      - NGN
      - NIO
      - NOK
      - NPR
      - NZD
      - OMR
      - PAB
      - PEN
      - PGK
      - PHP
      - PKR
      - PLN
      - PYG
      - QAR
      - RON
      - RSD
      - RUB
      - RWF
      - SAR
      - SBD
      - SCR
      - SDG
      - SEK
      - SGD
      - SHP
      - SLE
      - SOS
      - SRD
      - SSP
      - STN
      - SVC
      - SYP
      - SZL
      - THB
      - TJS
      - TMT
      - TND
      - TOP
      - TRY
      - TTD
      - TWD
      - TZS
      - UAH
      - UGX
      - USD
      - USN
      - UYI
      - UYU
      - UYW
      - UZS
      - VED
      - VEF
      - VES
      - VND
      - VUV
      - WST
      - XAF
      - XAG
      - XAU
      - XBA
      - XBB
      - XBC
      - XBD
      - XCD
      - XDR
      - XOF
      - XPD
      - XPF
      - XPT
      - XSU
      - XTS
      - XUA
      - XXX
      - YER
      - ZAR
      - ZMK
      - ZMW
      - ZWG
      - ZWL
      title: CurrencyEnum
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
            - type: string
            - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
        input:
          title: Input
        ctx:
          type: object
          title: Context
      type: object
      required:
      - loc
      - msg
      - type
      title: ValidationError
    PatchForecastsRequestSchema:
      properties:
        additionalInfo:
          additionalProperties: true
          type: object
          title: Additionalinfo
          description: Free-form key/value metadata to attach to the forecast.
          default: {}
        sync:
          anyOf:
          - type: boolean
          - type: 'null'
          title: Sync
          description: Marks the forecast as synchronized with your systems. Fields omitted from the request, or sent as `null`, are left unchanged.
          examples:
          - true
      type: object
      title: PatchForecastsRequestSchema
    ErrorResponse:
      properties:
        detail:
          type: string
          title: Detail
          description: Human-readable explanation of the error.
          examples:
          - user not authorized
      type: object
      required:
      - detail
      title: ErrorResponse
      description: Error payload returned by the API (FastAPI `detail` convention).
    PeriodicityEnum:
      type: string
      enum:
      - monthly
      - yearly
      - weekly
      - daily
      title: PeriodicityEnum
    GetForecastsResponseSchema:
      properties:
        id:
          anyOf:
          - type: string
          - type: 'null'
          title: Id
          description: Embat forecast ID.
          examples:
          - fct_00123
        companyId:
          anyOf:
          - type: string
          - type: 'null'
          title: Companyid
          description: Embat company ID. You can get them from "companies" endpoints.
        amount:
          anyOf:
          - type: number
          - type: 'null'
          title: Amount
          description: Forecasted amount, in the scenario `currency`. Positive for inflows, negative for outflows.
          examples:
          - 15000.0
        accountingAmount:
          anyOf:
          - type: number
          - type: 'null'
          title: Accountingamount
          description: Forecasted amount converted to EUR using the exchange rate for the forecast `date`. `null` when the forecast is dated before 2021 or no exchange rate is yet available for that date. Only computed when listing forecasts with `GET /forecasts/{companyId}`; retrieving a single forecast by id returns this field as stored, typically `null`.
          examples:
          - 13850.25
        accountingCurrency:
          anyOf:
          - $ref: '#/components/schemas/CurrencyEnum'
          - type: 'null'
          description: Currency of `accountingAmount`. Currently always `EUR`.
          examples:
          - EUR
        exchangeRate:
          anyOf:
          - type: number
          - type: 'null'
          title: Exchangerate
          description: Exchange rate applied to obtain `accountingAmount` from `amount`. Subject to the same conditions as `accountingAmount`.
          examples:
          - 1.083
        date:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: Date
          description: Date the forecast applies to.
        createdAt:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: Createdat
          description: Creation date of the forecast.
        updatedAt:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: Updatedat
          description: Last updated date of the forecast.
        categoryId:
          anyOf:
          - type: string
          - type: 'null'
          title: Categoryid
          description: Embat ID of the category the forecast is classified under.
        scenario:
          anyOf:
          - $ref: '#/components/schemas/ScenarioSchema'
          - type: 'null'
          description: Scenario the forecast belongs to.
      type: object
      title: GetForecastsResponseSchema
      description: Forecasts response data schema
    ScenarioSchema:
      properties:
        id:
          anyOf:
          - type: string
          - type: 'null'
          title: Id
          description: Embat scenario ID.
          examples:
          - scn_00045
        name:
          anyOf:
          - type: string
          - type: 'null'
          title: Name
          description: Scenario name.
          examples:
          - Base case
        currency:
          anyOf:
          - $ref: '#/components/schemas/CurrencyEnum'
          - type: 'null'
          description: Currency the scenario's forecasted amounts are expressed in.
          examples:
          - EUR
        description:
          anyOf:
          - type: string
          - type: 'null'
          title: Description
          description: Free-text description of the scenario.
          examples:
          - Baseline treasury projection for FY2026
        periodicity:
          anyOf:
          - $ref: '#/components/schemas/PeriodicityEnum'
          - type: 'null'
          description: 'Time granularity of the scenario''s forecasted periods: `daily`, `weekly`, `monthly` or `yearly`.'
          examples:
          - monthly
      type: object
      title: ScenarioSchema
    BulkPatchForecastsRequestSchema:
      properties:
        data:
          items:
            $ref: '#/components/schemas/AuxBulkPatchForecastsRequestSchema'
          type: array
          title: Data
          description: Forecasts to update, identified by `id`.
      type: object
      required:
      - data
      title: BulkPatchForecastsRequestSchema
    BulkModifyForecastsResponseSchema:
      properties:
        data:
          items:
            $ref: '#/components/schemas/ModifyForecastsResponseSchema'
          type: array
          title: Data
          description: Result of the bulk update, one entry per forecast.
      type: object
      required:
      - data
      title: BulkModifyForecastsResponseSchema
    ListForecastsResponseSchema:
      properties:
        data:
          items:
            $ref: '#/components/schemas/GetForecastsResponseSchema'
          type: array
          title: Data
          description: Forecasts matching the query.
        nextPageToken:
          anyOf:
          - type: string
          - type: 'null'
          title: Nextpagetoken
          description: Token to fetch the next page of results. `null` when there are no more pages.
      type: object
      required:
      - data
      title: ListForecastsResponseSchema
  securitySchemes:
    HTTPBearer:
      type: http
      scheme: bearer