The goal of categorizing transactions is to ensure that your user’s accounting reports are accurate. Teal’s auto-categorization pipeline streamlines much of this tedious process, but sometimes you will want to prompt your users to confirm some transactions.

We call this key accounting workflow Reviewing Transactions, and versions of this workflow exist in most popular accounting products. Using a combination of the Transactions and Ledger endpoints, you can build a customizable transaction review workflow for your users.

​
Implementation example

1

Display a list of Transactions for review

Display the transactions that you want your users to review. In this example, all transactions with review_status = unreviewed are displayed. This is the default status for all newly created transactions.

Use the List Transactions endpoint with the source_account_id of a specific transaction source account to get a list of all unreviewed transactions.

const options = {
	method: 'GET',
	headers: {
		Authorization: AUTHORIZATION_KEY
		'teal-instance-id': TEAL_INSTANCE_ID,
	}
};
const source_account_id = 12345;

const request = await fetch(`https://api.sandbox.teal.dev/v0/source-accounts/${source_account_id}/transactions?review_status=unreviewed&expand=opposing_line_entries.ledger`, options)
const data = await request.json();

Display these to the user by iterating over data.records.

2

Update the category (Optional)

Sometimes a user needs to change how a Transaction is categorized. To do this, you need a list of all Ledgers and then allow the user to select which one they would like to assign as the new category.

  1. Use /v0/ledgers to retrieve all Ledgers.
const options = {
	method: 'GET',
	headers: {
		Authorization: AUTHORIZATION_KEY,
		'teal-instance-id': TEAL_INSTANCE_ID
	}
};
const request = await fetch(`https://api.sandbox.teal.dev/v0/ledgers`, options)
const data = await request.json();

Display the possible ledgers in a <select> element by iterating over data.records.

  1. After a user has selected a category, submit the ledger_id of the new category to the Recategorize Transaction endpoint.
const selected_ledger_id = '67890';

const options = {
	method: 'PUT',
	headers: {
		Authorization: AUTHORIZATION_KEY,
		'Content-Type': 'application/json',
		'teal-instance-id': TEAL_INSTANCE_ID
	},
	body: {
		"updated_category_ledger_id": selected_ledger_id
	}
};
const source_account_id = 12345;

const request = await fetch(`https://api.sandbox.teal.dev/v0/source-accounts/${source_account_id}/transactions/${transaction_id}/categories`, options)
const response = await request.json();
3

Confirm the Transaction and remove from the list

Once the user has reviewed the transaction and confirm the category, update the Transaction review_status from unreviewed to reviewed using the Update Transaction endpoint with source_account_id and transaction_id, passing along the new review status.

const options = {
	method: 'PUT',
	headers: {
		Authorization: AUTHORIZATION_KEY,
		'Content-Type': 'application/json',
		'teal-instance-id': TEAL_INSTANCE_ID
	},
	body: {
		"review_status": "reviewed"
	}
};

const request = await fetch(`https://api.sandbox.teal.dev/v0/source-accounts/${source_account_id}/transactions/${transaction_id}`, options);
const response = await request.json();

​
Notes

  • When a Transaction is processed in Teal’s auto-categorization pipeline and it does not match any ledger, it will be categorized as either an Uncategorized Cash Inflow or Uncategorized Cash Outflow. You can choose to only display transactions with these categories in your review list.
  • Use the categorization_method attribute to filter transactions based on what categorization step they were categorized at. For example, you may want users to only review transactions that have gone through the AI categorization step, but not those categorized by Instance level rules.

​
Relevant resources