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 enriching transactions

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"
    }
  ]
}

Where the fields are as follows:

  • description (string)* Transaction description.
  • 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 the transaction
  • currency (string) 3 letter code for currency, e.g., USD
  • transaction_code (string) Refers to transaction code if available e.g., "transfer"

* : Required; ** : Required for recurrency and matching transactions; *** : 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-CY098123KA TECHNOLOGY INC"
        }
    ]
}'

Response includes a summary and transactions field:

{
  "_summary": {
    "transactions_loaded": 1,
    "transactions_categorised": 1,
    "task_id": "930a9eaf-c488-495c-9f23-9af7698a4e0a",
  },
  "transactions": [
     {
        ...,
        "description_clean": "cleaner_description",
        "merchant": {
              "name": "merchant_name",
              "url": "https://some_merchant_url.com"
                        },
        "is_recurring": boolean,
        "has_matching_transaction": boolean,
        "categories": [
            {
                "label": "some_category_label",
                "annotator_priority_type": "annotator_source_for_label"
                "confidence": float
            }
        ]
     }
  ]
}

where:

  • description_clean (string) is a substring of the original description string.
  • merchant (dict) contains the clean name of the merchant (not necessarily a substring of the original description) and the associated url for display back to your customer.
  • is_recurring (boolean) indicates recurrence of transactions
  • has_matching_transaction (boolean) indicates whether a corresponding transaction (inverse amount with timestamp in close proximity) exists
  • categories (dict) contains the category label (from your specific taxonomy), the source of the annotation (manual_review, heuristics or classifier), and the associated confidence.

Here, you can use the task_id to retrieve transactions for asynchronous categorisation jobs and 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>'