Ntropy Bank statements API

openapi: 3.1.0
info:
  title: API Reference Account Holder Bank statements API
  version: 1.0.0
  description: Ledger operations
servers:
- url: https://api.ntropy.com
  description: Production server (uses live data).
tags:
- name: Bank statements
  description: '

    The bank statements API allows you to view and enrich transactions found in bank statements. Below is a table with

    the description of each of the statuses and steps that each bank statement goes through:

    |  Status  |                          Description                           |

    |----------|----------------------------------------------------------------|

    |QUEUED    |The document is queued for processing                           |

    |PROCESSING|OCR is in progress                                              |

    |PROCESSED |The document was successfully processed                         |

    |FAILED    |An error occurred during processing of any of the previous steps|




    A list of error codes for the `FAILED` status can be found below:

    |Code|                  Description                   |

    |---:|------------------------------------------------|

    | 301|Failed to parse document as bank statement.     |

    | 301|Failed to enrich transactions in bank statement.|

    | 500|Unexpected error. Please contact support.       |


    '
paths:
  /datasources/bank_statements:
    post:
      tags:
      - Bank statements
      summary: Submit a bank statement PDF for OCR and enrichment
      description: Creates a new dataset from a bank statement and queues it for enrichment. The maximum size of the statement must be less than 50.0 MB
      operationId: _post_bank_statement_datasources_bank_statements_post
      security:
      - APIKeyHeader: []
        AppIdHeader: []
      parameters:
      - name: account_holder_id
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: ID for account holder. If no account holder with the given id exists, one will be created with `account_type` or "business" if not specified.
          title: Account Holder Id
        description: ID for account holder. If no account holder with the given id exists, one will be created with `account_type` or "business" if not specified.
      - name: account_type
        in: query
        required: false
        schema:
          anyOf:
          - $ref: '#/components/schemas/ntropy_core__db__account_holder_type__AccountHolderType'
          - type: 'null'
          description: Type of account holder to use when it is being created. Otherwise it'll override the type of the existing one for the transactions on this bank statement.
          title: Account Type
        description: Type of account holder to use when it is being created. Otherwise it'll override the type of the existing one for the transactions on this bank statement.
      - name: iso_currency_code
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: The currency of transactions in the bank statement in ISO 4217 format. Defaults to `USD`
          title: Iso Currency Code
        description: The currency of transactions in the bank statement in ISO 4217 format. Defaults to `USD`
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/Body__post_bank_statement_datasources_bank_statements_post'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BankStatementExternal'
        '401':
          description:
            details: User not authorized for requested operation
        '415':
          description:
            details: File type not supported
        '500':
          description:
            details: Internal server error
        '413':
          description:
            details: File has too many pages or is too long
        '429':
          description:
            details: You have submitted too many pages in a short amount of time
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    get:
      tags:
      - Bank statements
      summary: Check paginated processing status for bank statements
      operationId: _get_bank_statements_datasources_bank_statements_get
      security:
      - APIKeyHeader: []
        AppIdHeader: []
      parameters:
      - name: status
        in: query
        required: false
        schema:
          anyOf:
          - $ref: '#/components/schemas/DocumentStatus'
          - type: 'null'
          description: The status of the document to filter on
          title: Status
        description: The status of the document to filter on
      - name: account_holder_id
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: "\n    The unique ID of the account holder to which the bank statement is associated\n    "
          title: Account Holder Id
        description: "\n    The unique ID of the account holder to which the bank statement is associated\n    "
      - name: page
        in: query
        required: false
        schema:
          type: integer
          minimum: 0
          description: The page number to retrieve
          default: 0
          title: Page
        description: The page number to retrieve
      - name: per_page
        in: query
        required: false
        schema:
          type: integer
          minimum: 1
          exclusiveMaximum: 1000
          description: The page size to retrieve
          default: 20
          title: Per Page
        description: The page size to retrieve
      - name: order_by
        in: query
        required: false
        schema:
          enum:
          - desc
          - asc
          type: string
          description: The sorting order by creation
          default: desc
          title: Order By
        description: The sorting order by creation
      - name: query
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Query
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/BankStatementExternal'
                title: Response  Get Bank Statements Datasources Bank Statements Get
        '401':
          description:
            details: User not authorized for requested operation
        '404':
          description:
            details: Resource not found
        '500':
          description:
            details: Internal server error
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /datasources/bank_statements/{uuid}:
    get:
      tags:
      - Bank statements
      summary: Check processing status for a bank statement
      operationId: _get_bank_statement_datasources_bank_statements__uuid__get
      security:
      - APIKeyHeader: []
        AppIdHeader: []
      parameters:
      - name: uuid
        in: path
        required: true
        schema:
          type: string
          description: The unique ID of the bank statement
          title: Uuid
        description: The unique ID of the bank statement
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BankStatementExternal'
        '401':
          description:
            details: User not authorized for requested operation
        '404':
          description:
            details: Resource not found
        '500':
          description:
            details: Internal server error
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    delete:
      tags:
      - Bank statements
      summary: Delete a bank statement
      description: Deletes a bank statement and all its underlying transactions
      operationId: _delete_bank_statement_datasources_bank_statements__uuid__delete
      security:
      - APIKeyHeader: []
        AppIdHeader: []
      parameters:
      - name: uuid
        in: path
        required: true
        schema:
          type: string
          title: Uuid
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '401':
          description:
            details: User not authorized for requested operation
        '404':
          description:
            details: Resource not found
        '500':
          description:
            details: Internal server error
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    patch:
      tags:
      - Bank statements
      summary: Change information of an existing bank statement
      operationId: patch_statement_datasources_bank_statements__uuid__patch
      security:
      - APIKeyHeader: []
        AppIdHeader: []
      parameters:
      - name: uuid
        in: path
        required: true
        schema:
          type: string
          title: Uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Body_patch_statement_datasources_bank_statements__uuid__patch'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '401':
          description:
            details: User not authorized for requested operation
        '404':
          description:
            details: Resource not found
        '500':
          description:
            details: Internal server error
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /datasources/bank_statements/{uuid}/transactions:
    get:
      tags:
      - Bank statements
      summary: Gets the enriched transactions for a bank statement
      operationId: get_bank_statement_transactions_datasources_bank_statements__uuid__transactions_get
      security:
      - APIKeyHeader: []
        AppIdHeader: []
      parameters:
      - name: uuid
        in: path
        required: true
        schema:
          type: string
          title: Uuid
      - name: page
        in: query
        required: false
        schema:
          type: integer
          description: Page number
          default: 0
          title: Page
        description: Page number
      - name: per_page
        in: query
        required: false
        schema:
          type: integer
          maximum: 1000
          minimum: 1
          description: How many items per page
          default: 100
          title: Per Page
        description: How many items per page
      - name: sort_by
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: Column to sort items by, allowed values are `['date']`. When not specified the default order will be used.
          title: Sort By
        description: Column to sort items by, allowed values are `['date']`. When not specified the default order will be used.
      - name: sort_order
        in: query
        required: false
        schema:
          $ref: '#/components/schemas/SortOrder'
          description: Sorting direction `asc` or `desc`
          default: desc
        description: Sorting direction `asc` or `desc`
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/AccountHolderTransactionWithErrors'
                title: Response Get Bank Statement Transactions Datasources Bank Statements  Uuid  Transactions Get
        '401':
          description:
            details: User not authorized for requested operation
        '404':
          description:
            details: Resource not found
        '500':
          description:
            details: Internal server error
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /datasources/bank_statements/{uuid}/statement-info:
    get:
      tags:
      - Bank statements
      summary: Extracts bank and account details for instant file verification and UI enhancements.
      description: "Statement Info endpoint is a low-latency response analysing the first page of a bank statement which returns \n    key identification details such as the underlying bank institution and the account-holder.\n    The can be used for UX improvements through instant verification of correct file upload, for UI improvements \n    like returning bank names and logos, or for logging information about a file upon upload."
      operationId: get_bank_statement_statement_info_datasources_bank_statements__uuid__statement_info_get
      security:
      - APIKeyHeader: []
        AppIdHeader: []
      parameters:
      - name: uuid
        in: path
        required: true
        schema:
          type: string
          title: Uuid
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StatementInfo'
        '401':
          description:
            details: User not authorized for requested operation
        '404':
          description:
            details: Resource not found
        '500':
          description:
            details: Internal server error
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /datasources/bank_statements/{uuid}/results:
    get:
      tags:
      - Bank statements
      summary: ' Get Bank Statement Results'
      description: Return the extracted account information and associated transactions from a bank statement PDF. The results are accessible once the statement's status is `processed`.
      operationId: _get_bank_statement_results_datasources_bank_statements__uuid__results_get
      security:
      - APIKeyHeader: []
        AppIdHeader: []
      parameters:
      - name: uuid
        in: path
        required: true
        schema:
          type: string
          title: Uuid
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BankStatementResults'
        '401':
          description:
            details: User not authorized for requested operation
        '404':
          description:
            details: Resource not found
        '500':
          description:
            details: Internal server error
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
components:
  schemas:
    ntropy_core__db__statements__AccountHolder:
      properties:
        type:
          anyOf:
          - $ref: '#/components/schemas/AccountType'
          - type: 'null'
        name:
          anyOf:
          - type: string
          - type: 'null'
          title: Name
        address:
          anyOf:
          - $ref: '#/components/schemas/Address'
          - type: 'null'
      type: object
      title: AccountHolder
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
            - type: string
            - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
      type: object
      required:
      - loc
      - msg
      - type
      title: ValidationError
    BankStatementFile:
      properties:
        no_pages:
          type: integer
          title: No Pages
        size:
          type: integer
          title: Size
      type: object
      required:
      - no_pages
      - size
      title: BankStatementFile
    BankStatementTransaction:
      properties:
        date:
          type: string
          format: date
          title: Date
          description: The date that the transaction was posted. Uses ISO 8601 format (YYYY-MM-DD)
        entry_type:
          $ref: '#/components/schemas/EntryType-Output'
          description: The direction of the transaction (incoming or outgoing)
        amount:
          type: number
          minimum: 0.0
          title: Amount
          description: The amount of the transaction
        running_balance:
          anyOf:
          - type: number
          - type: 'null'
          title: Running Balance
        iso_currency_code:
          type: string
          title: Iso Currency Code
          description: The currency of the transaction in ISO 4217 format
        description:
          type: string
          maxLength: 1024
          minLength: 0
          title: Description
          description: The description string of the transaction
        transaction_id:
          type: string
          minLength: 1
          title: Transaction Id
          description: A unique identifier of the transaction
        page_number:
          anyOf:
          - type: integer
          - type: 'null'
          title: Page Number
          description: The page number this transaction appears on, where 1 is the first page.
      type: object
      required:
      - date
      - entry_type
      - amount
      - iso_currency_code
      - description
      - transaction_id
      title: BankStatementTransaction
    Address:
      properties:
        street:
          anyOf:
          - type: string
          - type: 'null'
          title: Street
        postcode:
          anyOf:
          - type: string
          - type: 'null'
          title: Postcode
        city:
          anyOf:
          - type: string
          - type: 'null'
          title: City
        state:
          anyOf:
          - type: string
          - type: 'null'
          title: State
        country:
          anyOf:
          - type: string
          - type: 'null'
          title: Country
      type: object
      title: Address
    BankStatementBankAccount:
      properties:
        name:
          anyOf:
          - type: string
          - type: 'null'
          title: Name
        bank_name:
          anyOf:
          - type: string
          - type: 'null'
          title: Bank Name
        account_holder:
          anyOf:
          - type: string
          - type: 'null'
          title: Account Holder
        account_number:
          anyOf:
          - type: string
          - type: 'null'
          title: Account Number
      type: object
      title: BankStatementBankAccount
    DocumentStatus:
      type: string
      enum:
      - queued
      - processing
      - processed
      - failed
      title: DocumentStatus
    TransactionType:
      type: string
      enum:
      - business
      - consumer
      - unknown
      title: TransactionType
    AccountHolderTransactionWithErrors:
      properties:
        transaction_id:
          type: string
          title: Transaction Id
        account_holder_id:
          anyOf:
          - type: string
            maxLength: 256
            minLength: 1
          - type: 'null'
          title: Account Holder Id
          description: The unique ID of the account holder of the transaction
        account_holder_type:
          anyOf:
          - $ref: '#/components/schemas/ntropy_core__db__account_holder_type__AccountHolderType'
          - type: 'null'
          description: The type of an account holder, may be one of 'consumer', 'business' or 'unknown'. Only used when create_account_holder is true.
        amount:
          type: number
          minimum: 0.0
          title: Amount
          description: The amount of the transaction
        entry_type:
          $ref: '#/components/schemas/EntryType-Output'
          description: The direction of the transaction (incoming or outgoing)
        date:
          type: string
          format: date
          title: Date
          description: The date that the transaction was posted. Uses ISO 8601 format (YYYY-MM-DD)
        iso_currency_code:
          type: string
          title: Iso Currency Code
          description: The currency of the transaction in ISO 4217 format
        description:
          type: string
          maxLength: 1024
          minLength: 0
          title: Description
          description: The description string of the transaction
        location:
          anyOf:
          - type: string
          - type: 'null'
          title: Location
        country:
          anyOf:
          - type: string
            pattern: '[A-Z]{2}(-[A-Z0-9]{1,3})?'
          - type: 'null'
          title: Country
          description: The country where the transaction was made in ISO 3166-2 format
        mcc:
          anyOf:
          - items:
              type: integer
            type: array
          - type: 'null'
          title: Mcc
        account_holder_name:
          anyOf:
          - type: string
            maxLength: 1024
            minLength: 0
          - type: 'null'
          title: Account Holder Name
          description: The name of the account holder
        logo:
          anyOf:
          - type: string
          - type: 'null'
          title: Logo
        website:
          anyOf:
          - type: string
          - type: 'null'
          title: Website
        location_structured:
          anyOf:
          - $ref: '#/components/schemas/LocationStructuredPublic'
          - type: 'null'
        merchant:
          anyOf:
          - type: string
          - type: 'null'
          title: Merchant
        merchant_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Merchant Id
        labels:
          anyOf:
          - items:
              type: string
            type: array
          - type: 'null'
          title: Labels
        recurrence:
          anyOf:
          - $ref: '#/components/schemas/RecurrenceType'
          - type: 'null'
        recurrence_group:
          anyOf:
          - $ref: '#/components/schemas/RecurrenceGroup'
          - type: 'null'
        recurrence_group_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Recurrence Group Id
        person:
          anyOf:
          - type: string
          - type: 'null'
          title: Person
        transaction_type:
          anyOf:
          - $ref: '#/components/schemas/TransactionType'
          - type: 'null'
        intermediaries:
          anyOf:
          - items:
              $ref: '#/components/schemas/EntityOut'
            type: array
          - type: 'null'
          title: Intermediaries
        error:
          anyOf:
          - type: string
          - type: 'null'
          title: Error
        error_details:
          anyOf:
          - type: string
          - type: 'null'
          title: Error Details
      additionalProperties: true
      type: object
      required:
      - transaction_id
      - amount
      - entry_type
      - date
      - iso_currency_code
      - description
      title: AccountHolderTransactionWithErrors
      examples:
      - intermediaries:
        - id: 916bc837-55ef-3106-88f6-5a8269ca9f2a
          logo: https://logos.ntropy.com/squareup.com
          name: Square
          website: squareup.com
        labels:
        - Cafes and coffee shop
        location: 10 Union Square East, New York, New York 10003, US
        location_structured:
          address: 10 Union Square East
          apple_maps_url: https://maps.apple.com/?q=Starbucks+10+Union+Square+East&sll=40.734834,-73.989782
          city: New York
          country: US
          country_name: United States
          google_maps_url: https://www.google.com/maps/search/?api=1&query=Starbucks%2C10+Union+Square+East%2C+New+York%2C+New+York+10003%2C+US
          latitude: '48.734834'
          longitude: '-73.989782'
          postcode: '10003'
          state: New York
        logo: https://logo.clearbit.com/aws.amazon.com
        merchant: Starbucks
        merchant_id: d4bc3c80-ec1a-3da2-836e-2a4ca4758be5
        recurrence: recurring
        recurrence_group:
          average_amount: 10.0
          first_payment_date: '2020-02-02'
          id: 3b0c689b-e123-30a6-9f53-878f3ebf46aa
          latest_payment_date: '2022-02-02'
          other_party: starbucks.com
          periodicity: monthly
          periodicity_in_days: 31
          total_amount: 240.0
          transaction_ids:
          - b708fbd8-be76-41c2-86d5-83f8ba05ed85
          - 0e34b24d-646d-416e-8d51-fda5b6e10684
        recurrence_group_id: 3b0c689b-e123-30a6-9f53-878f3ebf46aa
        transaction_id: xbx8YP14g565Xk
        website: starbucks.com
    BankStatementExternal:
      properties:
        id:
          type: string
          title: Id
        name:
          anyOf:
          - type: string
          - type: 'null'
          title: Name
        size:
          anyOf:
          - type: integer
          - type: 'null'
          title: Size
        created_at:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: Created At
        account_holder_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Account Holder Id
        account_type:
          $ref: '#/components/schemas/ntropy_core__db__account_holder_type__AccountHolderType'
        status:
          $ref: '#/components/schemas/DocumentStatus'
        bank_accounts:
          anyOf:
          - items:
              $ref: '#/components/schemas/BankStatementBankAccount'
            type: array
          - type: 'null'
          title: Bank Accounts
        statements:
          anyOf:
          - items:
              $ref: '#/components/schemas/BankStatementStatement'
            type: array
          - type: 'null'
          title: Statements
        error_code:
          anyOf:
          - type: integer
          - type: 'null'
          title: Error Code
        error:
          anyOf:
          - type: string
          - type: 'null'
          title: Error
        complete:
          type: boolean
          title: Complete
        batch_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Batch Id
        file:
          $ref: '#/components/schemas/BankStatementFile'
      type: object
      required:
      - id
      - account_type
      - status
      - complete
      - file
      title: BankStatementExternal
    Body__post_bank_statement_datasources_bank_statements_post:
      properties:
        file:
          type: string
          format: binary
          title: File
      type: object
      required:
      - file
      title: Body__post_bank_statement_datasources_bank_statements_post
    Account:
      properties:
        type:
          anyOf:
          - type: string
          - type: 'null'
          title: Type
        number:
          anyOf:
          - type: string
          - type: 'null'
          title: Number
        opening_balance:
          anyOf:
          - type: number
          - type: 'null'
          title: Opening Balance
        closing_balance:
          anyOf:
          - type: number
          - type: 'null'
          title: Closing Balance
        iso_currency_code:
          anyOf:
          - type: string
          - type: 'null'
          title: Iso Currency Code
      type: object
      title: Account
    EntryType-Output:
      type: string
      enum:
      - incoming
      - outgoing
      title: EntryType
    LocationStructuredPublic:
      properties:
        address:
          anyOf:
          - type: string
          - type: 'null'
          title: Address
        city:
          anyOf:
          - type: string
          - type: 'null'
          title: City
        state:
          anyOf:
          - type: string
          - type: 'null'
          title: State
        postcode:
          anyOf:
          - type: string
          - type: 'null'
          title: Postcode
        country:
          anyOf:
          - type: string
          - type: 'null'
          title: Country
        country_name:
          anyOf:
          - type: string
          - type: 'null'
          title: Country Name
        latitude:
          anyOf:
          - type: number
          - type: 'null'
          title: Latitude
        longitude:
          anyOf:
          - type: number
          - type: 'null'
          title: Longitude
        google_maps_url:
          anyOf:
          - type: string
          - type: 'null'
          title: Google Maps Url
        apple_maps_url:
          anyOf:
          - type: string
          - type: 'null'
          title: Apple Maps Url
        store_number:
          anyOf:
          - type: string
          - type: 'null'
          title: Store Number
        house_number:
          anyOf:
          - type: string
          - type: 'null'
          title: House Number
      type: object
      title: LocationStructuredPublic
    BankStatementAccount:
      properties:
        number:
          anyOf:
          - type: string
          - type: 'null'
          title: Number
        opening_balance:
          anyOf:
          - type: number
          - type: 'null'
          title: Opening Balance
        closing_balance:
          anyOf:
          - type: number
          - type: 'null'
          title: Closing Balance
        start_date:
          anyOf:
          - type: string
            format: date
          - type: 'null'
          title: Start Date
        end_date:
          anyOf:
          - type: string
            format: date
          - type: 'null'
          title: End Date
        is_balance_reconciled:
          anyOf:
          - type: boolean
          - type: 'null'
          title: Is Balance Reconciled
        transactions:
          items:
            $ref: '#/components/schemas/BankStatementTransaction'
          type: array
          title: Transactions
        total_incoming:
          anyOf:
          - type: number
          - type: 'null'
          title: Total Incoming
        total_outgoing:
          anyOf:
          - type: number
          - type: 'null'
          title: Total Outgoing
      type: object
      required:
      - transactions
      title: BankStatementAccount
    StatementInfo:
      properties:
        institution:
          anyOf:
          - type: string
          - type: 'null'
          title: Institution
        start_date:
          anyOf:
          - type: string
            format: date
          - type: 'null'
          title: Start Date
        end_date:
          anyOf:
          - type: string
            format: date
          - type: 'null'
          title: End Date
        account_holder:
          anyOf:
          - $ref: '#/components/schemas/ntropy_core__db__statements__AccountHolder'
          - type: 'null'
        accounts:
          anyOf:
          - items:
              $ref: '#/components/schemas/Account'
            type: array
          - type: 'null'
          title: Accounts
      type: object
      title: StatementInfo
      examples:
      - account_holder:
          address:
            city: Victoria
            country: United 

# --- truncated at 32 KB (36 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/ntropy/refs/heads/main/openapi/ntropy-bank-statements-api-openapi.yml