Skip to content

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 string
  • amount (float)* Transaction amount. We expect account inflows (credits) to be positive, account outflows (debits) to be negative.
  • timestamp (timestamp)** Timestamp of the transaction
  • end_user_id (string)** Unique identifier for the end user (i.e. your customer) who generated this transaction
  • reference_id (string)*** Unique identifier for transaction
  • currency (string) 3 letter code for currency, e.g., USD
  • transaction_code (string) Refers to transaction code if available e.g., transfer
  • merchant_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 labels
  • is_recurring (bool) calculated recurrency for transactions
  • has_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 form YYYY-MM-DD, inclusive
  • to_date (date) filters for latest uploaded date for transaction of form YYYY-MM-DD, inclusive
  • end_user_id (string) filters for end_user_id (if any) associated uploaded transactions
  • task_id (string) filters for task ID associated with the POST request that uploaded the transaction
  • page (integer) page number for pagination, default 1
  • limit (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>'