Bulk create category feedback
Provide bulk feedback on Transaction Categories
Authorizations:
Request Body schema: application/json
A list of objects containing a Transaction's heron id and the suggested Category. If you provide a heron_id
for Category, you don't need to provide other fields. If heron_id
is provided, we disregard label
.
object (CategoryFeedback) | |
source | string or null <= 120 characters Default: null your identifier for where the feedback comes from e.g. bob_the_underwriter |
transaction_heron_id required | string heron id of transaction |
Responses
Request samples
- Payload
[- {
- "category": {
- "heron_id": "ctg_mRNB6ZCRGJSNrdPWdtuJV4",
- "label": "Insurance"
}, - "source": null,
- "transaction_heron_id": "txn_7YpdQBPTguehbEBXbKVh75"
}
]
Response samples
- 201
{- "num_annotations": 1
}
Create category, merchant feedback
Provide feedback on a Transaction's Categories and Merchants
Authorizations:
path Parameters
heron_id required | string Transaction |
Request Body schema: application/json
A partial Transaction object with the suggested Category and/or Merchant. If you provide a heron_id
for Category or Merchant, you don't need to provide other fields. If you don't know the Merchant heron_id
nor name, you can just send the is_correct
boolean. If heron_id
is provided, we disregard name
and label
. If is_correct
is set to true, we disregard all other Merchant fields.
object (TransactionFeedbackSchema) | |||||||
|
Responses
Request samples
- Payload
{- "transaction": {
- "category": {
- "heron_id": "ctg_HJsgV7sRSbfXknUof5Fam4",
- "label": "Insurance"
}, - "merchant": {
- "heron_id": "mrc_QCJk7j3x6Hp5ipczRFZtyM",
- "is_correct": false,
- "name": "Spotify"
}, - "source": null
}
}
Response samples
- 200
{- "categories": [
- {
- "analytics_group": "revenue",
- "created": "2023-09-27T16:32:21.979662",
- "description": "Rent for offices, workspaces or storage facilities",
- "heron_id": "ctg_FoWfSzsjkTpC4D29yQfb8e",
- "label": "Rent"
}
]
}
Update a data source
Update a data source
Authorizations:
path Parameters
heron_id required | string |
Request Body schema: application/json
is_enabled | boolean Default: true Whether or not the data source is enabled. If disabled, hides related transactions from analytics |
Responses
Request samples
- Payload
{- "is_enabled": true
}
Response samples
- 200
{- "created": "2023-08-16T16:32:22.040862",
- "data_source_accounts": [
- {
- "account_id": "202348",
- "anomaly_score": 200,
- "enabled": true,
- "max_date": "2022-01-31",
- "min_date": "2022-01-01",
- "num_transactions": 120,
- "transactions_match_balances": true
}
], - "heron_id": "dso_DdxQe6EZK2Cs9wuRYvoDZV",
- "is_enabled": true,
- "last_updated": "2023-09-27T16:32:22.040910",
- "metadata": {
- "filename": "202348_JAN_2022.pdf",
- "status": "processed"
}, - "reference_id": "pdf_ZqDefQ7MSde9FN4Sfwteyn",
- "status": "new",
- "type": "pdf"
}
Get data sources
Get a list of data sources for a company
Authorizations:
path Parameters
end_user_id_or_heron_id required | string |
Responses
Response samples
- 200
[- {
- "created": "2023-08-16T16:32:22.040862",
- "data_source_accounts": [
- {
- "account_id": "202348",
- "anomaly_score": 200,
- "enabled": true,
- "max_date": "2022-01-31",
- "min_date": "2022-01-01",
- "num_transactions": 120,
- "transactions_match_balances": true
}
], - "heron_id": "dso_DdxQe6EZK2Cs9wuRYvoDZV",
- "is_enabled": true,
- "last_updated": "2023-09-27T16:32:22.040910",
- "metadata": {
- "filename": "202348_JAN_2022.pdf",
- "status": "processed"
}, - "reference_id": "pdf_ZqDefQ7MSde9FN4Sfwteyn",
- "status": "new",
- "type": "pdf"
}
]
List EndUsers
Get a list of EndUsers
Authorizations:
query Parameters
limit | integer [ 1 .. 10000 ] Default: 1000 Pagination limit per page |
include_data_sources | boolean Default: false Example: include_data_sources=true Whether the to include data sources for each end user |
is_portfolio | boolean or null Default: null Example: is_portfolio=true Whether the end user is part of a lending portfolio |
end_user_id | string or null Default: null Example: end_user_id=your_end_user_id Filter by ID associated with end_user_id field in transactions |
status | string or null Default: null Enum: "new" "ready" "processed" "reviewed" "review_requested" "failed" Example: status=reviewed Filter by status of end user |
heron_id | string or null Default: null Example: heron_id=eus_8UpzDVDvPRetuDtwZw42Fu Unique ID generated by Heron |
order_by | string Default: "last_updated_desc" Enum: "last_updated_desc" "last_updated_asc" Order to return end users by |
page | integer >= 1 Default: 1 Pagination page number |
name | string or null Default: null Example: name=your_end_user_name Filter by name associated with end user |
Responses
Response samples
- 200
{- "_meta": {
- "limit": 1000,
- "next_url": "string",
- "page": 1,
- "pages": 3,
- "prev_url": "string",
- "total": 3500
}, - "end_users": [
- {
- "confidence": 0.42,
- "created": "2023-08-16T16:32:22.118104",
- "criteria": [
- {
- "context": "higher_is_better",
- "currency": "string",
- "date_range": "last_180_days",
- "description": "The number of unique transactions with a timestamp",
- "group": "data_quality",
- "label": "unique_transactions",
- "status": "not_available",
- "unit": "n",
- "value": 42.42
}
], - "data_sources": [
- {
- "status": "new",
- "type": "pdf"
}
], - "end_user_id": "5f8217fd-297c-4e66-adcb-39b062f685aa",
- "heron_id": "eus_YpseZNi9U3BRuQmKXXru7T",
- "is_portfolio": true,
- "last_updated": "2023-09-27T16:32:22.118143",
- "name": "Company Name Inc.",
- "profit_and_loss_layout": null,
- "status": "ready"
}
]
}
Create EndUser
Create a new end user. If transactions have previously been sent for this end_user_id
, use PUT end_users
to update instead.
Authorizations:
Request Body schema: application/json
object (EndUser) | |||||||||||
|
Responses
Request samples
- Payload
{- "end_user": {
- "end_user_id": "5f8217fd-297c-4e66-adcb-39b062f685aa",
- "is_portfolio": true,
- "name": "Company Name Inc.",
- "profit_and_loss_layout": null,
- "status": "ready"
}
}
Response samples
- 201
{- "end_user": {
- "confidence": 0.42,
- "created": "2023-08-16T16:32:22.118104",
- "criteria": [
- {
- "context": "higher_is_better",
- "currency": "string",
- "date_range": "last_180_days",
- "description": "The number of unique transactions with a timestamp",
- "group": "data_quality",
- "label": "unique_transactions",
- "status": "not_available",
- "unit": "n",
- "value": 42.42
}
], - "data_sources": [
- {
- "status": "new",
- "type": "pdf"
}
], - "end_user_id": "5f8217fd-297c-4e66-adcb-39b062f685aa",
- "heron_id": "eus_YpseZNi9U3BRuQmKXXru7T",
- "is_portfolio": true,
- "last_updated": "2023-09-27T16:32:22.118143",
- "name": "Company Name Inc.",
- "profit_and_loss_layout": null,
- "status": "ready"
}
}
Update EndUser
Confirm an end user is ready for async procesing by sending a status of "ready". The end_user_id
must have previously been sent with at least one Transaction.
Authorizations:
Request Body schema: application/json
Dictionary representing an EndUser
object (EndUser) | |||||||||||
|
Responses
Callbacks
Request samples
- Payload
{- "end_user": {
- "end_user_id": "5f8217fd-297c-4e66-adcb-39b062f685aa",
- "is_portfolio": true,
- "name": "Company Name Inc.",
- "profit_and_loss_layout": null,
- "status": "ready"
}
}
Response samples
- 200
{- "end_user": {
- "confidence": 0.42,
- "created": "2023-08-16T16:32:22.118104",
- "criteria": [
- {
- "context": "higher_is_better",
- "currency": "string",
- "date_range": "last_180_days",
- "description": "The number of unique transactions with a timestamp",
- "group": "data_quality",
- "label": "unique_transactions",
- "status": "not_available",
- "unit": "n",
- "value": 42.42
}
], - "data_sources": [
- {
- "status": "new",
- "type": "pdf"
}
], - "end_user_id": "5f8217fd-297c-4e66-adcb-39b062f685aa",
- "heron_id": "eus_YpseZNi9U3BRuQmKXXru7T",
- "is_portfolio": true,
- "last_updated": "2023-09-27T16:32:22.118143",
- "name": "Company Name Inc.",
- "profit_and_loss_layout": null,
- "status": "ready"
}
}
Callback payload samples
{- "created": "2019-08-24T14:15:22Z",
- "data": {
- "end_user_id": "myenduser",
- "heron_id": "eus_Eqio3Y4dhyNiMphrXwG58p",
- "status": "processed"
}, - "meta": { },
- "topic": "string"
}
Get EndUser by heron_id or end_user_id
Get an end user using its end_user_id or heron_id
Authorizations:
path Parameters
end_user_id_or_heron_id required | string |
Responses
Response samples
- 200
{- "end_user": {
- "confidence": 0.42,
- "created": "2023-08-16T16:32:22.118104",
- "criteria": [
- {
- "context": "higher_is_better",
- "currency": "string",
- "date_range": "last_180_days",
- "description": "The number of unique transactions with a timestamp",
- "group": "data_quality",
- "label": "unique_transactions",
- "status": "not_available",
- "unit": "n",
- "value": 42.42
}
], - "data_sources": [
- {
- "status": "new",
- "type": "pdf"
}
], - "end_user_id": "5f8217fd-297c-4e66-adcb-39b062f685aa",
- "heron_id": "eus_YpseZNi9U3BRuQmKXXru7T",
- "is_portfolio": true,
- "last_updated": "2023-09-27T16:32:22.118143",
- "name": "Company Name Inc.",
- "profit_and_loss_layout": null,
- "status": "ready"
}
}
Send patch transactions for a pdf statement
Send patch transactions processed pdf that will override the extracted transactions in the specified statement
Authorizations:
path Parameters
heron_id required | string heron_id of the pdf |
Request Body schema: application/json
exclude | boolean True if the statement should be excluded from processing |
index required | integer The index of the statement in the pdf to patch |
object (PdfPatchStatementSummary) | |
required | Array of objects (PdfPatchTransaction) The full list of transactions that will be used to override the extracted transactions for the specified statement |
Responses
Request samples
- Payload
{- "exclude": true,
- "index": 0,
- "summary": {
- "account_number": "string",
- "bank_name": "string",
- "company": "string",
- "end_balance": 0,
- "start_balance": 0,
- "statement_end_date": "2019-08-24T14:15:22Z",
- "statement_start_date": "2019-08-24T14:15:22Z"
}, - "transactions": [
- {
- "amount": 0,
- "balance": 0,
- "bounds": {
- "page": 0,
- "x_max": 0,
- "x_min": 0,
- "y_max": 0,
- "y_min": 0
}, - "description": "string",
- "ocr_suspect": true,
- "reference_id": "string",
- "timestamp": "2019-08-24T14:15:22Z",
- "transaction_code": "string"
}
]
}
Response samples
- 200
{- "ok": true
}
Get EndUser balance
Get balance for given EndUser on a daily and account granularity
Authorizations:
query Parameters
to_currency | string or null Enum: "GBP" "USD" "EUR" Example: to_currency=USD ISO 4217 currency code to convert to |
timestamp_min | string or null <date-time> Default: null Example: timestamp_min=2023-09-27T16:32:22.024487 Deprecated (use date_min instead). Filter for transactions with timestamp after the input value |
include_forecast | boolean Default: false If true, forecasts the balances of each account |
date_min | string or null <date> Default: null Example: date_min=2023-09-27 Filter for transactions with timestamp after the input value (inclusive). It has precedence over timestamp_min |
date_max | string or null <date> Default: null Example: date_max=2023-09-26 Filter for transactions with date earlier than the input value (inclusive). It has precedence over timestamp_max |
end_user_id | string or null Default: null Example: end_user_id=your_end_user_id end_user_id for statistics; either end_user_id or end_user_heron_id is required |
end_user_heron_id | string or null Default: null Example: end_user_heron_id=eus_j9Hsdj3C8Mr6BYx34dM9QL Heron-generated id for end user; either end_user_id or end_user_heron_id is required |
timestamp_max | string or null <date-time> Default: null Example: timestamp_max=2023-09-26T16:32:22.024543 Deprecated (use date_max instead). Filter for transactions with timestamp earlier than the input value |
Responses
Response samples
- 200
{- "daily_balances": [
- {
- "accounts": [
- {
- "account_id": "string",
- "balance": 0,
- "balance_converted": 0,
- "currency": "USD",
- "currency_converted": "USD",
- "is_computed": true,
- "is_latest": true,
- "timestamp": "2019-08-24T14:15:22Z"
}
], - "accounts_not_converted": [
- {
- "account_id": "string",
- "balance": 0,
- "balance_converted": 0,
- "currency": "USD",
- "currency_converted": "USD",
- "is_computed": true,
- "is_latest": true,
- "timestamp": "2019-08-24T14:15:22Z"
}
], - "balance": 0,
- "currency": "USD",
- "date": "2019-08-24"
}
], - "forecasted": [
- {
- "account_id": "string",
- "balances": [
- {
- "date": "2023-09-27",
- "predicted": 42.42,
- "predicted_lower": 4.24,
- "predicted_upper": 420.42
}
], - "currency": "string"
}
], - "summary": {
- "accounts": [
- {
- "account_id": "string",
- "balance": 0,
- "balance_converted": 0,
- "currency": "USD",
- "currency_converted": "USD",
- "is_computed": true,
- "is_latest": true,
- "timestamp": "2019-08-24T14:15:22Z"
}
], - "accounts_not_converted": [
- {
- "account_id": "string",
- "balance": 0,
- "balance_converted": 0,
- "currency": "USD",
- "currency_converted": "USD",
- "is_computed": true,
- "is_latest": true,
- "timestamp": "2019-08-24T14:15:22Z"
}
], - "balance": 0,
- "currency": "USD",
- "date": "2019-08-24"
}
}
Get EndUser forecasts
Get forecast amounts for a given EndUser and category
Authorizations:
query Parameters
to_currency | string or null Enum: "GBP" "USD" "EUR" Example: to_currency=USD ISO 4217 currency code to convert to |
to_date | string or null <date> Default: null Example: to_date=2022-01-31 The latest transaction timestamp date to use in forecasting |
category_heron_id | string Example: category_heron_id=ctg_bLf8NBiJ8jqekUa7cFEeDS Heron ID of category to be forecasted; either category_heron_id or category_label must be present |
date_granularity | string Default: "month" Enum: "week" "month" Example: date_granularity=month Aggregate results over time, i.e., aggregate by week or by month |
end_user_id | string or null Default: null Example: end_user_id=your_end_user_id end_user_id for statistics; either end_user_id or end_user_heron_id is required |
from_date | string or null <date> Default: null Example: from_date=2022-01-01 The earliest transaction timestamp date to use in forecasting |
category_label | string Example: category_label=Revenue Label of category to be forecasted; either category_heron_id or category_label must be present |
end_user_heron_id | string or null Default: null Example: end_user_heron_id=eus_j9Hsdj3C8Mr6BYx34dM9QL Heron-generated id for end user; either end_user_id or end_user_heron_id is required |
Responses
Response samples
- 200
[- {
- "currency": "USD",
- "date": "2023-09-27",
- "predicted": 42.42,
- "predicted_lower": 4.24,
- "predicted_upper": 420.42
}
]
Get EndUser statistics
Get summarized statistics for a given EndUser
Authorizations:
query Parameters
to_currency | string or null Enum: "GBP" "USD" "EUR" Example: to_currency=USD ISO 4217 currency code to convert to |
to_date | string or null <date> Default: null Example: to_date=2023-09-26 Filter for transactions with timestamp before the input value (as date) |
date_granularity | string Default: "month" Enum: "day" "week" "month" "quarter" "year" Example: date_granularity=month Aggregate results over time, e.g., by week or by quarter |
end_user_id | string or null Default: null Example: end_user_id=your_end_user_id end_user_id for statistics; either end_user_id or end_user_heron_id is required |
category_heron_ids | Array of strings Default: [] Example: category_heron_ids=ctg_jDG5tB7fC8ZjBPUPyqSytJ&category_heron_ids=ctg_22zLn4JX5dfzd5Ti6HGWVH Filter by specific categories |
merchant_heron_ids | Array of strings Default: [] Example: merchant_heron_ids=mrc_U3MGsKDoAYrLhT8oE76MZU&merchant_heron_ids=mrc_VgUBCMTYYQgczoh2SPra8u Filter by specific merchants |
from_date | string or null <date> Default: null Example: from_date=2023-09-27 Filter for transactions with timestamp after the input value (as date) |
end_user_heron_id | string or null Default: null Example: end_user_heron_id=eus_j9Hsdj3C8Mr6BYx34dM9QL Heron-generated id for end user; either end_user_id or end_user_heron_id is required |
group_by | string Default: "category" Enum: "category" "merchant" Example: group_by=category Pivot results by merchant or by category |
Responses
Response samples
- 200
{- "statistics": [
- {
- "currency": "USD",
- "dt": "2023-09-27",
- "heron_id": "mrc_4sjEtDKm5Vk2TBfm3QPcae",
- "label": "Revenue",
- "metrics": {
- "inflow": {
- "amount": 42.42,
- "avg_amount": 1.01,
- "n": 42
}, - "net": {
- "amount": 42.42,
- "avg_amount": 1.01,
- "n": 42
}, - "outflow": {
- "amount": 42.42,
- "avg_amount": 1.01,
- "n": 42
}
}
}
]
}
Get EndUser anomalies
Get anomalies for given EndUser given a category label or heron id
Authorizations:
path Parameters
end_user_id_or_heron_id required | string The |
query Parameters
category_label_or_heron_id required | string Example: category_label_or_heron_id=Revenue Label or Heron ID of category to find anomalies for |
Responses
Response samples
- 200
[- {
- "amount": 42.42,
- "anomaly_score": 0.5,
- "currency": "USD",
- "heron_id": "txn_NVyFkdFSqFUnujJ5Furusf",
- "reference_id": "1342db06-feb7-4c33-a157-4351d74a98e9"
}
]
Get EndUser bank statement summary
Get the bank statement summary by month for an end user
Authorizations:
path Parameters
end_user_id_or_heron_id required | string |
query Parameters
grouping | string Default: "by_month" Enum: "by_month" "rolling_30_days_from_last_txn" "rolling_30_days_from_today" Determines how to group transactions. It supports calendar month (by_month) or rolling 30-day period (from last txns with rolling_30_days_from_last_txn or from today with rolling_30_days_from_today) |
Responses
Response samples
- 200
{- "average": {
- "average_balance": {
- "amount": "1234.56",
- "currency": "USD"
}, - "ending_balance": {
- "amount": "1234.56",
- "currency": "USD"
}, - "mca_debits": {
- "amount": "1234.56",
- "currency": "USD"
}, - "negative_balance_days": 0,
- "no_deposits": 0,
- "no_od_nsf": 0,
- "no_withdrawals": 0,
- "non_revenue": {
- "amount": "1234.56",
- "currency": "USD"
}, - "starting_balance": {
- "amount": "1234.56",
- "currency": "USD"
}, - "total_deposits": {
- "amount": "1234.56",
- "currency": "USD"
}, - "total_revenue": {
- "amount": "1234.56",
- "currency": "USD"
}, - "total_withdrawals": {
- "amount": "1234.56",
- "currency": "USD"
}
}, - "by_month": {
- "property1": {
- "average_balance": {
- "amount": "1234.56",
- "currency": "USD"
}, - "ending_balance": {
- "amount": "1234.56",
- "currency": "USD"
}, - "mca_debits": {
- "amount": "1234.56",
- "currency": "USD"
}, - "negative_balance_days": 0,
- "no_deposits": 0,
- "no_od_nsf": 0,
- "no_withdrawals": 0,
- "non_revenue": {
- "amount": "1234.56",
- "currency": "USD"
}, - "starting_balance": {
- "amount": "1234.56",
- "currency": "USD"
}, - "total_deposits": {
- "amount": "1234.56",
- "currency": "USD"
}, - "total_revenue": {
- "amount": "1234.56",
- "currency": "USD"
}, - "total_withdrawals": {
- "amount": "1234.56",
- "currency": "USD"
}
}, - "property2": {
- "average_balance": {
- "amount": "1234.56",
- "currency": "USD"
}, - "ending_balance": {
- "amount": "1234.56",
- "currency": "USD"
}, - "mca_debits": {
- "amount": "1234.56",
- "currency": "USD"
}, - "negative_balance_days": 0,
- "no_deposits": 0,
- "no_od_nsf": 0,
- "no_withdrawals": 0,
- "non_revenue": {
- "amount": "1234.56",
- "currency": "USD"
}, - "starting_balance": {
- "amount": "1234.56",
- "currency": "USD"
}, - "total_deposits": {
- "amount": "1234.56",
- "currency": "USD"
}, - "total_revenue": {
- "amount": "1234.56",
- "currency": "USD"
}, - "total_withdrawals": {
- "amount": "1234.56",
- "currency": "USD"
}
}
}, - "grouping": "string",
- "rolling_30_days_from_last_txn": {
- "property1": {
- "average_balance": {
- "amount": "1234.56",
- "currency": "USD"
}, - "ending_balance": {
- "amount": "1234.56",
- "currency": "USD"
}, - "mca_debits": {
- "amount": "1234.56",
- "currency": "USD"
}, - "negative_balance_days": 0,
- "no_deposits": 0,
- "no_od_nsf": 0,
- "no_withdrawals": 0,
- "non_revenue": {
- "amount": "1234.56",
- "currency": "USD"
}, - "starting_balance": {
- "amount": "1234.56",
- "currency": "USD"
}, - "total_deposits": {
- "amount": "1234.56",
- "currency": "USD"
}, - "total_revenue": {
- "amount": "1234.56",
- "currency": "USD"
}, - "total_withdrawals": {
- "amount": "1234.56",
- "currency": "USD"
}
}, - "property2": {
- "average_balance": {
- "amount": "1234.56",
- "currency": "USD"
}, - "ending_balance": {
- "amount": "1234.56",
- "currency": "USD"
}, - "mca_debits": {
- "amount": "1234.56",
- "currency": "USD"
}, - "negative_balance_days": 0,
- "no_deposits": 0,
- "no_od_nsf": 0,
- "no_withdrawals": 0,
- "non_revenue": {
- "amount": "1234.56",
- "currency": "USD"
}, - "starting_balance": {
- "amount": "1234.56",
- "currency": "USD"
}, - "total_deposits": {
- "amount": "1234.56",
- "currency": "USD"
}, - "total_revenue": {
- "amount": "1234.56",
- "currency": "USD"
}, - "total_withdrawals": {
- "amount": "1234.56",
- "currency": "USD"
}
}
}, - "rolling_30_days_from_today": {
- "property1": {
- "average_balance": {
- "amount": "1234.56",
- "currency": "USD"
}, - "ending_balance": {
- "amount": "1234.56",
- "currency": "USD"
}, - "mca_debits": {
- "amount": "1234.56",
- "currency": "USD"
}, - "negative_balance_days": 0,
- "no_deposits": 0,
- "no_od_nsf": 0,
- "no_withdrawals": 0,
- "non_revenue": {
- "amount": "1234.56",
- "currency": "USD"
}, - "starting_balance": {
- "amount": "1234.56",
- "currency": "USD"
}, - "total_deposits": {
- "amount": "1234.56",
- "currency": "USD"
}, - "total_revenue": {
- "amount": "1234.56",
- "currency": "USD"
}, - "total_withdrawals": {
- "amount": "1234.56",
- "currency": "USD"
}
}, - "property2": {
- "average_balance": {
- "amount": "1234.56",
- "currency": "USD"
}, - "ending_balance": {
- "amount": "1234.56",
- "currency": "USD"
}, - "mca_debits": {
- "amount": "1234.56",
- "currency": "USD"
}, - "negative_balance_days": 0,
- "no_deposits": 0,
- "no_od_nsf": 0,
- "no_withdrawals": 0,
- "non_revenue": {
- "amount": "1234.56",
- "currency": "USD"
}, - "starting_balance": {
- "amount": "1234.56",
- "currency": "USD"
}, - "total_deposits": {
- "amount": "1234.56",
- "currency": "USD"
}, - "total_revenue": {
- "amount": "1234.56",
- "currency": "USD"
}, - "total_withdrawals": {
- "amount": "1234.56",
- "currency": "USD"
}
}
}, - "total": {
- "average_balance": {
- "amount": "1234.56",
- "currency": "USD"
}, - "ending_balance": {
- "amount": "1234.56",
- "currency": "USD"
}, - "mca_debits": {
- "amount": "1234.56",
- "currency": "USD"
}, - "negative_balance_days": 0,
- "no_deposits": 0,
- "no_od_nsf": 0,
- "no_withdrawals": 0,
- "non_revenue": {
- "amount": "1234.56",
- "currency": "USD"
}, - "starting_balance": {
- "amount": "1234.56",
- "currency": "USD"
}, - "total_deposits": {
- "amount": "1234.56",
- "currency": "USD"
}, - "total_revenue": {
- "amount": "1234.56",
- "currency": "USD"
}, - "total_withdrawals": {
- "amount": "1234.56",
- "currency": "USD"
}
}
}
Get EndUser metric benchmarks
Get the benchmarks for each metric for an end user
Authorizations:
path Parameters
end_user_id_or_heron_id required | string |
Responses
Response samples
- 200
{- "benchmarks": [
- {
- "date_range": "last_180_days",
- "label": "unique_transactions",
- "percentile": 0.75,
- "rank": 22,
- "sample_size": 42,
- "scope": "user"
}
]
}
Get EndUser Heron Score (beta)
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.
Authorizations:
path Parameters
end_user_id_or_heron_id required | string |
query Parameters
date | string or null <date> Default: null Example: date=2023-01-19 Cut-off date to consider transactions to for calculating heron score (inclusive) |
min_category_confidence | number or null Default: null Example: min_category_confidence=0.8 Minimum company categorisation confidence to calculate Heron Score |
Responses
Response samples
- 200
{- "data_quality_issues": [
- "transactions_without_timestamps"
], - "feature_groups_contributions": {
- "property1": {
- "relative_contribution": 0,
- "relative_population_avg": 0
}, - "property2": {
- "relative_contribution": 0,
- "relative_population_avg": 0
}
}, - "predicted_at": "2019-08-24T14:15:22Z",
- "reference_timestamp": "2019-08-24T14:15:22Z",
- "status": "not_available",
- "value": 0
}
Get EndUser industry
Predict the industry of the end user based on its name
Authorizations:
path Parameters
end_user_id_or_heron_id required | string The |
query Parameters
naics_code_max_digits | integer [ 2 .. 6 ] Example: naics_code_max_digits=6 Maximum number of digits in NAICS code |
naics_code_min_digits | integer [ 2 .. 6 ] Example: naics_code_min_digits=2 Minimum number of digits in NAICS code |
Responses
Response samples
- 200
{- "label": "Fruit and Vegetable Preserving and Specialty Food Manufacturing",
- "probability": 0.42,
- "taxonomy": "naics",
- "taxonomy_value": "3114"
}
Get EndUser merchant summary
Get the summary of transactions by merchant for an end user for a given category
Authorizations:
path Parameters
end_user_id_or_heron_id required | string |
query Parameters
category_label_or_heron_id required | Array of strings non-empty |
Responses
Response samples
- 200
{- "by_merchant_summary": [
- {
- "group": "string",
- "inflow_metrics": {
- "amount": {
- "amount": "1234.56",
- "currency": "USD"
}, - "count": 0,
- "duration_days": 0,
- "estimated_monthly_amount": {
- "amount": "1234.56",
- "currency": "USD"
}, - "frequency": "not_enough_data",
- "max_amount": {
- "amount": "1234.56",
- "currency": "USD"
}, - "max_timestamp": "2019-08-24T14:15:22Z",
- "mean_amount": {
- "amount": "1234.56",
- "currency": "USD"
}, - "mean_interval_days": 0,
- "median_amount": {
- "amount": "1234.56",
- "currency": "USD"
}, - "min_amount": {
- "amount": "1234.56",
- "currency": "USD"
}, - "min_timestamp": "2019-08-24T14:15:22Z",
- "mode_amount": {
- "amount": "1234.56",
- "currency": "USD"
}, - "mode_interval_days": 0,
- "std_dev_amount": {
- "amount": "1234.56",
- "currency": "USD"
}
}, - "name": "string",
- "net_metrics": {
- "amount": {
- "amount": "1234.56",
- "currency": "USD"
}, - "count": 0,
- "duration_days": 0,
- "estimated_monthly_amount": {
- "amount": "1234.56",
- "currency": "USD"
}, - "frequency": "not_enough_data",
- "max_amount": {
- "amount": "1234.56",
- "currency": "USD"
}, - "max_timestamp": "2019-08-24T14:15:22Z",
- "mean_amount": {
- "amount": "1234.56",
- "currency": "USD"
}, - "mean_interval_days": 0,
- "median_amount": {
- "amount": "1234.56",
- "currency": "USD"
}, - "min_amount": {
- "amount": "1234.56",
- "currency": "USD"
}, - "min_timestamp": "2019-08-24T14:15:22Z",
- "mode_amount": {
- "amount": "1234.56",
- "currency": "USD"
}, - "mode_interval_days": 0,
- "std_dev_amount": {
- "amount": "1234.56",
- "currency": "USD"
}
}, - "outflow_metrics": {
- "amount": {
- "amount": "1234.56",
- "currency": "USD"
}, - "count": 0,
- "duration_days": 0,
- "estimated_monthly_amount": {
- "amount": "1234.56",
- "currency": "USD"
}, - "frequency": "not_enough_data",
- "max_amount": {
- "amount": "1234.56",
- "currency": "USD"
}, - "max_timestamp": "2019-08-24T14:15:22Z",
- "mean_amount": {
- "amount": "1234.56",
- "currency": "USD"
}, - "mean_interval_days": 0,
- "median_amount": {
- "amount": "1234.56",
- "currency": "USD"
}, - "min_amount": {
- "amount": "1234.56",
- "currency": "USD"
}, - "min_timestamp": "2019-08-24T14:15:22Z",
- "mode_amount": {
- "amount": "1234.56",
- "currency": "USD"
}, - "mode_interval_days": 0,
- "std_dev_amount": {
- "amount": "1234.56",
- "currency": "USD"
}
}
}
]
}
Get EndUser P&L
Calculates the profit & loss table for an end user, based on the layout defined (if any)
Authorizations:
path Parameters
end_user_id_or_heron_id required | string |
query Parameters
to_date | string or null <date> Default: null Example: to_date=2022-01-31 The latest transaction timestamp date to use |
from_date | string or null <date> Default: null Example: from_date=2022-01-01 The earliest transaction timestamp date to use |
dates_ascending | boolean Default: false If true, dates are sorted left to right by ascending order. False by default, i.e., by default sorted in descending date order so more recent dates are first |
currency | string or null = 3 characters Example: currency=USD ISO 4217 currency code for balance |
Responses
Response samples
- 200
{- "dates": [
- "2019-08-24"
], - "sections": [
- {
- "metrics": [
- {
- "confidence": 0,
- "indent": 0,
- "is_ratio": true,
- "name": "string",
- "values": [
- 0
]
}
], - "name": "string",
- "slug": "string"
}
]
}
Update EndUser P&L layout
Update the profit and loss layout for the end user, which determines how the profit and loss table is calculated
Authorizations:
path Parameters
end_user_id_or_heron_id required | string |
Request Body schema: application/json
category_labels required | Array of strings non-empty List of category labels to assign to a different section |
section_slug required | string Slug of section to assign labels to |
Responses
Request samples
- Payload
{- "category_labels": [
- "Postage"
], - "section_slug": "operational_expenses"
}
Response samples
- 200
{- "sections": [
- {
- "labels": [
- "string"
], - "metrics": [
- {
- "denominator": {
- "labels": [
- "string"
], - "sections": [
- "string"
]
}, - "indent": 0,
- "is_growth": true,
- "name": "string",
- "numerator": {
- "labels": [
- "string"
], - "sections": [
- "string"
]
}
}
], - "name": "string",
- "slug": "string"
}
]
}
Get EndUser scorecard
Get scorecard metrics and rule violations for a user
Authorizations:
path Parameters
end_user_id_or_heron_id required | string |
query Parameters
date | string or null <date> Default: null Example: date=2023-01-19 Cut-off date to consider transactions to for calculating scorecard (inclusive) |
named_date | string or null Default: null Enum: "end_user_created" "end_user_last_updated" "last_transaction" Example: named_date=end_user_created Qualitative description for date to calculate scorecard |
Responses
Response samples
- 200
{- "metrics": [
- {
- "context": "higher_is_better",
- "currency": "string",
- "date_range": "last_180_days",
- "description": "The number of unique transactions with a timestamp",
- "group": "data_quality",
- "label": "unique_transactions",
- "status": "not_available",
- "unit": "n",
- "value": 42.42
}
], - "rule_violations": [
- {
- "metric": {
- "context": "higher_is_better",
- "currency": "string",
- "date_range": "last_180_days",
- "description": "The number of unique transactions with a timestamp",
- "group": "data_quality",
- "label": "unique_transactions",
- "status": "not_available",
- "unit": "n",
- "value": 42.42
}, - "rule": {
- "condition": "equal",
- "created": "2023-08-16T16:32:22.859015",
- "date_range": "last_180_days",
- "group": "data_quality_datasource",
- "heron_id": "rul_dm88z28hcnnFRFLPALPmfm",
- "last_updated": "2023-09-27T16:32:22.859060",
- "metric_label": "unique_transactions",
- "name": "notify_if_debt_investment_count_gt_0_last_180d",
- "selector": {
- "is_portfolio": true
}, - "value": 42.42,
- "value_str": "mrc_12345678ijwdd321d921"
}
}
]
}
Evaluate all rules for an end user
Authorizations:
path Parameters
end_user_id_or_heron_id required | string |
Responses
Response samples
- 200
[- {
- "metric": {
- "context": "higher_is_better",
- "currency": "string",
- "date_range": "last_180_days",
- "description": "The number of unique transactions with a timestamp",
- "group": "data_quality",
- "label": "unique_transactions",
- "status": "not_available",
- "unit": "n",
- "value": 42.42
}, - "result": "PASS",
- "rule": {
- "condition": "equal",
- "created": "2023-08-16T16:32:22.859015",
- "date_range": "last_180_days",
- "group": "data_quality_datasource",
- "heron_id": "rul_dm88z28hcnnFRFLPALPmfm",
- "last_updated": "2023-09-27T16:32:22.859060",
- "metric_label": "unique_transactions",
- "name": "notify_if_debt_investment_count_gt_0_last_180d",
- "selector": {
- "is_portfolio": true
}, - "value": 42.42,
- "value_str": "mrc_12345678ijwdd321d921"
}
}
]
Upload Inscribe
Upload Inscribe JSON for a specified end user to translate into Heron Data format and add transactions for the end user
Authorizations:
path Parameters
end_user_id_or_heron_id required | string The |
Request Body schema: application/json
customer_name | string or null Default: null |
object (InscribeParsedDetails) |
Responses
Request samples
- Payload
{- "customer_name": null,
- "parsed_details": {
- "bank_accounts": [
- {
- "account_type": "string",
- "beginning_balance": {
- "confidence": 0,
- "normalized": 0,
- "raw": "string"
}, - "ending_balance": {
- "confidence": 0,
- "normalized": 0,
- "raw": "string"
}, - "institution_name": "string",
- "number": {
- "confidence": 0,
- "normalized": "string",
- "raw": "string"
}, - "transactions": [
- {
- "amount": 0,
- "date": "2019-08-24",
- "description": "string",
- "id": "string"
}
], - "transactions_match_balances": true
}
], - "name": {
- "raw": "string"
}
}
}
Response samples
- 201
{- "_summary": {
- "request_id": "string"
}
}
Get Integration Links
Get a list of integration links for a specified end user
Authorizations:
path Parameters
end_user_id_or_heron_id required | string The |
Responses
Response samples
- 200
{- "links": [
- {
- "access_token": "access-sandbox-de3ce8ef-33f8-452c-a685-8671031fc0f6",
- "end_user_id": "490d02bf-ea74-4197-87e1-ec02a8c20901",
- "end_user_name": "Acme Corp",
- "item_id": "M5eVJqLnv3tbzdngLDp9FL5OlDNxlNhlE55op"
}
]
}
Upload Ocrolus
Upload Ocrolus JSON for a specified end user to translate into Heron Data format and add transactions for the end user
Authorizations:
path Parameters
end_user_id_or_heron_id required | string The |
Request Body schema: application/json
required | object (OcrolusResponse) | ||||
|
Responses
Request samples
- Payload
{- "response": {
- "bank_accounts": [
- {
- "account_category": "string",
- "account_number": "string",
- "alternative_lender_transactions": [
- {
- "amount": "string",
- "description": "string",
- "pk": 0,
- "timestamp": "2019-08-24T14:15:22Z",
- "txn_date": "2019-08-24"
}
], - "daily_balances": {
- "property1": "string",
- "property2": "string"
}, - "debt_consolidator_txns": [
- {
- "amount": "string",
- "description": "string",
- "pk": 0,
- "timestamp": "2019-08-24T14:15:22Z",
- "txn_date": "2019-08-24"
}
], - "estimated_expense_txns_list": [
- {
- "amount": "string",
- "description": "string",
- "pk": 0,
- "timestamp": "2019-08-24T14:15:22Z",
- "txn_date": "2019-08-24"
}
], - "estimated_revenue_txns_list": [
- {
- "amount": "string",
- "description": "string",
- "pk": 0,
- "timestamp": "2019-08-24T14:15:22Z",
- "txn_date": "2019-08-24"
}
], - "factor_txns": [
- {
- "amount": "string",
- "description": "string",
- "pk": 0,
- "timestamp": "2019-08-24T14:15:22Z",
- "txn_date": "2019-08-24"
}
], - "holder_country": "string",
- "insurance_credits": [
- {
- "amount": "string",
- "description": "string",
- "pk": 0,
- "timestamp": "2019-08-24T14:15:22Z",
- "txn_date": "2019-08-24"
}
], - "insurance_debits": [
- {
- "amount": "string",
- "description": "string",
- "pk": 0,
- "timestamp": "2019-08-24T14:15:22Z",
- "txn_date": "2019-08-24"
}
], - "interbank_transactions": [
- {
- "amount": "string",
- "description": "string",
- "pk": 0,
- "timestamp": "2019-08-24T14:15:22Z",
- "txn_date": "2019-08-24"
}
], - "merchant_cash_advance_lender_txns": [
- {
- "amount": "string",
- "description": "string",
- "pk": 0,
- "timestamp": "2019-08-24T14:15:22Z",
- "txn_date": "2019-08-24"
}
], - "non_estimated_revenue_txns_list": [
- {
- "amount": "string",
- "description": "string",
- "pk": 0,
- "timestamp": "2019-08-24T14:15:22Z",
- "txn_date": "2019-08-24"
}
], - "nsf_transactions": [
- {
- "amount": "string",
- "description": "string",
- "pk": 0,
- "timestamp": "2019-08-24T14:15:22Z",
- "txn_date": "2019-08-24"
}
], - "nsf_transactions_paid_or_negative_balance": [
- {
- "amount": "string",
- "description": "string",
- "pk": 0,
- "timestamp": "2019-08-24T14:15:22Z",
- "txn_date": "2019-08-24"
}
], - "nsf_transactions_returned_or_not_paid": [
- {
- "amount": "string",
- "description": "string",
- "pk": 0,
- "timestamp": "2019-08-24T14:15:22Z",
- "txn_date": "2019-08-24"
}
], - "outside_source_deposits": [
- {
- "amount": "string",
- "description": "string",
- "pk": 0,
- "timestamp": "2019-08-24T14:15:22Z",
- "txn_date": "2019-08-24"
}
], - "payroll": [
- {
- "amount": "string",
- "description": "string",
- "pk": 0,
- "timestamp": "2019-08-24T14:15:22Z",
- "txn_date": "2019-08-24"
}
], - "period_balance_mismatches": [
- {
- "amount": "string",
- "description": "string",
- "pk": 0,
- "timestamp": "2019-08-24T14:15:22Z",
- "txn_date": "2019-08-24"
}
], - "ppp_loan_txns": [
- {
- "amount": "string",
- "description": "string",
- "pk": 0,
- "timestamp": "2019-08-24T14:15:22Z",
- "txn_date": "2019-08-24"
}
], - "probable_recurring_txns": [
- [
- {
- "amount": "string",
- "description": "string",
- "pk": 0,
- "timestamp": "2019-08-24T14:15:22Z",
- "txn_date": "2019-08-24"
}
]
], - "returned_items": [
- {
- "amount": "string",
- "description": "string",
- "pk": 0,
- "timestamp": "2019-08-24T14:15:22Z",
- "txn_date": "2019-08-24"
}
], - "round_number_txns": [
- {
- "amount": "string",
- "description": "string",
- "pk": 0,
- "timestamp": "2019-08-24T14:15:22Z",
- "txn_date": "2019-08-24"
}
], - "withdrawals": [
- {
- "amount": "string",
- "description": "string",
- "pk": 0,
- "timestamp": "2019-08-24T14:15:22Z",
- "txn_date": "2019-08-24"
}
]
}
], - "name": "string"
}
}
Response samples
- 201
{- "_summary": {
- "request_id": "string"
}
}
Get PDFs
Get list of PDFs for a specified end user
Authorizations:
path Parameters
end_user_id_or_heron_id required | string The |
query Parameters
with_processed_results | boolean Include processed results where applicable per pdf |
Responses
Response samples
- 200
{- "pdfs": [
- {
- "account_id": "checking_account_202348",
- "created": "2023-09-27T16:32:22.222024",
- "currency": "USD",
- "end_user": {
- "heron_id": "eus_YpseZNi9U3BRuQmKXXru7T"
}, - "filename": "my-favourite.pdf",
- "heron_id": "pdf_kvV9Ud8WA6wpdwp3HfuSv4",
- "last_updated": "2023-09-27T16:32:22.222057",
- "notes": "failed to send to external OCR provider",
- "parsing_version": "string",
- "reference_id": "my-favourite-pdf",
- "statements": [
- {
- "exclude": true,
- "invalid_transaction_partials": [
- {
- "amount": 0,
- "balance": 0,
- "bounds": {
- "page": 0,
- "x_max": 0,
- "x_min": 0,
- "y_max": 0,
- "y_min": 0
}, - "description": "string",
- "ocr_suspect": true,
- "reference_id": "string",
- "timestamp": "2019-08-24T14:15:22Z",
- "transaction_code": "string"
}
], - "summary": {
- "account_number": "string",
- "account_title": "string",
- "bank_name": "string",
- "company": "string",
- "end_balance": 0,
- "fraud_reasons": [
- "string"
], - "fraud_score": 0,
- "is_business_account": true,
- "is_ocr": true,
- "max_resolution": 0,
- "min_resolution": 0,
- "num_credits": 0,
- "num_debits": 0,
- "num_transactions": 0,
- "reconciled": true,
- "start_balance": 0,
- "statement_end_date": "2019-08-24T14:15:22Z",
- "statement_start_date": "2019-08-24T14:15:22Z",
- "total_credits": 0,
- "total_debits": 0,
- "unreconciled_end_balance": 0,
- "web_report": true
}, - "transaction_partials": [
- {
- "amount": 0,
- "balance": 0,
- "bounds": {
- "page": 0,
- "x_max": 0,
- "x_min": 0,
- "y_max": 0,
- "y_min": 0
}, - "description": "string",
- "ocr_suspect": true,
- "reference_id": "string",
- "timestamp": "2019-08-24T14:15:22Z",
- "transaction_code": "string"
}
]
}
], - "status": "processed"
}
]
}
Upload PDF
Upload encoded PDF of transactions for a specified end user to translate into Heron Data format
Authorizations:
path Parameters
end_user_id_or_heron_id required | string The |
Request Body schema: application/json
account_id | string or null Default: null Unique ID for account associated with PDF |
currency | string or null Default: null Enum: "USD" "GBP" ISO 4217 currency code for transactions in account. We currently only support GBP and USD PDFs |
filename | string or null Default: null The filename of the PDF |
pdf_base64 required | string^data\:\w+\/\w+\;base64\, The base64 encoded string of the PDF file. If using Javascript, this is directly the output of the FileReader.readAsDataURL() output. See https://developer.mozilla.org/en-US/docs/Web/API/FileReader/readAsDataURL for more info |
read_us_dates | boolean or null Default: null True if date formats in the statement are US: month/date/year |
reference_id | string or null <= 140 characters Default: null An optional field for your unique identifier for the PDF |
Responses
Request samples
- Payload
{- "account_id": "checking_account_202348",
- "currency": "USD",
- "filename": "my-favourite.pdf",
- "pdf_base64": "string",
- "read_us_dates": null,
- "reference_id": "my-favourite-pdf"
}
Response samples
- 201
{- "pdf_heron_id": "string",
- "request_id": "string"
}
Upload Plaid assets
Upload Plaid asset JSON for a specified end user to translate into Heron Data format and add transactions for the end user
Authorizations:
path Parameters
end_user_id_or_heron_id required | string The |
Request Body schema: application/json
required | object (PlaidAssetReport) | ||||||
|
Responses
Request samples
- Payload
{- "report": {
- "date_generated": "2019-08-24T14:15:22Z",
- "days_requested": 0,
- "items": [
- {
- "accounts": [
- {
- "account_id": "string",
- "balances": {
- "current": 0,
- "date": "2019-08-24",
- "iso_currency_code": "USD"
}, - "historical_balances": [
- {
- "current": 0,
- "date": "2019-08-24",
- "iso_currency_code": "USD"
}
], - "mask": "string",
- "name": "string",
- "official_name": "string",
- "owners": [
- {
- "names": [
- "string"
]
}
], - "subtype": "string",
- "transactions": [
- {
- "account_id": "string",
- "amount": 0,
- "balance": 0,
- "category": [
- "string"
], - "date": "2019-08-24",
- "iso_currency_code": "USD",
- "merchant_name": "string",
- "name": "string",
- "pending_transaction_id": null,
- "timestamp": "2019-08-24T14:15:22Z",
- "transaction_code": "string",
- "transaction_id": "string"
}
], - "type": "string"
}
], - "institution_name": "string"
}
]
}
}
Response samples
- 201
{- "_summary": {
- "request_id": "string"
}
}
Upload Plaid transactions
Upload Plaid transactions JSON for a specified end user to translate into Heron Data format and add transactions for the end user
Authorizations:
path Parameters
end_user_id_or_heron_id required | string The |
Request Body schema: application/json
Array of objects (PlaidAccountSnapshot) | |
required | Array of objects (PlaidTransaction) |
Responses
Request samples
- Payload
{- "accounts": [
- {
- "account_id": "string",
- "balances": {
- "available": 0,
- "current": 0,
- "iso_currency_code": "string"
}, - "mask": "string",
- "name": "string",
- "official_name": "string",
- "subtype": "string",
- "type": "string"
}
], - "transactions": [
- {
- "account_id": "string",
- "amount": 0,
- "balance": 0,
- "category": [
- "string"
], - "date": "2019-08-24",
- "iso_currency_code": "USD",
- "merchant_name": "string",
- "name": "string",
- "pending_transaction_id": null,
- "timestamp": "2019-08-24T14:15:22Z",
- "transaction_code": "string",
- "transaction_id": "string"
}
]
}
Response samples
- 201
{- "_summary": {
- "request_id": "string"
}
}
Upload P&L in CSV format
Upload P&L for a specified end user
Authorizations:
path Parameters
end_user_id_or_heron_id required | string The |
Request Body schema: application/json
csv required | string P&L of an end user in CSV format. String must be encoded. |
currency required | string Enum: "USD" "GBP" ISO 4217 currency code for transactions in account. We currently only support GBP and USD P&Ls |
Responses
Request samples
- Payload
{- "csv": "date%2Crevenue%0D%0AOct%202021%2C23580.87%0D%0ASept%202021%2C13464.07",
- "currency": "USD"
}
Response samples
- 201
{- "_summary": {
- "request_id": "string"
}
}
Upload Yodlee
Upload Yodlee JSON files for a specified end user to translate into Heron Data format and add transactions for the end user
Authorizations:
path Parameters
end_user_id_or_heron_id required | string The |
Request Body schema: application/json
Array of objects (YodleeAccount) | |
Array of objects (YodleeTransaction) |
Responses
Request samples
- Payload
{- "accounts": [
- {
- "balance": {
- "amount": 0,
- "currency": "string"
}, - "classification": "string",
- "id": 0
}
], - "transactions": [
- {
- "accountId": 0,
- "amount": {
- "amount": 0,
- "currency": "string"
}, - "baseType": "CREDIT",
- "category": "string",
- "date": "2019-08-24T14:15:22Z",
- "description": {
- "original": "string",
- "simple": "string"
}, - "id": 0
}
]
}
Response samples
- 201
{- "_summary": {
- "request_id": "string"
}
}
Get Missing Accounts (beta)
Get a list of possible missing accounts for a given End User. This endpoint is in beta and likely to change.
Authorizations:
path Parameters
end_user_id_or_heron_id required | string The |
Responses
Response samples
- 200
{- "missing_accounts": [
- {
- "account_name": "Checking",
- "account_number": "****4321",
- "transactions": [
- {
- "account_id": "checking_account_202348",
- "amount": -42.42,
- "currency": "USD",
- "heron_id": "txn_WBdGPEXnkUVaZphpKatWVp",
- "timestamp": "2021-11-12T10:38:05Z"
}
]
}
]
}
Get end user 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
Authorizations:
path Parameters
end_user_id_or_heron_id required | string |
query Parameters
page | integer >= 1 Default: 1 Results page |
last_updated_min | string or null <date-time> Default: null Example: last_updated_min=2023-09-27T16:32:22.120290 Filter for transactions whose values were last updated in Heron systems after the specified input value, isoformat |
per_page | integer [ 1 .. 50000 ] Default: 100 Desired results per page |
Responses
Response samples
- 200
{- "_meta": {
- "next_url": "string",
- "num_results": 0,
- "page": 0,
- "per_page": 0,
- "prev_url": "string"
}, - "transactions_enriched": [
- {
- "account_id": "checking_account_202348",
- "amount": -42.42,
- "annotation": {
- "annotator": {
- "context": "sync",
- "priority_type": "gold_standard"
}, - "category": {
- "heron_id": "ctg_FoWfSzsjkTpC4D29yQfb8e",
- "label": "Rent"
}, - "confidence": 0,
- "model_version": "string"
}, - "balance": 423,
- "currency": "USD",
- "end_user_id": "my_best_customer_203948",
- "features": {
- "description_clean": "GOOGLE ADS",
- "duplicate_of_id": "txn_2qVvrEsEj47dhkY7Ta9qVz",
- "has_matching_transaction": true,
- "is_potential_duplicate": true,
- "is_recurring": true
}, - "heron_id": "txn_WBdGPEXnkUVaZphpKatWVp",
- "last_updated": "2023-09-27T16:32:22.009960",
- "merchant": {
- "categories": [
- {
- "code": "7311",
- "description": "Advertising services",
- "slug": "advertising_services"
}
], - "group_id": "string",
- "heron_id": "mrc_aqSj5dFjPdpFpkG27ke9xz",
- "icon_url": "string",
- "is_priority": true,
- "logo_url": "string",
- "name": "string",
- "url": "string"
}, - "reference_id": "my_favourite_transaction_231098",
- "request_id": "req_oJ95qCshDsTgSQJoMbe3Du",
- "timestamp": "2021-11-12T10:38:05Z",
- "transaction_code": "card"
}
]
}
Get enriched transaction
Get enriched transaction
Authorizations:
path Parameters
reference_id_or_heron_id required | string |
Responses
Response samples
- 200
{- "transaction_enriched": {
- "account_id": "checking_account_202348",
- "amount": -42.42,
- "annotation": {
- "annotator": {
- "context": "sync",
- "priority_type": "gold_standard"
}, - "category": {
- "heron_id": "ctg_FoWfSzsjkTpC4D29yQfb8e",
- "label": "Rent"
}, - "confidence": 0,
- "model_version": "string"
}, - "balance": 423,
- "currency": "USD",
- "end_user_id": "my_best_customer_203948",
- "features": {
- "description_clean": "GOOGLE ADS",
- "duplicate_of_id": "txn_2qVvrEsEj47dhkY7Ta9qVz",
- "has_matching_transaction": true,
- "is_potential_duplicate": true,
- "is_recurring": true
}, - "heron_id": "txn_WBdGPEXnkUVaZphpKatWVp",
- "last_updated": "2023-09-27T16:32:22.009960",
- "merchant": {
- "categories": [
- {
- "code": "7311",
- "description": "Advertising services",
- "slug": "advertising_services"
}
], - "group_id": "string",
- "heron_id": "mrc_aqSj5dFjPdpFpkG27ke9xz",
- "icon_url": "string",
- "is_priority": true,
- "logo_url": "string",
- "name": "string",
- "url": "string"
}, - "reference_id": "my_favourite_transaction_231098",
- "request_id": "req_oJ95qCshDsTgSQJoMbe3Du",
- "timestamp": "2021-11-12T10:38:05Z",
- "transaction_code": "card"
}
}
Create end user transactions (async)
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)"
Authorizations:
path Parameters
end_user_id_or_heron_id required | string |
Request Body schema: application/json
Array of objects (AccountBalance) Bank account balance information for a particular account_id. The balance here must be the latest balance after all the transactions in this batch have been applied. | |
required | Array of objects (EndUserTransactionPostAsync) non-empty |
Responses
Request samples
- Payload
{- "balances": [
- {
- "account_id": "checking_account_202348",
- "batch_closing_balance": 25000.45
}
], - "transactions": [
- {
- "account_id": "checking_account_202348",
- "amount": -42.42,
- "balance": 423,
- "categories_default": "shopping",
- "currency": "USD",
- "date": "2020-04-27",
- "mcc_code": "string",
- "order": 0,
- "reference_id": "my_favourite_transaction_231098",
- "timestamp": "2021-11-12T10:38:05Z",
- "transaction_code": "card"
}
]
}
Response samples
- 201
{- "request_id": "string",
- "transactions_loaded": 0
}
Delete transactions
Delete transactions
Authorizations:
query Parameters
account_id | string or null Default: null account_id of transactions to be deleted |
only_duplicates | boolean or null Default: null if true, deletes only transactions that are marked as duplicates |
request_id | string or null Default: null Request ID of transactions to be deleted |
heron_ids | Array of strings Default: [] Heron IDs of transactions to be deleted |
end_user_id | string or null Default: null end_user_id of transactions to be deleted |
heron_id | string or null Default: null Example: heron_id=txn_SG6t5hMsv6fwUwFzJreZYh (legacy) Heron ID of transaction to be deleted |
reference_ids | Array of strings Default: [] Reference IDs of transactions to be deleted |
Responses
Callbacks
Response samples
- 202
{- "message": "string"
}
Callback payload samples
{- "created": "2023-09-27T16:32:22.017476",
- "data": {
- "transactions": [
- {
- "heron_id": "txn_WBdGPEXnkUVaZphpKatWVp",
- "reference_id": "my_favourite_transaction_231098"
}
]
}, - "meta": { },
- "topic": "end_user.processed"
}
Get transactions
Get transactions
Authorizations:
query Parameters
timestamp_date_max | string <date> Example: timestamp_date_max=2020-04-27 Filter by latest transaction timestamp |
merchant_group_id | string Filter by merchant group id |
order_by | string Default: "id_asc" Enum: "amount_asc" "amount_desc" "abs_amount_asc" "abs_amount_desc" "description_asc" "description_desc" "timestamp_asc" "timestamp_desc" "id_asc" "id_desc" "confidence_asc" "confidence_desc" What to order transactions by |
reference_id | string Reference Id of transaction |
min_amount | number Filter by minimum amount of transaction |
max_amount | number Filter by maximum amount of transaction |
is_recurring | boolean Filter by whether the transaction is recurring |
to_date | string <date> Deprecated; see created_date_ or timestamp_date_ |
last_updated_max | string <date-time> Example: last_updated_max=2023-09-27T16:32:22.012943 Filter for transactions whose values were last updated in Heron systems before the specified input value |
end_user_id | string End user id of transaction |
description_regex | string Filter by regex matching transaction description |
timestamp_date_min | string <date> Example: timestamp_date_min=2020-04-27 Filter by earliest transaction timestamp |
created_date_min | string <date> Example: created_date_min=2020-04-27 Filter by earliest transaction upload date - when Heron received the transaction |
request_id | string Request-Id header returned in the response of POST transactions. Sending this parameter will return all transactions sent in a particular POST request, including any duplicates. |
confidence_max | number [ 0 .. 1 ] Filter by maximum confidence of annotation associated with transaction |
description_keyword | string Filter by keyword match on transaction description; case insensitive |
has_matching_transaction | boolean Filter by whether the transaction has a matching transaction |
page | integer >= 1 Default: 1 Page of transaction to return |
last_updated_min | string <date-time> Example: last_updated_min=2023-09-27T16:32:22.012925 Filter for transactions whose values were last updated in Heron systems after the specified input value |
created_date_max | string <date> Example: created_date_max=2020-04-27 Filter by latest transaction upload date - when Heron received the transaction |
include_duplicates | boolean Whether or not to include duplicate transactions in the response. Defaults to false unless request_id is provided, in which case it defaults to true. |
category_heron_id | Array of strings or null Default: [] Example: category_heron_id=ctg_aR5kSKkhCQUHvmLC5zsnNL Filter by the heron_id of the category that the transaction is annotated with |
limit | integer [ 1 .. 10000 ] Default: 1000 Number of transactions to return per page |
transaction_code | string Filter by transaction code |
heron_id | string Example: heron_id=txn_9etzy2V3Nf8VrVopr5BNfC Heron generated Id of transaction |
confidence_min | number [ 0 .. 1 ] Filter by minimum confidence of annotation associated with transaction |
from_date | string <date> Deprecated; see created_date_ or timestamp_date_ |
Responses
Response samples
- 200
{- "_meta": {
- "next_url": "string",
- "page": 0,
- "pages": 0,
- "per_page": 0,
- "prev_url": "string"
}, - "_summary": {
- "returned_transactions": 0,
- "transactions": 0
}, - "transactions": [
- {
- "account_id": "checking_account_202348",
- "amount": -42.42,
- "balance": 423,
- "categories": [
- {
- "annotator": "predicted",
- "confidence": 0.5,
- "heron_id": "ctg_gme5zuMrUmjk9pDuigg2vG",
- "label": "Rent",
- "model_version": "5867dc86-17d5-478a-8036-0e5804c5e06a"
}
], - "created": "2023-09-27T16:32:22.012445",
- "currency": "USD",
- "description_clean": "GOOGLE ADS",
- "duplicate_of_id": "txn_2qVvrEsEj47dhkY7Ta9qVz",
- "end_user_id": "my_best_customer_203948",
- "has_matching_transaction": true,
- "heron_id": "txn_WBdGPEXnkUVaZphpKatWVp",
- "is_potential_duplicate": true,
- "is_recurring": true,
- "last_updated": "2023-09-27T16:32:22.012518",
- "merchant": {
- "categories": [
- {
- "code": "7311",
- "description": "Advertising services",
- "slug": "advertising_services"
}
], - "group_id": "string",
- "heron_id": "mrc_aqSj5dFjPdpFpkG27ke9xz",
- "icon_url": "string",
- "is_priority": true,
- "logo_url": "string",
- "name": "string",
- "url": "string"
}, - "payment_processor": {
- "heron_id": "mrc_nRYdGU7nYuevb7qem65cEb",
- "name": "Paypal",
}, - "reference_id": "my_favourite_transaction_231098",
- "request_id": "req_oJ95qCshDsTgSQJoMbe3Du",
- "timestamp": "2021-11-12T10:38:05Z",
- "transaction_code": "card"
}
]
}
Enrich transactions (sync)
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.
Authorizations:
Request Body schema: application/json
required | Array of objects (Transaction1) non-empty | ||||||||||||||||||||||||||
Array (non-empty)
|
Responses
Request samples
- Payload
{- "transactions": [
- {
- "account_id": "checking_account_202348",
- "amount": -42.42,
- "balance": 423,
- "categories_default": "shopping",
- "currency": "USD",
- "date": "2020-04-27",
- "end_user_id": "my_best_customer_203948",
- "mcc_code": "string",
- "order": 0,
- "reference_id": "my_favourite_transaction_231098",
- "timestamp": "2021-11-12T10:38:05Z",
- "transaction_code": "card"
}
]
}
Response samples
- 200
- 413
{- "_summary": {
- "request_id": "string"
}, - "transactions": [
- {
- "account_id": "checking_account_202348",
- "amount": -42.42,
- "balance": 423,
- "categories": [
- {
- "annotator": "predicted",
- "confidence": 0.5,
- "heron_id": "ctg_gme5zuMrUmjk9pDuigg2vG",
- "label": "Rent",
- "model_version": "5867dc86-17d5-478a-8036-0e5804c5e06a"
}
], - "currency": "USD",
- "description_clean": "GOOGLE ADS",
- "duplicate_of_id": "txn_2qVvrEsEj47dhkY7Ta9qVz",
- "end_user_id": "my_best_customer_203948",
- "has_matching_transaction": true,
- "is_potential_duplicate": true,
- "is_recurring": true,
- "merchant": {
- "categories": [
- {
- "code": "7311",
- "description": "Advertising services",
- "slug": "advertising_services"
}
], - "group_id": "string",
- "heron_id": "mrc_aqSj5dFjPdpFpkG27ke9xz",
- "icon_url": "string",
- "is_priority": true,
- "logo_url": "string",
- "name": "string",
- "url": "string"
}, - "payment_processor": {
- "heron_id": "mrc_nRYdGU7nYuevb7qem65cEb",
- "name": "Paypal",
}, - "reference_id": "my_favourite_transaction_231098",
- "request_id": "req_oJ95qCshDsTgSQJoMbe3Du",
- "timestamp": "2021-11-12T10:38:05Z",
- "transaction_code": "card"
}
]
}
Response samples
- 200
{- "integrations": [
- {
- "client_id": "string",
- "client_secret": "string",
- "heron_id": "string",
- "name": "Plaid Prod",
- "resource": "transaction",
- "type": "plaid",
}
]
}
Create an integration
Create an integration e.g. with Plaid
Authorizations:
Request Body schema: application/json
object (IntegrationSchema) | |||||||||||||||
|
Responses
Request samples
- Payload
{- "integration": {
- "client_id": "string",
- "client_secret": "string",
- "name": "Plaid Prod",
- "resource": "transaction",
- "type": "plaid",
}
}
Response samples
- 201
{- "integration": {
- "client_id": "string",
- "client_secret": "string",
- "heron_id": "string",
- "name": "Plaid Prod",
- "resource": "transaction",
- "type": "plaid",
}
}
Update Integration
Update an Integration
Authorizations:
path Parameters
heron_id required | string |
Request Body schema: application/json
Integration
object (IntegrationSchema) | |||||||||||||||
|
Responses
Request samples
- Payload
{- "end_user": {
- "client_id": "string",
- "client_secret": "string",
- "name": "Plaid Prod",
- "resource": "transaction",
- "type": "plaid",
}
}
Response samples
- 200
{- "integration": {
- "client_id": "string",
- "client_secret": "string",
- "heron_id": "string",
- "name": "Plaid Prod",
- "resource": "transaction",
- "type": "plaid",
}
}
Get IntegrationLinks by Integration
Get a list of IntegrationLinks for an Integration filtered by end user
Authorizations:
path Parameters
heron_id required | string The Integration's heron_id |
query Parameters
end_user_id_or_heron_id required | string Return only IntegrationLinks for that end user |
Responses
Response samples
- 200
{- "links": [
- {
- "access_token": "access-sandbox-de3ce8ef-33f8-452c-a685-8671031fc0f6",
- "end_user_id": "490d02bf-ea74-4197-87e1-ec02a8c20901",
- "end_user_name": "Acme Corp",
- "item_id": "M5eVJqLnv3tbzdngLDp9FL5OlDNxlNhlE55op"
}
]
}
Create an integration Link
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.
Authorizations:
path Parameters
heron_id required | string |
Request Body schema: application/json
access_token required | string The generated token that grants access to the bank (this is encrypted in transit and at-rest with a custom key) |
end_user_id required | string A unique identifier for your end user (customer) generated by you |
end_user_name | string An human readable name for this end user, like the company legal name |
item_id required | string Unique identifier for each bank connection made by your end users. In Plaid this is the 'item_id'. |
Responses
Request samples
- Payload
{- "access_token": "access-sandbox-de3ce8ef-33f8-452c-a685-8671031fc0f6",
- "end_user_id": "490d02bf-ea74-4197-87e1-ec02a8c20901",
- "end_user_name": "Acme Corp",
- "item_id": "M5eVJqLnv3tbzdngLDp9FL5OlDNxlNhlE55op"
}
Extract Merchant from a transaction description
Extract Merchant from a transaction description
Authorizations:
Request Body schema: application/json
The bank transaction description as a string
description required | string |
Responses
Request samples
- Payload
{- "description": "PAYPAL* AMZN Mktp 198748320"
}
Response samples
- 200
{- "description_clean": "Amzn Mktp",
- "merchant": {
- "categories": [
- {
- "code": "7311",
- "description": "Advertising services",
- "slug": "advertising_services"
}
], - "confidence": null,
- "group_id": "string",
- "heron_id": "mrc_aqSj5dFjPdpFpkG27ke9xz",
- "icon_url": "string",
- "logo_url": "string",
- "name": "Amazon",
}, - "payment_processor": {
- "heron_id": "mrc_nRYdGU7nYuevb7qem65cEb",
- "name": "Paypal",
}
}
Search Merchants by name
Search Merchants by name
Authorizations:
query Parameters
name required | string Full or partial name, minimum 3 characters |
only_priority | boolean If true, only returns priority merchants |
Responses
Response samples
- 200
{- "merchants": [
- {
- "categories": [
- {
- "code": "7311",
- "description": "Advertising services",
- "slug": "advertising_services"
}
], - "group_id": "string",
- "heron_id": "mrc_aqSj5dFjPdpFpkG27ke9xz",
- "icon_url": "string",
- "is_priority": true,
- "logo_url": "string",
- "name": "string",
- "url": "string"
}
]
}
Get Merchant by heron_id
Get Merchant by heron_id
Authorizations:
path Parameters
heron_id required | string The Merchant |
Responses
Response samples
- 200
{- "merchant": {
- "categories": [
- {
- "code": "7311",
- "description": "Advertising services",
- "slug": "advertising_services"
}
], - "group_id": "string",
- "heron_id": "mrc_aqSj5dFjPdpFpkG27ke9xz",
- "icon_url": "string",
- "is_priority": true,
- "logo_url": "string",
- "name": "string",
- "url": "string"
}
}
Response samples
- 200
{- "rules": [
- {
- "condition": "equal",
- "created": "2023-08-16T16:32:22.859015",
- "date_range": "last_180_days",
- "group": "data_quality_datasource",
- "heron_id": "rul_dm88z28hcnnFRFLPALPmfm",
- "last_updated": "2023-09-27T16:32:22.859060",
- "metric_label": "unique_transactions",
- "name": "notify_if_debt_investment_count_gt_0_last_180d",
- "selector": {
- "is_portfolio": true
}, - "value": 42.42,
- "value_str": "mrc_12345678ijwdd321d921"
}
]
}
Create a single rule
Create a new rule to send a 'end_user.review_required' webhook after processing if rule condition evaluates to true
Authorizations:
Request Body schema: application/json
object (Rule) | |||||||||||||||||
|
Responses
Request samples
- Payload
{- "rule": {
- "condition": "equal",
- "date_range": "last_180_days",
- "group": "data_quality_datasource",
- "metric_label": "unique_transactions",
- "name": "notify_if_debt_investment_count_gt_0_last_180d",
- "selector": {
- "is_portfolio": true
}, - "value": 42.42,
- "value_str": "mrc_12345678ijwdd321d921"
}
}
Response samples
- 201
{- "rule": {
- "condition": "equal",
- "created": "2023-08-16T16:32:22.859015",
- "date_range": "last_180_days",
- "group": "data_quality_datasource",
- "heron_id": "rul_dm88z28hcnnFRFLPALPmfm",
- "last_updated": "2023-09-27T16:32:22.859060",
- "metric_label": "unique_transactions",
- "name": "notify_if_debt_investment_count_gt_0_last_180d",
- "selector": {
- "is_portfolio": true
}, - "value": 42.42,
- "value_str": "mrc_12345678ijwdd321d921"
}
}
Update rule by heron_id
Update a rule
Authorizations:
path Parameters
heron_id required | string |
Request Body schema: application/json
Rule
object (RuleUpdateSchema) | |||||||||||||||||
|
Responses
Request samples
- Payload
{- "rule": {
- "condition": "equal",
- "date_range": "last_180_days",
- "group": "data_quality_datasource",
- "metric_label": "unique_transactions",
- "name": "notify_if_debt_investment_count_gt_0_last_180d",
- "selector": {
- "is_portfolio": true
}, - "value": 42.42,
- "value_str": "mrc_12345678ijwdd321d921"
}
}
Response samples
- 200
{- "rule": {
- "condition": "equal",
- "created": "2023-08-16T16:32:22.859015",
- "date_range": "last_180_days",
- "group": "data_quality_datasource",
- "heron_id": "rul_dm88z28hcnnFRFLPALPmfm",
- "last_updated": "2023-09-27T16:32:22.859060",
- "metric_label": "unique_transactions",
- "name": "notify_if_debt_investment_count_gt_0_last_180d",
- "selector": {
- "is_portfolio": true
}, - "value": 42.42,
- "value_str": "mrc_12345678ijwdd321d921"
}
}
Save user's company overview layout
Authorizations:
Request Body schema: application/json
The new company overview layout
group_name required | string |
id required | string A unique id used to reference the group |
required | Array of objects (Widget) |
Responses
Request samples
- Payload
[- {
- "group_name": "string",
- "id": "string",
- "widgets": [
- {
- "id": "string",
- "scorecard_metric_date_range": "latest",
- "scorecard_metric_label": "string",
- "type": "scorecard_metric"
}
]
}
]