​
Overview

Bank transactions must first be represented as journal entries and line entries to be of use in an accounting environment. While data integrations can handle this most of the time, you may have to import data manually.

Use the Create Transactions endpoint and pass in an array of transactions data. Use the ID from the returned Transaction Processing Task to see when the task is done.

Related guide: Data integrations.

​
How it works

After a transaction has been posted to a financial account, it needs to be imported into Teal, manually or through a data integration, Plaid or Unit, for example. Once the transaction comes into Teal it goes through our transaction submission pipeline and is categorized.

A journal entry is then created for the transaction, with one line entry recorded to the financial account ledger and the other to the ledger it was categorized as.

​
Prerequisites

In order to create transactions, the Instance must first have its financial accounts mapped to ledgers.

​
Creating a transaction source account

Teal supports multiple sources to receive transaction data and transactions are stored in a transaction source account. This is automatically handled when you use our data integrations.

To manually write transactions, you’ll need to create a transaction source account using the Create a Business Transaction Source Account endpoint.

curl --request POST \
--url 'https://api.sandbox.teal.dev/v0/source-accounts/business' \
--header 'authorization: Bearer <token>' \
--header 'teal-instance-id: <instance_id>' \
--data '{
  "name": "<descriptive name of account>",
  "ledger_id": "<financial account ledger id>"
}'

​
Creating transactions

You can create transactions in Teal using the /v0/source-accounts/{source_account_id}/transactions endpoint. The source_account_id parameter should be the ID of the transaction source account. The id parameter must be unique per transaction as it acts as an idempotency key to allow you to safely create multiple requests with the same data without creating duplicate information.

You can optionally use metadata to store arbitrary structured information about the transaction. This could be location of the transaction to display to the user or vendor information to use as part of a Platform categorization rule. Teal does not use metadata for any accounting purposes.

Transactions whose datetime is before the Instance’s entries_start date will be skipped. Other transactions will be processed as normal.

curl --request POST \
--url https://api.sandbox.teal.dev/v0/source-account/{source_account_id}/transactions \
--header 'authorization: Bearer <token>' \
--header 'teal-instance-id: <instance_id>' \
--data '[
  {
    "id": "txn_12345-20230801-UjL3",
    "amount": 100,
    "datetime": "2023-08-01T00:00:00Z",
    "description": "A sample transaction",
  }
]'

The endpoint responds with a Transaction Processing Task object.

A Transaction Processing Task is considered done after all the transactions have gone through the auto-categorization pipeline and have their respective journal entries and line entries created.

If you are using AI Categorization, Transaction Processing Tasks can sometimes take up to 5 minutes. Use /v0/transactions/tasks/{id} to check on the status.

​
Relevant resources

​
Guides

​
API references