openapi: 3.2.0
info:
  contact:
    email: support@herondata.io
    name: Support
  title: Heron Data End User Data Sources API
  version: '2021-07-19'
servers:
- description: Production
  url: https://app.herondata.io
security:
- ApiKeyAuth:
  - key_XXX
tags:
- name: EndUserDataSources
paths:
  /api/data_sources/{heron_id}:
    put:
      description: 'Update a data source

        '
      parameters:
      - in: path
        name: heron_id
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EndUserDataSourceUpdateSchema'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EndUserDataSource'
          description: Ok
      security:
      - ApiKeyAuth: []
      summary: Update a data source
      tags:
      - EndUserDataSources
  /api/end_users/{end_user_id_or_heron_id}/data_source_account_summary:
    get:
      description: 'Get a list of data sources accounts & their summarised information for a company

        '
      parameters:
      - in: path
        name: end_user_id_or_heron_id
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                items:
                  $ref: '#/components/schemas/DataSourceAccountSummaryPublicSchema'
                type: array
          description: Ok
      security:
      - ApiKeyAuth: []
      summary: Get data source account summary
      tags:
      - EndUserDataSources
  /api/end_users/{end_user_id_or_heron_id}/data_sources:
    get:
      description: 'Get a list of data sources for a company

        '
      parameters:
      - in: path
        name: end_user_id_or_heron_id
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                items:
                  $ref: '#/components/schemas/EndUserDataSources'
                type: array
          description: Ok
      security:
      - ApiKeyAuth: []
      summary: Get data sources
      tags:
      - EndUserDataSources
components:
  schemas:
    EndUser1:
      properties:
        end_user_id:
          description: id defined by user; links to the end_user_id for transactions
          example: 6a1d7831-8953-4f9f-a544-423cd8f48eb6
          maxLength: 140
          minLength: 1
          type: string
        heron_id:
          description: Unique id for end user generated by Heron
          example: eus_5yWkT2NZzCevkyPwbGhn2Z
          readOnly: true
          type: string
        name:
          description: Name of end user; may help to improve categorisation accuracy
          example: Company Name Inc.
          maxLength: 128
          type:
          - string
          - 'null'
      required:
      - end_user_id
      type: object
    DataSourceMetadata:
      properties:
        currency:
          description: Currency associated with the data source entity, where applicable (e.g. pdfs)
          example: USD
          type: string
        filename:
          description: Name of the file uploaded, where applicable (e.g. pdfs)
          example: 202348_JAN_2022.pdf
          type: string
        integration_heron_id:
          description: Unique Heron ID associated with an integration
          example: itg_mRmrrcVW6tH4VrCsNdJizV
          type: string
        integration_item_id:
          description: Unique item id associated with integration link data sources
          example: Ed6bjNrDLJfGvZWwnkQlfxwoNz54B5C97ejBr
          type: string
        last_successful_sync:
          description: Last successful sync date associated with integration link data sources
          example: '2026-08-14T12:24:30.631769'
          format: date-time
          type: string
        notes:
          description: Notes associated with the data source entity, where applicable (e.g. pdfs)
          example: error with processing, 52 invalid transaction(s) extracted from statement
          type: string
        parsing_version:
          description: Parsing version associated with the data source entity, where applicable (e.g. pdfs)
          example: 1.0.0
          type: string
        sub_type:
          description: Sub type of the data source entity, where applicable (e.g. integration links)
          example: transaction
          type: string
      type: object
    EndUserDataSourceUpdateSchema:
      properties:
        is_enabled:
          default: true
          description: Whether or not the data source is enabled. If disabled, hides related transactions from analytics
          example: true
          type: boolean
      type: object
    EndUserDataSource:
      properties:
        created:
          description: When the data source was created in Heron system
          example: '2026-07-03T12:24:30.632547'
          format: date-time
          type: string
        data_source_accounts:
          description: List of data source accounts associated with the data source
          example:
          - account_id: '202348'
            anomaly_reasons:
            - Statement metadata changed
            - Manual review flagged suspicious edits
            anomaly_score: 200
            enabled: true
            max_date: '2022-01-31'
            min_date: '2022-01-01'
            num_transactions: 120
            transactions_match_balances: true
          items:
            $ref: '#/components/schemas/DataSourceAccount'
          type: array
        heron_id:
          description: Unique ID for data source generated by Heron
          example: dso_TnbTswnK8BN4y6qmGDaSku
          readOnly: true
          type: string
        is_enabled:
          default: true
          description: Whether or not the data source is enabled. If disabled, hides related transactions from analytics
          example: true
          type: boolean
        last_updated:
          description: When the data source was last updated in Heron system
          example: '2026-08-14T12:24:30.632574'
          format: date-time
          type: string
        metadata:
          allOf:
          - $ref: '#/components/schemas/DataSourceMetadata'
          description: Metadata associated with the data source
          example:
            filename: 202348_JAN_2022.pdf
            status: processed
        reference_id:
          description: Unique ID to identify the data source
          example: pdf_hUDqEpJqC35aR8RQoz3hda
          type: string
        status:
          description: Status of the data source entity, where applicable (e.g. pdfs, integration links)
          enum:
          - new
          - parsing
          - parsed
          - processed
          - human_reviewing
          - approved
          - rejected
          - failed
          - transactions_loaded
          - transactions_unloaded
          - pending
          - active
          - syncing
          - erroring
          - sync_disabled
          - deleted_in_plaid
          - unknown
          example: new
          type: string
        type:
          description: Data source type
          enum:
          - api
          - csv
          - pdf
          - integration_link
          - legacy
          - legacy_pdf
          - legacy_integration_link
          example: pdf
          type: string
      required:
      - created
      - data_source_accounts
      - heron_id
      - last_updated
      - reference_id
      - type
      type: object
    AccountBalance:
      properties:
        closing_amount:
          allOf:
          - $ref: '#/components/schemas/Money'
          description: The closing balance for the day
          example: 25000.45
        currency:
          description: Currency of the balance
          example: USD
          type: string
        date:
          description: Date of the balance
          example: '2022-01-01'
          format: date
          type: string
      required:
      - closing_amount
      type: object
    BankStatementSummaryRow:
      properties:
        actual_holdback_percentage:
          description: Actual MCA payments to revenue as % (raw repayment amounts)
          type:
          - number
          - 'null'
        additional_no_od:
          description: Overdraft-item count a bank reports as a statement value for items absent from the transaction list. These items are not included in the transaction-derived no_od field. Null when the statement does not report a count.
          type:
          - integer
          - 'null'
        average_balance:
          allOf:
          - $ref: '#/components/schemas/Money'
          description: Average balance
        average_balance_to_revenue_ratio:
          description: Average balance divided by total revenue
          type: number
        business_day_average_balance:
          allOf:
          - $ref: '#/components/schemas/Money'
          description: Average balance over weekdays excluding public holidays
        dd_reversals:
          description: Number of DD Reversals
          type: integer
        ending_balance:
          allOf:
          - $ref: '#/components/schemas/Money'
          description: Ending balance
        expected_mca_debits:
          allOf:
          - $ref: '#/components/schemas/Money'
          description: Expected MCA debits amount
        holdback_percentage:
          description: Expected MCA payments to revenue as % (with frequency multiplier)
          type:
          - number
          - 'null'
        is_mtd:
          description: Whether this row represents a month-to-date (MTD) partial statement
          type: boolean
        is_unreconcilable:
          description: True when the statement period has no usable balance data for reconciliation (e.g. an unreconciled partial-month statement)
          type:
          - boolean
          - 'null'
        low_balance_days:
          description: Number of days where end of day balance falls below low balance threshold
          type: integer
        mca_credits:
          allOf:
          - $ref: '#/components/schemas/Money'
          description: MCA credits amount
        mca_debits:
          allOf:
          - $ref: '#/components/schemas/Money'
          description: MCA debits amount
        negative_balance_days:
          description: Number of days with negative balance
          type: integer
        no_deposits:
          description: Number of deposit transactions
          type: integer
        no_mca_credits:
          description: Number of MCA credit transactions
          type: integer
        no_mca_debits:
          description: Number of MCA debit transactions
          type: integer
        no_nsf:
          description: Number of NSF transactions (unambiguous NSF-only category labels).
          type: integer
        no_od:
          description: Number of overdraft transactions (unambiguous OD-only category labels).
          type: integer
        no_od_nsf:
          description: 'Total overdraft/NSF fees: overdraft fees + NSF fees + ambiguous fees.'
          type: integer
        no_overdraft_transactions:
          description: Number of transactions where the resulting balance falls below 0
          type: integer
        no_revenue:
          description: Number of revenue transactions
          type: integer
        no_withdrawals:
          description: Number of withdrawals transactions
          type: integer
        non_revenue:
          allOf:
          - $ref: '#/components/schemas/Money'
          description: Non-revenue amount
        period_end_date:
          description: The last day covered by the statement period (e.g. a partial April statement covering Apr 1–15 has period_end_date=Apr 15, while a full April statement with data only through Apr 15 would still show Apr 30)
          format: date
          type:
          - string
          - 'null'
        period_start_date:
          description: The first day covered by the statement period (e.g. a partial April statement covering Apr 5–15 has period_start_date=Apr 5)
          format: date
          type:
          - string
          - 'null'
        starting_balance:
          allOf:
          - $ref: '#/components/schemas/Money'
          description: Starting balance for the period
        total_deposits:
          allOf:
          - $ref: '#/components/schemas/Money'
          description: Total deposit amount
        total_revenue:
          allOf:
          - $ref: '#/components/schemas/Money'
          description: Total revenue amount
        total_withdrawals:
          allOf:
          - $ref: '#/components/schemas/Money'
          description: Total withdrawal amount
      type: object
    DataSourceAccountSummaryPublicSchema:
      properties:
        data_source_account_summaries:
          items:
            $ref: '#/components/schemas/DataSourceAccountSummary'
          type: array
        end_user:
          $ref: '#/components/schemas/EndUser1'
      type: object
    DataSourceAccount:
      properties:
        account_id:
          description: Unique account id associated with the data source account
          example: '202348'
          type: string
        anomaly_reasons:
          description: Reasons associated with anomaly_score for pdf bank statement account sources
          example:
          - Statement metadata changed
          - Manual review flagged suspicious edits
          items:
            type: string
          type:
          - array
          - 'null'
        anomaly_score:
          description: For pdf bank statement account sources, where the value is between 0 and 1000, with 1000 being the most anomalous
          example: 200
          type: integer
        balances:
          description: List of balances associated with the account
          example:
          - closing_amount: 25000.45
            currency: USD
            date: '2022-01-01'
          items:
            $ref: '#/components/schemas/AccountBalance'
          type: array
        currency:
          description: Currency of the account
          example: USD
          type: string
        display_account_id:
          description: 'Human-readable account label for display: the last four digits of the account number (falling back to the account title). Not unique and not a key; use account_id to join.'
          example: '7505'
          type:
          - string
          - 'null'
        end_date:
          description: End date of the account
          example: '2022-01-31'
          format: date
          type: string
        heron_id:
          description: Unique ID for data source generated by Heron
          example: dso_bSTsiBKd9gS5GtAzg7dSAb
          type: string
        institution_name:
          description: Name of the institution
          example: Chase
          type: string
        is_enabled:
          description: Whether or not the account is enabled. If disabled, hides related transactions from analytics
          example: true
          type: boolean
        max_date:
          description: Latest date of transactions associated with the data source account
          example: '2022-01-31'
          format: date
          type: string
        min_date:
          description: Earliest date of transactions associated with the data source account
          example: '2022-01-01'
          format: date
          type: string
        name:
          description: Name of the account
          example: Checking Account
          type: string
        num_transactions:
          description: Number of transactions associated with the data source account
          example: 120
          type: integer
        number:
          description: Number of the account
          example: '123456789'
          type: string
        owner_name:
          description: Name of the account owner
          example: John Doe
          type: string
        reference_id:
          description: This is the account ID provided as part of the transaction
          example: account-202348
          type: string
        start_date:
          description: Start date of the account
          example: '2022-01-01'
          format: date
          type: string
        transactions_match_balances:
          description: For pdf bank statements, represents whether all transactions extracted match the balances extracted
          example: true
          type: boolean
        type:
          description: Type of the account
          example: Checking
          type: string
      required:
      - is_enabled
      type: object
    EndUserDataSources:
      properties:
        created:
          description: When the data source was created in Heron system
          example: '2026-07-03T12:24:30.632547'
          format: date-time
          type: string
        data_source_accounts:
          description: List of data source accounts associated with the data source
          example:
          - account_id: '202348'
            anomaly_reasons:
            - Statement metadata changed
            - Manual review flagged suspicious edits
            anomaly_score: 200
            enabled: true
            max_date: '2022-01-31'
            min_date: '2022-01-01'
            num_transactions: 120
            transactions_match_balances: true
          items:
            $ref: '#/components/schemas/EndUserDataSourceAccount'
          type: array
        heron_id:
          description: Unique ID for data source generated by Heron
          example: dso_TnbTswnK8BN4y6qmGDaSku
          readOnly: true
          type: string
        is_enabled:
          default: true
          description: Whether or not the data source is enabled. If disabled, hides related transactions from analytics
          example: true
          type: boolean
        last_updated:
          description: When the data source was last updated in Heron system
          example: '2026-08-14T12:24:30.632574'
          format: date-time
          type: string
        metadata:
          allOf:
          - $ref: '#/components/schemas/EndUserDataSourceMetadata'
          description: Metadata associated with the data source
          example:
            filename: 202348_JAN_2022.pdf
            status: processed
        reference_id:
          description: Unique ID to identify the data source
          example: pdf_hUDqEpJqC35aR8RQoz3hda
          type: string
        status:
          description: Status of the data source entity, where applicable (e.g. pdfs, integration links)
          enum:
          - new
          - parsing
          - parsed
          - processed
          - human_reviewing
          - approved
          - rejected
          - failed
          - transactions_loaded
          - transactions_unloaded
          - pending
          - active
          - syncing
          - erroring
          - sync_disabled
          - deleted_in_plaid
          - unknown
          example: new
          type: string
        type:
          description: Data source type
          enum:
          - api
          - csv
          - pdf
          - integration_link
          - legacy
          - legacy_pdf
          - legacy_integration_link
          example: pdf
          type: string
      required:
      - created
      - data_source_accounts
      - heron_id
      - last_updated
      - reference_id
      - type
      type: object
    EndUserDataSourceMetadata:
      properties:
        currency:
          description: Currency associated with the data source entity, where applicable (e.g. pdfs)
          example: USD
          type: string
        filename:
          description: Name of the file uploaded, where applicable (e.g. pdfs)
          example: 202348_JAN_2022.pdf
          type: string
        integration_heron_id:
          description: Unique Heron ID associated with an integration
          example: itg_mRmrrcVW6tH4VrCsNdJizV
          type: string
        integration_item_id:
          description: Unique item id associated with integration link data sources
          example: Ed6bjNrDLJfGvZWwnkQlfxwoNz54B5C97ejBr
          type: string
        last_successful_sync:
          description: Last successful sync date associated with integration link data sources
          example: '2026-08-14T12:24:30.631769'
          format: date-time
          type: string
        notes:
          description: Notes associated with the data source entity, where applicable (e.g. pdfs)
          example: error with processing, 52 invalid transaction(s) extracted from statement
          type: string
        parsing_version:
          description: Parsing version associated with the data source entity, where applicable (e.g. pdfs)
          example: 1.0.0
          type: string
        sub_type:
          description: Sub type of the data source entity, where applicable (e.g. integration links)
          example: transaction
          type: string
      type: object
    DataSourceAccountSummary:
      properties:
        account:
          $ref: '#/components/schemas/EndUserDataSourceAccount'
        summary:
          allOf:
          - $ref: '#/components/schemas/BankStatementSummaryRow'
      type: object
    EndUserDataSourceAccount:
      properties:
        account_id:
          description: Unique account id associated with the data source account
          example: '202348'
          type: string
        anomaly_reasons:
          description: Reasons associated with anomaly_score for pdf bank statement account sources
          example:
          - Statement metadata changed
          - Manual review flagged suspicious edits
          items:
            type: string
          type:
          - array
          - 'null'
        anomaly_score:
          description: For pdf bank statement account sources, where the value is between 0 and 1000, with 1000 being the most anomalous
          example: 200
          type: integer
        balances:
          description: List of balances associated with the account
          example:
          - closing_amount: 25000.45
            currency: USD
            date: '2022-01-01'
          items:
            $ref: '#/components/schemas/AccountBalance'
          type: array
        currency:
          description: Currency of the account
          example: USD
          type: string
        display_account_id:
          description: 'Human-readable account label for display: the last four digits of the account number (falling back to the account title). Not unique and not a key; use account_id to join.'
          example: '7505'
          type:
          - string
          - 'null'
        end_date:
          description: End date of the account
          example: '2022-01-31'
          format: date
          type: string
        heron_id:
          description: Unique ID for data source generated by Heron
          example: dso_bSTsiBKd9gS5GtAzg7dSAb
          type: string
        institution_name:
          description: Name of the institution
          example: Chase
          type: string
        is_enabled:
          description: Whether or not the account is enabled. If disabled, hides related transactions from analytics
          example: true
          type: boolean
        max_date:
          description: Latest date of transactions associated with the data source account
          example: '2022-01-31'
          format: date
          type: string
        min_date:
          description: Earliest date of transactions associated with the data source account
          example: '2022-01-01'
          format: date
          type: string
        name:
          description: Name of the account
          example: Checking Account
          type: string
        num_transactions:
          description: Number of transactions associated with the data source account
          example: 120
          type: integer
        number:
          description: Number of the account
          example: '123456789'
          type: string
        owner_name:
          description: Name of the account owner
          example: John Doe
          type: string
        reference_id:
          description: This is the account ID provided as part of the transaction
          example: account-202348
          type: string
        start_date:
          description: Start date of the account
          example: '2022-01-01'
          format: date
          type: string
        transactions_match_balances:
          description: For pdf bank statements, represents whether all transactions extracted match the balances extracted
          example: true
          type: boolean
        type:
          description: Type of the account
          example: Checking
          type: string
      required:
      - is_enabled
      type: object
    Money:
      properties:
        amount:
          description: The amount of money
          example: '1234.56'
          type: number
        currency:
          description: The currency of the money
          example: USD
          type: string
      type: object
  securitySchemes:
    ApiKeyAuth:
      in: header
      name: x-api-key
      type: apiKey
externalDocs:
  description: Read Tutorial
  url: https://docs.herondata.io/