# Add a funder to broker's policies Source: https://docs.herondata.io/api-reference/add-a-funder-to-brokers-policies https://app.herondata.io/swagger post /api/broker_funder_policies/funders/ Add a funder to the current broker's funder policies table. Idempotent — if the funder already exists in the broker's table, returns the existing record without modification. New entries start with empty criteria. # Add and remove sender matchers across many funder exclusion rules Source: https://docs.herondata.io/api-reference/add-and-remove-sender-matchers-across-many-funder-exclusion-rules https://app.herondata.io/swagger patch /api/funder_exclusion_rules/bulk/ A rule left with no senders is deleted. # Add sender matchers to many funder exclusion rules Source: https://docs.herondata.io/api-reference/add-sender-matchers-to-many-funder-exclusion-rules https://app.herondata.io/swagger post /api/funder_exclusion_rules/bulk/ Creates a rule for each funder without one, and unions the senders into the rest. # Get decline analytics for a user Source: https://docs.herondata.io/api-reference/analytics/get-decline-analytics-for-a-user https://app.herondata.io/swagger get /api/analytics/decline Returns aggregated decline analytics for end users within a date range, including total end users, total declined, and per-check pass/fail/missing counts. Only the latest policy evaluation per end user is considered. # List available apps Source: https://docs.herondata.io/api-reference/appstore/list-available-apps https://app.herondata.io/swagger get /api/app_store/list List available apps # Authentication Source: https://docs.herondata.io/api-reference/authentication ## Development vs Production We handle development and production environments at the credential level. We will issue you with a set of dashboard and API credentials you can use for development purposes during your trial / onboarding phase. When you’re ready to move to production, please contact us, and we will issue you a set of production credentials. ## Dashboard Log in to the [Heron dashboard](https://dashboard.herondata.io) using the credentials you were issued. From **Settings → API Credentials**, you can manage the API keys used to authenticate against the Heron API. If you haven't received access, please speak to your Heron rep, or email us at [hello@herondata.io](mailto:hello@herondata.io). To reset your password, go to the [dashboard login page](https://dashboard.herondata.io) and follow the “Forgot password?” flow. ## API keys You can create, list, deactivate, reactivate, and delete API keys from **Settings → API Credentials** in the dashboard. API Keys ### Creating a key Click **Create API key**, give it a descriptive name (e.g. `CI pipeline`, `Production service`), and copy the token from the dialog that appears. The full token is shown **once, at creation time** and cannot be retrieved later. Store it in a secret manager (e.g. GCP Secret Manager, AWS Secrets Manager, Vault) immediately. If you lose a token, create a new key and delete or deactivate the old one. After the dialog closes, only the first 8 characters of the token (the prefix) are visible — enough to identify which key is which, but not enough to authenticate with. ### Deactivating and reactivating Deactivating a key takes effect **immediately** — requests using a deactivated key are rejected with a 401. Reactivating restores access. Use deactivation when you suspect a key may be compromised but aren’t ready to delete it (e.g. to confirm the key is no longer in use). Deleting a key is irreversible. ### Rotation A typical rotation flow: 1. Create a new key with a descriptive name. 2. Deploy the new key to the systems that use it. 3. Once the new key is in use, deactivate the old one and confirm nothing breaks. 4. Delete the old key. ### Authenticating with a key Send the API key in the `x-api-key` HTTP header. This works against every authenticated endpoint. ```bash theme={null} curl "https://app.herondata.io/api/hello_world/authenticated" \ --header 'x-api-key: ' ``` All API keys start with `key_` followed by 48 hex characters. # Get broker EndUser detail Source: https://docs.herondata.io/api-reference/brokers/get-broker-enduser-detail https://app.herondata.io/swagger get /api/broker/end_users/{end_user_id_or_heron_id} Get end-user detail with broker link context. Broker customers only; responds 404 for others. # List broker EndUsers with deal summary information Source: https://docs.herondata.io/api-reference/brokers/list-broker-endusers-with-deal-summary-information https://app.herondata.io/swagger get /api/broker/end_users/summary Get the broker deal list. Broker customers only; responds 404 for others. # Add details to broker submission Source: https://docs.herondata.io/api-reference/brokersubmissions/add-details-to-broker-submission https://app.herondata.io/swagger post /api/broker_submissions/{submission_heron_id}/update_information Add company and owner details to existing broker submission. **Authentication**: Requires a broker API key in the `x-api-key` header. Generate keys using the `/api/broker_submissions/api_keys/generate` endpoint. # Create broker submission Source: https://docs.herondata.io/api-reference/brokersubmissions/create-broker-submission https://app.herondata.io/swagger post /api/broker_submissions/ Create a new broker submission with end user details. **Authentication**: Requires a broker API key in the `x-api-key` header. Generate keys using the `/api/broker_submissions/api_keys/generate` endpoint. # Delete broker API key Source: https://docs.herondata.io/api-reference/brokersubmissions/delete-broker-api-key https://app.herondata.io/swagger delete /api/broker_submissions/api_keys/{broker_funder_api_key_heron_id} Delete an existing API key for a broker-funder relationship. The authenticated user must own the funder account associated with the API key. # Generate broker API key Source: https://docs.herondata.io/api-reference/brokersubmissions/generate-broker-api-key https://app.herondata.io/swagger post /api/broker_submissions/api_keys/generate Create a new API key for a broker-funder relationship. The broker is identified by email domain. If the funder account or broker-funder relationship doesn't exist, they will be created automatically. Returns an error if an API key already exists for this relationship. # List broker API keys for a given user. Source: https://docs.herondata.io/api-reference/brokersubmissions/list-broker-api-keys-for-a-given-user https://app.herondata.io/swagger get /api/broker_submissions/api_keys Retrieve all Broker API keys associated with the authenticated user's funder account. Returns a list of broker-funder relationships with their corresponding API keys. # Upload PDF files for broker submission Source: https://docs.herondata.io/api-reference/brokersubmissions/upload-pdf-files-for-broker-submission https://app.herondata.io/swagger post /api/broker_submissions/{submission_heron_id}/files Upload one or more PDF files for a specified broker submission. Authenticate by passing a broker API key in the `x-api-key` header. Generate keys via the `/api/broker_submissions/api_keys/generate` endpoint. # Bulk update broker funder policies Source: https://docs.herondata.io/api-reference/bulk-update-broker-funder-policies https://app.herondata.io/swagger patch /api/broker_funder_policies/ Create or update broker funder policies for the current user # Get categories Source: https://docs.herondata.io/api-reference/categories/get-categories https://app.herondata.io/swagger get /api/categories Get available categories # Create or replace a funder exclusion rule Source: https://docs.herondata.io/api-reference/create-or-replace-a-funder-exclusion-rule https://app.herondata.io/swagger put /api/funder_exclusion_rules/{funder_heron_id}/ # Activate an API key Source: https://docs.herondata.io/api-reference/credentials/activate-an-api-key https://app.herondata.io/swagger put /api/credentials/keys/{heron_id}/activate Re-activate a previously deactivated API key. # Create a new API key Source: https://docs.herondata.io/api-reference/credentials/create-a-new-api-key https://app.herondata.io/swagger post /api/credentials/keys Create a new named API key for the authenticated user. The full token is returned only in this response - it cannot be retrieved again. # Deactivate an API key Source: https://docs.herondata.io/api-reference/credentials/deactivate-an-api-key https://app.herondata.io/swagger put /api/credentials/keys/{heron_id}/deactivate Deactivate an API key. The key will stop working immediately but can be re-activated later. Use this instead of deleting to allow rollback. # Delete an API key Source: https://docs.herondata.io/api-reference/credentials/delete-an-api-key https://app.herondata.io/swagger delete /api/credentials/keys/{heron_id} Permanently delete an API key. This cannot be undone. Consider deactivating instead if you might need to rollback. # List API keys Source: https://docs.herondata.io/api-reference/credentials/list-api-keys https://app.herondata.io/swagger get /api/credentials/keys List all API keys for the authenticated user. Returns key metadata including name, token prefix, creation date, and active status. The `last_used` field is the most recent usage timestamp, or null if usage data is not available. Full tokens are never returned - only the first 8 characters where the first 4 are "key_". # Create a CRM integration Source: https://docs.herondata.io/api-reference/crmintegrations/create-a-crm-integration https://app.herondata.io/swagger post /api/crm_integrations Create a CRM integration, e.g., with Salesforce # List CRM Integrations Source: https://docs.herondata.io/api-reference/crmintegrations/list-crm-integrations https://app.herondata.io/swagger get /api/crm_integrations Get a list of CRM Integrations # Patch a CRM integration Source: https://docs.herondata.io/api-reference/crmintegrations/patch-a-crm-integration https://app.herondata.io/swagger patch /api/crm_integrations/{heron_id} patch a CRM integration # Delete a funder exclusion rule Source: https://docs.herondata.io/api-reference/delete-a-funder-exclusion-rule https://app.herondata.io/swagger delete /api/funder_exclusion_rules/{funder_heron_id}/ # Delete many funder exclusion rules Source: https://docs.herondata.io/api-reference/delete-many-funder-exclusion-rules https://app.herondata.io/swagger delete /api/funder_exclusion_rules/bulk/ # Create an email template Source: https://docs.herondata.io/api-reference/emailtemplates/create-an-email-template https://app.herondata.io/swagger post /api/email_templates Create an email template used to send emails conditional on events like policy evaluation # Get email templates Source: https://docs.herondata.io/api-reference/emailtemplates/get-email-templates https://app.herondata.io/swagger get /api/email_templates Read all available templates # Patch an email template Source: https://docs.herondata.io/api-reference/emailtemplates/patch-an-email-template https://app.herondata.io/swagger patch /api/email_templates/{heron_id} Update an email template # Get Missing Accounts (beta) Source: https://docs.herondata.io/api-reference/enduseraccounts/get-missing-accounts-beta https://app.herondata.io/swagger get /api/end_users/{end_user_id_or_heron_id}/missing_accounts Get a list of possible missing accounts for a given End User. This endpoint is in beta and likely to change. # Get EndUser attribute values Source: https://docs.herondata.io/api-reference/enduserattributes/get-enduser-attribute-values https://app.herondata.io/swagger get /api/end_users/{end_user_heron_id}/company_attributes Get calculated attribute values for a given end user # Export as a spreadsheet Source: https://docs.herondata.io/api-reference/endusercalculations/export-as-a-spreadsheet https://app.herondata.io/swagger get /api/end_users/{end_user_id_or_heron_id}/export_spreadsheet Export a spreadsheet for an end user containing key metrics and reports # Get EndUser anomalies Source: https://docs.herondata.io/api-reference/endusercalculations/get-enduser-anomalies https://app.herondata.io/swagger get /api/end_users/{end_user_id_or_heron_id}/anomalies Get anomalies for given EndUser given a category label or heron id # Get EndUser balance Source: https://docs.herondata.io/api-reference/endusercalculations/get-enduser-balance https://app.herondata.io/swagger get /api/end_users/balance Get balance for given EndUser on a daily and account granularity # Get EndUser bank statement summary Source: https://docs.herondata.io/api-reference/endusercalculations/get-enduser-bank-statement-summary https://app.herondata.io/swagger get /api/end_users/{end_user_id_or_heron_id}/bank_statement_summary Get the bank statement summary by month for an end user # Get EndUser cashflow P&L Source: https://docs.herondata.io/api-reference/endusercalculations/get-enduser-cashflow-p&l https://app.herondata.io/swagger get /api/end_users/{end_user_id_or_heron_id}/profit_and_loss Calculates the cashflow profit & loss table for an end user, based on the layout defined (if any) # Get EndUser debt candidates Source: https://docs.herondata.io/api-reference/endusercalculations/get-enduser-debt-candidates https://app.herondata.io/swagger get /api/end_users/{end_user_id_or_heron_id}/debt_candidates Identify potential debt candidates. # Get EndUser forecasts Source: https://docs.herondata.io/api-reference/endusercalculations/get-enduser-forecasts https://app.herondata.io/swagger get /api/end_users/forecast Get forecast amounts for a given EndUser and category # Get EndUser Heron Score (beta) Source: https://docs.herondata.io/api-reference/endusercalculations/get-enduser-heron-score-beta https://app.herondata.io/swagger get /api/end_users/{end_user_id_or_heron_id}/heron_score Get Heron Score for end user with a breakdown of the feature group contributions which resulted in the score. The score is calculated for the day of last transaction. This is a beta feature and is subject to change. # Get EndUser merchant summary Source: https://docs.herondata.io/api-reference/endusercalculations/get-enduser-merchant-summary https://app.herondata.io/swagger get /api/end_users/{end_user_id_or_heron_id}/merchant_summary Get the summary of transactions by merchant for an end user for given categories or analytics groups # Get EndUser metric benchmarks Source: https://docs.herondata.io/api-reference/endusercalculations/get-enduser-metric-benchmarks https://app.herondata.io/swagger get /api/end_users/{end_user_id_or_heron_id}/benchmarks Get the benchmarks for each metric for an end user # Get EndUser named dates Source: https://docs.herondata.io/api-reference/endusercalculations/get-enduser-named-dates https://app.herondata.io/swagger get /api/end_users/{end_user_id_or_heron_id}/named_dates Get the named dates associated with an end user, e.g., date of last transaction # Get EndUser recurring transactions report Source: https://docs.herondata.io/api-reference/endusercalculations/get-enduser-recurring-transactions-report https://app.herondata.io/swagger get /api/end_users/{end_user_id_or_heron_id}/recurring_transactions_report Get a report of recurring transactions grouped by merchant or counterparty for an end user # Get EndUser scorecard Source: https://docs.herondata.io/api-reference/endusercalculations/get-enduser-scorecard https://app.herondata.io/swagger get /api/end_users/{end_user_id_or_heron_id}/scorecard Get scorecard metrics and rule violations for a user # Get EndUser statistics Source: https://docs.herondata.io/api-reference/endusercalculations/get-enduser-statistics https://app.herondata.io/swagger get /api/end_users/statistics Get summarized statistics for a given EndUser # Get EndUser transaction data coverage Source: https://docs.herondata.io/api-reference/endusercalculations/get-enduser-transaction-data-coverage https://app.herondata.io/swagger get /api/end_users/{end_user_id_or_heron_id}/transaction_data_coverage Information about dates covered by any transaction data source # Get EndUser transactions grouped by counterparty or merchant Source: https://docs.herondata.io/api-reference/endusercalculations/get-enduser-transactions-grouped-by-counterparty-or-merchant https://app.herondata.io/swagger get /api/end_users/{end_user_id_or_heron_id}/grouped_transactions_report Get a report of transactions grouped by merchant or counterparty for an end user # Request EndUser scorecard Source: https://docs.herondata.io/api-reference/endusercalculations/request-enduser-scorecard https://app.herondata.io/swagger post /api/end_users/{end_user_id_or_heron_id}/scorecard/async Request scorecard metrics for a date and end user # Update EndUser P&L layout Source: https://docs.herondata.io/api-reference/endusercalculations/update-enduser-p&l-layout https://app.herondata.io/swagger put /api/end_users/{end_user_id_or_heron_id}/profit_and_loss_layout Update the profit and loss layout for the end user, which determines how the profit and loss table is calculated # Disable duplicate data source accounts for an end user Source: https://docs.herondata.io/api-reference/enduserdatasourceaccounts/disable-duplicate-data-source-accounts-for-an-end-user https://app.herondata.io/swagger post /api/end_users/{end_user_id_or_heron_id}/data_source_accounts/disable_duplicates # Update a data source account Source: https://docs.herondata.io/api-reference/enduserdatasourceaccounts/update-a-data-source-account https://app.herondata.io/swagger put /api/data_source_accounts/{heron_id} Update a data source account # Update a data source account's account number Source: https://docs.herondata.io/api-reference/enduserdatasourceaccounts/update-a-data-source-accounts-account-number https://app.herondata.io/swagger post /api/data_source_accounts/{dsa_heron_id_to_update}/update_number Update a data source account's account number # Get data source account summary Source: https://docs.herondata.io/api-reference/enduserdatasources/get-data-source-account-summary https://app.herondata.io/swagger get /api/end_users/{end_user_id_or_heron_id}/data_source_account_summary Get a list of data sources accounts & their summarised information for a company # Get data sources Source: https://docs.herondata.io/api-reference/enduserdatasources/get-data-sources https://app.herondata.io/swagger get /api/end_users/{end_user_id_or_heron_id}/data_sources Get a list of data sources for a company # Update a data source Source: https://docs.herondata.io/api-reference/enduserdatasources/update-a-data-source https://app.herondata.io/swagger put /api/data_sources/{heron_id} Update a data source # Export an end user email as an EML file Source: https://docs.herondata.io/api-reference/enduseremails/export-an-end-user-email-as-an-eml-file https://app.herondata.io/swagger get /api/end_user_emails/{heron_id}/export Export an end user email as an EML file. Attachments are not included. # Get all fields for all enrichers for a given user Source: https://docs.herondata.io/api-reference/enduserenrichers/get-all-fields-for-all-enrichers-for-a-given-user https://app.herondata.io/swagger get /api/end_user_enrichers/fields # Get enricher result by enricher name and end user Source: https://docs.herondata.io/api-reference/enduserenrichers/get-enricher-result-by-enricher-name-and-end-user https://app.herondata.io/swagger get /api/end_user_enrichers/{end_user_heron_id}/enricher_results/{enricher_name} Retrieve the latest result for a specific enricher and end user # Get enrichment results for an end user Source: https://docs.herondata.io/api-reference/enduserenrichers/get-enrichment-results-for-an-end-user https://app.herondata.io/swagger get /api/end_user_enrichers/{end_user_heron_id}/enricher_results Get all latest enrichment results for a given end user by their Heron ID. # Start enricher execution for a specific end user asynchronously Source: https://docs.herondata.io/api-reference/enduserenrichers/start-enricher-execution-for-a-specific-end-user-asynchronously https://app.herondata.io/swagger post /api/end_user_enrichers/definitions/{enricher_definition_name}/start_enrich Dispatches an enricher task for an end user and returns immediately. # Trigger enricher execution for a specific end user Source: https://docs.herondata.io/api-reference/enduserenrichers/trigger-enricher-execution-for-a-specific-end-user https://app.herondata.io/swagger post /api/end_user_enrichers/{end_user_heron_id}/enrich Executes a specified enricher for an end user and returns the enrichment result. The enrichment result is automatically saved to the database. # Bulk save entity attribute values by entity name and attribute name Source: https://docs.herondata.io/api-reference/enduserentity/bulk-save-entity-attribute-values-by-entity-name-and-attribute-name https://app.herondata.io/swagger put /api/end_users/{end_user_heron_id}/entities/values/bulk Save multiple entity attribute values in a single request. Each item specifies the entity name, attribute name, and value to set. If an API source doesn't exist for an attribute, one will be created. # Create an end user entity Source: https://docs.herondata.io/api-reference/enduserentity/create-an-end-user-entity https://app.herondata.io/swagger post /api/end_user_entities # Create an end user entity attribute Source: https://docs.herondata.io/api-reference/enduserentity/create-an-end-user-entity-attribute https://app.herondata.io/swagger post /api/end_user_entities/{entity_heron_id}/attributes # Create an end user entity attribute Source: https://docs.herondata.io/api-reference/enduserentity/create-an-end-user-entity-attribute-1 https://app.herondata.io/swagger post /api/end_user_entities/{entity_heron_id}/attributes/{attribute_heron_id}/clone # Create an end user entity attribute source Source: https://docs.herondata.io/api-reference/enduserentity/create-an-end-user-entity-attribute-source https://app.herondata.io/swagger post /api/end_user_entities/{entity_heron_id}/attributes/{attribute_heron_id}/sources # Delete an EndUserEntity Source: https://docs.herondata.io/api-reference/enduserentity/delete-an-enduserentity https://app.herondata.io/swagger delete /api/end_user_entities/{heron_id} # Delete an EndUserEntityAttribute Source: https://docs.herondata.io/api-reference/enduserentity/delete-an-enduserentityattribute https://app.herondata.io/swagger delete /api/end_user_entities/{entity_heron_id}/attributes/{attribute_heron_id} # Delete an EndUserEntityAttribute Source: https://docs.herondata.io/api-reference/enduserentity/delete-an-enduserentityattribute-1 https://app.herondata.io/swagger delete /api/end_user_entities/{entity_heron_id}/attributes/{attribute_heron_id}/sources/{source_heron_id} # Export all saved attribute for all end users to an Excel file Source: https://docs.herondata.io/api-reference/enduserentity/export-all-saved-attribute-for-all-end-users-to-an-excel-file https://app.herondata.io/swagger get /api/end_user_entities/attribute_values/export Export a spreadsheet with saved entity attribute values (API sources only) for all end users under the current user. # Get the definitions for all end user entities Source: https://docs.herondata.io/api-reference/enduserentity/get-the-definitions-for-all-end-user-entities https://app.herondata.io/swagger get /api/end_user_entities # Get the materialised end user entities for an end user Source: https://docs.herondata.io/api-reference/enduserentity/get-the-materialised-end-user-entities-for-an-end-user https://app.herondata.io/swagger get /api/end_users/{end_user_heron_id}/entities # Set the display order of end user entities Source: https://docs.herondata.io/api-reference/enduserentity/set-the-display-order-of-end-user-entities https://app.herondata.io/swagger patch /api/end_user_entities/reorder # Set the display order of end user entity attributes Source: https://docs.herondata.io/api-reference/enduserentity/set-the-display-order-of-end-user-entity-attributes https://app.herondata.io/swagger patch /api/end_user_entities/{entity_heron_id}/attributes/reorder # Update an end user entity Source: https://docs.herondata.io/api-reference/enduserentity/update-an-end-user-entity https://app.herondata.io/swagger patch /api/end_user_entities/{entity_heron_id}/attributes/{attribute_heron_id} # Update an end user entity Source: https://docs.herondata.io/api-reference/enduserentity/update-an-end-user-entity-1 https://app.herondata.io/swagger patch /api/end_user_entities/{heron_id} # Upsert an end user entity Source: https://docs.herondata.io/api-reference/enduserentity/upsert-an-end-user-entity https://app.herondata.io/swagger patch /api/end_user_entities/{entity_heron_id}/attributes/{attribute_heron_id}/sources/{source_heron_id} # Upsert the attribute value for an end user entity attribute source Source: https://docs.herondata.io/api-reference/enduserentity/upsert-the-attribute-value-for-an-end-user-entity-attribute-source https://app.herondata.io/swagger post /api/end_users/{end_user_heron_id}/entities/{entity_heron_id} # All EndUserFiles Source: https://docs.herondata.io/api-reference/enduserfiles/all-enduserfiles https://app.herondata.io/swagger get /api/end_user_files Get all files uploaded to Heron by your users, not including parsed results from files # Create a file rename rule Source: https://docs.herondata.io/api-reference/enduserfiles/create-a-file-rename-rule https://app.herondata.io/swagger post /api/end_user_files/rename_rules Add a new rename rule for files. # Delete an EndUserFile Source: https://docs.herondata.io/api-reference/enduserfiles/delete-an-enduserfile https://app.herondata.io/swagger delete /api/end_user_files/{heron_id} # Download EndUserFiles Source: https://docs.herondata.io/api-reference/enduserfiles/download-enduserfiles https://app.herondata.io/swagger get /api/end_users/{end_user_id_or_heron_id}/files/download Download all files for an end user as a zip # Download xlsx of parsed results from uploaded files Source: https://docs.herondata.io/api-reference/enduserfiles/download-xlsx-of-parsed-results-from-uploaded-files https://app.herondata.io/swagger get /api/end_users/{end_user_id_or_heron_id}/files/parsed_results/xlsx # Get a single end user file by Heron ID Source: https://docs.herondata.io/api-reference/enduserfiles/get-a-single-end-user-file-by-heron-id https://app.herondata.io/swagger get /api/end_user_files/{heron_id} Retrieve a single end user file by its Heron ID. Returns file metadata including filename, file class, parsed results (if any), and related info. Use this endpoint when you have an end user file Heron ID and need its details without listing or filtering all files. # Get EndUserFile as a base64 string Source: https://docs.herondata.io/api-reference/enduserfiles/get-enduserfile-as-a-base64-string https://app.herondata.io/swagger get /api/end_user_files/{heron_id}/file Get the base64 string representation of an end user file # Get EndUserFiles Source: https://docs.herondata.io/api-reference/enduserfiles/get-enduserfiles https://app.herondata.io/swagger get /api/end_users/{end_user_id_or_heron_id}/files Get all files for an end user # Get file rename rule variable slugs Source: https://docs.herondata.io/api-reference/enduserfiles/get-file-rename-rule-variable-slugs https://app.herondata.io/swagger get /api/end_user_files/rename_rules/slugs Retrieve all file rename rules slugs for the current user. # Get file rename rules Source: https://docs.herondata.io/api-reference/enduserfiles/get-file-rename-rules https://app.herondata.io/swagger get /api/end_user_files/rename_rules Retrieve all file rename rules for the current user. # Get parsed results from uploaded files Source: https://docs.herondata.io/api-reference/enduserfiles/get-parsed-results-from-uploaded-files https://app.herondata.io/swagger get /api/end_user_files/{heron_id}/parsed_results # Get recent files by file class Source: https://docs.herondata.io/api-reference/enduserfiles/get-recent-files-by-file-class https://app.herondata.io/swagger get /api/end_user_files/recent_by_file_class Retrieve the most recent files for the specified file class. # Post EndUserFile Source: https://docs.herondata.io/api-reference/enduserfiles/post-enduserfile https://app.herondata.io/swagger post /api/end_users/{end_user_id_or_heron_id}/files Deprecated — use [Post EndUserFile V2](/api-reference/enduserfiles/post-enduserfile-v2) instead. # Post EndUserFile V2 Source: https://docs.herondata.io/api-reference/enduserfiles/post-enduserfile-v2 https://app.herondata.io/swagger post /api/end_users/{end_user_id_or_heron_id}/files/v2 Upload file to an end user & asynchronously classify its type. After uploading, call the `/start_workflow` endpoint to trigger downstream processing (parsing, bank statement extraction, etc.). # Process file without creating EndUserFile record Source: https://docs.herondata.io/api-reference/enduserfiles/process-file-without-creating-enduserfile-record https://app.herondata.io/swagger post /api/end_user_files/process_standalone Process a file for classification and parsing without storing it as an EndUserFile. Results are delivered via webhook to subscribed endpoints. # Start Workflow Source: https://docs.herondata.io/api-reference/enduserfiles/start-workflow https://app.herondata.io/swagger post /api/end_users/{end_user_id_or_heron_id}/start_workflow Starts your configured Heron workflow for an end user # Trigger async parsing of an end user file Source: https://docs.herondata.io/api-reference/enduserfiles/trigger-async-parsing-of-an-end-user-file https://app.herondata.io/swagger post /api/end_user_files/{heron_id}/parse_file # Trigger file's rename rule Source: https://docs.herondata.io/api-reference/enduserfiles/trigger-files-rename-rule https://app.herondata.io/swagger post /api/end_user_files/{heron_id}/trigger_rename # Trigger splitting a combined end user file into its child files based on its page_classes Source: https://docs.herondata.io/api-reference/enduserfiles/trigger-splitting-a-combined-end-user-file-into-its-child-files-based-on-its-page_classes https://app.herondata.io/swagger post /api/end_user_files/{heron_id}/trigger_split # Update a file rename rule Source: https://docs.herondata.io/api-reference/enduserfiles/update-a-file-rename-rule https://app.herondata.io/swagger patch /api/end_user_files/rename_rules/{heron_id} Update an existing rename rule identified by its `heron_id`. # Update Parsed Results Source: https://docs.herondata.io/api-reference/enduserfiles/update-parsed-results https://app.herondata.io/swagger patch /api/end_user_files/{parsed_end_user_file_id}/parsed_results # Update the end user file's class Source: https://docs.herondata.io/api-reference/enduserfiles/update-the-end-user-files-class https://app.herondata.io/swagger patch /api/end_user_files/{heron_id} Use this endpoint to change the end user file's class. The file will be reprocessed as the new type. # Get EndUser's combined financials Source: https://docs.herondata.io/api-reference/enduserfinancials/get-endusers-combined-financials https://app.herondata.io/swagger get /api/end_users/{end_user_id_or_heron_id}/combined_financials Get the combined P&L & Balance Sheet data from financial documents for an EndUser # Get Integration Links Source: https://docs.herondata.io/api-reference/enduserintegrations/get-integration-links https://app.herondata.io/swagger get /api/end_users/{end_user_id_or_heron_id}/integration_links Get a list of integration links for a specified end user # Get PDFs Source: https://docs.herondata.io/api-reference/enduserintegrations/get-pdfs https://app.herondata.io/swagger get /api/end_users/{end_user_id_or_heron_id}/pdfs Get list of PDFs for a specified end user # Get single PDF by heron_id Source: https://docs.herondata.io/api-reference/enduserintegrations/get-single-pdf-by-heron_id https://app.herondata.io/swagger get /api/integrations/pdfs/{heron_id} Retrieve a single PDF document by its heron_id. Returns the PDF metadata, status information, and optionally the processed statements/transactions. Users can only access their own PDFs. # Parse all PDF Source: https://docs.herondata.io/api-reference/enduserintegrations/parse-all-pdf https://app.herondata.io/swagger post /api/end_users/{end_user_id_or_heron_id}/pdfs/parse Starts parsing all PDFs for a specified end users. This will not restart any PDFs that are already being parsed # Reloads transactions for a pdf Source: https://docs.herondata.io/api-reference/enduserintegrations/reloads-transactions-for-a-pdf https://app.herondata.io/swagger post /api/integrations/pdfs/{heron_id}/reload_transactions This will load transactions for the pdf that is in a transactions unloaded status # Send patch transactions for a pdf statement Source: https://docs.herondata.io/api-reference/enduserintegrations/send-patch-transactions-for-a-pdf-statement https://app.herondata.io/swagger patch /api/integrations/pdfs/{heron_id}/processed Send patch transactions processed pdf that will override the extracted transactions in the specified statement # Unloads transactions for a pdf Source: https://docs.herondata.io/api-reference/enduserintegrations/unloads-transactions-for-a-pdf https://app.herondata.io/swagger post /api/integrations/pdfs/{heron_id}/unload_transactions This will delete all transactions that were previously loaded for the pdf # Update PDF attributes including status Source: https://docs.herondata.io/api-reference/enduserintegrations/update-pdf-attributes-including-status https://app.herondata.io/swagger put /api/integrations/pdfs/{heron_id} Update PDF attributes including status # Update PDF currency Source: https://docs.herondata.io/api-reference/enduserintegrations/update-pdf-currency https://app.herondata.io/swagger post /api/integrations/pdfs/{heron_id}/update_currency Update the currency for a PDF and all its statement summaries. The PDF must be in transactions_unloaded status. # Upload DecisionLogic XML Source: https://docs.herondata.io/api-reference/enduserintegrations/upload-decisionlogic-xml https://app.herondata.io/swagger post /api/end_users/{end_user_id_or_heron_id}/decision_logic Upload DecisionLogic XML files for a specified end user to translate into Heron Data format and add transactions for the end user # Upload Inscribe Source: https://docs.herondata.io/api-reference/enduserintegrations/upload-inscribe https://app.herondata.io/swagger post /api/end_users/{end_user_id_or_heron_id}/inscribe Upload Inscribe JSON for a specified end user to translate into Heron Data format and add transactions for the end user # Upload Ocrolus Source: https://docs.herondata.io/api-reference/enduserintegrations/upload-ocrolus https://app.herondata.io/swagger post /api/end_users/{end_user_id_or_heron_id}/ocrolus Upload Ocrolus JSON for a specified end user to translate into Heron Data format and add transactions for the end user # Upload PDF Source: https://docs.herondata.io/api-reference/enduserintegrations/upload-pdf https://app.herondata.io/swagger post /api/end_users/{end_user_id_or_heron_id}/pdfs/v1 Upload encoded PDF of transactions for a specified end user to translate into Heron Data format # Upload Plaid assets Source: https://docs.herondata.io/api-reference/enduserintegrations/upload-plaid-assets https://app.herondata.io/swagger post /api/end_users/{end_user_id_or_heron_id}/plaid/assets Upload Plaid asset JSON for a specified end user to translate into Heron Data format and add transactions for the end user # Upload Plaid transactions Source: https://docs.herondata.io/api-reference/enduserintegrations/upload-plaid-transactions https://app.herondata.io/swagger post /api/end_users/{end_user_id_or_heron_id}/plaid/transactions Upload Plaid transactions JSON for a specified end user to translate into Heron Data format and add transactions for the end user # Upload Yodlee Source: https://docs.herondata.io/api-reference/enduserintegrations/upload-yodlee https://app.herondata.io/swagger post /api/end_users/{end_user_id_or_heron_id}/yodlee Upload Yodlee JSON files for a specified end user to translate into Heron Data format and add transactions for the end user # Evaluate all rules for an end user Source: https://docs.herondata.io/api-reference/enduserrules/evaluate-all-rules-for-an-end-user https://app.herondata.io/swagger get /api/end_users/{end_user_id_or_heron_id}/evaluate_rules # Clear all CLEAR candidate overrides for a background check Source: https://docs.herondata.io/api-reference/endusers/clear-all-clear-candidate-overrides-for-a-background-check https://app.herondata.io/swagger delete /api/end_users/{end_user_heron_id}/background_check/override Clears every subject's CLEAR candidate pin so the enricher runs its full search waterfall for all subjects on the next run. # Confirm a candidate for an affiliate report Source: https://docs.herondata.io/api-reference/endusers/confirm-a-candidate-for-an-affiliate-report https://app.herondata.io/swagger post /api/end_users/{end_user_heron_id}/background_check/affiliations/reports/confirm Chooses which of the parties a search found the affiliation's report should cover, either when the search settled on none of them or to correct an earlier choice. Only a party that affiliation's own search identified can be chosen. Its report is retrieved in the background, replacing any report already held for that affiliation; poll the affiliations endpoint for progress. # Create EndUser Source: https://docs.herondata.io/api-reference/endusers/create-enduser https://app.herondata.io/swagger post /api/end_users Create a new end user. If transactions have previously been sent for this `end_user_id`, use `PUT end_users` to update instead. # Delete EndUser by heron_id or end_user_id (async) Source: https://docs.herondata.io/api-reference/endusers/delete-enduser-by-heron_id-or-end_user_id-async https://app.herondata.io/swagger post /api/end_users/{end_user_id_or_heron_id}/delete Asynchronously delete an end user and its associated transactions. Returns immediately with a 202 status while deletion proceeds in the background. # Delete EndUser by heron_id or end_user_id (sync) Source: https://docs.herondata.io/api-reference/endusers/delete-enduser-by-heron_id-or-end_user_id-sync https://app.herondata.io/swagger delete /api/end_users/{end_user_id_or_heron_id} Synchronously delete an end user and its associated transactions. Deprecated — use POST /end_users/{end_user_id_or_heron_id}/delete for async deletion instead. # Download a subject's background check as XML Source: https://docs.herondata.io/api-reference/endusers/download-a-subjects-background-check-as-xml https://app.herondata.io/swagger get /api/end_users/{end_user_heron_id}/background_check/subjects/{subject_key}/raw_report Returns the requested subject's background check as machine-readable XML, base64-encoded in a JSON payload. The document is rooted at `` carrying `end_user_id`, `end_user_name`, `status`, `subject_key` and a UTC `generated_at`. Under it: `` with the deal's result, severity and check counts; `` of ``; and `` holding the one requested ``. Within the subject, `` is the identity that was searched, and each exported section is an element named for its key (`criminal`, `liens`, `ofac`, ...) carrying `count` and one `` per row. A section's list fields are siblings of those elements rather than nested in them, in the same `count`/`` shape — `phones`, `addresses`, `emails`, `business_profile_details`, `business_contacts` and `work_affiliations` — so `profile` itself has no element, only its lists. Element and field names are those of `BackgroundCheckResponseSchema`, which is the data dictionary for their meaning. Values are machine-typed rather than display-formatted: a boolean is `true`/`false`, a list is a repeated element, an amount is a bare decimal, and an absent field is omitted rather than empty so a consumer can test for presence. The deal's outcome and policy checks are repeated in every subject's file, so each file stands on its own. A check's `id` is `:`, and the scope is what the check covers rather than necessarily this subject: `owner_1`, `owner_2` and `business` each name one subject, `any_owner` is the worst outcome across the owners, and `submission` is computed over the whole deal. So a subject's file carries checks about the other subjects too, and a failing `any_owner` or `submission` check should not be attributed to the subject whose file it arrived in. # Enrich transactions of EndUser Source: https://docs.herondata.io/api-reference/endusers/enrich-transactions-of-enduser https://app.herondata.io/swagger post /api/end_users/{end_user_id_or_heron_id}/enrich Enriches transactions of an end user identified by its end_user_id or heron_id. There is an optional `priority` parameter that can be set to `high` to prioritize the enrichment over `normal` (default) priority. High priority enrichment is only enabled for enterprise-level accounts. Please contact support@herondata.io to upgrade your account. # Get duplicate end users for an end user Source: https://docs.herondata.io/api-reference/endusers/get-duplicate-end-users-for-an-end-user https://app.herondata.io/swagger get /api/end_users/{end_user_heron_id}/duplicate_end_users Find duplicate end users for the given end user by matching on EIN (federal_tax_id) or normalized legal business name. Only returns duplicates within the same user (lender). Matching strategy: (1) Priority - Match by EIN when available (fast indexed query), (2) Fallback - Match by normalized company_legal_business_name when EIN is missing. Requires the count_duplicate_end_users feature flag to be enabled for the user. # Get EndUser background check dashboard payload Source: https://docs.herondata.io/api-reference/endusers/get-enduser-background-check-dashboard-payload https://app.herondata.io/swagger get /api/end_users/{end_user_heron_id}/background_check Get the background check results for an end user, including the screening run status, each subject's identity matches and records, and the outcome of each policy check. # Get EndUser by heron_id or end_user_id Source: https://docs.herondata.io/api-reference/endusers/get-enduser-by-heron_id-or-end_user_id https://app.herondata.io/swagger get /api/end_users/{end_user_id_or_heron_id} Get an end user using its end_user_id or heron_id # Get EndUser emails Source: https://docs.herondata.io/api-reference/endusers/get-enduser-emails https://app.herondata.io/swagger get /api/end_user_emails Get all emails for all end users associate with this user # Get EndUser emails Source: https://docs.herondata.io/api-reference/endusers/get-enduser-emails-1 https://app.herondata.io/swagger get /api/end_users/{end_user_id_or_heron_id}/emails Get the emails associated with an end user # Get EndUser information Source: https://docs.herondata.io/api-reference/endusers/get-enduser-information https://app.herondata.io/swagger get /api/end_users/{end_user_id_or_heron_id}/end_user_information Get the company details of an end user including loan information # Get EndUser physical location Source: https://docs.herondata.io/api-reference/endusers/get-enduser-physical-location https://app.herondata.io/swagger get /api/end_users/{end_user_id_or_heron_id}/location Get the company physical address coordinates # Get EndUser processing status Source: https://docs.herondata.io/api-reference/endusers/get-enduser-processing-status https://app.herondata.io/swagger get /api/end_users/{end_user_id_or_heron_id}/processing_status Get the current processing status of an end user by heron_id or end_user_id. Returns whether the end user is currently being processed or has completed processing. # Get the pinned CLEAR candidate overrides for a background check Source: https://docs.herondata.io/api-reference/endusers/get-the-pinned-clear-candidate-overrides-for-a-background-check https://app.herondata.io/swagger get /api/end_users/{end_user_heron_id}/background_check/override Returns the per-subject CLEAR entity_id pins the background-check enricher fetches reports for directly, skipping its search. An empty value means that subject still runs the full search waterfall. # List an end user's background check affiliations Source: https://docs.herondata.io/api-reference/endusers/list-an-end-users-background-check-affiliations https://app.herondata.io/swagger get /api/end_users/{end_user_heron_id}/background_check/affiliations Lists every business and person the deal's background check connects it to: the businesses each owner is recorded as affiliated with, the businesses filed under each owner (corporate filings), the people associated with them, and the people and companies named as officers on the business's own filings. Each row carries the state of any report requested for it - shared across rows naming the same business - and is absent until a background check has completed. # List EndUsers Source: https://docs.herondata.io/api-reference/endusers/list-endusers https://app.herondata.io/swagger get /api/end_users Get a list of EndUsers # List EndUsers with Summary Information Source: https://docs.herondata.io/api-reference/endusers/list-endusers-with-summary-information https://app.herondata.io/swagger get /api/end_users/summary Get a list of EndUsers # Patch EndUser information Source: https://docs.herondata.io/api-reference/endusers/patch-enduser-information https://app.herondata.io/swagger patch /api/end_users/{end_user_id_or_heron_id}/end_user_information Update the end user information # Pin CLEAR candidate overrides for a background check Source: https://docs.herondata.io/api-reference/endusers/pin-clear-candidate-overrides-for-a-background-check https://app.herondata.io/swagger post /api/end_users/{end_user_heron_id}/background_check/override Pins a CLEAR entity_id per subject (owner_1, owner_2, business) so the enricher fetches that candidate's report directly and skips its search. A null value clears that subject's pin; unpinned subjects still run the full search waterfall. Returns the current pins. # Request background check reports for affiliations Source: https://docs.herondata.io/api-reference/endusers/request-background-check-reports-for-affiliations https://app.herondata.io/swagger post /api/end_users/{end_user_heron_id}/background_check/affiliations/reports Requests a background check report for each affiliation selected, business or person. Where the source records already identify the party, its report is retrieved for that party directly; otherwise a search runs first, and a search that settles on no single party returns `not_found` along with the parties it did find, so one can be confirmed. Poll the affiliations endpoint for progress. # Retrieve CRM sync events for an end user Source: https://docs.herondata.io/api-reference/endusers/retrieve-crm-sync-events-for-an-end-user https://app.herondata.io/swagger get /api/end_users/{heron_id}/crm_sync # Stop tracking an affiliate report Source: https://docs.herondata.io/api-reference/endusers/stop-tracking-an-affiliate-report https://app.herondata.io/swagger delete /api/end_users/{end_user_heron_id}/background_check/affiliations/reports/{ref} Removes an affiliate report request, so later screening runs no longer pull a report for that affiliation. Reports already pulled remain on the runs that produced them. # Trigger a CRM Sync for an End User Source: https://docs.herondata.io/api-reference/endusers/trigger-a-crm-sync-for-an-end-user https://app.herondata.io/swagger post /api/end_users/{heron_id}/crm_sync # Update EndUser Source: https://docs.herondata.io/api-reference/endusers/update-enduser https://app.herondata.io/swagger put /api/end_users Confirm an end user is ready for async processing by sending a status of "ready". The `end_user_id` must have previously been sent with at least one Transaction if attempting to update the status. # View a criminal-record mug shot Source: https://docs.herondata.io/api-reference/endusers/view-a-criminal-record-mug-shot https://app.herondata.io/swagger get /api/end_users/{end_user_heron_id}/background_check/subjects/{subject_key}/records/{record_id}/mugshot Returns the mug shot for one criminal or arrest record as authenticated image bytes. # Get apitransactions Source: https://docs.herondata.io/api-reference/enrichedtransactions/get-apitransactions https://app.herondata.io/swagger get /api/transactions/{reference_id_or_heron_id} Get enriched transaction # Get end user transactions Source: https://docs.herondata.io/api-reference/enrichedtransactions/get-end-user-transactions https://app.herondata.io/swagger get /api/end_users/{end_user_id_or_heron_id}/transactions Get all unique transactions for a single end user. Set end user status to "ready" to initiate transaction enrichment, otherwise may contain both enriched and unenriched transactions # Bulk create category feedback for an end user Source: https://docs.herondata.io/api-reference/enrichmentfeedback/bulk-create-category-feedback-for-an-end-user https://app.herondata.io/swagger post /api/end_users/{end_user_id_or_heron_id}/bulk_category_feedback Provide bulk feedback on Transaction Categories for a specified end user # Bulk create merchant feedback for an end user Source: https://docs.herondata.io/api-reference/enrichmentfeedback/bulk-create-merchant-feedback-for-an-end-user https://app.herondata.io/swagger post /api/end_users/{end_user_id_or_heron_id}/merchant_feedback Provide bulk feedback on Transaction Merchants for a specified end user # Create category, merchant feedback Source: https://docs.herondata.io/api-reference/enrichmentfeedback/create-category-merchant-feedback https://app.herondata.io/swagger put /api/transactions/{heron_id}/feedback Provide feedback on a Transaction's Categories and Merchants # Revert merchant feedback for an end user Source: https://docs.herondata.io/api-reference/enrichmentfeedback/revert-merchant-feedback-for-an-end-user https://app.herondata.io/swagger post /api/end_users/{end_user_id_or_heron_id}/merchant_feedback/revert Revert merchant feedback annotations created by the feedback_client annotator # Errors Source: https://docs.herondata.io/api-reference/errors We structure all errors which occur in our application into a JSON object with keys: * `code` (`integer`) - the HTTP status code * `description` (`string` or `dict`) - a longer description of what went wrong * `name` (`string`) - the error name ## Examples ### 404 ```json theme={null} { "code": 404, "description": "Transaction not found", "name": "Not Found" } ``` ### 422 ```json theme={null} { "code": 422, "description": { "json": { "merchant": { "_schema": [ "one of 'heron_id' or 'name' is required for merchant feedback" ] } } }, "name": "Unprocessable Entity" } ``` ### 429 ```json theme={null} { "code": 429, "description": "100 per 1 minute", "name": "Too Many Requests" } ``` We have different rate limits per API endpoint and per customer. If you want to know what your rate limit is, and how much of it you have remaining, we provide response headers for each request you send us indicating this. * `x-ratelimit-limit`: the number of requests per minute you can send * `x-ratelimit-remaining`: the number of requests remaining within the current rate limit window * `x-ratelimit-reset`: the Unix timestamp datetime when you limit resets For example, if you receive: ``` x-ratelimit-limit: 100 x-ratelimit-remaining: 99 x-ratelimit-reset: 1675334140 ``` It means the endpoint you're calling has a rate limit of `100` per minute. You have `99` requests left in the current window. And your limit will be replenished at `1675334140` which is `Thursday, 2 February 2023 10:35:40`. We use a [Fixed Window](https://flask-limiter.readthedocs.io/en/stable/strategies.html#fixed-window) algorithm to manage rate limits. ### 500 ```json theme={null} { "code": 500, "description": "Something went wrong - sorry about that! If you continue having issues please email help@herondata.io", "name": "Internal Server Error" } ``` # Export broker funder policies as Excel Source: https://docs.herondata.io/api-reference/export-broker-funder-policies-as-excel https://app.herondata.io/swagger get /api/broker_funder_policies/export/ Download the current user's broker funder policies as an Excel spreadsheet. The exported file can be re-uploaded via POST /broker_funder_policies/upload/ to round-trip policies. # Add a FileClass to Classify for a User Source: https://docs.herondata.io/api-reference/fileclass/add-a-fileclass-to-classify-for-a-user https://app.herondata.io/swagger post /api/users/file_classes/{file_class_name} # Get all file classes Source: https://docs.herondata.io/api-reference/fileclass/get-all-file-classes https://app.herondata.io/swagger get /api/end_user_files/file_classes # Get current file classes used in classification Source: https://docs.herondata.io/api-reference/fileclass/get-current-file-classes-used-in-classification https://app.herondata.io/swagger get /api/users/file_classes # Get file class groups enabled for a User Source: https://docs.herondata.io/api-reference/fileclass/get-file-class-groups-enabled-for-a-user https://app.herondata.io/swagger get /api/users/file_class_groups # Remove a FileClass from Classification for a User Source: https://docs.herondata.io/api-reference/fileclass/remove-a-fileclass-from-classification-for-a-user https://app.herondata.io/swagger delete /api/users/file_classes/{file_class_name} # Get a single funder Source: https://docs.herondata.io/api-reference/funders/get-a-single-funder https://app.herondata.io/swagger get /api/funders/{heron_id} Get details of a specific funder by heron_id # List your linked funders Source: https://docs.herondata.io/api-reference/funders/list-your-linked-funders https://app.herondata.io/swagger get /api/funders/linked Get a list of funders linked to the current user # Search funders by name Source: https://docs.herondata.io/api-reference/funders/search-funders-by-name https://app.herondata.io/swagger get /api/funders/ Returns funders whose name or aliases fuzzy-match `q`, capped at `limit` (max 50). Requires `q` (min 3 characters); bulk listing is no longer supported. # Get deal link entries for an end user Source: https://docs.herondata.io/api-reference/get-deal-link-entries-for-an-end-user https://app.herondata.io/swagger get /api/end_users/{end_user_heron_id}/deal_link/ List all end users linked to the same CRM opportunity as this end user — the original submission end user plus one end user per funder decision email. # Get funder submission status Source: https://docs.herondata.io/api-reference/get-funder-submission-status https://app.herondata.io/swagger get /api/funder_submissions/{submission_heron_id}/ Returns the status and details of a funder submission. Use this to poll after triggering a submission. # Get policy upload job status Source: https://docs.herondata.io/api-reference/get-policy-upload-job-status https://app.herondata.io/swagger get /api/broker_funder_policies/upload/status/ Get the status of the most recent policy upload job for the current user # Get specific policy upload job Source: https://docs.herondata.io/api-reference/get-specific-policy-upload-job https://app.herondata.io/swagger get /api/broker_funder_policies/upload/{job_heron_id}/ Get a specific policy upload job by its Heron ID # Ingest end user data from a CRM webhook Source: https://docs.herondata.io/api-reference/ingest-end-user-data-from-a-crm-webhook https://app.herondata.io/swagger post /api/ingestion/crm/{crm_integration_heron_id} Receives a webhook payload from a CRM integration and syncs the end user via the ingestion pipeline. Per-CRM payload shapes are parsed by the matching CRM client; only the generic ingestion controls documented below are read directly here. # Create an integration Source: https://docs.herondata.io/api-reference/integrations/create-an-integration https://app.herondata.io/swagger post /api/integrations Create an integration e.g. with Plaid # Create an integration Link Source: https://docs.herondata.io/api-reference/integrations/create-an-integration-link https://app.herondata.io/swagger post /api/integrations/{heron_id}/links Create a Link for an active Integration every time a customer connects their bank. In Plaid, this is a Plaid Link every time a customer connects their bank. For Plaid, call this after exchanging a public token for an Item access_token. # Get IntegrationLinks by Integration Source: https://docs.herondata.io/api-reference/integrations/get-integrationlinks-by-integration https://app.herondata.io/swagger get /api/integrations/{heron_id}/links Get a list of IntegrationLinks for an Integration filtered by end user # List Integrations Source: https://docs.herondata.io/api-reference/integrations/list-integrations https://app.herondata.io/swagger get /api/integrations Get a list of Integrations # Refresh an IntegrationLink Source: https://docs.herondata.io/api-reference/integrations/refresh-an-integrationlink https://app.herondata.io/swagger post /api/integrations/{heron_id}/links/{link_item_id}/refresh Trigger a refresh operation for an IntegrationLink # Refresh assets reports for integration links Source: https://docs.herondata.io/api-reference/integrations/refresh-assets-reports-for-integration-links https://app.herondata.io/swagger put /api/integrations/{heron_id}/links Refresh assets reports for an integration and specific end user. This will trigger a refresh operation for all active Plaid assets report links associated with the integration and end user. # Send a Finicity Connect email to an end user Source: https://docs.herondata.io/api-reference/integrations/send-a-finicity-connect-email-to-an-end-user https://app.herondata.io/swagger post /api/end_users/{end_user_id_or_heron_id}/finicity/connect Create a Finicity Link for an end user and send a Finicity Connect email to the end user to initiate the connection. The end user must have sufficient end user information to create the link. # (Soft-)Delete an integration link Source: https://docs.herondata.io/api-reference/integrations/soft-delete-an-integration-link https://app.herondata.io/swagger delete /api/integrations/{heron_id}/links Soft-deletes of an integration link (sync is disabled) # Trigger a cashflow report generation for an end user Source: https://docs.herondata.io/api-reference/integrations/trigger-a-cashflow-report-generation-for-an-end-user https://app.herondata.io/swagger post /api/end_users/{end_user_id_or_heron_id}/finicity/request_cashflow_report Request a cashflow report generation for an end user. When the report is ready it will be available as EndUserFile. # Trigger a Finicity VOE transactions report generation for an end user Source: https://docs.herondata.io/api-reference/integrations/trigger-a-finicity-voe-transactions-report-generation-for-an-end-user https://app.herondata.io/swagger post /api/end_users/{end_user_id_or_heron_id}/finicity/request_voe_transactions_report Request a Finicity VOE transactions report generation for an end user. When the report is ready it will be available as an EndUserFile. # Trigger a statement reports generation for an end user Source: https://docs.herondata.io/api-reference/integrations/trigger-a-statement-reports-generation-for-an-end-user https://app.herondata.io/swagger post /api/end_users/{end_user_id_or_heron_id}/finicity/request_statement_reports Request a Finicity statement reports generation for end user. Reports will be generated for each account available and each month going back in time between min_statement_index and max_statement_index. When the report is ready it will be available as EndUserFile. # Update an Integration Link Source: https://docs.herondata.io/api-reference/integrations/update-an-integration-link https://app.herondata.io/swagger put /api/integration_links/{item_id} Allows refreshing the access_token of an existing Integration Link # Update Integration Source: https://docs.herondata.io/api-reference/integrations/update-integration https://app.herondata.io/swagger put /api/integrations/{heron_id} Update an Integration # Get EndUser ISO Applications Source: https://docs.herondata.io/api-reference/isoapplication/get-enduser-iso-applications https://app.herondata.io/swagger get /api/end_users/{end_user_id_or_heron_id}/iso_applications Get all ISO applications for an end user # Get the scrubbed results and data validations of an uploaded ISO application by its heron_id (prefixed "iso_") Source: https://docs.herondata.io/api-reference/isoapplication/get-the-scrubbed-results-and-data-validations-of-an-uploaded-iso-application-by-its-heron_id-prefixed-"iso_" https://app.herondata.io/swagger get /api/iso_applications/{heron_id} Use this endpoint to retrieve the scrubbed results and data validations of an uploaded ISO application PDF once it has finished processing. If processing is still underway, the processing_status field will be "processing". # Reprocess a single ISO application Source: https://docs.herondata.io/api-reference/isoapplication/reprocess-a-single-iso-application https://app.herondata.io/swagger post /api/iso_applications/reprocess/{heron_id} Use this endpoint to trigger reprocessing of a specific ISO application. This will re-run the parsing and validation process for the specified application. # Upload an ISO application PDF for automated scrubbing in under 15 seconds Source: https://docs.herondata.io/api-reference/isoapplication/upload-an-iso-application-pdf-for-automated-scrubbing-in-under-15-seconds https://app.herondata.io/swagger post /api/iso_applications/ Use this endpoint to upload an ISO application PDF. Once uploaded, the file will be automatically scrubbed asynchronously. You can use the returned heron_id (prefixed "iso_") to fetch the scrubbing results from the GET endpoint below. Please contact support@herondata.io to enable this endpoint. # Upload an ISO application PDF for automated scrubbing in under 15 seconds (base64) Source: https://docs.herondata.io/api-reference/isoapplication/upload-an-iso-application-pdf-for-automated-scrubbing-in-under-15-seconds-base64 https://app.herondata.io/swagger post /api/iso_applications/base64 This endpoint is for uploading ISO application PDFs in base64 format. # Upload an ISO application PDF for for an end user Source: https://docs.herondata.io/api-reference/isoapplication/upload-an-iso-application-pdf-for-for-an-end-user https://app.herondata.io/swagger post /api/end_users/{end_user_id_or_heron_id}/iso_application_form Use this endpoint to upload an ISO application PDF. Once uploaded, the file will be automatically scrubbed asynchronously. You can use the returned iso_application heron_id (prefixed "iso_") to fetch the scrubbing results. Please contact support@herondata.io to enable this endpoint. # Link a funder to the current broker for self-service Source: https://docs.herondata.io/api-reference/link-a-funder-to-the-current-broker-for-self-service https://app.herondata.io/swagger post /api/funder_integrations/ Links a funder the broker can configure. Returns the new entry in the same shape as `GET /api/funder_integrations/`. # List broker funder policies for current user Source: https://docs.herondata.io/api-reference/list-broker-funder-policies-for-current-user https://app.herondata.io/swagger get /api/broker_funder_policies/ Get all broker funder policies for the current user, ordered by matching priority # List funder exclusion rules Source: https://docs.herondata.io/api-reference/list-funder-exclusion-rules https://app.herondata.io/swagger get /api/funder_exclusion_rules/ # List funder integration states for the current broker Source: https://docs.herondata.io/api-reference/list-funder-integration-states-for-the-current-broker https://app.herondata.io/swagger get /api/funder_integrations/ Returns one entry per linked integration (API/portal) funder, with its current state, configuration, and last test result. # List funder policy evaluations for an end user Source: https://docs.herondata.io/api-reference/list-funder-policy-evaluations-for-an-end-user https://app.herondata.io/swagger get /api/end_users/{end_user_heron_id}/funder_policy_evaluations/ Get all funder policy evaluations for a specific end user # List funder submissions with their current decision and offers Source: https://docs.herondata.io/api-reference/list-funder-submissions-with-their-current-decision-and-offers https://app.herondata.io/swagger get /api/broker/end_users/{end_user_heron_id}/funder_submissions/ One row per funder submission on the deal, newest first, each carrying the funder, outbound status, send eligibility, send attempts, the current (non-superseded) decision, and the full decision history with each decision's offers. The envelope also identifies the requested record's broker link, records linked to it, and submitting broker identities evaluated for funder exclusions. Broker customers only; responds 404 for others. # List funders available for self-service that the broker hasn't linked yet Source: https://docs.herondata.io/api-reference/list-funders-available-for-self-service-that-the-broker-hasnt-linked-yet https://app.herondata.io/swagger get /api/funder_integrations/candidates/ Returns the funders the broker can link but hasn't yet, sorted alphabetically. # List pending funder matches for a job Source: https://docs.herondata.io/api-reference/list-pending-funder-matches-for-a-job https://app.herondata.io/swagger get /api/broker_funder_policies/upload/{job_heron_id}/pending/ Get all pending funder matches that need manual resolution for a specific upload job # Extract merchant Source: https://docs.herondata.io/api-reference/merchants/extract-merchant https://app.herondata.io/swagger post /api/merchants/extract Extract Merchant from a transaction description # Get merchant by ID Source: https://docs.herondata.io/api-reference/merchants/get-merchant-by-id https://app.herondata.io/swagger get /api/merchants/{heron_id} Get Merchant by heron_id # List merchant groups Source: https://docs.herondata.io/api-reference/merchants/list-merchant-groups https://app.herondata.io/swagger get /api/merchants/groups Get Merchant groups # List merchants Source: https://docs.herondata.io/api-reference/merchants/list-merchants https://app.herondata.io/swagger get /api/merchants/list Get a paginated list of merchants with optional name and group_id filtering. Results are ordered by merchant ID for stable pagination. # Search merchants Source: https://docs.herondata.io/api-reference/merchants/search-merchants https://app.herondata.io/swagger get /api/merchants/search Search Merchants by name # Set merchant group override Source: https://docs.herondata.io/api-reference/merchants/set-merchant-group-override https://app.herondata.io/swagger patch /api/merchants/{merchant_heron_id}/user_merchant_group Update the group id for a merchant for the current user # Get parsed submissions for an End User Source: https://docs.herondata.io/api-reference/parsedendusersubmission/get-parsed-submissions-for-an-end-user https://app.herondata.io/swagger get /api/submission_parsers/{end_user_heron_id} # Get all policy definitions Source: https://docs.herondata.io/api-reference/policy/get-all-policy-definitions https://app.herondata.io/swagger get /api/policies Gets all policy definitions set up for a user # Get the policy evaluations for an end user Source: https://docs.herondata.io/api-reference/policy/get-the-policy-evaluations-for-an-end-user https://app.herondata.io/swagger get /api/end_users/{end_user_id_or_heron_id}/policy_evaluations Evaluates the user's policies against end user on-the-fly # Progress policies for an end user Source: https://docs.herondata.io/api-reference/policy/progress-policies-for-an-end-user https://app.herondata.io/swagger post /api/policies/progress Triggers the policy progression workflow for a specific end user # Get positions summary for end user Source: https://docs.herondata.io/api-reference/positions/get-positions-summary-for-end-user https://app.herondata.io/swagger get /api/end_users/{end_user_id_or_heron_id}/positions Returns positions with calculated metrics for an end user, optionally filtered by account IDs # Get transactions for a specific position Source: https://docs.herondata.io/api-reference/positions/get-transactions-for-a-specific-position https://app.herondata.io/swagger get /api/positions/{position_heron_id}/transactions Returns investment and repayment transactions for a specific position # Remove a funder from broker's policies Source: https://docs.herondata.io/api-reference/remove-a-funder-from-brokers-policies https://app.herondata.io/swagger delete /api/broker_funder_policies/funders/{funder_heron_id}/ Remove a funder from the current broker's funder policies table. Blocked if the broker-funder pair has active submission integrations (API keys). # Remove a funder, or delete one environment's saved integration Source: https://docs.herondata.io/api-reference/remove-a-funder-or-delete-one-environments-saved-integration https://app.herondata.io/swagger delete /api/funder_integrations/{funder_heron_id}/ With an `environment`, deletes that environment's saved integration. With `remove=true`, removes the funder entirely. Exactly one of the two must be given: full removal is destructive (scrubs credentials and deletes the funder's policies row), so it must be requested explicitly — an absent or mistyped `environment` must never escalate into it. # Resolve a held funder submission Source: https://docs.herondata.io/api-reference/resolve-a-held-funder-submission https://app.herondata.io/swagger post /api/broker/end_users/{end_user_heron_id}/funder_submissions/{submission_heron_id}/exclusion_resolution/ # Resolve a pending funder match Source: https://docs.herondata.io/api-reference/resolve-a-pending-funder-match https://app.herondata.io/swagger post /api/broker_funder_policies/upload/{job_heron_id}/pending/{index}/resolve/ Resolve a pending match by selecting a funder. This will create the broker_funder record with the policy data and mark the pending match as resolved. # Create a single rule Source: https://docs.herondata.io/api-reference/rules/create-a-single-rule https://app.herondata.io/swagger post /api/rules/ Create a new rule to send a 'end_user.review_required' webhook after processing if rule condition evaluates to true # Delete rule by heron_id Source: https://docs.herondata.io/api-reference/rules/delete-rule-by-heron_id https://app.herondata.io/swagger delete /api/rules/{heron_id} Delete a rule # Get metrics Source: https://docs.herondata.io/api-reference/rules/get-metrics https://app.herondata.io/swagger get /api/rules/metrics Read all available metrics to define rules on # Get rules Source: https://docs.herondata.io/api-reference/rules/get-rules https://app.herondata.io/swagger get /api/rules/ Read all available rules # Update rule by heron_id Source: https://docs.herondata.io/api-reference/rules/update-rule-by-heron_id https://app.herondata.io/swagger put /api/rules/{heron_id} Update a rule # Save staging or production form values for a funder integration Source: https://docs.herondata.io/api-reference/save-staging-or-production-form-values-for-a-funder-integration https://app.herondata.io/swagger put /api/funder_integrations/{funder_heron_id}/ Saves the funder's staging or production configuration. # Search funders by name Source: https://docs.herondata.io/api-reference/search-funders-by-name https://app.herondata.io/swagger get /api/funders/search/ Search the Heron funder database by name using fuzzy matching. Returns a lightweight list of matching funders for the frontend picker UI. # Skip a pending funder match Source: https://docs.herondata.io/api-reference/skip-a-pending-funder-match https://app.herondata.io/swagger post /api/broker_funder_policies/upload/{job_heron_id}/pending/{index}/skip/ Skip a pending match without resolving it. This will mark it as skipped. # Submit an end user to a single funder Source: https://docs.herondata.io/api-reference/submit-an-end-user-to-a-single-funder https://app.herondata.io/swagger post /api/end_users/{end_user_heron_id}/funder_submissions/{submission_heron_id}/submit_to_funder/ Triggers an async submission for a specific funder submission. Returns 202 immediately; poll the submission status to check progress. # Submit an end user to multiple funders Source: https://docs.herondata.io/api-reference/submit-an-end-user-to-multiple-funders https://app.herondata.io/swagger post /api/broker/end_users/{end_user_heron_id}/funder_submissions/submit_to_funders/ Queues eligible submissions and reports each requested submission separately. # Add tags to an end user Source: https://docs.herondata.io/api-reference/tags/add-tags-to-an-end-user https://app.herondata.io/swagger post /api/end_users/{end_user_id_or_heron_id}/tags Add the given tags to the end user, leaving any tags already applied in place. Re-sending a tag that is already applied is a no-op, so retries are safe. Every tag heron_id must exist, otherwise none are applied. # Create a tag Source: https://docs.herondata.io/api-reference/tags/create-a-tag https://app.herondata.io/swagger post /api/tags Create a tag. Names are normalized to lowercase. They must contain 1-140 alphanumeric characters plus _ - : and are unique to your account (case-insensitive). # Delete a tag Source: https://docs.herondata.io/api-reference/tags/delete-a-tag https://app.herondata.io/swagger delete /api/tags/{heron_id} Delete a tag. It is removed from everything it is currently applied to and no longer appears in tag lists. # Get a tag Source: https://docs.herondata.io/api-reference/tags/get-a-tag https://app.herondata.io/swagger get /api/tags/{heron_id} Return a single tag by its heron_id. Deleted tags return 404. # List an end user's tags Source: https://docs.herondata.io/api-reference/tags/list-an-end-users-tags https://app.herondata.io/swagger get /api/end_users/{end_user_id_or_heron_id}/tags Return the tags currently applied to the end user, ordered by name. # List tags Source: https://docs.herondata.io/api-reference/tags/list-tags https://app.herondata.io/swagger get /api/tags Return every tag on your account, excluding deleted ones. # Remove a tag from an end user Source: https://docs.herondata.io/api-reference/tags/remove-a-tag-from-an-end-user https://app.herondata.io/swagger delete /api/end_users/{end_user_id_or_heron_id}/tags/{tag_heron_id} Remove one tag from the end user. Removing a tag that is not applied succeeds, so retries are safe. The tag itself is not deleted. # Replace an end user's tags Source: https://docs.herondata.io/api-reference/tags/replace-an-end-users-tags https://app.herondata.io/swagger put /api/end_users/{end_user_id_or_heron_id}/tags Set the end user's tags to exactly the tags given, adding and removing as needed. Send an empty list to clear every tag. Every tag heron_id must exist, otherwise nothing changes. # Update a tag Source: https://docs.herondata.io/api-reference/tags/update-a-tag https://app.herondata.io/swagger patch /api/tags/{heron_id} Update a tag's name, description, or color. Only the fields you send are changed; send null to clear the description or color. # Get apihello world Source: https://docs.herondata.io/api-reference/testing/get-apihello_world https://app.herondata.io/swagger get /api/hello_world Test endpoint (no authentication) # Get apihello worldauthenticated Source: https://docs.herondata.io/api-reference/testing/get-apihello_worldauthenticated https://app.herondata.io/swagger get /api/hello_world/authenticated Test authentication # Create end user transactions (async) Source: https://docs.herondata.io/api-reference/transactions/create-end-user-transactions-async https://app.herondata.io/swagger post /api/end_users/{end_user_id_or_heron_id}/transactions Upload transactions for a specific end user. Does not include enriching transactions -- set end user status = 'ready' to initiate processing. For synchronous enrichment, please instead use "Enrich transactions (sync). Either timestamp (preferred) or date must be present in the transaction payload." # Delete transactions Source: https://docs.herondata.io/api-reference/transactions/delete-transactions https://app.herondata.io/swagger delete /api/transactions Please provide at least one of the following parameters: heron_ids, heron_id, request_id or end_user_id. # Enrich transactions (sync) Source: https://docs.herondata.io/api-reference/transactions/enrich-transactions-sync https://app.herondata.io/swagger post /api/transactions Enrich and categorize transactions and consume them in a sync response. For business lending and underwriting, please use "Create end user transactions" instead. Please send a maximum of 249 transactions per request. # Get apitransactions Source: https://docs.herondata.io/api-reference/transactions/get-apitransactions https://app.herondata.io/swagger get /api/transactions Get transactions. At least `end_user_id`, `heron_id` or `request_id` must be provided. # Trigger a funder submission Source: https://docs.herondata.io/api-reference/trigger-a-funder-submission https://app.herondata.io/swagger post /api/funder_submissions/{submission_heron_id}/trigger/ Triggers an async submission to a funder. Returns 202 immediately; poll via GET /funder_submissions/{submission_heron_id}/ to check progress. # Trigger a staging or production test submission for this funder Source: https://docs.herondata.io/api-reference/trigger-a-staging-or-production-test-submission-for-this-funder https://app.herondata.io/swagger post /api/funder_integrations/{funder_heron_id}/test/ Submits the synthetic test end user to the selected funder environment. Returns the funder submission Heron ID. Frontend polls `/funder_submissions/{id}/` for the result. # Update a funder's submission channel and email configuration Source: https://docs.herondata.io/api-reference/update-a-funders-submission-channel-and-email-configuration https://app.herondata.io/swagger patch /api/funder_integrations/{funder_heron_id}/ Saves the funder's submission email address and CC list, and optionally switches its submission channel (integration or email). An omitted or null `channel` keeps the current channel, so email-field saves can never change how deals are routed. Returns the updated funder entry. # Upload funder policy file for parsing Source: https://docs.herondata.io/api-reference/upload-funder-policy-file-for-parsing https://app.herondata.io/swagger post /api/broker_funder_policies/upload/ Upload a spreadsheet (XLS, XLSX, CSV) or PDF containing funder policies. The file will be parsed asynchronously and policies will be upserted for the current user. Only one upload job can be active at a time per user. # Upsert a funder submission Source: https://docs.herondata.io/api-reference/upsert-a-funder-submission https://app.herondata.io/swagger post /api/funder_submissions/ Find or create a funder submission for the given end user and funder pair. Returns the existing submission if one already exists (unique per end_user + funder). # This endpoint returns merchant groups categorized as pending, custom, or rejected. Source: https://docs.herondata.io/api-reference/usermerchantgroups/this-endpoint-returns-merchant-groups-categorized-as-pending-custom-or-rejected https://app.herondata.io/swagger get /api/user_merchant_groups # Get user's company overview layout Source: https://docs.herondata.io/api-reference/users/get-users-company-overview-layout https://app.herondata.io/swagger get /api/users/company_overview_layout # Save user's company overview layout Source: https://docs.herondata.io/api-reference/users/save-users-company-overview-layout https://app.herondata.io/swagger put /api/users/company_overview_layout # Save user's settings Source: https://docs.herondata.io/api-reference/users/save-users-settings https://app.herondata.io/swagger put /api/users/current/settings # Validate an end user for configured funders Source: https://docs.herondata.io/api-reference/validate-an-end-user-for-configured-funders https://app.herondata.io/swagger get /api/broker/end_users/{end_user_heron_id}/funder_submissions/preflight/ Returns validation failures without submitting or changing submission state. # Retrieve user logo Source: https://docs.herondata.io/api-reference/watermarks/retrieve-user-logo https://app.herondata.io/swagger get /api/watermarks/logo Retrieve the logo file for the current user as raw bytes. # Upload user logo Source: https://docs.herondata.io/api-reference/watermarks/upload-user-logo https://app.herondata.io/swagger post /api/watermarks/logo Upload a logo file for the current user. The file is validated for security and stored in GCS. # Webhooks Source: https://docs.herondata.io/api-reference/webhooks We can send notifications about the progress of certain async processes to a URL of your choice. You can configure the webhook URL in the [Heron dashboard](https://dashboard.herondata.io/) by navigating to the "Settings" tab on the left menu bar. This is an example structure of our webhooks: ```json webhook.json theme={null} { "topic": "end_user.processed", "created": "2021-05-20T09:23:53+00:00", "data": { "heron_id": "eus_Eqio3Y4dhyNiMphrXwG58p", "end_user_id": "myenduser", "status": "processed" }, "meta": null } ``` * `topic` is the topic of this webhook in the format `.`. Currently we support webhooks for the following topics: Triggered when asynchronous automated processing of an end user has finished. Processing is started after the EndUser status is set to "ready". Triggered when an underwriter / Heron has manually reviewed a company and set the EndUser status to "reviewed" This webhook is in the process of being deprecated, please do not subscribe to this webhook topic. Triggered when an end\_user violates a rule during process and needs further review. Triggered when transactions are deleted. Triggered within 10 minutes of the last change on transactions for a given end user (e.g. after feedback on category or Heron manual review). Triggered when Heron has successfully processed a PDF document. Triggered when the PDF document reconciles and the PDF does not exceed the anomaly threshold (if fraud is enabled for your account). Triggered when either the PDF does not reconcile and/or the PDF exceeds the anomaly threshold (if fraud is enabled for your account). Triggered when Heron has failed to process a PDF document i.e., failed to extract any transactions. Triggered when the transactions from a processed PDF document have been loaded into an end\_user\_id. * `created` is the UTC datetime when the webhook was sent, in ISO format. * `data` contains the data of the resource which relates to this event. * `meta` (optional) contains further information about the event. For a full list of webhook topics we support, use the [GET /webhooks/topics endpoint](https://docs.herondata.io/api-reference/webhooks/get-webhook-topics#get-webhook-topics). ## Verification We send a `Heron-Signature` header in every webhook request. This header is a base64-encoded HMAC SHA256 digest of your shared secret and the webhook's payload. To verify the webhook was sent by us, calculate the digital signature using the same algorithm and compare it to the `Heron-Signature` header. ### Keep in Mind * The JSON stringified representation of the payload should not contain whitespace after the `:` and `,` separators * Some programming languages and their libraries automatically convert datetimes from UTC to your local timezone when converting to a JSON string, ensure this is disabled Here is an example of how to calculate the signature in Python: ```py theme={null} import base64 import hashlib import hmac import json secret = "sec_..." # shared secret, *not* your API credentials data = {"topic": "end_user.processed", ...} message = json.dumps(data, separators=(",", ":")) dig = hmac.new( secret.encode("utf-8"), msg=message.encode("utf-8"), digestmod=hashlib.sha256, ).digest() signature = base64.b64encode(dig).decode() ``` And in JavaScript (Node): ```js theme={null} const crypto = require('crypto') const secret = 'sec_...' const data = {"topic": "end_user.processed", ...} const signature = crypto .createHmac('sha256', secret) .update(JSON.stringify(data)) .digest('base64') ``` ## Slack webhooks integration If you don't want to build a system for receiving webhooks, we support Slack [Incoming Webhooks](https://api.slack.com/messaging/webhooks) URLs when you create a webhook. This allows you to fire alerts generated by Heron Data (e.g. a rule has been broken) directly into a Slack channel for you to take action. Follow these steps: 1. Follow the [Slack Incoming Webhook Documentation](https://api.slack.com/messaging/webhooks). 2. Slack will create a webhook url of the format `https://hooks.slack.com/services....` for you. Copy this url. 3. Open the Heron Data dashboard, navigate to the `Settings` page on the left, and go to `Webhooks`. 4. Press `Add webhook` and pick the appropriate topic. Most commonly, you'll want to fire a Slack alert when a rule has been broken. The webhook topic for this is `end_user.review_required`. 5. Press `Create webhook`. 6. To test the Slack webhook, re-process a company that breaks a rule. This will now fire a Slack alert! # Create a webhook Source: https://docs.herondata.io/api-reference/webhooks/create-a-webhook https://app.herondata.io/swagger post /api/webhooks Create a webhook # Delete a webhook Source: https://docs.herondata.io/api-reference/webhooks/delete-a-webhook https://app.herondata.io/swagger delete /api/webhooks/{heron_id} Delete a webhook by its heron_id. The webhook must belong to the authenticated user. # Get webhook topics Source: https://docs.herondata.io/api-reference/webhooks/get-webhook-topics https://app.herondata.io/swagger get /api/webhooks/topics Get webhook topics # Get webhooks Source: https://docs.herondata.io/api-reference/webhooks/get-webhooks https://app.herondata.io/swagger get /api/webhooks Get webhook # Update a webhook Source: https://docs.herondata.io/api-reference/webhooks/update-a-webhook https://app.herondata.io/swagger put /api/webhooks/{heron_id} Update a webhook # List workflows for the current user Source: https://docs.herondata.io/api-reference/workflows/list-workflows-for-the-current-user https://app.herondata.io/swagger get /api/workflow/user/workflows Returns all workflows belonging to the authenticated user. # Start a workflow by Heron ID for an end user Source: https://docs.herondata.io/api-reference/workflows/start-a-workflow-by-heron-id-for-an-end-user https://app.herondata.io/swagger post /api/workflow/start_by_heron_id Start a workflow by Heron ID for an end user # Start a workflow by name for an end user Source: https://docs.herondata.io/api-reference/workflows/start-a-workflow-by-name-for-an-end-user https://app.herondata.io/swagger post /api/workflow/start_by_name Start a workflow by name for an end user # Duplicate Transactions Source: https://docs.herondata.io/faqs/duplicate-transactions ### Q: What happens if we send duplicate transactions or we link multiple identical Plaid files to Heron - will transactions be duplicated? We currently deduplicate each transactions based on `reference_id` of each transaction. If you have multiple sources of bank accounts and/or transactions for a company, you can disable the duplicate source via API or dashboard # Get Transaction Methods Source: https://docs.herondata.io/faqs/get-transactions There are three methods of getting transaction data from Heron: * Get transactions relate to a given end\_user - [https://app.herondata.io/api/end\_users/\{end\_user\_id\_or\_heron\_id}/transactions](https://app.herondata.io/api/end_users/\{end_user_id_or_heron_id}/transactions) * Get an individual transaction - [https://app.herondata.io/api/transactions/\{reference\_id\_or\_heron\_id}](https://app.herondata.io/api/transactions/\{reference_id_or_heron_id}) * Get all transactions - [https://app.herondata.io/api/transactions/](https://app.herondata.io/api/transactions/) ### Q: What are the differences between each of the methods and what are the benefits for each one? All three methods return the **exact same data**, there is no difference to the results. However, the first two methods are optimised for performance, therefore they return results quicker. **Note:** the structure of the results are slightly different, so you will not be able to simply switch between the endpoints without updating how your integration consumes the results. ### Q: I only want to get the latest transactions that have been enriched and not the full set - how can I do that? In order to do this, in any of the above three methods, you are able to include a `last_updated_min` parameter. You should set this equal to the last time you sent transactions for enrichment. Sometimes old transactions sent in prior batches may be re-categorised in the context of new batches/transactions, and the timestamps of these transactions will also be updated to reflect the most recent change and will therefore be returned in your latest `GET` request. ### Q: I sometimes see unenriched transactions in the get enriched transactions endpoint - is something wrong? In order for transactions to be enriched, an `end_user` must be set to `ready` **each time** new transactions are added to an `end_user`. Therefore, if you see unenriched transactions, our first suggestion is to re-set the `end_user` to `ready`. If you continue to have problems with unenriched transactions, please reach out via slack or email us at [support@herondata.io](mailto:support@herondata.io). # OpenAPI JSON (Swagger) Source: https://docs.herondata.io/faqs/open-api-json We provide an up to date openAPI.json file available at: [https://app.herondata.io/swagger](https://app.herondata.io/swagger) # Rate Limits and 429 Errors - Too Many Requests Source: https://docs.herondata.io/faqs/rate-limits-429-errors ### Q: We are currently receiving 429 errors for “Too Many Requests” - what is happening and how can I fix this problem? We currently limit the number of requests that a user can send in order to prevent system abuse and balance load across all of our users. Typically, the standard number of requests that a user is able to send is 100 requests per minute across all API endpoints. **Note:** this is a **request limit** and **not a transaction limit**, so in one minute, you could `POST` 50 sets of 1000 transactions for 50 individual `end_users` and then send 50 `PUT` requests setting the `end_users` to `ready`. We provide information in the response headers to help you understand how many requests you have remaining in your given limit window and when your limit window will reset. For more details, view our API docs [here](https://docs.herondata.io/errors#429). # Supported Currencies Source: https://docs.herondata.io/faqs/supported-currencies ### Q: What currencies are currently supported by Heron? Heron displays all data in either USD, GBP, or EUR - this is set at an account level and will apply to all end\_users (i.e., companies) in your account. The following currencies can be uploaded into Heron and will be converted into the currency set for your account: USD, GBP, EUR, SEK, AED, AUD, SGD, CAD, NOK, IDR, CHF, DKK, MXN, PLN, MYR, VND, RON, TRY, CZK, BGN, HKD, PHP, HUF, NZD, BRL, ILS, COP, RUB, INR, ZAR, THB, JPY, CLP, MAD, and RSD # Supported File Formats Source: https://docs.herondata.io/faqs/supported-file-formats ### What file types does Heron support for document processing? Heron supports a wide and growing range of file formats for document processing. The following table lists the file formats that Heron supports: | **Type** | **Extension** | | -------------------------------- | ---------------------------------------- | | **PDF** | `.pdf` | | **Microsoft Word** | `.docx`, `.doc` | | **Microsoft Excel** | `.xlsx`, `.xlsb`, `.xls` | | **Comma-Seperated Values (CSV)** | `.csv` | | **Images** | `.jpg`, `.jpeg`, `.png` | | **Text-Based Files** | `.txt`, `.md`, `.xml`, `.json`, `.html` | | **Emails** | `.eml` | | **Audio** | `.mp3`, `.wav`, `.flac`, `.webm`, `.pcm` | # Sync vs. Async Source: https://docs.herondata.io/faqs/sync-vs-async When sending transactions via API, we can process them either `sync` or `async` - this FAQ aims to provide more information as to the different use cases for when you should use `sync` or `async` and the general pros and cons of each methodology. ### Q: What is the difference between processing end\_user transactions sync vs. async? What are the benefits of one versus the other? We typically segregate `sync` and `async` by customer use case. For creating a **Beautiful Transaction Feed**, i.e. extracting a clean merchant name and icon from a single or multiple transaction descriptions: * And you are enriching a **single transaction**, we recommend processing transactions using the `merchants/extract` endpoint * And you are enriching a **batch of transactions**, we recommend processing a batch of transactions `synchronously` * And you **have business data and want categories** in addition to merchant name and icons, then we would consider you an SMB analytics use case, and we recommend processing transactions `asynchronously` For **SMB underwriting** and **SMB analytics** - we **always** recommend processing transactions `async`. `Async` has additional features that increase accuracy given that the process evaluates the end\_user holistically, instead of just evaluating a single batch of transactions. To summarise, the key differences between `sync` and `async` processing are: * **Speed**: `sync` is faster with respect to processing a single batch of transactions and you do not have to rely on receiving a webhook to know when the process is complete (more information on webhooks here) * **Accuracy**: the `async` data flow offers enhanced accuracy compared to the sync flow due to additional features and a holistic consideration of the end user. Specifically, the async flow provides up to 10 percentage points higher accuracy, making it the recommended choice for businesses. It excels in accurately categorizing inter-company transfers, which is not possible with the sync flow. This higher accuracy applies to both merchant extraction and categorization classification at a transaction level. Additionally, at the company level, the async flow delivers improved accuracy for metrics, scores, and predictions. * **Number of transactions you are able to process in a single batch**: for `sync`, you are able to send a maximum of **2,500 transactions in a single batch**, whereas for `async`, you are able to send a maximum of **20,000 transactions in a single batch** ### Q: Am I able to process transactions both sync and async? Processing transactions both `sync` and `async` in a single production environment is not optimal. If you need to be able to do both - please let us know via slack or email us at [support@herondata.io](mailto:support@herondata.io). ### Q: I am currently processing transactions sync, how do I process transactions async (and vice versa)? If you would like to switch your processing methodology, please reach out via slack or email us at [support@herondata.io](mailto:support@herondata.io). # Webhook Delivery Source: https://docs.herondata.io/faqs/webhooks ### Q: Do you guarantee delivery webhooks to our servers? What happens if we are down when a webhook is sent but not received? Is there any retry logic? Currently webhooks are sent on a best effort basis, in other words, we send the webhooks and re-try but do not guarantee receipt. The webhooks currently will retry after the first failure (e.g. non-2xx HTTP status code), 3 times with exponential backoff. Specifically we retry after 1, 5 and 15 minutes before giving up. These values are configurable, please contact support to update these. ### Q: Are you able to include more identifying information in the webhook so that we are able to identify which transactions are related to the end\_user that is has been enriched/processed? At present, we keep webhook details purposefully minimal as we cannot control the destination of the webhook and we do not want to send our customers' identifying information to undesireable destinations. # Navigating This Documentation Source: https://docs.herondata.io/get-started/introduction Heron allows you to create entities ("submissions"), upload files or raw data about those entities -- bank data, application forms, tax returns, and other sources -- and retrieve parsed data from those files in your desired format. We support a wide variety of use cases, including small business underwriting (for lenders and MCAs), submission intake and other workflows in insurance, case intake for lawyers and many more. If you have a workflow that you are trying to automate, we would love to help! Feel free to [book a call](https://calendly.com/d/dkg-bn4-9rc/product-demo) with us to discuss. ## What we enable you to do To get started with the tutorial, see our [Quickstart Guide](/get-started/quickstart), or for more detail, navigate to the use case that best describes your workflow. **Core use case**: * 🏦 [I want to implement Heron for MCA or cash flow (bank data) underwriting](/use-cases/smb-underwriting) * 📥 I want to automate submission intake for commercial insurance lines (documentation coming soon!) * ⛨ I want to automate inspection report processing for commercial insurance lines (documentation coming soon!) * ⚖ I want to automate my legal case intake (documentation coming soon!) ## Data Flows To ensure seamless integration with Heron, we offer two different data flows tailored to your specific use case. We strive to make the integration process as user-friendly as possible, and these two data flows cater to various integration requirements, ensuring a smooth and efficient experience for our users. ### Async Data Flow (recommended for cash flow underwriting) The **async** data flow delivers fast responses, with a p95 response time of approximately 3 minutes. This data flow is specifically designed for high-accuracy transaction categorization and comprehensive merchant enrichment. ### Sync Data Flow The **sync** data flow provides instantaneous responses, making it the ideal choice for fast merchant enrichment tasks such as retrieving logos and cleaning up names. For a more in-depth understanding of the differences between the sync and async data flows, please refer to our [Sync vs Async FAQ](/faqs/sync-vs-async) page. **Legacy use cases**: * 🔐 [I want to lock credit cards to merchants to control spending for certain accounts](/use-cases/merchant-locking) * 📈 [I want to enrich transactions with merchant information to report on customers' spending trends](/use-cases/smb-analytics) ## Need more info? * **Email:** Contact `hello@herondata.io` (new customers) or `support@herondata.io` (existing customers). * **Slack:** Ask the main Heron contact within your organization for access to the shared Slack! * **Book a call:** For existing customers, [book a call](https://calendly.com/d/d7n-s64-fv4/heron-check-in). If you're not yet a customer, [talk to us](https://calendly.com/d/dkg-bn4-9rc/product-demo)! # Quickstart Source: https://docs.herondata.io/get-started/quickstart In Heron, files are grouped together into **submissions** (also called end users). A submission represents data relating to an entity in your workflow, such as an applicant business, plaintiff, etc. This guide will walk you using the Heron API to: * Create a new submission, * Upload files or raw data to that submission, * Start the Heron workflow processing for that submission, and * Retrieve the parsed data from files in the submission. ## Create a New Submission Creating a new submission requires sending a [POST request to the `/end_users` endpoint](/api-reference/endusers/create-enduser). The request body should include the `end_user_id` of the submission which should be a unique reference to the submission in your system. You may also include a `name` field to give the submission a human-readable name. ```js index.js theme={null} const BASE_URL = 'https://app.herondata.io/api'; const API_KEY = 'key_xxxxxxxxx'; const response = await fetch('/api/end_users', { method: 'POST', headers: { "x-api-key": `${API_KEY}`, }, body: JSON.stringify({ end_user: { end_user_id: '[END_USER_ID]', name: 'New Submission', }, }), }); if (!response.ok) { throw new Error(`Failed to create submission: ${response.statusText}`); } const response_body = await response.json(); // ^ { end_user: { heron_id: 'eus_12345342', name: 'New Submission', end_user_id: '[END_USER_ID]' } } const end_user_heron_id = response_body.end_user.heron_id; ``` ```python app.py theme={null} import requests BASE_URL = "https://app.herondata.io/api" API_KEY = "key_xxxxxxxxx" response = requests.post( f"{BASE_URL}/end_users", headers={ "x-api-key": API_KEY, }, json={ "end_user": { "end_user_id": "[END_USER_ID]", "name": "New Submission" } } ) response.raise_for_status() response_body = response.json() ## ^{ "end_user": { "heron_id": "eus_12345342", "name": "New Submission", "end_user_id": "[END_USER_ID]" } } end_user_heron_id = response_body["end_user"]["heron_id"] ``` ## Upload Files to a Submission Now we've created a new submission to hold our files, we can upload files to it and start extracting data from them. To upload a file to a submission, send a [POST request to the `/end_users/{heron_id}/files/v2` endpoint](/api-reference/enduserfiles/post-enduserfile-v2) as a `multipart/form-data` request with the file attached. The `file_class` may be omitted, in which case Heron will classify the file based on its contents. ```js index.js theme={null} const formData = new FormData(); formData.append('file', fileBlob, 'file.pdf'); formData.append('file_class', 'bank_statement'); formData.append('reference_id', 'file_1234'); const response = await fetch(`${BASE_URL}/end_users/${end_user_heron_id}/files/v2`, { method: 'POST', headers: { "x-api-key": `${API_KEY}`, }, body: formData, }); const response_body = await response.json(); const file_heron_id = response_body.heron_id; ``` ```python app.py theme={null} with open("file.pdf", "rb") as f: response = requests.post( f"{BASE_URL}/end_users/{end_user_heron_id}/files/v2", headers={ "x-api-key": API_KEY, }, files={"file": ("file.pdf", f, "application/pdf")}, data={ "file_class": "bank_statement", "reference_id": "file_1234", }, ) response.raise_for_status() response_body = response.json() file_heron_id = response_body["heron_id"] ``` ## Starting Heron Workflow Processing Once all files for a given submission have been uploaded, you can start the Heron workflow processing by sending a [POST request to the `/end_users/{heron_id}/start_workflow` endpoint](/api-reference/enduserfiles/start-workflow). This will trigger Heron to start processing the files in the submission and extracting data from them. ## Retrieve Parsed Data from Uploaded Files Now we've uploaded a file, we can poll the [`/end_users/{end_user_id_or_heron_id}/files` endpoint](/api-reference/enduserfiles/get-enduserfiles) to retrieve the parsed data from files in the submission. The response body will be an array of files in the submission, and will contain a `parsed_results` array for each file. This array will contain the extracted data from the file and and a `parsing_status` field indicating the status of the parsing process, you should continue to poll this endpoint until the parsing status is either `succeeded` or `failed`. ```js index.js theme={null} const response = await fetch(`/api/end_users/${end_user_heron_id}/files`, { headers: { "x-api-key": `${API_KEY}`, }, }); const response_body = await response.json(); // ^ [{ heron_id: "euf_xxxxx", parsed_results: [ { ... } ] }] ``` ```python app.py theme={null} response = requests.get( f"{BASE_URL}/end_users/{end_user_heron_id}/files", headers={ "x-api-key": API_KEY, }, ) response.raise_for_status() response_body = response.json() # ^ [{ "heron_id": "euf_xxxxx", "parsed_results": [ { ... } ] }] ``` We can also subscribe to webhooks to be notified when the parsing process is complete, this can be configured via the Heron Dashboard. Please reach out to support for further details on setting up or configuring webhooks. # Background Checks Source: https://docs.herondata.io/integrations/background-check Screen a deal's owners and business and retrieve the structured results via the Heron API The Background Check API screens a deal's **owners** and **business** against public-records data and returns Heron's structured work product: a per-subject breakdown of criminal records, bankruptcies, liens and judgments, lawsuits, UCC filings, sanctions / OFAC matches, corporate filings, and more, plus the outcome of each policy check you've configured. The flow is: 1. Make sure the deal's owner and business details have reached Heron - usually automatically from the ISO applications you already send us. 2. Trigger the background check. 3. Poll for completion and fetch the results. The background check runs **asynchronously**. Triggering it returns immediately; you poll the results endpoint until the run completes. This page is the narrative walkthrough. The full request and response schema for each endpoint is generated from our OpenAPI spec and lives in the API reference, so it always matches the live API: * [Trigger a background check](/api-reference/enduserenrichers/start-enricher-execution-for-a-specific-end-user-asynchronously) * [Get background check results](/api-reference/endusers/get-enduser-background-check-dashboard-payload) * [Set application data](/api-reference/endusers/patch-enduser-information) ## Prerequisites Before following this guide, you will need: * An API key (see [Authentication](/api-reference/authentication)). All requests send it in the `x-api-key` header. * The background check product enabled for your account. Speak to your Heron rep to switch it on - it is not enabled by default. * An end user representing the deal you want to screen. Most integrations already have these - an end user is created whenever you send Heron an ISO application, or you can create one directly ([Create EndUser](/api-reference/endusers/create-enduser)). The calls below address it by its `heron_id` (an `eus_` string) or your own `end_user_id`. ## Steps ### 1. Make sure the deal's details have reached Heron The background check searches on the owner and business identity Heron holds for the deal. There are two ways that data gets there. #### From your ISO applications (most common) If you already send Heron the deal's ISO application - by API or email forwarding - Heron extracts the owner and business details from it automatically. There's nothing extra to do here; skip to step 2. #### Send the details over the API If you don't send ISO applications, supply the identity directly with `PATCH /end_users/{id}/end_user_information` ([reference](/api-reference/endusers/patch-enduser-information)): ```python app.py theme={null} import requests BASE_URL = "https://app.herondata.io" API_KEY = "key_xxxxxxxx" end_user_heron_id = "eus_xxxxxxxx" # the deal you're screening requests.patch( f"{BASE_URL}/api/end_users/{end_user_heron_id}/end_user_information", headers={"x-api-key": API_KEY, "Content-Type": "application/json"}, json={ "company_legal_business_name": "ACME Logistics LLC", "federal_tax_id": "12-3456789", "company_physical_address": {"line_1": "123 Main St", "city": "Austin", "state": "TX", "zip": "78701"}, "owner_1": { "first_name": "Jane", "last_name": "Doe", "date_of_birth": "1985-03-20", "social_security_number": "123-45-6789", "home_address": {"line_1": "456 Oak Ave", "city": "Austin", "state": "TX", "zip": "78704"}, }, }, ).raise_for_status() ``` The [Set application data](/api-reference/endusers/patch-enduser-information) reference lists every accepted field. The fields that drive the background check search are: | Subject | Fields used | | -------- | ---------------------------------------------------------------------------------------------------------- | | Owners | `first_name`, `last_name`, `social_security_number`, `date_of_birth`, `home_address` | | Business | `company_legal_business_name`, `dba`, `federal_tax_id`, `company_physical_address`, `company_phone_number` | The more identity available, the more precise the match. A **name** is the minimum for an owner (first + last) and a **legal name or DBA** is the minimum for the business, but an owner's **SSN and date of birth** is what reliably resolves them to the right person and avoids false matches. Up to two owners (`owner_1`, `owner_2`) are supported. ### 2. Trigger the background check Start the check with the `background_check` enricher ([reference](/api-reference/enduserenrichers/start-enricher-execution-for-a-specific-end-user-asynchronously)). It returns `202 Accepted` as soon as the run is dispatched: ```python app.py theme={null} import requests BASE_URL = "https://app.herondata.io" API_KEY = "key_xxxxxxxx" end_user_heron_id = "eus_xxxxxxxx" # the deal you're screening requests.post( f"{BASE_URL}/api/end_user_enrichers/definitions/background_check/start_enrich", headers={"x-api-key": API_KEY, "Content-Type": "application/json"}, json={"end_user_heron_id": end_user_heron_id}, ).raise_for_status() ``` ### 3. Poll and fetch the results Fetch the background check ([reference](/api-reference/endusers/get-enduser-background-check-dashboard-payload)) and read the top-level `status` until it is no longer `processing`: ```python app.py theme={null} import requests, time BASE_URL = "https://app.herondata.io" API_KEY = "key_xxxxxxxx" end_user_heron_id = "eus_xxxxxxxx" # the deal you're screening def get_background_check(): response = requests.get( f"{BASE_URL}/api/end_users/{end_user_heron_id}/background_check", headers={"x-api-key": API_KEY}, ) response.raise_for_status() return response.json() result = get_background_check() while result["status"] == "processing": time.sleep(10) result = get_background_check() # status is now "succeeded", "failed", or "missing_input_data" ``` #### Status lifecycle | `status` | Meaning | | -------------------- | ------------------------------------------------------------------------------------------------------ | | `never_run` | No background check has been triggered for this end user yet. | | `processing` | A run is in flight. `processing_stage` reports the phase: `searching`, `pulling_reports`, `analysing`. | | `succeeded` | The run completed; `overall`, `subjects`, and `policy` are populated. | | `failed` | The run errored. No results are available. | | `missing_input_data` | No owner or business identity was available to search on (see step 1). | ## Understanding the result A succeeded response has three parts: * **`overall`** - the headline: a `result` (`pass` / `review_required` / `failed` / `missing_data`), a `severity`, and pass / review / fail counts. * **`subjects[]`** - one entry per `owner_1`, `owner_2`, and `business`, each with how it was matched (`resolution`), the search trail (`searches`), and the findings grouped by record type (`sections`). * **`policy`** - the outcome of your configured checks, each with its status and the evidence (subject, section, and records) behind it. The full field-level schema - every section type, record shape, and enum - is on the [Get background check results](/api-reference/endusers/get-enduser-background-check-dashboard-payload) reference page, generated from the live API. An abridged example to show the shape: ```json theme={null} { "end_user_id": "eus_xxxxxxxx", "status": "succeeded", "overall": { "result": "review_required", "severity": "medium", "check_counts": { "pass": 12, "review": 2, "fail": 0 } }, "subjects": [ { "key": "owner_1", "kind": "person", "name": "Jane A Doe", "resolution": { "status": "found", "method": "ssn_dob", "confidence_score": 0.97 }, "sections": [ { "key": "criminal", "label": "Criminal Records", "count": 1, "severity": "medium", "flag": "fail", "records": [{ "offense": "Theft - petit", "disposition": "Convicted", "is_felony": false }] } ] }, { "key": "business", "kind": "business", "name": "ACME Logistics LLC", "resolution": { "status": "found", "method": "name_state" }, "duns_numbers": ["123456789"], "unreported_officers": ["John Smith"] } ], "policy": { "result": "review_required", "checks": [ { "id": "owner_felony_recent", "auto_status": "pass", "evidence": { "subject_key": "owner_1", "section": "criminal" } } ] } } ``` ## Downloading a report as a PDF Heron returns the background check as **structured data** (above), which is the source of truth and the most flexible format to integrate against - you can render it however suits your product. We can also generate a **single combined PDF** covering all owners and the business in one document, branded as Heron's work product. Heron provides its own background check work product. We can't redistribute the raw third-party reports our data comes from. If a rendered PDF is something you need, talk to your Heron rep about format and branding. # Bank Statements Integration Source: https://docs.herondata.io/integrations/bank-statements You can send bank transaction data in PDF bank statements directly to Heron either by uploading files in the Heron dashboard or sending to us via API ## Prerequisites Before following this guide, you will need: * Access to [dashboard.herondata.io](http://dashboard.herondata.io) via your `username` and `password` * A PDF of a bank statement from one of your customers ## Upload Bank Statements via Heron Dashboard 1. Log in to [dashboard.herondata.io](http://dashboard.herondata.io) 2. Go to **Companies** on the sidebar menu. 3. Either create or find the customer that you want to upload a bank statement PDF for 4. Click the **transactions** drop down menu and select **PDF** under **Upload transactions** 5. In the message box, input the requested information about the bank statement 6. Select and upload your PDF file 7. During processing, you will be able to view all your PDF files by clicking **PDFs** under **View transactions** from the **transactions** drop down menu 8. By viewing a PDF, you can view the extracted results from the PDF and either approve or reject the PDF 9. Approving the PDF loads the transactions into the Heron system for the particular company and automatically set the end\_user status to `ready` 10. Once the company is done processing, you can then see results like balance, P\&L, and scorecard ## Integration steps (API) 1. You can upload a PDF for a company directly via API by sending us a POST request with the base 64 encoded PDF (see [API docs](/api-reference/enduserintegrations/upload-pdf)) 2. When posting a PDF, you can optionally specify the `account_id`, `currency`, and `read_us_dates` (date format) of the PDF. If not provided, we will infer these values 3. You can see all PDFs and their processing status with a GET request (see [API docs](/api-reference/enduserintegrations/get-pdfs)) If you are using Python, you can use the following function: ```python theme={null} def get_url_safe_base64_encoding_from_s3_url(s3_url: str) -> str: encoded = base64.b64encode(requests.get(s3_url).content) base64_encoded_string = encoded.replace(b"-", b"+").replace(b"_", b"/").decode("utf-8") data_url = f"data:application/pdf;base64,{base64_encoded_string}" return data_url ``` ## PDF status Your PDF can be in 1 of a few statuses: * **new** -- the PDF has just been created in the Heron system * **parsed** -- the PDF has been parsed by the OCR service * **processed** -- the OCR service response has been processed and the results are ready to review in the dashboard * **approved** -- if auto-approval is turned off, you can manually approve PDFs to load transactions into the Heron system * **rejected** -- if auto-approval is turned off, you can also reject PDFs based on the quality of the processed output and not load transactions into Heron system * **failed** -- when Heron encounters an error during processing, including when no transactions are found * **transactions\_loaded** -- when the transactions have been loaded from the PDF into the Heron system -- success! ## PDF approval When uploading PDFs, we will perform some high-level checks to ensure the data is uploaded correctly, e.g., balances reconcile (i.e., `starting_balance` +/- `transaction.amounts` = `ending_balance`) and anomaly score is above a certain threshold (more info on anomaly scores below). If a document fails to pass any of these checks, the system will require a user to manually approve a PDF document. In order to approve a document, the user will need to click into the PDF file in question and click the green button at the top of the screen to approve the document. Once approved, the transactions will then be uploaded to the end\_user. You can quickly and easily see the status of PDFs at the end\_user level in the Companies table in the main dashboard. The value of this column will be a ratio where the numerator is the number of PDF files that have transactions successfully uploaded to the end\_user. The denominator will be the total number of files uploaded (regardless of if the transactions have been uploaded or not). If the numerator does not match the denominator, then you should review the files that have not had their transactions uploaded, and either approve the file or make any changes to "fix" the document. ## Auto-approval * If you deal with large volumes of PDFs, we recommend you enable auto-approval for PDFs. Ask your Heron contact to turn on auto-approval * What this means is that if the processed PDF passes certain checks (e.g., anomaly score below a certain threshold, balances reconcile), we will automatically load the transactions into the Heron system * If any of the checks fail, we will flag that to you and manual review will be required ## Anomalies * We provide an "anomaly score" between 0 to 1000 based on how anomalous the PDF is * An "anomaly" is defined as the difference between the submitted PDF and other PDFs from the same financial institution * We display back to you via dashboard and API the reasons for which we find certain PDFs to be anomalous, e.g. the use of an editing software, differences in formatting, etc. * You can choose to set auto approval thresholds based on the anomaly score of a PDF ## Duplicate PDF detection * When uploading a PDF bank statement, we will determine whether or not the given file has been previously uploaded to this specific end\_user. If a duplicate file is found, we will return a 409 conflict error during the upload process and we will not save/process the file ## Webhook topics 1. `pdf.processed` -- PDF status has been set to "processed" 2. `pdf.checks_passed` -- PDF checks have passed 3. `pdf.checks_failed` -- PDF checks have failed 4. `pdf.transactions_loaded` -- PDF status has been set to "transactions\_loaded" 5. `pdf.failed` -- PDF status has been set to "failed" and we provide reasons in `pdf.notes` # Managing Broker API Keys Source: https://docs.herondata.io/integrations/broker-api-keys Handle your own brokers' integrations with Heron via our Broker API key management endpoints As a funder, you can generate and manage API keys for your broker partners. These keys allow brokers to programmatically submit applications with company details and supporting documents directly to your account through the [Broker Submissions API](/integrations/broker-submissions). ## Prerequisites Before following this guide, you will need: * Access to [dashboard.herondata.io](http://dashboard.herondata.io) via your `username` and `password` * Your user `api_key` to call the Heron API * The email address of the broker you want to grant API access to ## How Broker API Keys Work Broker API keys establish a secure, one-to-one connection between a specific broker and your funder account. * Keys are tied to the broker's email domain * Brokers use these keys to authenticate when creating submissions * You maintain full control over which brokers have API access ## Generate a Broker API Key To create a new API key for a broker partner you'll need to provide their email address. The broker is identified by their email domain so the domain must already correspond to an existing broker in the system. If the broker exists but isn't yet linked to your funder account the broker-funder relationship will be created automatically. ```python app.py theme={null} import requests BASE_URL = "https://app.herondata.io" USER_API_KEY = "key_xxxxxxxxx" response = requests.post( f"{BASE_URL}/api/broker_submissions/api_keys/generate", headers={ "x-api-key": USER_API_KEY, "Content-Type": "application/json", }, json={ "email": "broker@example.com" } ) response.raise_for_status() data = response.json() # ^ { "broker_funder_token": "bft_xxxxxxxxx" } broker_api_key = data["broker_funder_token"] # Securely share this API key with your broker partner print(f"Broker API Key: {broker_api_key}") ``` After generating the API key, securely share it with your broker partner. They will use this key to authenticate all API requests when creating submissions on your behalf. ### Error Responses When generating API keys, you may encounter these errors: * **404**: Broker with the specified email domain does not exist in the system * **409**: An API key already exists for this broker email. ## List All Broker API Keys You can retrieve all broker API keys associated with your funder account to see which brokers currently have API access: ```python app.py theme={null} BASE_URL = "https://app.herondata.io" USER_API_KEY = 'key_xxxxxxxxx' response = requests.get( f"{BASE_URL}/api/broker_submissions/api_keys", headers={ "x-api-key": USER_API_KEY, } ) response.raise_for_status() api_keys = response.json() # ^ [ # { # "broker": "ABC Broker LLC", # "broker_funder_api_key_heron_id": "bfk_xxxxxxxxx", # "broker_funder_api_key_token": "bft_xxxxxxxxx" # } # ] ``` ## Delete a Broker API Key To revoke a broker's API access, delete their API key using the `broker_funder_api_key_heron_id` you've received from the `GET` API keys endpoint. ```python app.py theme={null} broker_api_key_heron_id = "bfk_xxxxxxxxx" BASE_URL = 'https://app.herondata.io' USER_API_KEY = 'key_xxxxxxxxx' response = requests.delete( f"{BASE_URL}/api/broker_submissions/api_keys/{broker_api_key_heron_id}", headers={ "x-api-key": USER_API_KEY, } ) response.raise_for_status() print("API key successfully deleted") # The broker will no longer be able to use this key to submit applications ``` Once deleted, the broker will immediately lose access to submit applications using that API key. Any in-flight requests using the deleted key will fail with an authentication error. ### Error Responses * **404**: API key not found (may have already been deleted or invalid ID) * **403**: You do not have permission to delete this API key ## Managing Broker Access via Dashboard In addition to the API, you can also manage broker API keys through the Heron Dashboard: 1. Log in to [dashboard.herondata.io](http://dashboard.herondata.io) 2. Navigate to **Settings** on the sidebar menu 3. Scroll to the **Broker Credentials** section 4. Here you can view all active broker API keys, generate new keys, and revoke existing ones API Key Generation ## Next Steps After generating an API key for your broker partner, direct them to the [Broker Submissions Integration](/integrations/broker-submissions) guide to learn how to use the API key to submit applications programmatically. # Broker Submissions API Source: https://docs.herondata.io/integrations/broker-submissions Send complete funding submissions directly to funders using our Broker Submissions API The Broker Submissions API allows brokers to programmatically submit applications with company details and supporting documents directly to a funder. ## Prerequisites Before following this guide, you will need: * A broker email address associated with your organization * Access to generate API keys (requires funder authentication) ## Steps ### 1. Create a Broker Submission Create a new submission with a name ([API reference](https://docs.herondata.io/api-reference/brokersubmissions/create-broker-submission)): ```python app.py theme={null} BROKER_API_KEY = "bft_xxxxxxxxx" BASE_URL = "https://app.herondata.io" response = requests.post( f"{BASE_URL}/api/broker_submissions/", headers={ "x-api-key": BROKER_API_KEY, "Content-Type": "application/json", }, json={ "name": "ABC Company - Working Capital Request" } ) response.raise_for_status() data = response.json() # ^ { "heron_id": "sub_xxxxxxxxx" } submission_heron_id = data["heron_id"] ``` The submission name must be at least 10 characters long and is used for reference purposes to help identify the submission. The returned submission Heron ID will be used to upload files and company details, linking them to a unique ID. ### 2. Add Company and Owner Details Update the submission with detailed business and owner information ([API reference](https://docs.herondata.io/api-reference/brokersubmissions/add-details-to-broker-submission)): ```python app.py theme={null} BASE_URL = "https://app.herondata.io" BROKER_API_KEY = 'bft_xxxxxxxxx' response = requests.post( f"{BASE_URL}/api/broker_submissions/{submission_heron_id}/update_information", headers={ "x-api-key": BROKER_API_KEY, "Content-Type": "application/json", }, json={ "source_email_address": "jane.broker@abcbroker.com", "company_legal_business_name": "ABC Company LLC", "company_email": "contact@abccompany.com", "company_phone_number": "555-123-4567", "federal_tax_id": "12-3456789", "amount_requested": 100000, "annual_revenue": 500000, "industry_type": "Restaurant", "business_start_date": "2018-05-15", "company_physical_address": { "line_1": "123 Main St", "city": "New York", "state": "NY", "zip": "10001" }, "owner_1": { "first_name": "John", "last_name": "Doe", "email_address": "john.doe@abccompany.com", "mobile_phone": "555-987-6543", "ownership_percentage": 75, "date_of_birth": "1985-03-20" } } ) response.raise_for_status() updated_info = response.json() # ^ The full submission record with the merged company + owner details # (see EndUserInformationSchema in the API reference) ``` Set `source_email_address` to the email of the broker who submitted the deal so they receive credit for the submission. All fields in the update request are optional, allowing you to provide only the information you have available. ### 3. Upload PDF Files Upload supporting documents to the submission ([API reference](https://docs.herondata.io/api-reference/brokersubmissions/upload-pdf-files-for-broker-submission)). Optionally include a `file_class` form field to apply that classification to all files in the request — if omitted, Heron will automatically classify each file based on its contents: ```python app.py theme={null} BASE_URL = "https://app.herondata.io" BROKER_API_KEY = 'bft_xxxxxxxxx' files = [ ('files', ('statement_q4.pdf', open('statement_q4.pdf', 'rb'), 'application/pdf')), ('files', ('statement_q3.pdf', open('statement_q3.pdf', 'rb'), 'application/pdf')) ] response = requests.post( f"{BASE_URL}/api/broker_submissions/{submission_heron_id}/files", headers={ "x-api-key": BROKER_API_KEY, }, data={"file_class": "bank_statement"}, # optional — applies to all files in this request files=files ) response.raise_for_status() upload_results = response.json() # ^ [ # { "file": "statement_q4.pdf", "status": "uploaded" }, # { "file": "statement_q3.pdf", "status": "uploaded" } # ] ``` Because `file_class` applies to every file in the request, uploads with files of different classes must be split into separate requests (one per class). Alternatively, omit `file_class` and let Heron classify each file automatically. ## Response Status Codes The file upload endpoint returns different status codes based on the outcome: * **201**: All files uploaded successfully * **207**: Partial success - some files uploaded, others failed * **400**: All files failed validation or upload For partial failures (207), the response will include details about which files succeeded and which failed: ```json theme={null} [ { "file": "statement.pdf", "status": "uploaded" }, { "file": "invalid.pdf", "status": "error", "reason": "File type application/msword not allowed. Allowed: application/pdf" } ] ``` ## File Restrictions When uploading files: * Only PDF files are accepted * Duplicate files for the same submission will be rejected # Plaid Integration Source: https://docs.herondata.io/integrations/plaid To integrate with Heron Data using Plaid, you’ll need to configure an integration in the Heron and Plaid Dashboards. ## Prerequisites Before following this guide, you will need: * Access to [dashboard.herondata.io](http://dashboard.herondata.io) and via your `username` and `password`, and also an `api_key` to call our API. * A working [Plaid Link](https://plaid.com/docs/link/) implementation including storing `item_id`s and `access_token`s in your system. * A unique identifier for each of your customers (which can have many Plaid connections) that you can send to us. We call this the `end_user_id`. ## Integration steps 1. Log in to [dashboard.herondata.io](http://dashboard.herondata.io) 2. Go to **Settings** on the sidebar menu then scroll to the **Integrations** section. 3. Select “Plaid” as an integration type and give your integration a meaningful name. Heron Dashboard Add Plaid Integration 4. Go to your Plaid dashboard ([https://dashboard.plaid.com/team/keys](https://dashboard.plaid.com/team/keys)) and copy over the `client_id` and `secret`. :::note Ensure the `secret` is for the environment (Development, Sandbox, Production) you intend to use ::: Plaid Dashboard Keys 5. Enter the Plaid keys from above into the Heron Dashboard, and then submit the form. 6. Once created you will see your integration in a table. Click **View** to get the **webhook URL** and **link URL** which you will need in the next steps. Heron Dashboard Integrations List 7. In your code, set the `webhook` parameter of **[`/link/token/create`](https://plaid.com/docs/api/tokens/#linktokencreate)** to the **webhook URL**. (Alternatively, if you want to keep your webhook handling, forward all Plaid incoming webhooks including headers to the **webhook URL**) 8. **New Requirement:** When creating a link token with the **[`/link/token/create`](https://plaid.com/docs/api/tokens/#linktokencreate)** endpoint, you must now include the transactions.days\_requested field to specify the desired historical transaction length. The default is 90 days, but you should now set the transaction.days\_requested field to 730 days. 9. In your code, after calling **[`/item/public_token/exchange`](https://plaid.com/docs/api/tokens/#itempublic_tokenexchange)** send the resulting Plaid `item_id` and `access_token`, along with your `end_user_id` as a `POST` request to the **link URL**, [documented here](/api-reference/integrations/create-an-integration-link). ## Final result This diagram illustrates the final flow of data between your customers, your Plaid Link flow, Plaid and Heron Data. The blue lines represent the code changes explained in the previous section. Plaid Integration Diagram Whenever Plaid has new transactions for this Item, we will retrieve, store and process them. The incremental transactions will be available to consume via our API or our dashboard. # Release Notes Source: https://docs.herondata.io/miscellaneous/release-notes Starting in 2025, Heron Data will maintain an ongoing changelog of product updates and new features. For inquiries, new customers can reach us at [hello@herondata.io](mailto:hello@herondata.io), while existing customers should contact [support@herondata.io](mailto:support@herondata.io). It's been a busy month at Heron, and we're excited to share the latest updates we've rolled out to make your underwriting faster and smarter. Here's what's new: # New Enrichers ## Court Search Record 🏛️ Our unified court enricher now combines federal court and state court data, giving you comprehensive court records for the business and its owners in one search. No more toggling between systems or missing critical litigation history. Screenshot2025 09 19at1 40 22PM Pn *See court judgments, liens, and legal proceedings all in one place - helping you catch legal risks before they become losses.* ## Web Presence Analysis 🌐 Our new web presence enricher validates business legitimacy through comprehensive online footprint analysis of the business and its owners. Including social media presence, adverse media, business directory listings, and more to get a complete picture of a business's digital credibility. Screenshot2025 09 19at1 46 19PM Pn *Instantly spot fake businesses and verify authentic operations - reducing fraud losses while boosting your approval confidence.* ## DataMerch Lending History**📊** Heron’s now integrated with DataMerch's 100,000+ merchant database, revealing payment histories and defaults specific to alternative lending that traditional credit reports miss. Access real-time data on suspicious activity, slow pays, and industry-specific risk flags. *Avoid funding businesses that have already burned other lenders - preventing costly defaults before they happen.* ## Secretary-of-State (SOS) Checks **🏛️** Automatically verify business legitimacy across all 50 states with comprehensive Secretary of State filings lookup. Get instant access to business status, filing dates, ownership details, and UCC liens without manual website searches. Screenshot2025 09 19at2 21 31PM Pn *Catch inactive, suspended, or fraudulent businesses instantly - ensuring you only fund legitimate, active entities.* ## Industry Restriction Lists with NAICS/SIC Codes 🚫 Enhancements to industry prediction now automatically flag businesses against your custom restricted NAICS/SIC code lists. The industry classifier is AI-powered classification with 97.56% accuracy on restricted industries with automatic policy enforcement. *Block prohibited industries before underwriting begins - eliminating manual industry checks and policy violations.* # Enhanced Analytics ## Upgraded Debt Candidates Table 💳 Built on advanced transaction clustering, this new feature identifies debt candidates and recurring payment patterns. Now includes counterparty filtering and weekly frequency analysis. *Now you can, spot over-leveraged borrowers through hidden debt relationships and payment obligations - reducing your charge-off risk.* # Improved Integrations ## Dropbox Link Handling from Email 📁 We've supercharged document ingestion to automatically handle Dropbox links that are in emails, crawl Salesforce-site links, and process zip files that used to cause delays. *Get complete document packages from your company’s Dropbox!* ## Enhanced CRM Integration 🔗 **LendSaas Users -** now get automatic decline reason sync, deal underwriting status updates, and seamless file upload support. We've also added detailed logging and optional billing address features. *With Heron’s integrations to your CRM, keep your pipeline moving with automated workflow updates.* # Dev & Ops Tools ## Single-Sign On Access 👥 We’ve added Single Sign-On (SSO) support! Now you can log into Heron with Google and other third-party identity providers—making access faster, easier, and more secure. *Want to centralize user management? Reach out to the Heron team to enable SSO with your organization’s provider.* *** ***Are you ready to enable these features?*** *Contact our support team (*[*support@herondata.io*](mailto:support@herondata.io)*) or reach out if you have specific tools you'd like to see added.* It's been a busy few months at Heron, and we're excited to share some of the latest features and improvements we've rolled out to enhance your experience. Here's a quick overview of what's new: ### The Nest 🪺 Heron's Automation Hub is your command center to automate document-heavy workflows — connect sources, extract insights, enrich with context, and send data where it needs to go. ![Image of the Nest in the Heron Dashboard](https://storage.googleapis.com/public-heron-docs-assets/2025-07/TheNest.png) ### Smart Review with Judge-in-the-Loop Our new agent now helps identify, verify, and validate parsed data before it reaches you, drasticly increasing parsing accuracy. See a validations summary of the agent's findings and field-specific suggestions directly in the UI. ![Image of JITL](https://storage.googleapis.com/public-heron-docs-assets/2025-07/JITL.png) ### Visualise Document Parsing Instantly see how Heron extracts data from documents with interactive bounding boxes. Giving you clear, visual context into how we understand your docs - making it easier to trust and verify the data we extract. ![Image of document parsing visualisation](https://storage.googleapis.com/public-heron-docs-assets/2025-07/BoundingBoxes.png) ### Widgets View your enriched data, in a way that makes sense to you. Our new dashboard widgets let us show you the data we extract in a way that makes sense to you. Whether it’s a table, links, an image generated from enrichment, or a text-based summary of a business' operations, we can build dynamic UI's to show you the data you need to make decisions. ### New Enrichers We've added new ways to get insights into your submissions with new enrichers: * **Business Summary Generation**: Get a quick overview of the business's financial health and operations. * **Secretary-of-State Checks**: Verify business registrations and compliance. * **HazardHub**: Assess environmental risks associated with properties. * **Cysmo**: Gain insights into cybersecurity posture. * **DataMerch**: Access comprehensive data on businesses and individuals. Connect with us via support if you'd like to enable any of these in your environment or if you have other enrichers you'd like to see! ### Customizable End User Output * Heron now supports the ability to translate the output of parsed files into a variety of different customizations: 1. Set arbitrary policy checks 2. Show custom results in the Heron dashboard 3. Export specific views to Excel 4. Create entities for syncing with your CRM * This enables Heron to much more powerfully customize your environment to your needs * Reach out to if there are specific checks or views you would like to implement based on the data we extratc! ![Image of customized dashboard view](https://storage.googleapis.com/public-heron-docs-assets/2025-05/Screenshot%202025-06-09%20at%2017.35.29.png) ### CRM integrations * Heron now integrates with Google Drive, HubSpot * Let us know if you have other integrations you would like to add! ### Other * Users with multiple environments in Heron (e.g,. dev, staging, production) can access each environment from single login * We have a faster, cleaner new end users view, let us know if you would like this enabled! ![Image of new end user dashboard](https://storage.googleapis.com/public-heron-docs-assets/2025-05/Screenshot%202025-06-09%20at%2017.44.08.png) ### Restricted industry & NAICS classification * Heron now supports 2 industry related features - 1) the ability to specify your restricted industry and for Heron to detect whether an end user belongs in the restricted industry, and 2) NAICS prediction * For restricted industry, you can specify the restricted industries in your settings ![Image of restricted industry setting](https://storage.googleapis.com/public-heron-docs-assets/2025-03/restricted-industry-setting.png) * Based on your specified restricted industries descriptions, we determine whether the end user matches your description. This includes a confidence score and reasoning for why we make that determination ![Image of restricted industry result](https://storage.googleapis.com/public-heron-docs-assets/2025-03/restricted-industry-result.png) * We additionally provide both a 4- and 6-digit NAICS code prediction, including a confidence score ![Image of NAICS prediction](https://storage.googleapis.com/public-heron-docs-assets/2025-03/naics-prediction.png) * This information is available to all customers in the dashboard and via API. You can now set Policies within Heron to reject submissions based on restricted industry or NAICS ### Enhanced Debt Positions Detection * Heron has improved our debt position detection in multiple ways: 1. Enhanced logic for identifying and grouping recurring debt 2. Introducing an "is\_active" indicator on debt summary table, to indicate whether we believe a given debt position is still being paid off * This will allow higher accuracy in debt identification, and allow users to more easily see which debt positions are currently relevant * This is available in the dashboard, API, and in our Excel export feature ![Image of debt positions table](https://storage.googleapis.com/public-heron-docs-assets/2025-03/debt-positions.png) ### Other * **Retrigger document processing in UI** trigger classification and processing of documents * **Strengthening Heron core platform** we invested in some core Heron platform functionality, so we expect to deliver higher quality features more quickly in the coming months ### End User Entities * Heron can now aggregate and reconcile information from different sources * e.g., does the extracted company name match between all of application form, bank statement, and voided check? * This helps to surface any discrepancies between sources, and creates a "source of truth" for information across different files * This feature is live but in beta. Reach out to the Heron team if you are interested in enabling this for your Heron instance! ![Image of end user entities](https://storage.googleapis.com/public-heron-docs-assets/2025-02/end-user-entities.png) ### Configurable policy checks  * Heron customers can now configure custom policy checks based on your criteria * e.g., define custom thresholds for bank statement attributes like the \$ threshold for low balance * This enables you to further customize kickout rules based on bank statements based on your policies * Get started with this today by toggling thresholds in the [settings](https://dashboard.herondata.io/settings) page ![Image of threshold](https://storage.googleapis.com/public-heron-docs-assets/2025-02/thresholds.png) ### Daily CRM sync report * You can now subscribe to a daily report of end users and their CRM sync status * e.g., we report on either on sync success, failure, or "kick out" where we have automatically filtered out a submission for you * This enables you to have greater visiblity over Heron system reliability and failure cases * Reach out to Heron team if you want this enabled! ### Other * **Better Excel export** Information on emails relating to a submission are now included in our Excel export * **Starred companies** Return of the starred button on companies page to help separate companies you want to differentiate ![Starred company](https://storage.googleapis.com/public-heron-docs-assets/2025-02/starred-company.png) * **FICO score extraction** Heron now extracts FICO scores when reading application forms * **Better CRM integrations** We sync files to Orgmeter and now support Microsoft Dynamics as CRM ### Upload additional files to existing company profile in Heron via Email Do you ever receive new information for an existing application on a different thread? Do brokers send stips directly to your ISO rep or upload to a portal instead of replying to the existing email chain? Now each submission in Heron has a unique email address where you and your team can forward files directly to, which will be appended to the existing deal Add additional bank statements, drivers licenses, voided check with one click ### Data Integrity & Coverage Improvements Last month we soft-launched our Transaction Data Coverage feature and since then we have massively improved the functionality of it - you will now see it prominently on the Bank and Debt Summary tab, the one-stop shop for managing your data and underwriting a file: * Data source discrepancies are now reported and displayed in the front end * Users can now reassign any data source to any account ID on the front end * Users can enable or disable data source accounts directly from the data coverage chart ### Whitelist Specific IPs to restrict access to Heron Given the sensitive nature of the data you share with us, we have added the ability to restrict access to certain IP addresses for your users so that they do not access Heron inappropriately We are still planning on launching SSO capabilities this quarter ### Marking Recurring Transactions as MCA Debits You can now mark certain recurring transactions as specifically MCA related transactions if we are unable to identify the funder This will automatically include the debits in the MCA debits and holdback percentage columns in the bank statement summary table Additionally, our team will be automatically alerted so we can make sure we identify that merchant as an MCA going forward ### Policy Feature Updates We can now auto-decline any deal if any bank statement has a high anomaly score ### Bank Statement Summary Updates In addition to showing the number of Overdraft or NSF Fees that a company incurs in a monthly period, we will also show the number of transactions for each month where the resulting balance for that transaction was negative. A company may not receive a fee for all their overdraft transactions so seeing the number of overdraft transactions separately will help in the risk assessment process. ### Balance Table Updates Added a plot ↔ table toggle to the existing balance chart for improved visualization. Ability to add a user-designated threshold that will highlight any daily balance under that amount ### API updates The end\_user/transactions endpoint now supports filtering by multiple account IDs and category IDs Improved webhook reliability with exponential backoff retries for failed webhooks ### New Scorecard Metrics A new custom metric was created to track the number of new MCA positions taken in the last 45 days (we previously only shows last 30 days or last 60 days). ### Account Insights Account data (Owner, Bank Name, Account Number, etc.) from bank statements now populate the Balance Insights table. We were previously only showing this information for Plaid data sources ### Data Coverage & Display Fixed incorrect data coverage ranges for Plaid data sources. Resolved stacking issues in the Data Coverage chart. Improved performance of the data coverage report endpoint. ### UI/UX Enhancements Improved the menu dropdown for data coverage bars. Added cursor:pointer to all clickable data coverage bars. Disabled the context menu on missing data bars to prevent unnecessary interactions. ### Bank Statement Summary  * Resolved issues where filtering by account caused metrics like Starting Balance, Ending Balance, Avg. Balance, and Negative Days to not update ### Policy Updates Bank Statement Summary company attributes now default correctly instead of to zero ### Miscellaneous * Heron is now able to create Advance objects in Centrex via API * Fixed the issue where the auto-decline email was sent multiple times * Enhanced counterparty detection from transaction descriptions These updates are designed to streamline your experience and provide more powerful tools to manage your workflows. We appreciate your feedback and will continue to improve the platform based on your needs. ### Automatically rename files Files come with a variety of different naming from "statement1.pdf" to "mybankstatement.pdf" to much more outlandish - Now you can normalize filenames based on the type of file and variables extracted from the file, based on a template that you define - e.g., a bank statement can be renamed from "mybankstatement.pdf" to "bank\_statement\_account\_3482\_jan\_2025.pdf" programmatically - These renamed files can be downloaded directly or synced to CRMs, and can be set up from the dashboard directly in [settings](https://dashboard.herondata.io/file_rename_rules) ### Inspect data coverage for bank transactions For submissions with a variety of different sources of bank data it can be difficult to identify which months for which accounts are missing or duplicate - Now you can easily identify which months have missing or overlapping data across all your bank statement PDFs and bank connections (e.g., Plaid) - This is already available for all customers in the [Heron Data dashboard](https://dashboard.herondata.io/end_users) ### Respond to email submissions automatically (improved) It can be difficult to stay on top of email submission inboxes, particularly with spiky volumes - For email submissions that are forwarded to Heron, you can now automate email responses based on the Heron results - For example, Heron can request missing bank statements for submissions missing bank statements - This can be set up by speaking to a member of Heron Data directly ### Populate spreadsheet templates Often our customers want to populate their own spreadsheet templates in Excel or Google Spreadsheets with Heron Data results, a process which was previously manual - Customers can now automatically populate spreadsheets based on customer-specific templates - This can be set up by speaking to a member of Heron Data directly # Merchant Locking Source: https://docs.herondata.io/use-cases/merchant-locking ## Overview Enabling your users to lock cards to specific merchants is a common use case of Heron Data. We have invested significant time & effort to make sure that we can provide you with merchant extraction that is both accurate and has low enough latency to “fit” into a card auth flow. We believe that we are the only provider that can currently enable this use case, and we’re excited to receive any feedback on it! The key outcomes we achieve for our customers are: * More cards issued as companies move their spend over to merchant-locked cards * Higher card spend per card An overview of the flow is here: Merchant Lock Schema ## Locking flow 1. First, you have to enable your user to pick a canonical Heron merchant to lock a card to. You can do this by offering a free-form “search merchant” text field to the customer that sends GET `/merchants/search` [requests](/api-reference/merchants/get-apimerchantssearch). You can populate possible results you show to the user from the results you get from our endpoint. 2. Once the customer has confirmed a merchant, store the `heron_id` of that merchant as the whitelisted merchant for that card. 3. When the user makes a transaction, send a POST `merchants/extract` [request](/api-reference/merchants/post-apimerchantsextract). This endpoint is optimized for very low latency of 200ms-500ms as part of an auth flow, and only accepts a single transaction. 4. Only authorize the transaction with your payment gateway when the `heron_id` you receive back in the response matches the `heron_id` that the card was locked to in step 2. # Customer Spend Reporting Source: https://docs.herondata.io/use-cases/smb-analytics ## Overview Many of our customers use Heron's capabilities to display back insights and analytics to their customers. The key outcomes we help our customers achieve are: 1. Allow users to see spend by merchant or by category 2. Help users with revenue and runway calculations 3. Give users an overview over their cash-based P\&L, for example to monitor spend on certain categories This helps our customers drive retention and engagement for their users. :::info If you have specific requirements for low latency, we are able to process your transactions in a priority queue to ensure we deliver the latency needed. Please contact your Heron representative to find out more. ::: ## Get started ## For a batch of transactions, synchronously enrich all bank data (either business or consumer data) :::caution **For this use case, please limit batch sizes to 2,500 transactions maximum.** ::: 1. **Post Transactions:** Send POST `/transactions` [requests](/api-reference/transactions/enrich-transactions-sync). Make sure that the `end_user_id` in the payload matches a canonical identifier for the consumer from your systems. 1. **Note:** that in the payload, only `amount` and `description` are required. 2. **Note:** If you receive transactions directly from Plaid, Ocrolus or in PDF, we allow you to just pass on the file without any manipulation. This replaces using the `/transactions` endpoint in this step. The endpoints you can use are: * [Plaid - Assets Report](/api-reference/enduserintegrations/upload-plaid-assets) * [Plaid - Transactions Report](/api-reference/enduserintegrations/upload-plaid-transactions) * [Ocrolus Report](/api-reference/enduserintegrations/upload-ocrolus) * [PDF](/api-reference/enduserintegrations/upload-pdf) 2. **Parse response:** In the response to this `POST` request, you will receive back all items you need for a beautiful transaction feed! ```json theme={null} { "transactions": [ { ... "description_clean": "cleaner_description", "merchant": { "heron_id": "mrc_nF5uQ1LPBJn5REabCQGeTH", "name": "merchant_name", "url": "https://some_merchant_url.com", "logo_url": "https://url_to_logo.com/merchant_logo.png", "icon_url": "https://url_to_icon.com/merchant_icon.svg" }, "payment_processor": { "heron_id": "mrc_98gzPbisCPwDkeU123pZ3h", "name": "Square", "url": "https://squareup.com/us/en" } } ] } ``` ## How to display the enriched transactions **Description/name** * You should display back the `merchant.name` where available. * If no `merchant.name`is available, display back either the `payment_processor` or the `description_clean`. * `payment_processor` is the name of the company that processed the payment, like Square, Stripe, Shopify, etc. * `description_clean` will always be a substring of the `description`, but without information about payment methods, store numbers, transaction dates, amounts, etc. :::info Example If you send a description like `SQ* 01203433383 ESPRESSO CIELO SANTA MONICA CA`, you receive back: "payment\_processor": "Square", "description\_clean": "Espresso Cielo Santa Monica" Which one you choose to display back depends on your use case. Note that `payment_processor` will always have a logo/icon attached. ::: **Logo/icon** * You will receive back either a `logo_url`, an `icon_url` or both * The logo is generally rectangular, and the icon is a square * Both are either in `png` or `svg` format * The icon/logo are hosted in one of our Google Cloud Storage buckets, and the URL is static with format: * Icon: `https://storage.googleapis.com/heron-merchant-assets/icons/{merchant_heron_id}.{png|svg}` * Logo: `https://storage.googleapis.com/heron-merchant-assets/logos/{merchant_heron_id}.{png|svg}` **Unique identifier** * You will receive back a unique identifier, the `heron_id`, for each merchant. You can use this identifier as a basis for further logic. For example: * Allow your users to choose a custom category for a specific merchant, based on that merchant's `heron_id`. * Show your users all spend with one merchant by aggregating all spend on one merchant `heron_id`. **Categories \[optional]** :::tip If you do not currently receive categories but would like to receive them, please contact Heron! ::: * If categories are enabled for you, you will receive them back as a dictionary in the transactions object ([see here](/api-reference/transactions/get-apitransactions)). You can display back the `label` to your customer, or assign a static logo to each category instead. ## Feedback We want to receive feedback on incorrect merchants and categories whenever possible, so we can make improvements. There are two ways you can share feedback with us: * **Manual**: You can send us free-form feedback in our shared Slack channel. We also share spreadsheets with customers that enable them to share feedback with us, which we can also make available via Slack. ## How to use the output **Merchants** * A standard use case would be to show your customer all spend per merchant. To do this, sum all spend for a given `heron_id` for a merchant. * You can also build comparative statistics and recommendations on top: For example, for a customer with a given revenue, are they spending relatively more or less than others on a payroll provider? **Categories** * You can display back categories directly, or use the category labels to calculate items like a company's P\&L or historical revenue. * You may want to use confidences to only show back transactions that are categorised with high accuracy. If the annotator on the category label is `reconciled`, your category model has been fine-tuned to have confidence values that map directly to accuracy. This means that for a category label with a confidence of `0.9`, we’d expect the label to be accurate 90% of the time. * You can use these confidences to display back only labels with a certain probability of being correct, depending on your use case. * If the annotator on the category label is either `heuristics` or `predicted`, your model is not fine-tuned for reliable confidences. If you still want to use confidences, please contact Heron. ```json theme={null} { "categories": [ { "annotator": "reconciled", "confidence": 0.91, "heron_id": "ctg_4q5tDaLi66h3EAWYTY11YC", "label": "Rent", "model_version": "0f74d346-10f8-454d-abc2-5980674e07b1" } ] } ``` # MCA/Cash Flow Underwriting Source: https://docs.herondata.io/use-cases/smb-underwriting ## Overview Heron Data’s main use case is to help lenders and fintechs underwrite SMBs using bank data. We do this by enriching each transaction with a category identifying the transaction (e.g., `Revenue` or `Debt Investment`), and then aggregating amounts across these labels to give insights into the company. The key outcomes we achieve for our customers are: 1. **Supercharge underwriters**: Speed up underwriting by an order of magnitude vs. having to manually parse bank data 2. **Expand addressable market**: Underwrite businesses without up-to-date accounting or e-commerce data 3. **Catch fraud**: Because bank data is up-to-date, we have enabled customers to avoid millions of dollars in losses to customers who were loan stacking or had other previously unidentified risk factors We will begin by enriching the bank data, and then looking at how it can be used to analyse companies from the dashboard and via the API. ## Post & enrich company bank data ### Create an end user and enrich transactions 1. **Create an end\_user:** Begin by creating an end\_user in Heron’s systems that corresponds to a company/applicant in your systems. You do this by sending a POST `end_users` [request](/api-reference/endusers/create-enduser#create-enduser). 1. For the `end_user_id` field, use a canonical reference/identifier for the company 2. **Note:** If you are sending transactions for a company that you’ve already sent to Heron before, skip this step. 2. **Send Transactions to Heron** Once you have created the end\_user, you can start sending us transactions in many ways 1. Set up a Direct Plaid Integration - this is recommended if you use Plaid and want to perform ongoing portfolio monitoring. By setting up a Direct Plaid Integration, we will automatically retrieve new transactions automatically from Plaid whenever there is an update, without any manual intervention required. Steps to set up this integration can be found [here](/integrations/plaid) 2. Send PDF bank statements - **note: this will incur a separate fee per bank statement and PDF parsing must be enabled for your account prior to uploading the documents.** Steps to set up this integration can be found [here](/integrations/bank-statements) 3. Send system output files - Heron can accept certain files directly without any manipulation. For example, if you use Plaid but do not wish to integrate Heron directly to Plaid, then you can send us Plaid reports instead 1. [Plaid - Assets Report](/api-reference/enduserintegrations/upload-plaid-assets#upload-plaid-assets) 2. [Plaid - Transactions Report](/api-reference/enduserintegrations/upload-plaid-transactions) 3. [Ocrolus Report](/api-reference/enduserintegrations/upload-ocrolus#upload-ocrolus) 4. POST transactions via API 1. If you want to send us transactions directly from your system, you can POST transactions for a given end\_user using the `/end_users/{end_user_id}/transactions` endpoint for sending [requests](/api-reference/transactions/create-end-user-transactions-async). 2. **Note:** Please batch up to 20k transactions per request 3. **Process Transactions:** When you are done sending us transactions for a company, please send a PUT `end_users` [request](/api-reference/endusers/update-enduser#update-enduser), indicating that the end\_user is `ready` for processing. 1. **Note:** if you have set up a Direct Plaid Integration or are sending Heron PDF bank statements, skip this step. 4. **Listen to webhook:** We will notify you via a [webhook](/api-reference/webhooks.mdx) when the `end_user_id` is `processed`, and available for you to retrieve. You can configure your webhook in the [dashboard](https://dashboard.herondata.io/). 5. **Get transactions**: Once you have received the webhook, you can send a [request to retrieve the enriched transaction data](/api-reference/enrichedtransactions/get-end-user-transactions). 1. **Note**: We still support the `/transactions` [endpoint](/api-reference/transactions/get-apitransactions) that was previously used by most customers. The new endpoint that is now standard is much more performant, so we recommend using that endpoint instead. If using the old endpoint, you can use the `end_user_id` parameter to ensure you only pull transactions for the `end_user_id` that was just enriched. If you get transactions for a company that you’ve already sent to Heron before, you can use the `last_updated_min` filter to only get transactions where labels have changed since the last time you send and fetched transactions. You now have enriched data for a given company. ## Inspect company using the dashboard *This section only describes the dashboard at a very high-level. To get more detailed information, please contact Heron Data for an onboarding session* During your integration, you can use the [dashboard](https://dashboard.herondata.io/) to make sure that all steps work as expected. 1. Navigate to the `All Companies` page. This will give you an overview over the companies (i.e., `end_user`) you have created. Companies Page 2. You can see the status of the company in the `status` column of the main table. To view the generated reports for a company, click on the companies' `name`. 3. To ensure that the reports are suitable for underwriting, confirm that the three sets of data quality checks have passed for the company (i.e. Data Sources, Accounts, Transactions). 1. To view the data checks, click on the applicable application component on the left hand panel and then `Data Checks` at the top 4. If all of the Data Quality checks have passed, navigate to one of the `Underwriting Reports` for one of the companies. Here, you will see multiple reports that visualize Deposits, Withdrawals, Debt, Revenue, P\&L, risk flags and other financial metrics about the company. 5. To inspect the transactions uploaded, click on the `transactions` button on the left. 6. To verify all possible categories that your model may attach to transactions, navigate to the `Categories` tab. You can inspect all labels there. ## Retrieve aggregate metrics on a company Instead of consuming the enriched transaction data, it may be easier to consume aggregated metrics for a given company. For example, you may want to see monthly historical revenue for a company, as estimated by Heron Data. We allow you to do this by downloading either self-contained reports (e.g. Bank Statement Summary, Cash-Based P\&L), certain aggregate metrics contained in our Heron Scorecard, and/or historical time series and forecasts per category label. ### Get Heron Scorecard We have aggregated the most common metrics calculated on top of Heron Data output in our Heron Scorecard. The Scorecard will allow you to quickly evaluate a company, by providing labels such as: To get the Heron Scorecard, send a GET `end_users/{end_user_id_or_heron_id}/scorecard` [request](/api-reference/endusercalculations/get-enduser-scorecard). * **Data Quality**: Measures to help you understand the quality and completeness of the bank data our analysis is based on, e.g. `Data Coverage` & `Data Freshness`. Also includes a measure to see what percentage of all transactions (as a proportion of revenue) appear to be going to an unconnected account held by the company we are analysing. * **Risk Flags**: Flags like `ATM Cash Withdrawals` and distinct days with insufficient funds / overdraft fees. * **Balance**: Statistics about average, max and min balances. * **Profit & Loss**: Approximations of standard cashflow-based metrics like `Revenue`, `Net Operating Cashflow`, etc. * **Debt**: Number, recency and amounts of recent debt investments and repayments ### Get historical timeseries To get historical time series, (e.g. `Revenue` over time for each month), send a GET `end_users/statistics` [request](/api-reference/endusercalculations/get-enduser-statistics). In the parameters, you can specify: 1. The `end_user_id` of the company you are looking at 2. The time periods over which you want to aggregate, often this is per month (`date_granularity`) 3. Whether you want to pivot by `merchant`, `category` or both 4. If you want to see only certain categories, filter by `category_heron_ids` :::info Example To get the monthly revenue for end\_user\_id `12345` you would send a `GET` request to the following: ``` https://app.herondata.io/api/end_users/statistics?end_user_id=12345&group_by=category&date_granularity=month&category_heron_ids={category_heron_id_for_revenue} ``` ::: ### Get forecast To get forecasts for a category timeseries, send a GET `end_users/forecast` [request](/api-reference/endusercalculations/get-enduser-forecasts). You can use similar logic to the historical timeseries section above to get forecasts for the time intervals and category labels you care about. For more information on forecasts and any feedback, please talk to us!