Embat Accounting Entries API

openapi: 3.2.0
info:
  title: Embat Accounting Entries 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: Accounting Entries
  description: '`AccountingEntry` represents a single line of a company''s general accounting journal — an outflow (`assetAmount`) or inflow (`liabilityAmount`) movement posted to a ledger account (`accountingCode`).'
paths:
  /accountingentries/{companyId}:
    get:
      tags:
      - Accounting Entries
      summary: List accounting entries
      description: 'Returns the accounting entries of a company, ordered by accounting date (most recent first). Results are paginated: use `limit` to control page size and pass the returned `nextPageToken` to fetch the next page. `startDate`/`endDate` filter by accounting date, and `startUpdatedAt`/`endUpdatedAt` filter by last modification time, useful for incremental synchronization. `startDate`/`startUpdatedAt` are inclusive, `endDate`/`endUpdatedAt` are exclusive, and each date range spans at most 90 days. If neither `startDate` nor `endDate` is given, only entries dated up to today are returned.'
      operationId: list_accounting_entries_accountingentries__companyId__get
      security:
      - HTTPBearer: []
      parameters:
      - name: companyId
        in: path
        required: true
        schema:
          type: string
          title: Companyid
      - name: reconciled
        in: query
        required: false
        schema:
          type: boolean
          description: Filter by reconciliation status. `false` also matches entries that are not yet reconciled or have no status set.
          title: Reconciled
        description: Filter by reconciliation status. `false` also matches entries that are not yet reconciled or have no status set.
      - name: accountingCode
        in: query
        required: false
        schema:
          type: string
          description: Filter by ledger account code (`accountingCode`).
          title: Accountingcode
        description: Filter by ledger account code (`accountingCode`).
      - name: accountingEntryCode
        in: query
        required: false
        schema:
          type: string
          description: Filter by `accountingEntryCode` (does not match `accountingEntryCodeId`).
          title: Accountingentrycode
        description: Filter by `accountingEntryCode` (does not match `accountingEntryCodeId`).
      - name: startDate
        in: query
        required: false
        schema:
          type: string
          format: date
          description: 'Only return entries 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 entries 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 entries 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 entries 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: startUpdatedAt
        in: query
        required: false
        schema:
          type: string
          format: date-time
          description: 'Only return entries last modified on or after this timestamp (inclusive). The range cannot exceed 90 days: if `endUpdatedAt` is also given, the span between the two cannot exceed 90 days; if `endUpdatedAt` is omitted, `startUpdatedAt` cannot be more than 90 days in the past.'
          title: Startupdatedat
        description: 'Only return entries last modified on or after this timestamp (inclusive). The range cannot exceed 90 days: if `endUpdatedAt` is also given, the span between the two cannot exceed 90 days; if `endUpdatedAt` is omitted, `startUpdatedAt` cannot be more than 90 days in the past.'
      - name: endUpdatedAt
        in: query
        required: false
        schema:
          type: string
          format: date-time
          description: Only return entries last modified before this timestamp (exclusive). Combined with `startUpdatedAt`, the range cannot exceed 90 days. If used without `startUpdatedAt`, results start 90 days before this timestamp.
          title: Endupdatedat
        description: Only return entries last modified before this timestamp (exclusive). Combined with `startUpdatedAt`, the range cannot exceed 90 days. If used without `startUpdatedAt`, results start 90 days before this timestamp.
      - 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/ListAccountingEntriesResponseSchema'
        '400':
          description: 'Invalid date range: when only a start bound (`startDate` or `startUpdatedAt`) 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, invalid `nextPageToken`, or an invalid date range when both bounds 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'
    post:
      tags:
      - Accounting Entries
      summary: Create accounting entry
      description: Creates a single accounting entry (one line of a general ledger journal). If `customId` is omitted, Embat auto-generates one; if the `customId` already exists, the entry is updated instead of duplicated (upsert). An entry always carries both an outflow side (`assetAmount`, stored with its sign inverted so negative means money out) and an inflow side (`liabilityAmount`, stored as sent); if you only send one, the other defaults to 0. If `description` is omitted, Embat generates one from the entry's identifier. Entries dated before the ledger account's configured start date are excluded from reconciliation matching.
      operationId: create_accounting_entry_accountingentries__companyId__post
      security:
      - HTTPBearer: []
      parameters:
      - name: companyId
        in: path
        required: true
        schema:
          type: string
          title: Companyid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostAccountingEntriesRequestSchema'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UpsertAccountingEntriesResponseSchema'
        '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'
    patch:
      tags:
      - Accounting Entries
      summary: Update accounting entries in bulk
      description: Updates one or more fields of several accounting entries, identified by `customId`, following the same rules as the single-entry update endpoint — including the `description` reset-when-omitted behavior. Entries whose `customId` does not match any existing entry are silently skipped; the call still returns `200` for the whole batch.
      operationId: update_accounting_entries_bulk_accountingentries__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/BulkPatchAccountingEntriesRequestSchema'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BulkUpsertAccountingEntriesResponseSchema'
        '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'
    delete:
      tags:
      - Accounting Entries
      summary: Delete accounting entries in bulk
      description: Deletes several accounting entries in a single call, identified by `customId`. The call returns `200` immediately — even for `customId` values that do not match any existing entry — and entries may still briefly appear in `GET` results right after deletion.
      operationId: delete_accounting_entries_bulk_accountingentries__companyId__delete
      security:
      - HTTPBearer: []
      parameters:
      - name: companyId
        in: path
        required: true
        schema:
          type: string
          title: Companyid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BulkDeleteAccountingEntriesRequestSchema'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BulkModifyAccountingEntriesResponseSchema'
        '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'
  /accountingentries/{companyId}/{customId}:
    get:
      tags:
      - Accounting Entries
      summary: Retrieve accounting entry
      description: Returns a single accounting entry by `customId`.
      operationId: retrieve_accounting_entry_accountingentries__companyId___customId__get
      security:
      - HTTPBearer: []
      parameters:
      - name: customId
        in: path
        required: true
        schema:
          type: string
          title: Customid
      - name: companyId
        in: path
        required: true
        schema:
          type: string
          title: Companyid
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetAccountingEntriesResponseSchema'
        '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 accounting entry matches the given `customId`.
          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:
      - Accounting Entries
      summary: Update accounting entry
      description: 'Updates one or more fields of an accounting entry identified by `customId`. Only the fields you send are changed — except `description`: if it is omitted, Embat resets it to an auto-generated value derived from the entry''s identifier, overwriting any previously set custom description; resend the current value to keep it unchanged. Updating a `customId` that does not match any existing entry is a no-op: the call still returns `200` without creating or changing anything, and no `404` is raised.'
      operationId: update_accounting_entry_accountingentries__companyId___customId__patch
      security:
      - HTTPBearer: []
      parameters:
      - name: customId
        in: path
        required: true
        schema:
          type: string
          title: Customid
      - name: companyId
        in: path
        required: true
        schema:
          type: string
          title: Companyid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PatchAccountingEntriesRequestSchema'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UpsertAccountingEntriesResponseSchema'
        '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'
    delete:
      tags:
      - Accounting Entries
      summary: Delete accounting entry
      description: Deletes an accounting entry by `customId`. The call returns `200` immediately — even if `customId` does not match any existing entry — and the entry may still briefly appear in `GET` results right after deletion.
      operationId: delete_accounting_entry_accountingentries__companyId___customId__delete
      security:
      - HTTPBearer: []
      parameters:
      - name: customId
        in: path
        required: true
        schema:
          type: string
          title: Customid
      - name: companyId
        in: path
        required: true
        schema:
          type: string
          title: Companyid
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ModifyAccountingEntriesResponseSchema'
        '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'
  /accountingentries/{companyId}/bulk:
    post:
      tags:
      - Accounting Entries
      summary: Create accounting entries in bulk
      description: Creates several accounting entries in a single call, following the same rules as the single entry creation endpoint. Entries sharing the same `customId` within the request are deduplicated and only the first occurrence is processed.
      operationId: create_accounting_entries_bulk_accountingentries__companyId__bulk_post
      security:
      - HTTPBearer: []
      parameters:
      - name: companyId
        in: path
        required: true
        schema:
          type: string
          title: Companyid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BulkPostAccountingEntriesRequestSchema'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BulkUpsertAccountingEntriesResponseSchema'
        '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'
  /accountingentries/accountingentrycode/{companyId}:
    delete:
      tags:
      - Accounting Entries
      summary: Delete accounting entries in bulk by entry code
      description: Deletes every accounting entry whose `accountingEntryCode` or `accountingEntryCodeId` matches one of the given codes. The call returns `200` immediately; matching entries may still briefly appear in `GET` results right after deletion.
      operationId: delete_accounting_entries_bulk_by_entry_code_accountingentries_accountingentrycode__companyId__delete
      security:
      - HTTPBearer: []
      parameters:
      - name: companyId
        in: path
        required: true
        schema:
          type: string
          title: Companyid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BulkDeleteAccountingEntriesEntryCodeRequestSchema'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BulkModifyAccountingEntriesResponseSchema'
        '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:
    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
    BulkDeleteAccountingEntriesEntryCodeRequestSchema:
      properties:
        data:
          items:
            $ref: '#/components/schemas/DeleteAccountingEntriesEntryCodeRequestSchema'
          type: array
          title: Data
          description: Entry codes to delete by.
      type: object
      required:
      - data
      title: BulkDeleteAccountingEntriesEntryCodeRequestSchema
    AccountingTypeEnum:
      type: string
      enum:
      - banks
      - analytics
      - accountings
      title: AccountingTypeEnum
    PatchAccountingEntriesRequestSchema:
      properties:
        accountingCode:
          anyOf:
          - type: string
          - type: 'null'
          title: Accountingcode
          description: Ledger account code the entry is posted to.
          examples:
          - '4300001'
        counterpartAccountingCode:
          anyOf:
          - type: string
          - type: 'null'
          title: Counterpartaccountingcode
          description: Ledger account code of the counterpart side of the entry, when applicable.
          examples:
          - '5720001'
        accountingName:
          anyOf:
          - type: string
          - type: 'null'
          title: Accountingname
          description: Display name of the ledger account (`accountingCode`).
          examples:
          - Trade debtors
        assetAmount:
          anyOf:
          - type: number
          - type: 'null'
          title: Assetamount
          description: 'Outflow side of the entry, in `currency` (money leaving the account, e.g. a supplier payment). An entry always has both sides: if you set only `assetAmount` or only `liabilityAmount`, the other one defaults to 0. The sign is inverted on storage (0 always stays 0): a positive value you send is stored and returned as negative, following the convention that negative amounts are outflows.'
          examples:
          - 1250.5
        accountingAssetAmount:
          anyOf:
          - type: number
          - type: 'null'
          title: Accountingassetamount
          description: Outflow side expressed in the company accounting currency (`accountingCurrency`). Subject to the same sign convention as `assetAmount`.
          examples:
          - 1250.5
        balance:
          anyOf:
          - type: number
          - type: 'null'
          title: Balance
          description: Running balance of the ledger account (`accountingCode`) after this entry, typically calculated by Embat rather than provided by you.
        liabilityAmount:
          anyOf:
          - type: number
          - type: 'null'
          title: Liabilityamount
          description: 'Inflow side of the entry, in `currency` (money entering the account, e.g. a customer collection), stored with the sign you send. An entry always has both sides: if you set only `assetAmount` or only `liabilityAmount`, the other one defaults to 0.'
          examples:
          - 0.0
        accountingLiabilityAmount:
          anyOf:
          - type: number
          - type: 'null'
          title: Accountingliabilityamount
          description: Inflow side expressed in the company accounting currency (`accountingCurrency`).
          examples:
          - 0.0
        currency:
          anyOf:
          - $ref: '#/components/schemas/CurrencyEnum'
          - type: 'null'
          description: ISO currency code of `assetAmount`/`liabilityAmount`.
          examples:
          - EUR
        accountingCurrency:
          anyOf:
          - $ref: '#/components/schemas/CurrencyEnum'
          - type: 'null'
          description: ISO currency code of `accountingAssetAmount`/`accountingLiabilityAmount`.
          examples:
          - EUR
        contactCustomId:
          anyOf:
          - type: string
          - type: 'null'
          title: Contactcustomid
          description: Custom ID of the contact (client/supplier), used when `accountingCode` is a contacts ledger account.
          examples:
          - contact-001
        exchangeRate:
          anyOf:
          - type: number
          - type: 'null'
          title: Exchangerate
          description: Exchange rate applied between `currency` and `accountingCurrency`.
          examples:
          - 1.0
        additionalInfo:
          anyOf:
          - additionalProperties: true
            type: object
          - type: 'null'
          title: Additionalinfo
          description: Free-form key/value metadata to attach to the entry. Sending an empty object (`{}`) has no effect and does not clear previously stored metadata.
        description:
          anyOf:
          - type: string
          - type: 'null'
          title: Description
          description: 'Free-text description of the entry. If omitted — on both creation and update — Embat sets (or resets) it to an auto-generated value: `"Asiento "` followed by `accountingEntryCode` if set, otherwise by `customId`. On `PATCH`, this means leaving `description` out overwrites any previously set custom description; resend the current value to keep it unchanged.'
          examples:
          - 'Invoice #2024-001 posting'
        documentId:
          anyOf:
          - type: string
          - type: 'null'
          title: Documentid
          description: Identifier of the source document (e.g. invoice) this entry relates to.
        transactionsIds:
          anyOf:
          - items:
              type: string
            type: array
          - type: 'null'
          title: Transactionsids
          description: Embat IDs of the bank transactions related to this entry.
        paymentId:
          anyOf:
          - type: string
          - type: 'null'
          title: Paymentid
          description: Embat ID of the payment related to this entry.
        date:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: Date
          description: Accounting date of the entry. Send a plain date at midnight (e.g. `2024-01-15T00:00:00Z`) — sending a different time of day can shift the stored calendar date and is not fully normalized to midnight.
          examples:
          - '2024-01-15T00:00:00Z'
        attributes:
          anyOf:
          - items:
              $ref: '#/components/schemas/AttributeValueRequestSchema'
            type: array
          - type: 'null'
          title: Attributes
          description: Custom attribute values to attach to the entry. Duplicate values and attributes flagged as internal-only are omitted when the entry is returned.
      type: object
      title: PatchAccountingEntriesRequestSchema
    PostAccountingEntriesRequestSchema:
      properties:
        acco

# --- truncated at 32 KB (61 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/embat/refs/heads/main/openapi/embat-accounting-entries-api-openapi.yml