Embat Products API

openapi: 3.1.0
info:
  title: Embat AccountingAccounts Products 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: Products
  description: '`Product` represents a bank account, credit line, card or wallet held by the company — either aggregated automatically from a bank connection, or added manually in Embat. A product can optionally be linked to an accounting account via `accountingCode`, used to reconcile its balance against Embat''s chart of accounts.


    Products are grouped under a `Bank` relationship (`bankId`), hold the end-of-day snapshots reported by `Balances` and the movements reported by `Transactions`, and are referenced by `Payments` (`productId`) to resolve the accounting code used for classification.


    **Typical flow:** retrieve the products of a company with `GET /products/{companyId}` (or a single one with `GET /products/{companyId}/{id}`) to obtain the `id` values used across other endpoints — for example to filter `Transactions` or `Balances`, or to set `productId` on a `Payment`. Once a product''s accounting account is known, set it with `PATCH /products/{companyId}/{id}` (or the bulk variant `PATCH /products/{companyId}`).

    '
paths:
  /products/{companyId}:
    get:
      tags:
      - Products
      summary: List products
      description: Returns the active products (bank accounts, credit lines, cards or wallets) of a company, whether aggregated from a bank connection or added manually. Results are not paginated. Products not marked as visible in Embat are excluded.
      operationId: list_products_products__companyId__get
      security:
      - HTTPBearer: []
      parameters:
      - name: companyId
        in: path
        required: true
        schema:
          type: string
          title: Companyid
      - name: manual
        in: query
        required: false
        schema:
          type: boolean
          description: 'Filter by how the product was added: `true` for manually added products, `false` for products aggregated from a bank connection.'
          title: Manual
        description: 'Filter by how the product was added: `true` for manually added products, `false` for products aggregated from a bank connection.'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListProductsResponseSchema'
        '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'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    patch:
      tags:
      - Products
      summary: Update products in bulk
      description: Updates the accounting code and/or additional info of several products, identified by `id`. Entries whose `id` does not match any product are silently skipped — the call returns `200` for the whole batch. If the same `id` appears more than once, all entries are applied in order and the last one determines the final values.
      operationId: update_products_bulk_products__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/BulkPatchProductsRequestSchema'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BulkModifyProductsResponseSchema'
        '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'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /products/{companyId}/{id}:
    get:
      tags:
      - Products
      summary: Retrieve product
      description: Returns a single product by its Embat `id`.
      operationId: retrieve_product_products__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/GetProductsResponseSchema'
        '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 product 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:
      - Products
      summary: Update product
      description: Updates the accounting code and/or additional info of a product identified by `id`. Updating an `id` that does not match any product also returns `200` without applying any change — no `404` is raised.
      operationId: update_product_products__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/PatchProductsRequestSchema'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ModifyProductsResponseSchema'
        '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'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
components:
  schemas:
    ReconciliationSchema:
      properties:
        accountingCode:
          anyOf:
          - type: string
          - type: 'null'
          title: Accountingcode
          description: Accounting account code this reconciliation status refers to.
          examples:
          - '5720001'
        originalBalanceDate:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: Originalbalancedate
          description: Date up to which the linked accounting account's opening balance has been established in Embat. `null` if the account has not been initialized with an opening balance.
          examples:
          - '2024-01-01T00:00:00Z'
      type: object
      title: ReconciliationSchema
    PatchProductsRequestSchema:
      properties:
        additionalInfo:
          additionalProperties: true
          type: object
          title: Additionalinfo
          description: Free-form key/value metadata to attach to the product. Replaces the existing value entirely.
          default: {}
        accountingCode:
          anyOf:
          - type: string
          - type: 'null'
          title: Accountingcode
          description: Accounting account code to link the product to.
          examples:
          - '5720001'
      type: object
      title: PatchProductsRequestSchema
    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
    ModifyProductsResponseSchema:
      properties:
        id:
          type: string
          title: Id
          description: Embat product ID
      type: object
      required:
      - id
      title: ModifyProductsResponseSchema
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    BulkPatchProductsRequestSchema:
      properties:
        data:
          items:
            $ref: '#/components/schemas/AuxBulkPatchProductsRequestSchema'
          type: array
          title: Data
          description: Products to update, identified by `id`.
      type: object
      required:
      - data
      title: BulkPatchProductsRequestSchema
    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
    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).
    BulkModifyProductsResponseSchema:
      properties:
        data:
          items:
            $ref: '#/components/schemas/ModifyProductsResponseSchema'
          type: array
          title: Data
          description: Result of the bulk operation, one entry per product.
      type: object
      required:
      - data
      title: BulkModifyProductsResponseSchema
    GetProductsResponseSchema:
      properties:
        id:
          type: string
          title: Id
          description: Embat product ID.
          examples:
          - prod_8f3a1c
        bankId:
          type: string
          title: Bankid
          description: Embat ID of the bank relationship this product belongs to. You can get them from "banks" endpoints.
        companyId:
          type: string
          title: Companyid
          description: Embat company ID. You can get them from "companies" endpoints.
        accountingCode:
          anyOf:
          - type: string
          - type: 'null'
          title: Accountingcode
          description: Accounting account code this product is posted to, if it has been reconciled with one.
          examples:
          - '5720001'
        balance:
          anyOf:
          - type: number
          - type: 'null'
          title: Balance
          description: Current balance of the product, in its own `currency`.
          examples:
          - 15234.67
        balanceCreditGranted:
          anyOf:
          - type: number
          - type: 'null'
          title: Balancecreditgranted
          description: Total credit limit granted on the product (e.g. for lines of credit).
          examples:
          - 50000.0
        countableBalance:
          anyOf:
          - type: number
          - type: 'null'
          title: Countablebalance
          description: Balance used for reporting purposes. Defaults to `balance` when the bank does not report a countable balance, or reports it as zero.
          examples:
          - 15234.67
        arrangedBalance:
          anyOf:
          - type: number
          - type: 'null'
          title: Arrangedbalance
          description: Arranged balance of the product (e.g. amount drawn against a credit line), as reported by the bank.
          examples:
          - 10000.0
        updatedAt:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: Updatedat
          description: Last time this product was updated in Embat.
        createdAt:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: Createdat
          description: Date this product was created in Embat.
        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
        iban:
          anyOf:
          - type: string
          - type: 'null'
          title: Iban
          description: IBAN or account number identifying the product.
          examples:
          - ES9121000418450200051332
        type:
          type: string
          title: Type
          description: Product type reported by the bank, e.g. `checking`, `savings`, `card`, `loan`, `lineofcredit` or `wallet`.
          examples:
          - checking
        alias:
          anyOf:
          - type: string
          - type: 'null'
          title: Alias
          description: Custom alias given to the product in Embat, if any.
          examples:
          - Main checking account
        description:
          anyOf:
          - type: string
          - type: 'null'
          title: Description
          description: Description of the product as reported by the bank.
        notes:
          anyOf:
          - type: string
          - type: 'null'
          title: Notes
          description: Notes attached to the product in Embat. Falls back to `description` when not set.
        bank:
          type: string
          title: Bank
          description: Identifier of the bank providing this product.
          examples:
          - bbva
        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
        additionalInfo:
          anyOf:
          - additionalProperties: true
            type: object
          - type: 'null'
          title: Additionalinfo
          description: Free-form key/value metadata attached to the product.
        hasTransactions:
          anyOf:
          - type: boolean
          - type: 'null'
          title: Hastransactions
          description: 'Whether the product supports bank transactions. Always recomputed by Embat: `true` for `checking`, `lineofcredit`, `card` and `wallet` products, `false` otherwise.'
        manual:
          type: boolean
          title: Manual
          description: Whether the product was added manually, rather than aggregated from a bank connection.
          default: false
        tags:
          anyOf:
          - items:
              type: string
            type: array
          - type: 'null'
          title: Tags
          description: Custom tags assigned to the product in Embat.
        financialDetails:
          anyOf:
          - additionalProperties: true
            type: object
          - type: 'null'
          title: Financialdetails
          description: Additional financial detail attributes reported for the product.
        reconciliation:
          anyOf:
          - $ref: '#/components/schemas/ReconciliationSchema'
          - type: 'null'
          description: Reconciliation status of the accounting account linked to this product via `accountingCode`. `null` when the product has no `accountingCode` or when no accounting account matches it.
      type: object
      required:
      - id
      - bankId
      - companyId
      - currency
      - product
      - type
      - bank
      title: GetProductsResponseSchema
    AuxBulkPatchProductsRequestSchema:
      properties:
        additionalInfo:
          additionalProperties: true
          type: object
          title: Additionalinfo
          description: Free-form key/value metadata to attach to the product. Replaces the existing value entirely.
          default: {}
        accountingCode:
          anyOf:
          - type: string
          - type: 'null'
          title: Accountingcode
          description: Accounting account code to link the product to.
          examples:
          - '5720001'
        id:
          type: string
          title: Id
          description: Embat product ID
      type: object
      required:
      - id
      title: AuxBulkPatchProductsRequestSchema
    ListProductsResponseSchema:
      properties:
        data:
          items:
            $ref: '#/components/schemas/GetProductsResponseSchema'
          type: array
          title: Data
          description: Products of the company.
      type: object
      required:
      - data
      title: ListProductsResponseSchema
  securitySchemes:
    HTTPBearer:
      type: http
      scheme: bearer