Embat Balances API

openapi: 3.1.0
info:
  title: Embat AccountingAccounts Balances 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: Balances
  description: '`Balance` represents the end-of-day balance of a bank product (account) for a given calendar day. Embat records one balance per product per day, expressed both in the product''s own currency (`balance`) and, when available, in the company accounting currency (`accountingBalance`, converted using the exchange rate as of that day).


    Each balance is linked to a `Product` (a bank account, credit line, card...) held at one of the company''s connected `Banks`. Balances whose linked product no longer exists in Embat are not returned.


    **Typical flow:** use `GET /balances/{companyId}` to read the daily balance history of a company''s bank products, filtering by `productId` and by date range, or `GET /balances/{companyId}/{id}` to retrieve a single balance you already know the `id` of — for example after obtaining it from a previous list call.

    '
paths:
  /balances/{companyId}:
    get:
      tags:
      - Balances
      summary: List balances
      description: 'Returns the end-of-day balances of a company''s bank products (accounts), one entry per product per day. Results are paginated: use `limit` to control page size and pass the returned `nextPageToken` to fetch the next page. `startDate`/`endDate` filter by balance date; `startDate` is inclusive and `endDate` is exclusive, and when only one bound is given the range is capped at 90 days. If neither is given, all available balances are returned, paginated. Balances whose linked bank product no longer exists are excluded from the results.'
      operationId: list_balances_balances__companyId__get
      security:
      - HTTPBearer: []
      parameters:
      - name: companyId
        in: path
        required: true
        schema:
          type: string
          title: Companyid
      - name: productId
        in: query
        required: false
        schema:
          type: string
          description: Filter balances of a single bank product (account) by its Embat product ID.
          title: Productid
        description: Filter balances of a single bank product (account) by its Embat product ID.
      - name: startDate
        in: query
        required: false
        schema:
          type: string
          format: date
          description: 'Only return balances dated on or after this date (inclusive). The range cannot exceed 90 days: if `endDate` is also given, the span between the two cannot exceed 90 days; if `endDate` is omitted, `startDate` cannot be more than 90 days in the past.'
          title: Startdate
        description: 'Only return balances dated on or after this date (inclusive). The range cannot exceed 90 days: if `endDate` is also given, the span between the two cannot exceed 90 days; if `endDate` is omitted, `startDate` cannot be more than 90 days in the past.'
      - name: endDate
        in: query
        required: false
        schema:
          type: string
          format: date
          description: Only return balances dated before this date (exclusive). Combined with `startDate`, the range cannot exceed 90 days. If used without `startDate`, results start 90 days before this date.
          title: Enddate
        description: Only return balances dated before this date (exclusive). Combined with `startDate`, the range cannot exceed 90 days. If used without `startDate`, results start 90 days before this date.
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          maximum: 5000
          title: Response length of objects limit
          description: Maximum number of objects to return in the response. Default 500, maximum 5000.
          default: 500
        description: Maximum number of objects to return in the response. Default 500, maximum 5000.
      - 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.
        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.
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListBalancesResponseSchema'
        '400':
          description: 'Invalid date range: when only a start bound (`startDate`) is given, it must not be in the future and cannot be more than 90 days in the past.'
          content:
            application/json:
              example:
                detail: startDate is a date after endDate
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '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, unknown `nextPageToken`, or an invalid date range when both `startDate` and `endDate` are given (start after end, or a span of more than 90 days).
          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'
  /balances/{companyId}/{id}:
    get:
      tags:
      - Balances
      summary: Retrieve balance
      description: Returns a single balance by its Embat `id`.
      operationId: retrieve_balance_balances__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/GetBalancesResponseSchema'
        '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, no balance matches the given `id`, or the balance's linked bank product no longer exists.
          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'
components:
  schemas:
    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).
    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
    GetBalancesResponseSchema:
      properties:
        id:
          anyOf:
          - type: string
          - type: 'null'
          title: Id
          description: Embat balance ID. Use it with `GET /balances/{companyId}/{id}` to retrieve this balance directly.
          examples:
          - 65a1f9c2e4b0a1b2c3d4e5f6
        balance:
          anyOf:
          - type: number
          - type: 'null'
          title: Balance
          description: Balance of the bank product at the end of `date`, in the product's own currency.
          examples:
          - 125430.75
        date:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: Date
          description: Calendar day this end-of-day balance corresponds to.
        companyId:
          anyOf:
          - type: string
          - type: 'null'
          title: Companyid
          description: Embat company ID. You can get them from "companies" endpoints.
        product:
          anyOf:
          - $ref: '#/components/schemas/ProductBaseSchema'
          - type: 'null'
          description: Bank product (account) this balance belongs to.
        accountingCurrency:
          anyOf:
          - $ref: '#/components/schemas/CurrencyEnum'
          - type: 'null'
          description: Currency `accountingBalance` is expressed in. When not provided by the balance source, Embat computes it and defaults to `EUR`.
          examples:
          - EUR
        accountingBalance:
          anyOf:
          - type: number
          - type: 'null'
          title: Accountingbalance
          description: Balance converted to the company accounting currency. When not provided by the balance source, Embat computes it using the exchange rate as of `date`; it can be `null` if no exchange rate is available for that date and currency.
          examples:
          - 128500.2
        exchangeRate:
          anyOf:
          - type: number
          - type: 'null'
          title: Exchangerate
          description: Exchange rate applied between the product currency and `accountingCurrency`. When not provided by the balance source, Embat computes it as of `date`; it can be `null` if no exchange rate is available for that date and currency.
          examples:
          - 1.0245
        createdAt:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: Createdat
          description: Created date of the entity in the database.
        updatedAt:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: Updatedat
          description: Last updated date of the entity in the database.
      type: object
      title: GetBalancesResponseSchema
    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
    ProductBaseSchema:
      properties:
        id:
          type: string
          title: Id
          description: Embat product ID.
          examples:
          - prod_8f3a1c
        currency:
          $ref: '#/components/schemas/CurrencyEnum'
          description: ISO currency code of the product.
          examples:
          - EUR
        product:
          type: string
          title: Product
          description: Product name as reported by the bank.
          examples:
          - Cuenta Corriente
        bankFullName:
          anyOf:
          - type: string
          - type: 'null'
          title: Bankfullname
          description: Full legal name of the bank this product belongs to, if known.
          examples:
          - Banco Bilbao Vizcaya Argentaria
        alias:
          anyOf:
          - type: string
          - type: 'null'
          title: Alias
          description: Custom alias given to the product in Embat, if any.
          examples:
          - Main checking account
      type: object
      required:
      - id
      - currency
      - product
      title: ProductBaseSchema
    ListBalancesResponseSchema:
      properties:
        data:
          items:
            $ref: '#/components/schemas/GetBalancesResponseSchema'
          type: array
          title: Data
          description: Balances 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: ListBalancesResponseSchema
  securitySchemes:
    HTTPBearer:
      type: http
      scheme: bearer