Transactions
Note
For more precise documentation see the swagger UI / Open API version of the documentation
Base_url
https://app.herondata.io/api
Posting and categorising transactions
Once categories have been defined, you can POST
transactions to the /transactions
endpoint, where the body of the expected request is of the following format:
{
"transactions": [
{
"description": "string",
"amount": 0,
"timestamp": "2020-11-24T18:46:13.683Z",
"end_user_id": "string",
"reference_id": "string",
"currency": "string",
"transaction_code": "string",
"merchant_name": "string",
}
]
}
Where the fields are as follows:
description
(string
)* Transaction description stringamount
(float
)* Transaction amount. We expect account inflows (credits) to be positive, account outflows (debits) to be negative.timestamp
(timestamp
)** Timestamp of the transactionend_user_id
(string
)** Unique identifier for the end user (i.e. your customer) who generated this transactionreference_id
(string
)*** Unique identifier for transactioncurrency
(string
) 3 letter code for currency, e.g.,USD
transaction_code
(string
) Refers to transaction code if available e.g., transfermerchant_name
(string
) Refers to merchant name of transaction if available
* : Required; ** : Required for recurrency; *** : Required for feedback
Example request:
curl --location --request POST 'https://app.herondata.io/api/transactions/' \
--header '<your-authorisation>' \
--header 'Content-Type: application/json' \
--data-raw '{
"transactions": [
{
"amount": -4000,
"currency": "USD",
"description": "STRIPE TRANSFER ST-C9Y9T6F1L3J5 MURCUL INC"
}
]
}'
Based on your Heron plan, you will receive transactions as a response with the following fields:
categories
(bool
) applied categorisation to transactions and returns labelsis_recurring
(bool
) calculated recurrency for transactionshas_matching_transaction
(bool
) whether any matching transactions based on amount and date (e.g., inter-account transfers)
Response includes a summary and transactions field:
{
"_summary": {
"transactions_loaded": 1,
"transactions_categorised": 1,
"task_id": "930a9eaf-c488-495c-9f23-9af7698a4e0a",
},
"transactions": [
{
...,
"categories": [
{
"label": "some_category"
}
]
}
]
}
Here, you can use the task_id
to retrieve transactions for asynchronous categorisation jobs or labels with
improved accuracy / confidence at a later point in time
Reading transactions
As expected, you can also issue GET
requests to the /transactions
endpoint. This returns a paginated
response. You can modify the request with the following optional query parameters:
from_date
(date
) filters for earliest uploaded date for transaction of formYYYY-MM-DD
, inclusiveto_date
(date
) filters for latest uploaded date for transaction of formYYYY-MM-DD
, inclusiveend_user_id
(string
) filters for end_user_id (if any) associated uploaded transactionstask_id
(string
) filters for task ID associated with thePOST
request that uploaded the transactionpage
(integer
) page number for pagination, default 1limit
(integer
) items to return per page, default 100
An example request would look like:
curl --location --request GET 'https://app.herondata.io/api/transactions/?from_date=2020-11-15&to_date=2020-11-20&task_id=8f1a7b43-b650-47dd-b04f-efeaf457ab01&page=2&limit=20' \
--header '<your-authorisation>'
Which would yield a response similar to:
{
"_summary": {
"transactions": 0,
"returned_transactions": 0
},
"_meta": {
"page": 2,
"pages": 0,
"per_page": 20,
"next_url": null,
"prev_url": "/api/transactions?from_date=2020-11-15&page=1&limit=20&to_date=2020-11-20&task_id=8f1a7b43-b650-47dd-b04f-efeaf457ab01"
},
"transactions": [
{...}
]
}
Where _meta
contains the information necessary to navigate through the pagination
Retrieving tasks
You can also retrieve the task IDs associated with loading transactions by issuing a GET
request to the tasks/
endpoint,
which will give you your prior tasks ordered by most recent
curl --location --request GET 'https://app.herondata.io/api/tasks' \
--header '<your-authorisation>'