API Reference
REQUEST ACCESS

Transaction Form

Hurdlr's Transaction Form Embedded experience makes it easy for you to direct a user or accountant to a specific transaction for review. This serves as a simple way to have your users or their accountant interact with and update their transactions in the Hurdlr API

1. Initializing the Embedded Experience

To initialize the Hurdlr Embedded experience in your project, follow the instructions on Embedding Hurdlr's white-labelled UI.

2. Render the form of a specific transaction

To render a specific transaction overlay form, you will need to provide an elementId parameter, which is the HTML id of the main <div> where you would like the form to render from. The form will be styled with the CSS property “position: fixed”, so it can be overlayed on top of your existing UI. When your user selects a CTA to view the form, you simply need to invoke the following line of JavaScript:

Hurdlr.renderTransactionForm(elementId, entity, entityId);

You will need to provide an entity parameter to specify the type of the transaction. An entityId is also required. These parameters are described in the following table:

ParameterDescriptionFormat
entityIndicates the type of transaction to display. This is aligned with the entities enumeration of POST /banks/getTransactions.Must be one of the following enumerations:
EXPENSE,
REVENUE, BANK_TRANSFER, TAX_PAYMENT
entityIdId of the transaction to display. This can be obtained by sending a request to the corresponding GET endpoint for an expense, revenue, bank transfer, or tax paymentNumeric

📘

Rendering the form for an accountant

If you're rendering the Transaction Form for an accountant (i.e. you've initialized Hurdlr Embedded for an accountant), you will additionally need to specify the userId for the client that the given transaction belongs to. The numeric userId can be obtained from the accountant users endpoint.

3. Reacting to user actions

After rendering a form, the user can review or edit the transaction as needed. If you’d like to display your own UI before a user opens or after closing a form, you will want to take advantage of the Hurdlr Embedded experience's registerTransactionFormListener functionality. By registering a listener, the provided callback function will be invoked with the data of the rendered transaction and the result of the form submission.

To register a listener, simply add the following line of JS to be ran once after Hurdlr.renderTransactionForm(...):

Hurdlr.registerTransactionFormListener(myTransactionFormCallback);

Whenever a user either opens the form or closes it, myTransactionFormCallback will be invoked with a JSON object as the single argument, containing the following attributes.

FieldDescriptionFormat
typeThe Hurdlr.TRANSACTION_FORM_OPEN event is emitted when the details of a transaction have been successfully retrieved and the form is opened. You may want to display a loader between the time the CTA to render the form is selected and when this event is emitted.
The Hurdlr.TRANSACTION_FORM_CLOSE event is emitted anytime the user selects a CTA to close the form. If necessary, this indicates that the Embedded experience can safely be removed from the DOM.		Must be one of the following enumerations:
Hurdlr.TRANSACTION_FORM_OPEN,
Hurdlr.TRANSACTION_FORM_CLOSE
datadata is populated with the details of the transaction when Hurdlr.TRANSACTION_FORM_OPEN is emitted, the result of a successful form submission when Hurdlr.TRANSACTION_FORM_CLOSE is emitted, and empty when the error attribute is non-null.Object
errorerror is a string indicating any errors while fetching details of the transaction, an object populated with details of an unsuccessful form submission, or null when data is not empty.One of object, string, or null

Example arguments for a myTransactionFormCallback invocation when rendering an Expense form is shown below.

{
   "type": "Hurdlr.TRANSACTION_FORM_OPEN",
   "data": {
     "id": 1234567,
     "status": "ACTIVE",
     "type": "BUSINESS",
     "date": "2024-01-01T00:00:00.000Z",
     "amount": 10,
     "apiName": "PLAID",
     "apiExpenseId": "12345678",
     ...
  },
  "error": null
}

{
 "type": "Hurdlr.TRANSACTION_FORM_CLOSE",
 "data": {
   "result": "SUCCESS",
     "errors": null,
     "id": "1234567",
     "dataObject": null,
     "didNotInsertBecauseDupe": false,
     "webhook": null
 },
 "error": null
}