# Insights
Source: https://docs.getasset.com/accounting/insights



Many small [Businesses](/getstarted/CoreConcepts#businesses-your-smb-customers) want more than just a snapshot of their finances. They want to see how they compare to others in their field to uncover real opportunities for growth. We are building a robust Insights feature that uses AI to analyze each Business’s financial data, along with aggregated information from similar Businesses, to deliver tailored, vertical-specific, and actionable intelligence. Think of it like having a personal advisor that not only highlights potential issues, such as unexpected cost spikes or low-margin products, but also recommends actions you can take right away.

Our goal is to make these Insights feel at home in your platform, so you can offer SMB owners meaningful guidance without them leaving your ecosystem. We are still in the early stages, and your feedback will shape how these features look and function.

<Note>
  Excited to learn more or let us know what your Business Owners want? Reach out via our [Contact form](https://www.getasset.com/get-in-touch).
</Note>


# Tax
Source: https://docs.getasset.com/accounting/tax



Tax compliance can be one of the biggest challenges for many small [Businesses](/getstarted/CoreConcepts#businesses-your-smb-customers), especially when it comes to filing Tax Returns on time and staying up to date with changing regulations. We’re mapping out a comprehensive set of Tax-related features within Asset to help you, the Tenant, guide your users through these complexities more efficiently.

Our vision is to offer solutions that streamline workflows—automating calculations, simplifying form preparation, and ensuring a clear path to compliance for your SMB customers. While we’re still in the planning stages, your input is invaluable in shaping our roadmap.

<Note>
  Are you eager to offer your SMBs these features? Reach out via our [Contact form](https://www.getasset.com/get-in-touch).
</Note>


# Generate a Magic Link
Source: https://docs.getasset.com/api-reference/authentication/generate-a-magic-link

/api-reference/openapi.json post /v0/auth/magic-link
**Scopes:** `auth:create`



# Get an Access Token
Source: https://docs.getasset.com/api-reference/authentication/get-an-access-token

/api-reference/openapi.json post /v0/auth/token



# Logout a user
Source: https://docs.getasset.com/api-reference/authentication/logout-a-user

/api-reference/openapi.json post /v0/auth/logout
**Scopes:** `auth:delete`



# Apply Transaction to a Bill
Source: https://docs.getasset.com/api-reference/bill/apply-transaction-to-a-bill

/api-reference/openapi.json post /v0/business/{business_id}/bill-payment
Manually apply a payment to a bill.

Pass a `transaction_id` to apply a bank transaction as payment, or omit
`transaction_id` and pass `payment_amount` to draw from the vendor's
available credit pool.

**Scopes:** `bill:create`



# Create Bills
Source: https://docs.getasset.com/api-reference/bill/create-bills

/api-reference/openapi.json post /v0/business/{business_id}/bills
**Scopes:** `bill:create`



# Delete a Bill
Source: https://docs.getasset.com/api-reference/bill/delete-a-bill

/api-reference/openapi.json delete /v0/business/{business_id}/bills/{bill_id}
**Scopes:** `bill:delete`



# List all Bills
Source: https://docs.getasset.com/api-reference/bill/list-all-bills

/api-reference/openapi.json get /v0/business/{business_id}/bills
Get paginated list of bills for a business with optional filtering.

**Scopes:** `bill:read`



# Remove Bill Payment
Source: https://docs.getasset.com/api-reference/bill/remove-bill-payment

/api-reference/openapi.json delete /v0/business/{business_id}/bill-payment/{payment_id}
**Scopes:** `bill:delete`



# Retrieve a Bill
Source: https://docs.getasset.com/api-reference/bill/retrieve-a-bill

/api-reference/openapi.json get /v0/business/{business_id}/bills/{bill_id}
**Scopes:** `bill:read`



# Update a Bill
Source: https://docs.getasset.com/api-reference/bill/update-a-bill

/api-reference/openapi.json patch /v0/business/{business_id}/bills/{bill_id}
**Scopes:** `bill:update`



# Create a Business
Source: https://docs.getasset.com/api-reference/business/create-a-business

/api-reference/openapi.json post /v0/business
**Scopes:** `business:create`



# Delete a Business
Source: https://docs.getasset.com/api-reference/business/delete-a-business

/api-reference/openapi.json delete /v0/business/{business_id}
**Scopes:** `business:delete`



# Get Books Status for a Business
Source: https://docs.getasset.com/api-reference/business/get-books-status-for-a-business

/api-reference/openapi.json get /v0/business/{business_id}/books-status
**Scopes:** `business:read`



# Get the receipt request config in force for the business
Source: https://docs.getasset.com/api-reference/business/get-the-receipt-request-config-in-force-for-the-business

/api-reference/openapi.json get /v0/business/{business_id}/rules/receipts
The business's own override if it has one, otherwise the tenant config for
its country, otherwise receipts off.

**Scopes:** `business:read`



# List all Businesses
Source: https://docs.getasset.com/api-reference/business/list-all-businesses

/api-reference/openapi.json get /v0/business
**Scopes:** `business:read`



# Retrieve a Business
Source: https://docs.getasset.com/api-reference/business/retrieve-a-business

/api-reference/openapi.json get /v0/business/{business_id}
**Scopes:** `business:read`



# Update a Business
Source: https://docs.getasset.com/api-reference/business/update-a-business

/api-reference/openapi.json patch /v0/business/{business_id}
**Scopes:** `business:update`



# Update the business's own receipt request config (supersedes the tenant's)
Source: https://docs.getasset.com/api-reference/business/update-the-businesss-own-receipt-request-config-supersedes-the-tenants

/api-reference/openapi.json patch /v0/business/{business_id}/rules/receipts
**Scopes:** `business:update`



# List high-impact Transaction groups to categorize
Source: https://docs.getasset.com/api-reference/categorization/list-high-impact-transaction-groups-to-categorize

/api-reference/openapi.json get /v0/business/{business_id}/categorization
Return groups of similar unconfirmed transactions ranked by impact.

**Scopes:** `transaction:update`



# Create a Classification Rule
Source: https://docs.getasset.com/api-reference/classification-rules/create-a-classification-rule

/api-reference/openapi.json post /v0/business/{business_id}/rules/classifications
Create a rule that categorizes and tags matching transactions.

**Scopes:** `classification_rule:create`



# Create a Tenant Classification Rule
Source: https://docs.getasset.com/api-reference/classification-rules/create-a-tenant-classification-rule

/api-reference/openapi.json post /v0/tenant/rules/classifications
Create a tenant rule that categorizes and tags matching transactions
across the tenant's businesses.

**Scopes:** `tenant:update`



# Get a Classification Rule
Source: https://docs.getasset.com/api-reference/classification-rules/get-a-classification-rule

/api-reference/openapi.json get /v0/business/{business_id}/rules/classifications/{rule_id}
**Scopes:** `classification_rule:read`



# Get a Tenant Classification Rule
Source: https://docs.getasset.com/api-reference/classification-rules/get-a-tenant-classification-rule

/api-reference/openapi.json get /v0/tenant/rules/classifications/{rule_id}
**Scopes:** `tenant:read`



# List Classification Rules for a Business
Source: https://docs.getasset.com/api-reference/classification-rules/list-classification-rules-for-a-business

/api-reference/openapi.json get /v0/business/{business_id}/rules/classifications
List classification rules, newest first.

**Scopes:** `classification_rule:read`



# List the Tenant's Classification Rules
Source: https://docs.getasset.com/api-reference/classification-rules/list-the-tenants-classification-rules

/api-reference/openapi.json get /v0/tenant/rules/classifications
List the tenant's classification rules, newest first.

**Scopes:** `tenant:read`



# Update a Classification Rule
Source: https://docs.getasset.com/api-reference/classification-rules/update-a-classification-rule

/api-reference/openapi.json patch /v0/business/{business_id}/rules/classifications/{rule_id}
Update a rule. Omitted fields keep their current values.

**Scopes:** `classification_rule:update`



# Update a Tenant Classification Rule
Source: https://docs.getasset.com/api-reference/classification-rules/update-a-tenant-classification-rule

/api-reference/openapi.json patch /v0/tenant/rules/classifications/{rule_id}
Update a tenant rule. Omitted fields keep their current values.

**Scopes:** `tenant:update`



# Create one or more Credit Memos (max 100)
Source: https://docs.getasset.com/api-reference/credit-memo/create-one-or-more-credit-memos-max-100

/api-reference/openapi.json post /v0/business/{business_id}/credit-memo
**Scopes:** `credit_memo:create`



# Get a Credit Memo by ID
Source: https://docs.getasset.com/api-reference/credit-memo/get-a-credit-memo-by-id

/api-reference/openapi.json get /v0/business/{business_id}/credit-memo/{credit_memo_id}
**Scopes:** `credit_memo:read`



# List Credit Memos for a Business
Source: https://docs.getasset.com/api-reference/credit-memo/list-credit-memos-for-a-business

/api-reference/openapi.json get /v0/business/{business_id}/credit-memo
**Scopes:** `credit_memo:read`



# Void a Credit Memo
Source: https://docs.getasset.com/api-reference/credit-memo/void-a-credit-memo

/api-reference/openapi.json post /v0/business/{business_id}/credit-memo/{credit_memo_id}/void
**Scopes:** `credit_memo:update`



# Create a new customer
Source: https://docs.getasset.com/api-reference/customer/create-a-new-customer

/api-reference/openapi.json post /v0/business/{business_id}/customers
**Scopes:** `customer:create`



# Delete a Customer
Source: https://docs.getasset.com/api-reference/customer/delete-a-customer

/api-reference/openapi.json delete /v0/business/{business_id}/customers/{customer_id}
Deletes a customer. If the customer is referenced by other records
like invoices, the customer is diabled instead.

**Scopes:** `customer:delete`



# List customers for a business
Source: https://docs.getasset.com/api-reference/customer/list-customers-for-a-business

/api-reference/openapi.json get /v0/business/{business_id}/customers
**Scopes:** `customer:read`



# Update a customer
Source: https://docs.getasset.com/api-reference/customer/update-a-customer

/api-reference/openapi.json patch /v0/business/{business_id}/customers/{customer_id}
**Scopes:** `customer:update`



# Delete a Document
Source: https://docs.getasset.com/api-reference/document/delete-a-document

/api-reference/openapi.json delete /v0/business/{business_id}/document/{document_id}
**Scopes:** `document:delete`



# Delete Multiple Document Associations
Source: https://docs.getasset.com/api-reference/document/delete-multiple-document-associations

/api-reference/openapi.json delete /v0/business/{business_id}/document-association/{document_id}
Delete multiple document associations.

**Scopes:** `document:delete`



# Download a Document
Source: https://docs.getasset.com/api-reference/document/download-a-document

/api-reference/openapi.json get /v0/business/{business_id}/document/{document_id}/download
**Scopes:** `document:read`



# List all Documents for a Business
Source: https://docs.getasset.com/api-reference/document/list-all-documents-for-a-business

/api-reference/openapi.json get /v0/business/{business_id}/document
**Scopes:** `document:read`



# Retrieve Document Information
Source: https://docs.getasset.com/api-reference/document/retrieve-document-information

/api-reference/openapi.json get /v0/business/{business_id}/document/{document_id}
**Scopes:** `document:read`



# Upload documents for a Business
Source: https://docs.getasset.com/api-reference/document/upload-documents-for-a-business

/api-reference/openapi.json post /v0/business/{business_id}/document
**Scopes:** `document:create`



# Apply a Payment to an Invoice
Source: https://docs.getasset.com/api-reference/invoice/apply-a-payment-to-an-invoice

/api-reference/openapi.json post /v0/business/{business_id}/invoice-payment
Manually apply a payment to an invoice.

Pass a `transaction_id` to apply a bank transaction as payment, or omit
`transaction_id` and pass `payment_amount` to draw from the customer's
available credit pool.

**Scopes:** `invoice:create`



# Apply Transaction to a Refund
Source: https://docs.getasset.com/api-reference/invoice/apply-transaction-to-a-refund

/api-reference/openapi.json post /v0/business/{business_id}/refund-payment
Manually apply an existing transaction as payment of a refund.

**Scopes:** `invoice:create`



# Create an Invoice
Source: https://docs.getasset.com/api-reference/invoice/create-an-invoice

/api-reference/openapi.json post /v0/business/{business_id}/invoice
**Scopes:** `invoice:create`



# Delete an Invoice
Source: https://docs.getasset.com/api-reference/invoice/delete-an-invoice

/api-reference/openapi.json delete /v0/business/{business_id}/invoice/{invoice_id}
**Scopes:** `invoice:delete`



# List all Invoice Refunds for a Business
Source: https://docs.getasset.com/api-reference/invoice/list-all-invoice-refunds-for-a-business

/api-reference/openapi.json get /v0/business/{business_id}/refunds
Get all refunds for a business.

**Scopes:** `invoice:read`



# List all Invoices
Source: https://docs.getasset.com/api-reference/invoice/list-all-invoices

/api-reference/openapi.json get /v0/business/{business_id}/invoice
Get paginated list of invoices for a business with optional filtering.

**Scopes:** `invoice:read`



# List all Refunds for an Invoice
Source: https://docs.getasset.com/api-reference/invoice/list-all-refunds-for-an-invoice

/api-reference/openapi.json get /v0/business/{business_id}/invoice/{invoice_id}/refunds
**Scopes:** `invoice:read`



# Refund an Invoice
Source: https://docs.getasset.com/api-reference/invoice/refund-an-invoice

/api-reference/openapi.json post /v0/business/{business_id}/refund
**Scopes:** `invoice:create`



# Remove Invoice Payment
Source: https://docs.getasset.com/api-reference/invoice/remove-invoice-payment

/api-reference/openapi.json delete /v0/business/{business_id}/invoice-payment/{payment_id}
**Scopes:** `invoice:delete`



# Remove Refund Payment
Source: https://docs.getasset.com/api-reference/invoice/remove-refund-payment

/api-reference/openapi.json delete /v0/business/{business_id}/refund-payment/{refund_payment_id}
**Scopes:** `invoice:delete`



# Retrieve an Invoice
Source: https://docs.getasset.com/api-reference/invoice/retrieve-an-invoice

/api-reference/openapi.json get /v0/business/{business_id}/invoice/{invoice_id}
**Scopes:** `invoice:read`



# Update an Invoice
Source: https://docs.getasset.com/api-reference/invoice/update-an-invoice

/api-reference/openapi.json patch /v0/business/{business_id}/invoice/{invoice_id}
**Scopes:** `invoice:update`



# Write Off an Invoice
Source: https://docs.getasset.com/api-reference/invoice/write-off-an-invoice

/api-reference/openapi.json post /v0/business/{business_id}/invoice/{invoice_id}/write-off
**Scopes:** `invoice:update`



# Bulk Create Journal Entries
Source: https://docs.getasset.com/api-reference/journal-entry/bulk-create-journal-entries

/api-reference/openapi.json post /v0/business/{business_id}/journal-entries/bulk
Create up to 100 Journal Entries in one request. An entry that cannot be
created is reported in `errors`, by its `external_id` and its position in
the submitted list, and does not stop the rest of the batch from being
created.

**Scopes:** `journal_entry:create`



# Bulk Update Journal Entries
Source: https://docs.getasset.com/api-reference/journal-entry/bulk-update-journal-entries

/api-reference/openapi.json patch /v0/business/{business_id}/journal-entries
**Scopes:** `journal_entry:update`



# Create a Journal Entry
Source: https://docs.getasset.com/api-reference/journal-entry/create-a-journal-entry

/api-reference/openapi.json post /v0/business/{business_id}/journal-entries
**Scopes:** `journal_entry:create`



# Create a note against a journal entry
Source: https://docs.getasset.com/api-reference/journal-entry/create-a-note-against-a-journal-entry

/api-reference/openapi.json post /v0/business/{business_id}/journal-entries/{journal_entry_id}/notes
**Scopes:** `journal_entry:create`



# Delete a Journal Entry
Source: https://docs.getasset.com/api-reference/journal-entry/delete-a-journal-entry

/api-reference/openapi.json delete /v0/business/{business_id}/journal-entries/{journal_entry_id}
**Scopes:** `journal_entry:delete`



# List Journal Entries for a Business
Source: https://docs.getasset.com/api-reference/journal-entry/list-journal-entries-for-a-business

/api-reference/openapi.json get /v0/business/{business_id}/journal-entries
**Scopes:** `journal_entry:read`



# List Notes for a Journal Entry
Source: https://docs.getasset.com/api-reference/journal-entry/list-notes-for-a-journal-entry

/api-reference/openapi.json get /v0/business/{business_id}/journal-entries/{journal_entry_id}/notes
**Scopes:** `journal_entry:read`



# Retrieve a Journal Entry
Source: https://docs.getasset.com/api-reference/journal-entry/retrieve-a-journal-entry

/api-reference/openapi.json get /v0/business/{business_id}/journal-entries/{journal_entry_id}
**Scopes:** `journal_entry:read`



# Update a Journal Entry
Source: https://docs.getasset.com/api-reference/journal-entry/update-a-journal-entry

/api-reference/openapi.json patch /v0/business/{business_id}/journal-entries/{journal_entry_id}
**Scopes:** `journal_entry:update`



# Create a Ledger
Source: https://docs.getasset.com/api-reference/ledger/create-a-ledger

/api-reference/openapi.json post /v0/business/{business_id}/ledger
**Scopes:** `ledger:create`



# Delete a Ledger
Source: https://docs.getasset.com/api-reference/ledger/delete-a-ledger

/api-reference/openapi.json delete /v0/business/{business_id}/ledger/{ledger_id}
**Scopes:** `ledger:delete`



# List all Ledgers for a Business
Source: https://docs.getasset.com/api-reference/ledger/list-all-ledgers-for-a-business

/api-reference/openapi.json get /v0/business/{business_id}/ledger
**Scopes:** `ledger:read`



# Retrieve a Ledger
Source: https://docs.getasset.com/api-reference/ledger/retrieve-a-ledger

/api-reference/openapi.json get /v0/business/{business_id}/ledger/{ledger_id}
**Scopes:** `ledger:read`



# Set the Opening Balance for a Ledger
Source: https://docs.getasset.com/api-reference/ledger/set-the-opening-balance-for-a-ledger

/api-reference/openapi.json put /v0/business/{business_id}/ledger/{ledger_id}/opening-balance
**Scopes:** `ledger:update`



# Update a Ledger
Source: https://docs.getasset.com/api-reference/ledger/update-a-ledger

/api-reference/openapi.json patch /v0/business/{business_id}/ledger/{ledger_id}
**Scopes:** `ledger:update`



# Create one or more trips (max 100)
Source: https://docs.getasset.com/api-reference/mileage/create-one-or-more-trips-max-100

/api-reference/openapi.json post /v0/business/{business_id}/trips
**Scopes:** `trip:create`



# Delete a trip
Source: https://docs.getasset.com/api-reference/mileage/delete-a-trip

/api-reference/openapi.json delete /v0/business/{business_id}/trips/{trip_id}
**Scopes:** `trip:delete`



# Get a trip by ID
Source: https://docs.getasset.com/api-reference/mileage/get-a-trip-by-id

/api-reference/openapi.json get /v0/business/{business_id}/trips/{trip_id}
**Scopes:** `trip:read`



# List trips for a business
Source: https://docs.getasset.com/api-reference/mileage/list-trips-for-a-business

/api-reference/openapi.json get /v0/business/{business_id}/trips
**Scopes:** `trip:read`



# Update a trip
Source: https://docs.getasset.com/api-reference/mileage/update-a-trip

/api-reference/openapi.json patch /v0/business/{business_id}/trips/{trip_id}
**Scopes:** `trip:update`



# Retrieve the Aged Payables Report
Source: https://docs.getasset.com/api-reference/reports/retrieve-the-aged-payables-report

/api-reference/openapi.json get /v0/business/{business_id}/reports/aged-payables
**Scopes:** `report:read`



# Retrieve the Aged Receivables Report
Source: https://docs.getasset.com/api-reference/reports/retrieve-the-aged-receivables-report

/api-reference/openapi.json get /v0/business/{business_id}/reports/aged-receivables
**Scopes:** `report:read`



# Retrieve the Balance Sheet Report
Source: https://docs.getasset.com/api-reference/reports/retrieve-the-balance-sheet-report

/api-reference/openapi.json get /v0/business/{business_id}/reports/balance-sheet
**Scopes:** `report:read`



# Retrieve the Cash Flow Report
Source: https://docs.getasset.com/api-reference/reports/retrieve-the-cash-flow-report

/api-reference/openapi.json get /v0/business/{business_id}/reports/cash-flow
**Scopes:** `report:read`



# Retrieve the Customer Credit Balance Report
Source: https://docs.getasset.com/api-reference/reports/retrieve-the-customer-credit-balance-report

/api-reference/openapi.json get /v0/business/{business_id}/reports/customer-credits
**Scopes:** `report:read`



# Retrieve the General Ledger Report
Source: https://docs.getasset.com/api-reference/reports/retrieve-the-general-ledger-report

/api-reference/openapi.json get /v0/business/{business_id}/reports/general-ledger
**Scopes:** `report:read`



# Retrieve the Ledger Statement Report
Source: https://docs.getasset.com/api-reference/reports/retrieve-the-ledger-statement-report

/api-reference/openapi.json get /v0/business/{business_id}/reports/ledger-statement/{ledger_id}
**Scopes:** `report:read`



# Retrieve the Profit & Loss Report
Source: https://docs.getasset.com/api-reference/reports/retrieve-the-profit-&-loss-report

/api-reference/openapi.json get /v0/business/{business_id}/reports/profit-and-loss
**Scopes:** `report:read`



# Retrieve the Trial Balance Report
Source: https://docs.getasset.com/api-reference/reports/retrieve-the-trial-balance-report

/api-reference/openapi.json get /v0/business/{business_id}/reports/trial-balance
**Scopes:** `report:read`



# Create a Task for a Business
Source: https://docs.getasset.com/api-reference/request/create-a-task-for-a-business

/api-reference/openapi.json post /v0/business/{business_id}/task
**Scopes:** `request:create`



# Delete a Task for a Business
Source: https://docs.getasset.com/api-reference/request/delete-a-task-for-a-business

/api-reference/openapi.json delete /v0/business/{business_id}/task/{task_id}
**Scopes:** `request:delete`



# Get all Tasks for a Business
Source: https://docs.getasset.com/api-reference/request/get-all-tasks-for-a-business

/api-reference/openapi.json get /v0/business/{business_id}/task
**Scopes:** `request:read`



# Update a Task for a Business
Source: https://docs.getasset.com/api-reference/request/update-a-task-for-a-business

/api-reference/openapi.json patch /v0/business/{business_id}/task/{task_id}
**Scopes:** `request:update`



# Bill Object
Source: https://docs.getasset.com/api-reference/schema/bill





# Business Object
Source: https://docs.getasset.com/api-reference/schema/business





# Credit Memo Object
Source: https://docs.getasset.com/api-reference/schema/credit-memo





# Customer Object
Source: https://docs.getasset.com/api-reference/schema/customer





# Document Object
Source: https://docs.getasset.com/api-reference/schema/document





# External Account Object
Source: https://docs.getasset.com/api-reference/schema/external-account





# Invoice Object
Source: https://docs.getasset.com/api-reference/schema/invoice





# Journal Entry Object
Source: https://docs.getasset.com/api-reference/schema/journal-entry





# Ledger Object
Source: https://docs.getasset.com/api-reference/schema/ledger





# Tag Field Object
Source: https://docs.getasset.com/api-reference/schema/tag-field





# Tag Value Object
Source: https://docs.getasset.com/api-reference/schema/tag-value





# Task Object
Source: https://docs.getasset.com/api-reference/schema/task





# Transaction Object
Source: https://docs.getasset.com/api-reference/schema/transaction





# Trip Object
Source: https://docs.getasset.com/api-reference/schema/trip





# Vehicle Object
Source: https://docs.getasset.com/api-reference/schema/vehicle





# Vendor Object
Source: https://docs.getasset.com/api-reference/schema/vendor





# Vendor Credit Object
Source: https://docs.getasset.com/api-reference/schema/vendor-credit





# Webhook Object
Source: https://docs.getasset.com/api-reference/schema/webhook





# Create a Tag Value
Source: https://docs.getasset.com/api-reference/tag/create-a-tag-value

/api-reference/openapi.json post /v0/business/{business_id}/tag-values
**Scopes:** `tag:create`



# Delete a Tag Value
Source: https://docs.getasset.com/api-reference/tag/delete-a-tag-value

/api-reference/openapi.json delete /v0/business/{business_id}/tag-values/{tag_value_id}
**Scopes:** `tag:delete`



# Get a Tag Value
Source: https://docs.getasset.com/api-reference/tag/get-a-tag-value

/api-reference/openapi.json get /v0/business/{business_id}/tag-values/{tag_value_id}
**Scopes:** `tag:read`



# List Tag Fields for a Business
Source: https://docs.getasset.com/api-reference/tag/list-tag-fields-for-a-business

/api-reference/openapi.json get /v0/business/{business_id}/tag-fields
**Scopes:** `tag:read`



# List Tag Values for a Business
Source: https://docs.getasset.com/api-reference/tag/list-tag-values-for-a-business

/api-reference/openapi.json get /v0/business/{business_id}/tag-values
**Scopes:** `tag:read`



# Update a Tag Value
Source: https://docs.getasset.com/api-reference/tag/update-a-tag-value

/api-reference/openapi.json patch /v0/business/{business_id}/tag-values/{tag_value_id}
**Scopes:** `tag:update`



# Create a global Tag Field
Source: https://docs.getasset.com/api-reference/tenant/create-a-global-tag-field

/api-reference/openapi.json post /v0/tenant/tag-fields
Create a new global tag field that is available for all businesses.

**Scopes:** `tag:create`



# Delete a global Tag Field
Source: https://docs.getasset.com/api-reference/tenant/delete-a-global-tag-field

/api-reference/openapi.json delete /v0/tenant/tag-fields/{tag_field_id}
Delete a global tag field for all businesses.

**Scopes:** `tag:delete`



# List global Tag Fields
Source: https://docs.getasset.com/api-reference/tenant/list-global-tag-fields

/api-reference/openapi.json get /v0/tenant/tag-fields
List global tag fields that are available for all businesses.

**Scopes:** `tag:read`



# List the tenant's receipt request configs
Source: https://docs.getasset.com/api-reference/tenant/list-the-tenants-receipt-request-configs

/api-reference/openapi.json get /v0/tenant/rules/receipts
**Scopes:** `tenant:read`



# Update a global Tag Field
Source: https://docs.getasset.com/api-reference/tenant/update-a-global-tag-field

/api-reference/openapi.json patch /v0/tenant/tag-fields/{tag_field_id}
Update a global tag field for all businesses.

**Scopes:** `tag:update`



# Upsert the tenant's receipt request configs for every country at once
Source: https://docs.getasset.com/api-reference/tenant/upsert-the-tenants-receipt-request-configs-for-every-country-at-once

/api-reference/openapi.json patch /v0/tenant/rules/receipts
**Scopes:** `tenant:update`



# Create an External Account
Source: https://docs.getasset.com/api-reference/transaction/create-an-external-account

/api-reference/openapi.json post /v0/business/{business_id}/external-account
**Scopes:** `transaction:create`



# Create Transactions
Source: https://docs.getasset.com/api-reference/transaction/create-transactions

/api-reference/openapi.json post /v0/business/{business_id}/transactions
**Scopes:** `transaction:create`



# Delete External Account
Source: https://docs.getasset.com/api-reference/transaction/delete-external-account

/api-reference/openapi.json delete /v0/business/{business_id}/external-account/{external_account_id}
Deletes an external account and all associated documents, transactions, journal entries, and line entries.

If the external account is a business account, it will also delete the ledger.

**Scopes:** `transaction:delete`



# Delete Multiple Transactions
Source: https://docs.getasset.com/api-reference/transaction/delete-multiple-transactions

/api-reference/openapi.json delete /v0/business/{business_id}/transactions
**Scopes:** `transaction:delete`



# Get a single Transaction
Source: https://docs.getasset.com/api-reference/transaction/get-a-single-transaction

/api-reference/openapi.json get /v0/business/{business_id}/transactions/{transaction_id}
**Scopes:** `transaction:read`



# List all External Accounts for a Business
Source: https://docs.getasset.com/api-reference/transaction/list-all-external-accounts-for-a-business

/api-reference/openapi.json get /v0/business/{business_id}/external-account
**Scopes:** `external_account:read`



# List Transactions for a Business
Source: https://docs.getasset.com/api-reference/transaction/list-transactions-for-a-business

/api-reference/openapi.json get /v0/business/{business_id}/transactions
**Scopes:** `transaction:read`



# Retrieve an External Account
Source: https://docs.getasset.com/api-reference/transaction/retrieve-an-external-account

/api-reference/openapi.json get /v0/business/{business_id}/external-account/{external_account_id}
**Scopes:** `external_account:read`



# Update External Account
Source: https://docs.getasset.com/api-reference/transaction/update-external-account

/api-reference/openapi.json patch /v0/business/{business_id}/external-account/{external_account_id}
**Scopes:** `external_account:update`



# Update Transactions for a Business
Source: https://docs.getasset.com/api-reference/transaction/update-transactions-for-a-business

/api-reference/openapi.json patch /v0/business/{business_id}/transactions
Update one or more Transactions. Each item may change the date,
description, amount, the type, reviewed or status flags, merge tags, or set
`line_items` to recategorize the Transaction (a single line item) or split
it across categories (several). A new date or description is applied to the
Journal Entries derived from the Transaction as well.

**Scopes:** `transaction:update`



# Create one or more vehicles (max 100)
Source: https://docs.getasset.com/api-reference/vehicle/create-one-or-more-vehicles-max-100

/api-reference/openapi.json post /v0/business/{business_id}/vehicles
**Scopes:** `vehicle:create`



# Get a vehicle by ID
Source: https://docs.getasset.com/api-reference/vehicle/get-a-vehicle-by-id

/api-reference/openapi.json get /v0/business/{business_id}/vehicles/{vehicle_id}
**Scopes:** `vehicle:read`



# List vehicles for a business
Source: https://docs.getasset.com/api-reference/vehicle/list-vehicles-for-a-business

/api-reference/openapi.json get /v0/business/{business_id}/vehicles
**Scopes:** `vehicle:read`



# Update a vehicle
Source: https://docs.getasset.com/api-reference/vehicle/update-a-vehicle

/api-reference/openapi.json patch /v0/business/{business_id}/vehicles/{vehicle_id}
**Scopes:** `vehicle:update`



# Create one or more Vendor Credits (max 100)
Source: https://docs.getasset.com/api-reference/vendor-credit/create-one-or-more-vendor-credits-max-100

/api-reference/openapi.json post /v0/business/{business_id}/vendor-credit
**Scopes:** `vendor_credit:create`



# Get a Vendor Credit by ID
Source: https://docs.getasset.com/api-reference/vendor-credit/get-a-vendor-credit-by-id

/api-reference/openapi.json get /v0/business/{business_id}/vendor-credit/{vendor_credit_id}
**Scopes:** `vendor_credit:read`



# List Vendor Credits for a Business
Source: https://docs.getasset.com/api-reference/vendor-credit/list-vendor-credits-for-a-business

/api-reference/openapi.json get /v0/business/{business_id}/vendor-credit
**Scopes:** `vendor_credit:read`



# Void a Vendor Credit
Source: https://docs.getasset.com/api-reference/vendor-credit/void-a-vendor-credit

/api-reference/openapi.json post /v0/business/{business_id}/vendor-credit/{vendor_credit_id}/void
**Scopes:** `vendor_credit:update`



# Create a new vendor
Source: https://docs.getasset.com/api-reference/vendor/create-a-new-vendor

/api-reference/openapi.json post /v0/business/{business_id}/vendors
**Scopes:** `vendor:create`



# Delete a Vendor
Source: https://docs.getasset.com/api-reference/vendor/delete-a-vendor

/api-reference/openapi.json delete /v0/business/{business_id}/vendors/{vendor_id}
Deletes a vendor. If the vendor is referenced by other records
like invoices, the vendor is disabled instead.

**Scopes:** `vendor:delete`



# Get a vendor by ID
Source: https://docs.getasset.com/api-reference/vendor/get-a-vendor-by-id

/api-reference/openapi.json get /v0/business/{business_id}/vendors/{vendor_id}
**Scopes:** `vendor:read`



# List vendors for a business
Source: https://docs.getasset.com/api-reference/vendor/list-vendors-for-a-business

/api-reference/openapi.json get /v0/business/{business_id}/vendors
**Scopes:** `vendor:read`



# Update a vendor
Source: https://docs.getasset.com/api-reference/vendor/update-a-vendor

/api-reference/openapi.json patch /v0/business/{business_id}/vendors/{vendor_id}
**Scopes:** `vendor:update`



# Account balance updated
Source: https://docs.getasset.com/api-reference/webhook-events/account-balance-updated

/api-reference/openapi.json webhook account_balance_updated
Sent when the balance is updated on an account.



# Business activated
Source: https://docs.getasset.com/api-reference/webhook-events/business-activated

/api-reference/openapi.json webhook business_activated
Sent when a business status changes to active.



# Business created
Source: https://docs.getasset.com/api-reference/webhook-events/business-created

/api-reference/openapi.json webhook business_created
Sent when a new business is created.



# Business deactivated
Source: https://docs.getasset.com/api-reference/webhook-events/business-deactivated

/api-reference/openapi.json webhook business_deactivated
Sent when a business status changes to inactive.



# Certificate validation timed out
Source: https://docs.getasset.com/api-reference/webhook-events/certificate-validation-timed-out

/api-reference/openapi.json webhook certificate_validation_timed_out
Sent when SSL certificate validation for a custom domain times out.



# Document processed
Source: https://docs.getasset.com/api-reference/webhook-events/document-processed

/api-reference/openapi.json webhook document_processed
Sent when a document finishes processing.



# Plaid account connected
Source: https://docs.getasset.com/api-reference/webhook-events/plaid-account-connected

/api-reference/openapi.json webhook plaid_account_connected
Sent when a Plaid account is successfully connected.



# Plaid account disconnected
Source: https://docs.getasset.com/api-reference/webhook-events/plaid-account-disconnected

/api-reference/openapi.json webhook plaid_account_disconnected
Sent when a Plaid account is disconnected.



# Plaid account expired
Source: https://docs.getasset.com/api-reference/webhook-events/plaid-account-expired

/api-reference/openapi.json webhook plaid_account_expired
Sent when a Plaid account connection expires and needs to be reconnected.



# Plaid sync started
Source: https://docs.getasset.com/api-reference/webhook-events/plaid-sync-started

/api-reference/openapi.json webhook plaid_sync_started
Sent when a Plaid transactions sync starts.



# Plaid transactions synced
Source: https://docs.getasset.com/api-reference/webhook-events/plaid-transactions-synced

/api-reference/openapi.json webhook plaid_transactions_synced
Sent when transactions are synced from Plaid.



# Receipt matched
Source: https://docs.getasset.com/api-reference/webhook-events/receipt-matched

/api-reference/openapi.json webhook receipt_matched
Sent when a receipt document is matched to a transaction.



# Statement imported
Source: https://docs.getasset.com/api-reference/webhook-events/statement-imported

/api-reference/openapi.json webhook statement_imported
Sent when an uploaded bank statement finishes importing into an account.



# Task request
Source: https://docs.getasset.com/api-reference/webhook-events/task-request

/api-reference/openapi.json webhook task_request
Sent when tasks are requested from a business.



# Tasks completed
Source: https://docs.getasset.com/api-reference/webhook-events/tasks-completed

/api-reference/openapi.json webhook tasks_completed
Sent when all pending tasks for a business are completed.



# Webhook test
Source: https://docs.getasset.com/api-reference/webhook-events/webhook-test

/api-reference/openapi.json webhook webhook_test
Sent when testing webhook configuration via the /tenant/webhook/test endpoint.



# Get the webhook configuration
Source: https://docs.getasset.com/api-reference/webhooks/get-the-webhook-configuration

/api-reference/openapi.json get /v0/tenant/webhook
**Scopes:** `webhook:read`



# Load webhook notifications
Source: https://docs.getasset.com/api-reference/webhooks/load-webhook-notifications

/api-reference/openapi.json get /v0/tenant/webhook/notifications
Returns a paginated list of webhook notifications



# Test the webhook configuration by sending a test message
Source: https://docs.getasset.com/api-reference/webhooks/test-the-webhook-configuration-by-sending-a-test-message

/api-reference/openapi.json post /v0/tenant/webhook/test
**Scopes:** `webhook:create`



# Update the webhook configuration
Source: https://docs.getasset.com/api-reference/webhooks/update-the-webhook-configuration

/api-reference/openapi.json patch /v0/tenant/webhook
**Scopes:** `webhook:update`



# API Authentication
Source: https://docs.getasset.com/apioverview/authentication



Asset's API uses OAuth 2.0 for authentication. All API requests require a valid access token, included in the `Authorization` header.

## **Getting an Access Token**

1. **Set Up Your Tenant Account**
   * A Tenant Account is required to authenticate with Asset's API. If you don't have one, reach out via our Contact form.
   * Once set up, you can manage OAuth credentials in the Asset Dashboard.
2. **Obtain Client Credentials**
   * Register an application in the Asset Dashboard to receive a `client_id` and `client_secret`.
   * Separate credentials exist for **Production** and **Sandbox** environments.
3. **Request a Token**

Use your client credentials to request an access token:

```bash theme={null}
curl --request POST \
  --url https://api.sandbox.getasset.com/v0/auth/token \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data 'client_id=<string>' \
  --data 'client_secret=The oauth client secret'
```

A successful response returns:

```bash theme={null}
{
  "access_token": "your-access-token",
  "token_type": "Bearer",
  "expires_in": 1777657168
}
```

### Scoping the access token to a business

You can scope the access token to a business by passing the business id as a body parameter

```bash theme={null}
curl --request POST \
  --url https://api.sandbox.getasset.com/v0/auth/token \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data 'client_id=<string>' \
  --data 'client_secret=The oauth client secret' \
  --data business_id=biz_GA6EG2qFxA97NZHtxeLPUy
```

### Scoping the access token to a resource

You can scope the access token to a subset of resources and actions that can be done on that resource.
For example, to create an access token to only create, read and update the ledgers, you can add the
list of scopes to the request:

```bash theme={null}
curl --request POST \
 --url https://api.sandbox.getasset.com/v0/auth/token \
 --header 'Content-Type: application/x-www-form-urlencoded' \
 --data 'client_id=<string>' \
 --data 'client_secret=The oauth client secret' \
 --data 'scope=ledger:create ledger:update ledger:read'
```

## **Authenticating API Requests**

Include the access token in the `Authorization` header:

```bash theme={null}
curl --request GET \
  --url "https://api.sandbox.getasset.com/v0/business?page_size=100" \
  --header "Authorization: Bearer YOUR_ACCESS_TOKEN"
```

Access tokens expire after a set time and must be renewed using the same OAuth flow. Manage credentials in the Asset Dashboard.

<Warning>
  Credentials and tokens should always be kept secure—never share them outside
  your organization and exercise caution when sharing internally.
</Warning>

<Note>
  Questions? Reach out via our [Contact
  form](https://www.getasset.com/get-in-touch).
</Note>


# Headers
Source: https://docs.getasset.com/apioverview/headers



### Authorization

This is a required header in the form of `Bearer <token>`. It is used to authenticate all requests against the API.

### x-user-id

Some Asset API operations accept an optional `x-user-id` request header. When you send it, we associate the call with
that identifier so we can **track user actions on specific resources** .

The header is **optional**. Endpoints behave the same whether or not you include it.

Use a stable value your platform already uses to represent a person or service account (for example, the user's email
address). In the **API Reference** tab, each operation documents this header when it is supported.

<Note>
  Questions? Reach out via our [Contact
  form](https://www.getasset.com/get-in-touch).
</Note>


# Pagination
Source: https://docs.getasset.com/apioverview/pagination



Most Asset API endpoints that return lists of objects support pagination, allowing you to retrieve data in smaller chunks. Asset uses **cursor-based pagination**, which ensures no records are skipped between pages and provides better performance than offset-based pagination.

## Paginating Through Records

When an endpoint supports pagination, the API response includes pagination tokens:

```json theme={null}
{
  "next_page_token": "xK8QZ5JpT0L4FzDc6VaRb1MNhgAAAAABk9cXz3G2hJn7Yx2K1Nv==",
  "previous_page_token": "pT0L4FzDc6VaRb1MNhxK8QZ5JgAAAAABk9cXz3G2hJn7Yx2K1Nv==",
  "records": []
}
```

* **Use** `next_page_token` to request the next page.
* **Use** `previous_page_token` to request the previous page.
* If either token is `null`, there are no additional pages in that direction.

To retrieve the next page, include the `page_token` parameter in your request:

```bash theme={null}
curl --request GET \
  --url "https://api.asset.com/v0/business?page_token=<next_page_token>" \
  --header "Authorization: Bearer <token>"
```

To request the previous page:

```bash theme={null}
curl --request GET \
  --url "https://api.asset.com/v0/business?page_token=<previous_page_token>" \
  --header "Authorization: Bearer <token>"
```

## Page Size

By default, the API returns 50 records per page, with a maximum of 100 records per page. You can adjust this by setting the `page_size` parameter:

```bash theme={null}
curl --request GET \
--url 'https://api.asset.com/v0/business?page_token=<next_page_token>&page_size=100' \
--header 'Authorization: Bearer <token>'
```

<Note> Questions? Reach out via our [Contact form](https://www.getasset.com/get-in-touch). </Note>


# Rate Limits
Source: https://docs.getasset.com/apioverview/rate_limits



Asset applies rate limits to API requests to ensure reliable performance across our Platform. Rate limits protect the system from sudden spikes in traffic, ensuring consistent availability and response times for everyone.

### **Request Limits**

Asset enforces the following API rate limits:

* **Tenant-level requests**: 300 requests per minute
* **Business-level requests**: 300 requests per minute

Limits are applied independently at the [Tenant](/getstarted/CoreConcepts#tenants-your-platform) and [Business](/getstarted/CoreConcepts#businesses-your-smb-customers) levels, preventing heavy usage in one area from affecting others.

### **API Response Headers**

Every API response includes headers to help you monitor your usage and stay within rate limits:

| Header | Description |
| - | - |
| x-ratelimit-limit | The maximum number of requests permitted per minute. |
| x-ratelimit-remaining | The number of requests remaining in the current time window. |
| x-ratelimit-reset | The time (in UNIX timestamp format) when the rate limit resets. |

Using these headers, your application can manage its request patterns.

### **Exceeding Rate Limits**

If you exceed these limits, Asset APIs return:

* **HTTP status code**: 429 Too Many Requests

The response body will include a clear message indicating you've reached your limit.

### **Managing Your Requests**

To ensure optimal performance and avoid exceeding rate limits, we recommend:

* Monitoring the rate-limit headers returned with each response to proactively manage your usage.
* Implementing retry mechanisms with exponential backoff.
* Spacing requests evenly and batching API calls whenever possible.

If you have questions or anticipate higher usage needs, contact Asset support—we're here to help.
<Note> Questions? Reach out via our [Contact form](https://www.getasset.com/get-in-touch). </Note>


# Webhooks
Source: https://docs.getasset.com/apioverview/webhooks



Asset uses **webhooks** to send notifications regarding specific requests and updates about
the platform.

## **Configuring Webhooks**

* In the **Asset Dashboard**, go to **Developers → Webhooks**.
* Enter your `Endpoint URL` (HTTPS only).
* *(Optional)* Add custom `Headers` such as an `Authorization` token or an `x-asset-signature` secret.
* Click **Save**.

## **Disabling Webhooks**

There might be times in which you want to temporarily disable webhooks. To do this, follow the steps below:

1. In the **Asset Dashboard**, open **Developers → Webhooks**.
2. Toggle `Enabled` off.
3. Click **Save**.

## **Retries**

If there is non-200 response or the request times out, Asset will retry the request up to four more times,
each with an exponential backoff. The first delay will be 10 seconds, and subsequent delays will double from there.

## **Catching Up on Missed Webhooks**

If your endpoint was down or you missed some deliveries, you can replay past notifications with the
[Load webhook notifications](/api-reference/webhooks/load-webhook-notifications) endpoint:

```
GET /v0/tenant/webhook/notifications
```

* Pass `webhook_id` (the `asset-id` header of the last webhook you received) to get all notifications created after it.
* Filter by delivery status with the `status` query parameter (`pending`, `sent`, `error`), comma-separated for multiple values.
* Results are paginated.

Each item in the response contains the notification `id`, the `datetime` it was sent (or created if it has not
been sent yet), and the original `notification` message, so you can process missed events exactly as if they had
been delivered to your endpoint.

## **Headers**

Every webhook request comes with two headers `asset-id` and `asset-signature`. The `asset-id` header uniquely
identifies the webhook request, and `asset-signature` is the signature of the request. You can use the public key
at `https://api.getasset.com/.well-known/jwks.json` to validate the signature. Below is a sample Python code snippet
that shows how to validate the signature.

```python theme={null}
import json
import base64
import requests
from cryptography.hazmat.backends import default_backend
from cryptography.hazmat.primitives import hashes
from cryptography.hazmat.primitives.asymmetric import rsa, padding
from jwcrypto import jwk

def base64url_decode(val):
    val += "=" * (-len(val) % 4)  # Fix padding
    return base64.urlsafe_b64decode(val)

asset_id = "<VALUE FROM HEADER>"
asset_signature = "<VALUE FROM HEADER>"
body = <BODY OF WEBHOOK MESSAGE>
payload = f"{asset_id}.{json.dumps(body)}"
decoded_signature = base64url_decode(asset_signature)

# Download the public key for signature verification and convert to RSA format
resp = requests.get("https://api.getasset.com/.well-known/jwks.json").json()
key = jwk.JWK.from_json(json.dumps(resp["keys"][0]))
n = int.from_bytes(base64url_decode(key.get("n")), "big")
e = int.from_bytes(base64url_decode(key.get("e")), "big")
public_numbers = rsa.RSAPublicNumbers(e, n)
rsa_key = public_numbers.public_key(default_backend())

# Validate the signature
rsa_key.verify(
    decoded_signature,
    payload.encode(),
    padding.PKCS1v15(),
    hashes.SHA256(),
)

```

## **Notifications**

### Plaid connections

For bank integrations, we have the following notifications available:

* **PLAID\_ACCOUNT\_CONNECTED**: Sent when a new account is connected via Plaid.
* **PLAID\_ACCOUNT\_DISCONNECTED**: Sent when an existing account is disconnected through the Plaid link flow.
* **PLAID\_ACCOUNT\_EXPIRED**: Sent when Plaid detects that the account connection is not active. This means the account must be reconnected.
* **PLAID\_SYNC\_STARTED**: Sent when a transactions sync starts for a Plaid-connected account.
* **PLAID\_TRANSACTIONS\_SYNCED**: Sent when new transactions have been synced for a Plaid-connected account.
* **ACCOUNT\_BALANCE\_UPDATED**: Sent when the balance is updated on an account.

All notifications above have the same message structure:

```json theme={null}
{
  "type": "<PLAID_ACCOUNT_CONNECTED, PLAID_ACCOUNT_DISCONNECTED, PLAID_ACCOUNT_EXPIRED, PLAID_SYNC_STARTED, PLAID_TRANSACTIONS_SYNCED, ACCOUNT_BALANCE_UPDATED>",
  "content": {
    "business_id": "biz_Pk2fNFDd8wj7EFeLWJywc7",
    "timestamp": "<current timestamp in UTC>",
    "account_id": "<the plaid linked item id>"
  }
}
```

### Bookkeeping requests

As the books are being completed for a business, Asset will send requests that lists the set of tasks that need to be completed by the
business owner.

Message structure:

```json theme={null}
{
  "type": "TASK_REQUEST",
  "content": {
    "business_id": "biz_Pk2fNFDd8wj7EFeLWJywc7",
    "task_types": [
      "categorize_transaction",
      "reconnect_account",
      "request_other_document",
      "request_receipt",
      "request_statement",
      "review_personal_transaction",
      "other"
    ]
  }
}
```

In addition, when the business owner has completed the tasks, a notification is also sent.

Message structure:

```json theme={null}
{
  "type": "TASKS_REQUEST_COMPLETED",
  "content": {
    "business_id": "biz_Pk2fNFDd8wj7EFeLWJywc7",
    "timestamp": "<current timestamp in UTC ISO 8601>"
  }
}
```

<Note>
  Questions? Reach out via our [Contact form](https://www.getasset.com/get-in-touch)
  or email [support@getasset.com](mailto:support@getasset.com).
</Note>

### Business notifications

We have the following notifications when a Business changes state:

* **BUSINESS\_CREATED**: Sent when a business is created.
* **BUSINESS\_ACTIVATED**: Sent when an inactive business is activated.
* **BUSINESS\_DEACTIVATED**: Sent when an active business is deactivated.

Message structure:

```json theme={null}
{
  "type": "BUSINESS_CREATED",
  "content": {
    "business_id": "biz_Pk2fNFDd8wj7EFeLWJywc7",
    "business_external_id": "<the external business id>",
    "timestamp": "<current timestamp in UTC ISO 8601>"
  }
}
```

### Document notifications

We have the following notifications for uploaded documents:

* **RECEIPT\_MATCHED**: Sent when a receipt document is matched to a transaction.

Message structure:

```json theme={null}
{
  "type": "RECEIPT_MATCHED",
  "content": {
    "document_id": "doc_2xPQDLmNeWsrahR4bj3oGc9i6Nb",
    "transaction_id": "txn_3yQRENoPfXtsbhS5ck4pHd0j7Oc",
    "timestamp": "<current timestamp in UTC ISO 8601>"
  }
}
```

* **STATEMENT\_IMPORTED**: Sent when an uploaded bank statement finishes importing into an account.

Message structure:

```json theme={null}
{
  "type": "STATEMENT_IMPORTED",
  "content": {
    "business_id": "biz_Pk2fNFDd8wj7EFeLWJywc7",
    "account_id": "<the external account id>",
    "document_id": "doc_2xPQDLmNeWsrahR4bj3oGc9i6Nb",
    "timestamp": "<current timestamp in UTC ISO 8601>"
  }
}
```


# Managing Businesses
Source: https://docs.getasset.com/bookkeeping/businesses



## **Onboarding**

Before you can manage a [Business](/getstarted/CoreConcepts#businesses-your-smb-customers) in Asset, it must first be onboarded to ensure accurate bookkeeping. This process ensures essential information is stored in Asset —such as the business structure, financial tracking start date, and status—allowing Asset to configure the appropriate [Chart of Accounts](/getstarted/CoreConcepts#ledgers) and begin [Transaction](/getstarted/CoreConcepts#transactions) tracking. Proper onboarding ensures that financial data is categorized correctly, enabling seamless reporting and reconciliation.

To onboard a Business into Asset, call the **[Create a Business](/api-reference/business/create-a-business)** endpoint and include the required business details in your request. The following attributes must be provided

| Attribute | Request Parameter | Description |
| :- | :- | :- |
| Name | name | The Business’ name |
| Start Date | entries\_start | The first date from which Asset should begin pulling Transactions. |
| Entity Type | entity\_type | The Business structure, which determines the default Chart of Accounts. Supported types: Sole Proprietorships LLCs Partnerships S-Corporations C-Corporations |
| Fiscal Year | fiscal\_year | The specific date the Business' fiscal year ends on |
| Status | status | Indicates whether the Business is active or inactive. Transactions cannot be pulled for inactive businesses |

Once a Business is created, Asset will automatically assign the appropriate default **Chart of Accounts based on the provided Entity Type** and begin tracking Transactions from the specified Start Date.

## **Ongoing Management**

As a [Tenant](/getstarted/CoreConcepts#tenants-your-platform), you need visibility and control over all Businesses created in your platform. This includes updating Business details, retrieving Business information, and managing status (e.g., marking a Business as inactive due to delinquent payments).

Asset provides three API endpoints for Business management:

1. [Retrieve a Business](/api-reference/business/retrieve-a-business)
   * This endpoint provides you with access to all the details of one specific Business
2. [Update a Business](/api-reference/business/update-a-business)
   * Modify one or more attributes of a Business
     * **Note:** The **Entity Type of a Business cannot be changed** after creation. If an entity type update is required, you must create a new Business.
3. [List all Businesses](/api-reference/business/list-all-businesses)
   * Retrieve a list of all Businesses under your Tenant.
   * The response always includes the Business ID and can be customized to include additional attributes such as Status and Entity Type based on request parameters.
     <Note> Questions? Reach out via our [Contact form](https://www.getasset.com/get-in-touch). </Note>


# Categorizing Transactions
Source: https://docs.getasset.com/bookkeeping/categorization



### **Overview**

Categorization assigns [Transactions](/getstarted/CoreConcepts#transactions) to the correct [Ledger(s)](/getstarted/CoreConcepts#ledgers) in the Chart of Accounts, ensuring accurate financial reporting and compliance.

Accurate categorization is not just good bookkeeping—it’s a legal and financial necessity. Misclassified expenses can lead to tax complications, compliance issues, and financial misreporting. Yet, manual categorization is consistently reported as one of the most tedious responsibilities for [Business owners](/getstarted/CoreConcepts#businesses-your-smb-customers).

At Asset, we’ve built a **best-in-class categorization system** that reduces the time and effort required to categorize Transactions, ensuring accuracy while allowing Business Owners to focus on running their companies.

### **How Categorization Works in Asset**

Categorization happens directly on the **Transaction**. Each Transaction carries a review status and a set of **line items** that record how the Transaction is categorized, and each line item assigns an amount to a Ledger (its category). A Transaction with a single line item is categorized to one Ledger; a Transaction with several line items is split across multiple categories, with the line item amounts always summing to the Transaction amount.

Each Transaction that enters Asset follows a structured categorization pipeline to determine those line items:

1. **Transaction Enters Asset**

   * When a new Transaction enters Asset, it starts out uncategorized: it has no line items and its `posted` flag is `false`.

2. **Categorization Pipeline**
   The Transaction moves through a multi-step process to determine the appropriate category:

   * **Transfers Detection** - Was the Transaction a transfer between accounts?

   * **Similarity-Based Categorization -** Have we previously categorized a similar Transaction?

   * **AI-Powered Categorization -** What does AI predict the Transaction should be?

   * **Uncategorized Transactions -** If no match is found, the customer provides the correct category.

3. **Business Review and Finalization**

   * Once the Categorization Pipeline assigns line items, the Transaction is categorized and its `posted` flag is set to `true`, and it is ready for Business review.
   * Asset recommends that [Tenants](/getstarted/CoreConcepts#tenants-your-platform) include a workflow step requiring Businesses to review and confirm assigned categories, ensuring accuracy.
   * Any Uncategorized Transactions should be manually assigned to complete the books for the period.

### **Categorization Attributes in Asset**

To support customizable workflows, Asset exposes the following categorization attributes on each Transaction:

| Attribute | Description |
| :- | :- |
| **Posted** | Whether the Transaction is posted to the books: `false` while it is uncategorized, and `true` once it has been categorized. |
| **Status** | The categorization review status of the Transaction, derived from its journal entry: `bookkeeper_pending`, `business_pending`, or `confirmed`. A Transaction is finalized once its status is `confirmed`. Null when the Transaction has no status. |
| **Line Items** | The categorized allocations of the Transaction. Each line item carries the `ledger_id` (and `category` name) it is categorized to and the `amount` allocated to it, signed in the same direction as the Transaction amount. Null when the Transaction has no categorization. |

These attributes allow Tenants to build workflows that ensure Transactions are properly categorized while maintaining flexibility based on Business needs.

### **How to Categorize a Transaction in Asset**

To categorize or re-categorize a Transaction, call the [Update Transactions for a Business](/api-reference/transaction/update-transactions-for-a-business) endpoint. The endpoint accepts an array, so one or more Transactions can be updated in a single request.

```
PATCH /v0/business/{business_id}/transactions
```

**Path Parameters:**

* **Business ID** – Specifies the Business where the Transactions are being updated.

**Request Body** – an array of update items, each with:

* **Transaction ID** (required) – Identifies the specific Transaction to update.
* **Type** (optional) – The updated type of the Transaction (`business` or `personal`).
* **Tags** (optional) – Inline tag input to merge into the Transaction's tags.
* **Line Items** (optional) – Replaces the Transaction's line items with a new set of categorized allocations. Each line item has:
  * **Ledger ID** – The Ledger (category) to allocate the amount to.
  * **Description** – The description of the line item.
  * **Amount** – The amount allocated to the line item, signed in the same direction as the Transaction amount. Provide a single line item to change the category, or several to split the Transaction across categories; the amounts must sum to the Transaction amount.

**Re-categorize to a single category** (a \$89.23 outflow assigned entirely to Office Supplies):

```json theme={null}
[
  {
    "transaction_id": "txn_WQMDNUHpBThYSNh4AprDBo",
    "line_items": [
      {
        "ledger_id": "ldg_Ns6rRRLYVZPh4cVB7MDby5",
        "description": "Office Supplies",
        "amount": -89.23
      }
    ]
  }
]
```

**Split across multiple categories** (a \$100 outflow split evenly between Office Supplies and Travel):

```json theme={null}
[
  {
    "transaction_id": "txn_WQMDNUHpBThYSNh4AprDBo",
    "line_items": [
      {
        "ledger_id": "ldg_Ns6rRRLYVZPh4cVB7MDby5",
        "description": "Office Supplies",
        "amount": -50.00
      },
      {
        "ledger_id": "ldg_WQMDNUHpBThYSNh4AprDBo",
        "description": "Travel",
        "amount": -50.00
      }
    ]
  }
]
```

Categorizing a Transaction—assigning its line items—is what confirms it: its `status` moves to `confirmed` and it is finalized on the books.

Once updated, the new categorization will reflect in the application. A typical Tenant workflow is to [List Transactions for a Business](/api-reference/transaction/list-transactions-for-a-business) (optionally filtering to unconfirmed Transactions), review each Transaction's line items, and call the update endpoint to set the correct Ledger on the line items, confirming the Transaction.

### **Categorizing High-Impact Transactions First**

Not all Transactions carry the same weight. To help Businesses clear the most outstanding value with the least effort, Asset groups similar unconfirmed Transactions and ranks those groups by **impact**—the share of outstanding dollar value each group represents. Categorizing a high-impact group at once clears more of the books in a single step.

To fetch these groups, call the [List high-impact Transaction groups to categorize](/api-reference/categorization/list-high-impact-transaction-groups-to-categorize) endpoint:

```
GET /v0/business/{business_id}/categorization
```

**Query Parameters:**

* **limit** (optional) – Maximum number of Transaction groups to return (1–50, default 10).
* **account\_ids** (optional) – Restrict to these External Account IDs, comma-separated.

Each group in the response contains:

| Field | Description |
| :- | :- |
| **transaction\_ids** | The IDs of the unconfirmed Transactions in this group. Applying a category to all of them clears the whole group. |
| **transaction\_count** | The number of Transactions in the group. |
| **total\_amount** | The total dollar value of the Transactions in the group, summed as absolute amounts. |
| **impact** | The share of outstanding dollar value this group represents (`total_amount` divided by the total dollar value of all unconfirmed Transactions). Higher means categorizing this group clears more outstanding value. |

Example response:

```json theme={null}
{
  "data": [
    {
      "transaction_ids": [
        "txn_WQMDNUHpBThYSNh4AprDBo",
        "txn_2xPbN4qFxA97NZHtxeLPUy"
      ],
      "transaction_count": 12,
      "total_amount": 1480.32,
      "impact": 0.18
    }
  ]
}
```

A recommended bulk-categorization workflow:

1. **Fetch the high-impact groups** from `GET /v0/business/{business_id}/categorization`.
2. **Fetch the Transactions** in a group (using the returned `transaction_ids`) so the Business can confirm they belong together.
3. **Update them all at once** by passing every Transaction in the group to `PATCH /v0/business/{business_id}/transactions` with the chosen line items, categorizing the entire group in a single request.

<Note> Questions? Reach out via our [Contact form](https://www.getasset.com/get-in-touch). </Note>


# Invoice Reconciliation
Source: https://docs.getasset.com/bookkeeping/invoices



## **Overview**

Invoice Reconciliation is the process of creating Invoices, matching Transactions, and handling Refunds for a [Business](/getstarted/CoreConcepts#businesses-your-smb-customers).

It ensures the correct bookkeeping entries are made for outstanding, paid, and voided Invoices, while helping Business owners clearly see earned revenue and cash still to be collected.

***

## **Working with Invoices in Asset**

### 1. Create an Invoice

1. Call the **[Create an Invoice](/api-reference/invoice/create-an-invoice)** endpoint.

<Note>
  You can use the **[Customer Credit Balance Report](/bookkeeping/reports/customercredit)** to check available credits for a customer before creating an Invoice. This lets you apply credits immediately to reduce the amount due.
</Note>

2. Asset automatically creates a **[Journal Entry](/getstarted/CoreConcepts#journal-entry)** to record earned revenue:
   * Debit **Accounts Receivable**
   * Credit **Sales Revenue** (selected Ledger)

***

### 2. Match Payments to an Invoice

1. Call the **[Create Transactions](/api-reference/transaction/create-transactions)** endpoint to create a new Transaction in Asset. Alternatively, use a Transaction that already exists.\*
2. Call the **[Apply a Payment to an Invoice](/api-reference/invoice/apply-a-payment-to-an-invoice)** endpoint to match a Transaction to an Invoice:
   * If the Transaction amount is **less than** the Invoice amount, additional Transactions can be applied later.
   * If the Transaction amount is **greater than** the Invoice amount, the extra amount can be applied to another Invoice. If not, Asset records the excess as **Customer Credit**.
3. Asset creates a Journal Entry to record the payment date.
4. Once the sum of matched Transactions is greater than or equal to the Invoice amount, the Invoice status updates to **paid**.

\*Asset attempts to automatically match Transactions to Invoices based on description, amount, and date.

***

### 3. Refund an Invoice

1. Call the **[Refund an Invoice](/api-reference/invoice/refund-an-invoice)** endpoint.

<Note>
  Do not manually update the Invoice status to **refunded** or **partially\_refunded**. The status updates automatically when you call the Refund an Invoice endpoint.
</Note>

2. Refund rules:
   * **Partial Refund:** You must provide the line ID being refunded. Asset sets the Invoice status to **partially\_refunded**.
   * **Full Refund:** When the Refund amount equals the Invoice amount, the status updates to **refunded**.
   * Refunds **cannot exceed** the Invoice amount (the system returns an error).

3. The `refund_credit` field specifies refund type:
   * **True** → Creates a **Customer Credit Journal Entry** (Refund completed).
   * **False** → Creates a **Journal Entry** increasing **Accounts Payable** (Refund pending).

***

### 4. Match Payments to an Invoice Refund

1. Call the **[Create Transactions](/api-reference/transaction/create-transactions)** endpoint to create a new Transaction in Asset.\*
2. Call the **[Apply Transaction to a Refund](/api-reference/invoice/apply-transaction-to-a-refund)** endpoint to match a Transaction to a Refund:
   * If the Transaction amount is **less than** the Refund amount, additional Transactions can be applied later.
   * If the Transaction amount is **greater than** the Refund amount, the excess can be applied to another Refund. If not, Asset records the extra as **Uncategorized Outflow**.
3. Asset creates a Journal Entry to record the payment date.
4. Once the sum of matched Transactions is greater than or equal to the Refund amount, the Refund status updates to **completed**.

\*Asset attempts to automatically match Transactions to Refunds based on description, amount, and date.

***

<Note>
  Questions? Reach out via our [Contact form](https://www.getasset.com/get-in-touch).
</Note>


# Personal Accounts
Source: https://docs.getasset.com/bookkeeping/personaltransactions



## Overview

The **Personal Business Crossover** feature allows small business owners to efficiently manage the separation between personal and business finances. Many small business owners use personal accounts for business transactions, which can lead to financial tracking issues, tax complications, and bookkeeping overhead.

This functionality provides a structured way to:

* Connect personal accounts through Plaid or manually
* Mark personal transactions as business when necessary
* Automatically generate journal entries with appropriate ledger mappings
* Revert business transactions back to personal when needed

## Key Concepts

### Personal External Accounts

**Personal External Accounts** are financial accounts that belong to the business owner but are not primarily designated for business use. Common examples include:

* Personal bank accounts
* Personal credit cards
* Personal savings accounts

When connecting an external account, users must designate it as either **Personal** or **Business**. This designation determines how associated transactions will be treated.

### Ledger Mapping

Each Personal External Account requires specific ledger mappings:

1. **Contribution Ledger**: Used when expenses are paid from a personal account
2. **Distribution Ledger**: Used when revenue is received in a personal account

<Note> Even though the API schema does not mark these ledger IDs as strictly required, our system requires both `contribution_ledger_id` and `distribution_ledger_id` for any **Personal** external account. Without these, we cannot track contributions or distributions accurately. </Note>

## How It Works

### Connecting Personal External Accounts

Personal external accounts can be connected in two ways:

#### 1. Plaid Integration

1. The user selects their accounts through the Plaid Link component.
2. In the confirmation screen, they designate the account as **Personal**.
3. They select appropriate ledgers for Contributions and Distributions.

#### 2. Manual Creation

Users can manually create a personal external account by calling the **[Create an External Account](/api-reference/transaction/create-an-external-account)** endpoint:

```
POST /v0/business/{business_id}/external-account
```

Providing:

* Designation as `"type": personal`
* Ledger IDs for `contribution_ledger_id` and `distribution_ledger_id`

Example request:

```json theme={null}
{
  "name": "Personal Bank Account",
  "mask": "1234",
  "type": "personal",
  "source": "manual",
  "contribution_ledger_id": "ldg_123456",
  "distribution_ledger_id": "ldg_789012"
}
```

### Managing Personal Transactions

All transactions from personal accounts are automatically created with `"type": "personal"`. These transactions:

* Do not affect the business books until marked as business
* Can be filtered in the UI or API with `"type": "personal"`
* Appear in the "Personal Review" page for processing

### Marking Transactions as Business

When a personal transaction should be treated as business:

1. The user marks the transaction as business through the UI or API by calling the **[Update Transactions for a Business](/api-reference/transaction/update-transactions-for-a-business)** endpoint:

   ```
   PATCH /v0/business/{business_id}/transactions
   ```

   Example request:

   ```json theme={null}
   [
     {
       "transaction_id": "txn_WQMDNUHpBThYSNh4AprDBo",
       "type": "business"
     },
     {
       "transaction_id": "txn_ZXMPQRSfLmOaNBc5DqrEFp",
       "type": "business"
     }
   ]
   ```

2. The system automatically **generates a journal entry** to reflect the transaction on the books.

   * **For expenses paid from a personal account**:
     * **Debit**: Expense ledger (e.g., Meals, Office supplies)
     * **Credit**: Contribution ledger (representing the owner’s money contributed)

   * **For revenue received in a personal account**:
     * **Debit**: Distribution ledger (representing funds drawn by the owner)
     * **Credit**: Revenue ledger (e.g., Sales Revenue)

   From an accounting perspective:

   * Paying for a business expense from personal funds increases the business’s expenses, offset by an equity contribution.
   * Receiving business revenue in a personal account increases the business’s revenue, offset by an equity distribution (or “owner’s draw”).

### Reverting to Personal

If a transaction previously marked as business needs to be reverted:

1. The user updates the transaction’s type from `"business"` back to `"personal"` through the UI or API by calling the **[Update Transactions for a Business](/api-reference/transaction/update-transactions-for-a-business)** endpoint:

   ```
   PATCH /v0/business/{business_id}/transactions
   ```

   ```json theme={null}
   [
     {
       "transaction_id": "txn_abc123",
       "type": "personal"
     }
   ]
   ```

2. The system automatically **deletes** the associated journal entry, removing its impact on the books.

## Common Use Cases

### Case 1: Business Expenses on Personal Credit Card

A business owner pays \$100 for office supplies using their personal credit card:

1. The transaction appears as `personal` in the review page.
2. The owner marks the transaction as `business`.
3. The system creates a journal entry:
   * **Debit**: Office Supplies \$100
   * **Credit**: Owner’s Contribution \$100

### Case 2: Business Revenue in Personal Bank Account

A customer pays \$500 to the owner’s personal bank account:

1. The transaction appears as `personal` in the review page.
2. The owner marks the transaction as `business`.
3. The system creates a journal entry:
   * **Debit**: Owner’s Distribution \$500 (or “Owner’s Draw”)
   * **Credit**: Sales Revenue \$500

<Note>
  Questions? Reach out via our [Contact form](https://www.getasset.com/get-in-touch).
</Note>

<Accordion title="API Examples">
  ### Creating a Personal External Account

  Call the **[Create an External Account](/api-reference/transaction/create-an-external-account)** endpoint:

  ```
  POST /v0/business/{business_id}/external-account
  ```

  Example request:

  ```json theme={null}
  {
    "name": "Personal Bank Account",
    "mask": "1234",
    "type": "personal",
    "source": "manual",
    "contribution_ledger_id": "ldg_123456",
    "distribution_ledger_id": "ldg_789012"
  }
  ```

  ### Creating Personal Transactions

  Call the **[Create Transactions](/api-reference/transaction/create-transactions)** endpoint:

  ```
  POST /v0/business/{business_id}/transactions
  ```

  Transactions for personal external accounts are automatically marked `"personal"`.

  ### Listing Personal Transactions

  Call the **[List Transactions for a Business](/api-reference/transaction/list-transactions-for-a-business)** endpoint, filtering by type:

  ```
  GET /v0/business/{business_id}/transactions?type=personal&reviewed=false
  ```

  ### Converting Personal Transactions to Business

  Call the **[Update Transactions for a Business](/api-reference/transaction/update-transactions-for-a-business)** endpoint:

  ```
  PATCH /v0/business/{business_id}/transactions
  ```

  ```json theme={null}
  [
    {
      "transaction_id": "txn_WQMDNUHpBThYSNh4AprDBo",
      "type": "business"
    },
    {
      "transaction_id": "txn_ZXMPQRSfLmOaNBc5DqrEFp",
      "type": "business"
    }
  ]
  ```

  ### Marking Transactions as Reviewed

  Call the same **[Update Transactions for a Business](/api-reference/transaction/update-transactions-for-a-business)** endpoint, specifying `"reviewed": true`:

  ```
  PATCH /v0/business/{business_id}/transactions
  ```

  ```json theme={null}
  [
    {
      "transaction_id": "txn_WQMDNUHpBThYSNh4AprDBo",
      "reviewed": true
    },
    {
      "transaction_id": "txn_ZXMPQRSfLmOaNBc5DqrEFp",
      "reviewed": true
    }
  ]
  ```

  ### Disconnecting Personal External Accounts

  Call the **[Update External Account](/api-reference/transaction/update-external-account)** endpoint:

  ```
  PATCH /v0/business/{business_id}/external-account/{external_account_id}
  ```

  ```json theme={null}
  {
    "status": "disconnected"
  }
  ```

  <Note> (While the API also supports an `untracked` status, it is generally unused for the personal-business crossover use case.) </Note>
</Accordion>


# Reconciliation
Source: https://docs.getasset.com/bookkeeping/reconciliation



### **Overview**

**Reconciliation** is the process of matching recorded [Transactions](/getstarted/CoreConcepts#transactions) in Asset with external financial data (e.g., bank statements) to ensure accuracy. This step is essential for detecting discrepancies and maintaining reliable financial records.

Asset simplifies reconciliation by maintaining a running balance of recorded Transactions and comparing it against the balance provided by the Transaction source e.g. [Plaid](/importingdata/plaid).

* If the balances match, the [Account](/getstarted/CoreConcepts#accounts) is reconciled.
* If the balances do not match, the Business User or Bookkeeper must investigate the discrepancy.

The recommended approach is to review a Bank Statement, identify the missing or incorrect entry, and adjust the books accordingly. Any necessary corrections should be made through **adjusting Journal Entries**, ensuring that the recorded balance aligns with the actual financial data. Once balanced, the Account is considered reconciled.

### **How to Create an Adjusting Journal Entry on Asset**

Let’s say a [Business Owner](/getstarted/CoreConcepts#businesses-your-smb-customers) notices that a Bank Account is unreconciled due to an incorrect transaction amount. In this scenario, the Owner purchased a new lawn mower on June 25, 2024, but the Transaction was incorrectly recorded as 6,686 instead of the correct amount of 6,886.

To correct this, the Business Owner must create an **adjusting Journal Entry** to reflect the missing \$200.

Your application can support this by following these steps:

1. **Journal Entry Creation Interface** – Provide a front-end form that allows users to input:
   * The correct transaction amount
   * The affected [Ledgers](/getstarted/CoreConcepts#ledgers) for each line
   * A brief description for reference
2. **Call Create a Journal Entry** – When the user submits the correction, your application should call the [Create a Journal Entry](/api-reference/journal-entry/create-a-journal-entry) endpoint, including:
   * **Date:** The original transaction date (06/25/2024)
   * **Description:** A clear reason for the adjustment (e.g., "Adjusting Entry – Correcting Bank Transaction Error")
   * **Ledger details**: The appropriate accounts, amounts, and debit/credit directions

**Example Adjusting Journal Entry**

Date: 06/25/2024

Description: Adjusting Entry - Correcting Bank Transaction Error

| Ledger | Debit (\$) | Credit (\$) |
| :- | :- | :- |
| Property, Plant, and Equipment (PPE) | 200 | |
| Chase Checking X1234 | | 200 |

**Accounting Breakdown**

* Debit PPE (+\$200): Increases the asset value to reflect the correct purchase amount.
* Credit Bank Account (-\$200): Adjusts the cash balance to match the actual amount spent.

<Note> Questions? Reach out via our [Contact form](https://www.getasset.com/get-in-touch). </Note>


# Aged Receivables Report
Source: https://docs.getasset.com/bookkeeping/reports/agedreceivables



## **Overview**

The **Aged Receivables Report** shows all unpaid Invoices for a [Business](/getstarted/CoreConcepts#businesses-your-smb-customers), grouped by how long they have been overdue.

An **Invoice** is considered **outstanding** only after its **due date** has passed and payment has not been applied. The report shows which customers owe money, the overdue duration of their payments, and the total outstanding balance.

Key components (per customer):

* **Customer ID** – Unique identifier for the customer.
* **Customer Name** – Display name of the customer.
* **Overdue 0–30** – Amount past due by up to 30 days.
* **Overdue 31–60** – Amount past due by 31–60 days.
* **Overdue 61–90** – Amount past due by 61–90 days.
* **Overdue 90+** – Amount past due by more than 90 days.
* **Total Outstanding** – Sum of all overdue Invoices for the customer.

***

## **How to Generate an Aged Receivables Report**

1. Call the [Retrieve the Aged Receivables Report](/api-reference/reports/retrieve-the-aged-receivables-report) endpoint with:
   * **Business ID**
   * **start\_datetime** (ISO‑8601) — the reference date used to calculate aging buckets

**Example request:**

```bash theme={null}
curl --request GET   --url "https://api.sandbox.getasset.com/v0/business/{business_id}/reports/aged-receivables?start_datetime=2025-01-01T00:00:00Z"   
--header 'Authorization: Bearer <token>'
```

2. Use the response to display customer-level balances across the standard aging buckets:
   * **0–30 days overdue**
   * **31–60 days overdue**
   * **61–90 days overdue**
   * **90+ days overdue**
   * **Total Outstanding**

***

## **Aged Receivables Best Practices**

* **Use today’s date for most cases.** Passing today’s date as `start_datetime` ensures aging buckets reflect overdue balances as of the current day, which aligns with standard collections workflows.
* **Provide drill-downs.** Users may need to inspect overdue Invoices for a specific customer. Use the [Invoice Reconciliation](/bookkeeping/invoices) guide and [Invoice endpoints](/api-reference/schema/invoice) to retrieve details.
* **Handle time zones carefully.** The `start_datetime` parameter anchors aging buckets. Use UTC consistently or clearly state how local time zones are applied.

***

<Note>
  Questions? Reach out via our [Contact form](https://www.getasset.com/get-in-touch).
</Note>


# Balance Sheet
Source: https://docs.getasset.com/bookkeeping/reports/balancesheet



## **Overview**

The **Balance Sheet** provides a snapshot of a [Business’s](/getstarted/CoreConcepts#businesses-your-smb-customers) financial position at **a given point in time**, summarizing what the Business owns (assets), what it owes (liabilities), and the owner’s interest in the company (equity).

The Balance Sheet is based on the **fundamental accounting equation**:

$\textit{Assets} = \textit{Liabilities} + \textit{Equity}$

Key components:

* **Assets** – Resources owned by the Business, such as cash, receivables, and equipment.
* **Liabilities** – Obligations owed to others, such as loans and unpaid bills.
* **Equity** – The Business’s net worth after liabilities are deducted from assets.

The Balance Sheet helps Businesses assess financial stability and creditworthiness.

## **How to Generate a Balance Sheet**

1. Call the [Retrieve the Balance Sheet Report](/api-reference/reports/retrieve-the-balance-sheet-report) endpoint with:
   * Business ID
   * Simple Date or Timestamp
2. Display the data using the following structure (backed by customer research for clarity):
   * **Assets**
     * Current Assets (e.g., cash, accounts receivable, inventory)
     * Non-Current Assets (e.g., equipment, long-term investments)
     * **Total Assets**

   * **Liabilities**
     * Current Liabilities (e.g., accounts payable, short-term loans)
     * Non-Current Liabilities (e.g., long-term loans, deferred revenue)
     * **Total Liabilities**

   * **Equity**
     * Retained Earnings
     * Owner’s Equity / Shareholder Equity
     * **Total Equity**

Since the Balance Sheet is a snapshot in time, all values should reflect the financial position at the specified report date

## **Balance Sheet Best Practices**

* **Handling Report Dates Accurately –** The Balance Sheet reflects a **single moment in time**, which can cause confusion if not communicated properly. When requesting a Balance Sheet, you can pass either:
  * **A date →** Asset will return the Balance Sheet as of 23:59:59 EST on that date.
  * **A full timestamp →** Recommended for high-transaction-volume Businesses to align reporting with local time zones. Clearly indicate to users that the Balance Sheet represents a fixed point in time.

* **Enable Ledger Drill-Downs** – Users may need to investigate specific balances. Use the [Ledger Statement](/bookkeeping/reports/ledgerstatement) report to provide transaction-level details.

* **Set Opening Balances Correctly** – When creating an [External Account](/getstarted/CoreConcepts#accounts), ensure the **Opening Balance** is accurate. Asset uses this as the starting point for running balances in the Balance Sheet. An incorrect Opening Balance will lead to misstated financials.
  <Note> Questions? Reach out via our [Contact form](https://www.getasset.com/get-in-touch). </Note>


# Introduction to Reports
Source: https://docs.getasset.com/bookkeeping/reports/creatingreports



Generating accurate financial reports is essential for [Businesses](/getstarted/CoreConcepts#businesses-your-smb-customers) to file taxes, analyze performance, and make informed decisions. Asset’s APIs allow you to construct custom reports using [Journal Entry](/getstarted/CoreConcepts#journal-entry) and [Ledger](/getstarted/CoreConcepts#ledgers) data. However, to streamline report generation and accelerate time to value, Asset provides pre-built endpoints for the following key financial reports:

1. **[Profit and Loss Report](/bookkeeping/reports/profitandloss)** (Income Statement) – Measures Business performance by summarizing revenue, expenses, and net profit over a given period.
2. **[Simplified Cash Flow Report](/bookkeeping/reports/simplecashflow)** – A straightforward summary of cash inflows and outflows, helping Business Owners quickly assess their cash position.
3. **[Ledger Statement](/bookkeeping/reports/ledgerstatement)** – A Transaction-level view of all entries within a specific ledger over a defined period.
4. **[Balance Sheet](/bookkeeping/reports/balancesheet)** – A financial snapshot of assets, liabilities, and equity at a specific point in time.

<Note> Questions? Reach out via our [Contact form](https://www.getasset.com/get-in-touch). </Note>


# Customer Credit Balance Report
Source: https://docs.getasset.com/bookkeeping/reports/customercredit



## **Overview**

The **Customer Credit Balance Report** shows all outstanding credits a [Business](/getstarted/CoreConcepts#businesses-your-smb-customers) has issued to its customers.

Customer credits are created when payments exceed the balance of an Invoice, or when a Refund is issued as a **credit** rather than cash. These credits can later be applied to future Invoices.

Key components:

* **Total Credits** – The total dollar value of credits issued to a customer.
* **Total Applied Credits** – The portion of credits already used against Invoices.
* **Total Available Credits** – The remaining credits that can still be applied.

This report helps Businesses track liabilities to customers and ensure credits are properly managed and applied.

***

## **How to Generate a Customer Credit Balance Report**

1. Call the [Retrieve the Customer Credit Balance Report](/api-reference/reports/retrieve-the-customer-credit-balance-report) endpoint with:
   * **Business ID**

2. Use the response to present customer-level credit balances:
   * **Customer ID** – Unique identifier for the customer.
   * **Customer Name** – Display name of the customer.
   * **Total Credits** – Value of all credits ever issued to this customer.
   * **Total Applied Credits** – Credits already applied to Invoices.
   * **Total Available Credits** – Credits still available to be applied.

***

## **Customer Credit Report Use Cases**

* **Highlight Available Credits** – The `total_available_credits` field represents actionable credits that can be applied to reduce future Invoice payments.
* **Apply to New Invoices** – Credits can be applied when Invoices are created using the [Create an Invoice](/api-reference/invoice/create-an-invoice) endpoint.
* **Monitor Liability Exposure** – Credits represent an obligation of the Business. Regularly reviewing this report ensures liabilities to customers are properly accounted for.

***

<Note>
  Questions? Reach out via our [Contact form](https://www.getasset.com/get-in-touch).
</Note>


# Ledger Statement
Source: https://docs.getasset.com/bookkeeping/reports/ledgerstatement



## **Overview**

A **Ledger Statement** provides a detailed view of all Lines recorded in a specific [Ledger](/getstarted/CoreConcepts#ledgers) over a given period. It allows [Business Owners](/getstarted/CoreConcepts#businesses-your-smb-customers) to analyze [Transactions](/getstarted/CoreConcepts#transactions) within an [External Account](/getstarted/CoreConcepts#accounts), helping them track spending patterns and identify unusual activity.

For example, if Operating Expenses are unexpectedly high, a Business Owner can review the Ledger Statement to pinpoint changes in spending and make informed decisions.

## **How to Generate a Ledger Statement**

1. Call the **Retrieve the Ledger Statement** endpoint with:
   1. Business ID
   2. Start Date
   3. End Date

2. Use the returned data to structure the report as a list of transactions made in that ledger over the selected period.

## **Ledger Statement Best Practices**

* **Filter by date range** – Use a date picker with standard periods like months, quarters, and years to give users control.
* **Enable drill-down into Transactions** – Users may want to inspect specific Transactions. Use the [Journal Entry endpoints](/api-reference/schema/journal-entry) to provide detailed transaction data.

<Note> Questions? Reach out via our [Contact form](https://www.getasset.com/get-in-touch). </Note>


# Profit and Loss Report
Source: https://docs.getasset.com/bookkeeping/reports/profitandloss



## **Overview**

The **Profit & Loss** (or Income Statement) summarizes a [Business’s](/getstarted/CoreConcepts#businesses-your-smb-customers) revenue and expenses over a specific period. It calculates net income (profit or loss) by subtracting total expenses from total revenue.

Key components:

* **Revenue** – Money earned from Business operations.
* **Cost of Goods Sold (COGS)** – Direct costs of producing goods or services.
* **Gross Profit** – Revenue minus COGS.
* **Operating Expenses** – Costs of running the Business (e.g., salaries, rent, utilities).
* **Net Income** – The final profit or loss after all expenses are deducted.

A Profit & Loss Report helps Businesses assess profitability and track financial performance over time.

## **How to Generate a Profit and Loss Report**

1. Call the [Retrieve the Profit and Loss Report](/api-reference/reports/retrieve-the-profit-&-loss-report) endpoint with:
   1. Business ID
   2. Start Date
   3. End Date

2. Use the returned data to structure the report as follows:
   1. **Revenue**
      * Sales Revenue
      * Other Revenue ledgers
      * **Total Revenue**

   2. **Cost of Goods Sold**
      * Cost of goods sold
      * Other COGS ledgers
      * **Total COGS**

   3. **Gross Profit**

   4. **Operating Expenses**
      * Display all relevant Operating Expense ledgers
      * **Total Operating Expenses**

   5. **Operating Profit**

   6. **Other Incomes and Expenses**
      * Other income (e.g., investment earnings)
      * Other expenses (e.g., loan interest payments)

   7. **Net Profit**

## **P\&L Best Practices**

* **Filter by date range** – Use a date picker with standard periods like months, quarters, and years to give users control.
* **Hide zero-value [Ledgers](/getstarted/CoreConcepts#ledgers)** – The API returns all Ledgers, including those with a balance of \$0. Hiding these improves clarity.
* **Enable drill-down into ledgers** – Users may want to inspect specific ledgers. Use the [Ledger Statement](/bookkeeping/reports/ledgerstatement) report to provide detailed transaction data.

<Note> Questions? Reach out via our [Contact form](https://www.getasset.com/get-in-touch). </Note>


# Simple Cash Flow Report
Source: https://docs.getasset.com/bookkeeping/reports/simplecashflow



## **Overview**

While traditional Cash Flow Statements are useful for investors and loan applications, most [SMB owners](/getstarted/CoreConcepts#businesses-your-smb-customers) struggle to interpret them. Asset’s **Simplified Cash Flow Report** provides a clearer, more actionable view of a Business’s cash movements over time.

This report helps Business owners quickly assess:

1. Start and End Cash Balances
2. Where cash entered the business (e.g., sales, loans)
3. Where cash left the business (e.g., expenses, loan payments)

Unlike the [Profit & Loss Report](/bookkeeping/reports/profitandloss), which includes non-cash items like depreciation, the Cash Flow Statement focuses only on actual cash movements, giving a clear picture of financial liquidity.

## **How to Generate a Simplified Cash Flow Report**

1. Call the [Retrieve the Cash Flow Report](/api-reference/reports/retrieve-the-cash-flow-report) endpoint with:
   1. Business ID
   2. Start Date
   3. End Date
2. Display the data using the following structure (backed by customer research for clarity):
   1. Starting Total Cash
   2. Cash Flow from Ops (Cash in and out of the business from Operating Activities)
   3. Other Cash Flows (e.g. Loans and interest payments)
   4. Ending Total Cash

## **Cash Flow Best Practices**

* **Filter by date range** – A date picker with standardized options (months, quarters, years) makes comparisons easy.
* **Enable [Ledger](/getstarted/CoreConcepts#ledgers) drill-downs** – Users may want to explore details behind cash movements. Use the [Ledger Statement](/bookkeeping/reports/ledgerstatement) report to provide transaction-level data

<Note> Questions? Reach out via our [Contact form](https://www.getasset.com/get-in-touch). </Note>


# Tagging
Source: https://docs.getasset.com/bookkeeping/tagging



### **Overview**

Tags let you label [Business](/getstarted/CoreConcepts#businesses-your-smb-customers) data with structured dimensions (for example **Job**, **Location**, or **Department**) so you can filter, report, and automate workflows consistently across entities.

Tagging is a **two-step** process:

1. **Define tag fields** (the dimensions you want to tag by).
2. **Set tag values on entities** that support tagging (assign or remove values using each entity’s **`tags`** field in the API).

***

### **Step 1: Create tag fields**

A **tag field** is the name of a dimension (for example `"Job"`). Tag fields fall into two scopes:

| Scope | What it means |
| :- | :- |
| **Global tag fields** | Created at the **tenant** level. Every business under the tenant can use these fields. |
| **Business tag fields** | Created for **one specific business**. Only that business uses them (for example a field that does not apply tenant-wide). |

**API (global tag fields)**

* [List global Tag Fields](/api-reference/tenant/list-global-tag-fields) — `GET /v0/tenant/tag-fields`
* [Create a global Tag Field](/api-reference/tenant/create-a-global-tag-field) — `POST /v0/tenant/tag-fields`
* [Update a global Tag Field](/api-reference/tenant/update-a-global-tag-field) — `PATCH /v0/tenant/tag-fields/{tag_field_id}`
* [Delete a global Tag Field](/api-reference/tenant/delete-a-global-tag-field) — `DELETE /v0/tenant/tag-fields/{tag_field_id}`

**API (see fields available to a business)**

* [List Tag Fields for a Business](/api-reference/tag/list-tag-fields-for-a-business) — `GET /v0/business/{business_id}/tag-fields`\
  Use this to discover which tag fields apply to a given business (including global fields and business-specific fields).

The [Tag Field](/api-reference/schema/tag-field) object describes the shape returned by the API.

**Optional: predefined tag values**

If you want a controlled list of allowed values for a field (instead of only free-form values created when tagging), create **[Tag Values](/api-reference/schema/tag-value)** for that business:

* [Create a Tag Value](/api-reference/tag/create-a-tag-value) — `POST /v0/business/{business_id}/tag-values`
* [List Tag Values for a Business](/api-reference/tag/list-tag-values-for-a-business) — `GET /v0/business/{business_id}/tag-values`

***

### **Step 2: Tag entities**

After the tag field exists, set tags on any **entity that supports tagging** by sending a **`tags`** object on create or update requests.

**Simple Tagging**

Shape

* Keys are **tag field names** (strings), for example `"Job"` or `"Location"`.
* Values are **tag value names** (strings), for example `"job-123"` or `"NYC"`.

```json theme={null}
{
  "Job": "job-123",
  "Location": "NYC"
}
```

The tag field must already exist for that business. If the value string does not exist yet, the API can **create the tag value automatically** when you save the entity (see entity-specific API docs for details).

**Advanced Tagging**

There are times in which you want to split an entitiy across multiple tags. For example, let's say that you pay for a software license that costs \$500 for two business locations (NYC and LA), and you want to split the expense across the two.
You can achieve that by specifying a tag object that contains the tag value and amount. Example:

```
{
  "Location": [
    {"value": "NYC", "amount": "300.00"},
    {"value": "LA", "amount": "300.00"}
  ]
}
```

**Removing a tag**

On update payloads that support **merge** semantics for `tags`, set the field’s value to **`null`** to clear that tag on the entity. Keys you omit are typically left unchanged.

```json theme={null}
{
  "Job": null
}
```

**Examples of entities that support `tags`**

* [Transactions](/api-reference/transaction/create-transactions) (inline tags on transaction payloads)
* [Journal Entry](/api-reference/journal-entry/create-a-journal-entry) line entries (`tags` on lines)
* [Invoices](/api-reference/invoice/create-an-invoice) (`tags` on create/update)
* [Bills](/api-reference/bill/create-bills) (`tags` on create/update)

Check the request schema for each endpoint: if it includes a **`tags`** property, you can use the pattern above.

<Note>
  Questions? Reach out via our [Contact
  form](https://www.getasset.com/get-in-touch).
</Note>


# Tasks & Notifications
Source: https://docs.getasset.com/bookkeeping/tasks



## **Tasks**

Tasks are the specific actions that a Business Owner must complete so their bookkeeping can be
finalized. Asset automatically generates Tasks whenever new Transactions are imported from the bank.
The following types of Tasks are currently supported, with more to be added in the future:

* **Transaction Categorization**: Created when input is needed from the Business Owner
  to properly categorize a Transaction.

* **Review Personal Transactions**: If a Business uses [Personal Accounts](/bookkeeping/personaltransactions),
  a Task is created so the Business Owner can review and mark which Transactions should be treated as Business-related.

* **Reconnect Bank Account**: When using Plaid as the source for bank Transactions, the bank may
  sometimes disconnect from Plaid. This stops new Transactions from syncing, so the Business Owner
  must reconnect the bank account using the Plaid Reconnect Flow.

* **Receipt Request**: Created when a Transaction requires a receipt to verify or complete the
  bookkeeping for that Transaction.

* **Statement**: Generated when a bank statement is needed for Manual External Accounts or to reconcile
  Transactions or verify Balances for Plaid-connected External Accounts.

* **Other Document**: Used when any other type of document is required to complete the bookkeeping
  or address a specific request.

* **Other**: Covers more general Tasks. Asset will enhance the Task types as they become required

#### **Listing Pending Tasks**

To view Tasks for a Business, use the [Get all Tasks for a Business](/api-reference/request/get-all-tasks-for-a-business) endpoint.\
By default, this endpoint returns only Pending Tasks and provides the count for each category.
To view Completed Tasks, pass the `status` query parameter with the value `completed`.

## **Notifications**

Tasks are generated in real time as new Transactions are imported. Since multiple Tasks may be created at once,
users are not notified every time a Task is generated. Instead, Webhook Notifications are sent once or twice a week,
summarizing any Pending Tasks that need attention.


# Core Concepts
Source: https://docs.getasset.com/getstarted/CoreConcepts



### **Overview**

The Asset API is infrastructure to build accounting software. It enables a company to easily offer accounting services to its customers. This page outlines key accounting terms and Asset specific definitions which will help you utilize our APIs.

## **Tenants - Your Platform**

A Tenant is Asset’s representation of our Customers: the company that is providing accounting features to their SMB customers. Tenants integrate with the Asset API and  manage their [Businesses](#businesses-your-smb-customers).

## **Businesses - Your SMB Customers**

A Business represents a business entity (SMB) in Asset. Each Business has its own profile, defining financial details, legal information, and authorized users. A Business has its own set of financial records within Asset (i.e. their “books”).

## **Ledgers**

Ledgers represent the financial activity and value within a Business. Ledgers have one of five types:

* **Revenues** – Money earned.
* **Expenses** – Money spent.
* **Assets** – Resources owned by the Business.
* **Liabilities** – Debts or financial obligations owed by the Business.
* **Equity** – The residual value in the business liabilities are deducted from assets.

Each Business has a **Chart of Accounts**, a unique and complete set of Ledgers used to track financial activity. While no two Businesses are identical, standard accounting principles influence how accounts are structured. Asset provides a default Chart of Accounts to streamline setup, which can be customized as needed.

Asset supports **ledger subtypes** to further classify accounts based on standard accounting practices. For example, assets can be divided into current assets (e.g., cash, accounts receivable) and non-current assets (e.g., real estate, long-term investments).

## **Journal Entry**

A Journal Entry records the movement of value between **Ledgers**, consisting of two or more **Lines**. Each Journal Entry must be balanced, meaning total **debits** must equal total **credits**.

Journal Entries fall into two categories:

* **Cash Entries**: Transactions where money changes hands.
* **Accrual Entries**: Transactions where value is recorded before cash moves. Examples include:
  * **Accounts Receivable**: A sale is recorded when an invoice is issued, even if payment hasn’t been received.
  * **Depreciation**: A business records the decline in an asset’s value over time, even though no money is exchanged.

Asset supports both **cash and accrual accounting**, providing flexibility in how financial activity is tracked and reported.

Each Line in the Journal Entry has:

* **An amount** – The value being recorded.
* **Direction** – Debit (value added to a ledger) or Credit (value removed from a ledger).
* **Ledger** – The specific account affected by the transaction.
* **Date** - The date the transaction occurs

#### **What are Debits and Credits?**

* **Debits** typically represent money going into something valuable (e.g., increasing cash, buying equipment, paying rent).
* **Credits** typically represent money going out or obligations increasing (e.g., decreasing cash, taking on a loan, earning revenue)

## **Transactions**

A Transaction represents a real-world financial activity, such as a payment, deposit, or expense, that occurs within a Business. Transactions contain key financial details, including amount, date, description, and account information. They may also include additional metadata, such as merchant details or payment methods, when available.

Transactions in Asset are imported via the API or through native data integrations with external financial systems. Each Transaction is categorized and recorded in the ledger for accurate financial tracking.

#### **Key Transaction Fields**

* **Amount** – The monetary value of the transaction.
* **Date** – The date when the transaction occurred.
* **Description** – A brief summary of the transaction.
* **Account** – The source or destination ledger for the transaction.

#### **Transaction Integrity in Asset**

Once a Transaction is posted in Asset, **it cannot be directly edited** by a Tenant. This ensures data integrity and auditability in the accounting system. Any necessary adjustments must be made through **adjusting Journal Entries**, preserving a clear financial record. If a Transaction is updated or deleted by the source (e.g. Plaid) the corresponding Journal Entry will be deleted and a new one created.

## **External Accounts**

In Asset, External Accounts are the origin of Transaction data, representing external financial sources where actual business activity occurs. The most common example is **bank accounts**, but other sources include payroll providers (e.g., Gusto) and merchant processors (e.g., Square). These External Accounts act as the entry point for financial transactions that flow into Asset

#### **Accounts Attributes in Asset**

| Attribute | API Request Field | Description |
| :- | :- | :- |
| Institution Name | institution\_name | The name of the financial institution (e.g., "Wells Fargo") |
| Account Type | account\_type | Defines the type of financial account. Allowed values: *bank\_account*, *credit\_card, prepaid\_card, payments, payroll, loan, accounts\_receivable, accounts\_payable* |
| External Account Balance | external\_account\_balance | The External Account balance as provided by the data source at the end of the reporting period. |
| Ledger Balance | ledger\_balance | The running balance after each Transaction is processed in Asset |
| Account Status | account\_status | Indicates whether the account is actively tracked. Accepted values: *Active, Inactive*. |
| (Optional) Inactive Date | inactive\_date | The date a External Account was marked as inactive. Transactions will not be imported after this date |

<Note> Questions? Reach out via our [Contact form](https://www.getasset.com/get-in-touch). </Note>


# Quickstart
Source: https://docs.getasset.com/getstarted/quickstart



## **Getting Started**

To begin using the Asset API, follow these steps:

2. **Obtain API Tokens**: After registration, retrieve your API Tokens from the Asset Tenant dashboard.
3. **Sign Up**: [Register for an Asset Tenant Account](https://www.getasset.com/get-in-touch) to obtain your API credentials.
4. **Authentication**: Authenticate your application using the provided credentials.

## **Making Your First API Call**

Once authenticated, you can start making API requests. For instance, to [Create your first Business](/api-reference/business/create-a-business):

**Request:**

```bash theme={null}
curl --request POST \
--url https://api.sandbox.getasset.com/v0/business \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '{
  "name": "Roofing Pros",
  "entity_type": "c-corp",
  "entries_start": "2023-11-07T05:31:56Z",
  "fiscal_year": "2024-12-31T11:59:59Z",
  "status": "active"
}' 
```

**Response:**

```bash theme={null}
{
  "tenant_id": "b_123456",
  "name": "Roofing Pros",
  "entity_type": "c-corp",
  "entries_start": "2023-11-07T05:31:56Z",
  "fiscal_year": "2024-12-31T11:59:59Z",
  "status": "active",
  "id": "b_123456",
}
```

## **Next Steps**

<CardGroup>
  <Card icon="abacus" href="/getstarted/CoreConcepts" title="Core Concepts">
    Learn key accounting terms and Asset specific definitions which will help you utilize our APIs
  </Card>

  <Card icon="laptop-code" href="/api-reference" title="API Reference">
    Explore our detailed API documentation
  </Card>

  <Card icon="lock-open" href="/apioverview/authentication" title="Authentication">
    Learn how our Authentication works
  </Card>

  <Card icon="buildings" href="/bookkeeping/businesses" title="Managing Businesses">
    Learn how to create your first Business in Asset
  </Card>
</CardGroup>


# API Import
Source: https://docs.getasset.com/importingdata/apiimport



Use Asset’s [Create Transactions](/api-reference/transaction/create-transactions) endpoint to quickly add one or more new [Transactions](/getstarted/CoreConcepts#transactions) for a [Business](/getstarted/CoreConcepts#businesses-your-smb-customers). This is especially useful when you need to capture Transactions that aren’t automatically retrieved via [Plaid](/importingdata/plaid), ensuring a complete record of money flowing in and out of accounts on a daily basis.

**How to Import Transactions**

**Call the [Create Transactions](/api-reference/transaction/create-transactions) Endpoint:** Make a POST request to the Create Transactions endpoint, including an array of Transaction objects and the Business ID. Each Transaction object should have:

* Description
* Transaction datetime (UTC ISO-8601)
* Amount
* transaction\_id
* linked\_account\_id
* Metadata (optional)

**Automatic Journal Entries and [Categorization](/bookkeeping/categorization)**\
After submission, Asset automatically:

1. Converts each Transaction into a [Journal Entry](/getstarted/CoreConcepts#journal-entry).
2. Passes the Journal Entry through our Categorization Pipeline.

<Note> Questions? Reach out via our [Contact form](https://www.getasset.com/get-in-touch). </Note>


# Merchants
Source: https://docs.getasset.com/importingdata/merchants



Many small [Businesses](/getstarted/CoreConcepts#businesses-your-smb-customers) rely on merchant processors like Square or Stripe to collect payments, which generate critical [Transaction](/getstarted/CoreConcepts#transactions) data for bookkeeping. Soon, you’ll have the ability to sync those Transactions directly into Asset, making it easier to keep your records accurate. By centralizing revenue streams in one place, you reduce manual input and speed up reconciliation for your SMBs.

<Note>
  We would love to gather your feedback on this feature. If you’re interested in chatting with us, please reach out via our [Contact form](https://www.getasset.com/get-in-touch).
</Note>


# Payroll
Source: https://docs.getasset.com/importingdata/payroll



Payroll activity is a key part of day-to-day operations for many small [Businesses](/getstarted/CoreConcepts#businesses-your-smb-customers), generating crucial Transaction data through providers such as Gusto or ADP. Soon, you’ll have the ability to sync those Transactions directly into Asset, making your bookkeeping process more efficient and reducing manual work.

<Note>
  We would love to gather your feedback on this feature. If you’re interested in chatting with us, please reach out via our [Contact form](https://www.getasset.com/get-in-touch).
</Note>


# Bank integrations
Source: https://docs.getasset.com/importingdata/plaid



Asset integrates with Plaid to securely access banking data from over 11,000 U.S. financial institutions. Leveraging Plaid is crucial for automating the collection of [Transaction](/getstarted/CoreConcepts#transactions) data from your [Businesses'](/getstarted/CoreConcepts#businesses-your-smb-customers). Plaid connections allow you to pull up to 24 months of historical Transactions and keep new Transactions synced daily.

There are two ways to connect with Plaid in Asset:

1. Use Asset’s Plaid Connection
2. Use your own Plaid Connection

### How to use Asset’s Plaid Integration

If your platform doesn’t already have a Plaid integration, Asset makes it simple to connect to your Businesses' [bank accounts and credit cards](/getstarted/CoreConcepts#accounts). We take care of all the technical details for you.

1. **Add the Plaid Link Component**\
   Insert Asset’s Plaid Link component into your product. This component will securely connect to your Businesses’ accounts and guide them through granting read-only access to their financial data.
2. **Begin Importing Data**\
   After a Business grants access, Asset automatically ingests the Transaction data from Plaid and converts it into [Journal Entries](/getstarted/CoreConcepts#journal-entry).

### How to use your own Plaid Integration

If your platform already has a Plaid integration, you can grant Asset access to your Businesses' Transaction data via a [Plaid Processor Token](https://plaid.com/docs/api/processors/). Here are the steps to do this:

1. **Obtain a Processor Token from Plaid**\
   Generate a Processor Token associated with the bank accounts you wish to share with Asset. Use [Processor/Token/Create](https://plaid.com/docs/api/processors/#processortokencreate) from Plaid’s APIs.
2. **Provide the Token to Asset**\
   Send the Processor Token to Asset through the secure API. This enables Asset to link your existing Plaid integration to its accounting tools.
3. **Confirm Connection**\
   Once the token is validated, Asset will begin ingesting Transaction data from your Businesses’ connections. Transactions are then automatically transformed into Journal Entries.

<Note>
  Questions? Reach out via our [Contact form](https://www.getasset.com/get-in-touch).
</Note>


# QuickBooks import
Source: https://docs.getasset.com/importingdata/quickbooks



The QuickBooks import feature allows users to migrate their financial data from their QuickBooks
account to Asset, starting from 2 full fiscal years before the Business' entries start date.

### How to use Asset’s QuickBooks Integration

Within Asset's platform, click `Add Account` in the Business' account page,
and select `Connect QuickBooks Online`. You will be redirected to QuickBooks Online login page
to authorize Asset to access your account. Follow the instructions on the wizard until the
account is connected. **Note that it may take up to 20 minutes to complete the import.**

### What gets imported

* The QuickBooks chart of accounts are imported and matched to Asset's standard ledgers.
* Unmatched QuickBooks accounts are created as new Ledgers in Asset.
* Unused QuickBooks accounts are not imported.
* Accounts balances are also imported and consolidated at the end of the 2 full fiscal years.
* All accounting entries from 2 full fiscal years to the business' entries start date.

### What happens after data is imported

Asset will ensure that bank accounts from QuickBooks are properly matched to connected accounts
in Asset. You can also perform this action within Asset from the chart of accounts page, by
selecting `Move Line Entries` for a Ledger, and following the instructions in the
wizard.

### How to delete a Business' QuickBooks data

In case a user wants to remove their QuickBooks data, they can go to the Accounts page
in the Asset platform and remove the connection. This will remove all of the imported
data including accounting data, ledgers that are unused and the balances that where
created during the import.

<Note>
  Questions? Reach out via our [Contact
  form](https://www.getasset.com/get-in-touch).
</Note>


# Asset MCP server overview
Source: https://docs.getasset.com/mcp/overview

Connect AI assistants to Asset's MCP server to query accounting data, financial reports, and ledger activity using natural language instead of API calls.

Asset exposes a [Model Context Protocol (MCP)](https://modelcontextprotocol.io) server that lets AI assistants query financial data from your accounting platform—transactions, reports, ledger activity, and more—using natural language instead of writing API calls by hand.

## **Server endpoint**

| Environment | URL |
| :- | :- |
| Production | `https://api.getasset.com/mcp` |
| Sandbox | `https://api.sandbox.getasset.com/mcp` |

The server uses remote HTTP transport. Connect your MCP client to the URL for the environment you are working in.

## **Authentication**

The MCP server uses the same OAuth 2.0 flow as the Asset API. Every request must include a valid access token in the `Authorization` header.

Tokens used with MCP must be scoped to the MCP resource using the `resource` parameter when you request the token. This sets the JWT `aud` (audience) claim so the token is only valid for the MCP server.

<Warning>
  Use a dedicated token with `resource=https://api.getasset.com/mcp` (or the
  sandbox equivalent). Do not reuse API tokens that were issued for the REST API
  without the MCP resource indicator.
</Warning>

## **Getting an access token**

You need OAuth client credentials from the Asset Dashboard. See [API Authentication](/apioverview/authentication) for setup details.

Request a token scoped to the MCP resource:

```bash theme={null}
curl --request POST \
  --url https://api.getasset.com/v0/auth/token \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data 'client_id=<string>' \
  --data 'client_secret=<string>' \
  --data 'resource=https://api.getasset.com/mcp'
```

For sandbox, use `https://api.sandbox.getasset.com/v0/auth/token` and `resource=https://api.sandbox.getasset.com/mcp`.

A successful response returns:

```json theme={null}
{
  "access_token": "your-access-token",
  "token_type": "Bearer",
  "expires_in": 3600
}
```

### Scoping to a business

To limit the token to a single business, pass `business_id` in the token request—the same as with REST API tokens:

```bash theme={null}
curl --request POST \
  --url https://api.getasset.com/v0/auth/token \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data 'client_id=<string>' \
  --data 'client_secret=<string>' \
  --data 'resource=https://api.getasset.com/mcp' \
  --data 'business_id=biz_GA6EG2qFxA97NZHtxeLPUy'
```

Access tokens expire after a set time. Request a new token using the same flow when it expires.

## **Connecting from an AI client**

Configure a remote MCP server in your client with the server URL and the bearer token from the previous step.

### Cursor

Add the server to `~/.cursor/mcp.json` (global) or `.cursor/mcp.json` (project-scoped):

```json theme={null}
{
  "mcpServers": {
    "asset": {
      "url": "https://api.getasset.com/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_ACCESS_TOKEN"
      }
    }
  }
}
```

Open **Settings → Tools & MCP** to confirm the server is connected and its tools are available.

### Claude Desktop

Add the server to your Claude Desktop MCP config (`claude_desktop_config.json`):

```json theme={null}
{
  "mcpServers": {
    "asset": {
      "url": "https://api.getasset.com/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_ACCESS_TOKEN"
      }
    }
  }
}
```

Restart Claude Desktop after saving the config.

<Note>
  Token values in config files are sensitive. Prefer environment variable
  substitution where your client supports it, and avoid committing tokens to
  version control.
</Note>

## **What you can do**

Once connected, your AI assistant can use MCP tools exposed by Asset to work with your accounting data—for example:

* Pull financial reports such as profit and loss or balance sheet
* Answer questions about a business's books in context

<Warning>
  Credentials and tokens should always be kept secure—never share them outside
  your organization and exercise caution when sharing internally.
</Warning>

<Note>
  Questions? Reach out via our [Contact
  form](https://www.getasset.com/get-in-touch).
</Note>


# get_aged_payables
Source: https://docs.getasset.com/mcp/tools/get-aged-payables

MCP tool that returns unpaid vendor bills grouped into aging buckets to track accounts payable, overdue invoices, and upcoming payment obligations.

Returns a list of unpaid vendor bills grouped by aging buckets (current, 1–30 days, 31–60 days, 61–90 days, and 90+ days past due). Use this tool to answer questions about what the business owes to vendors, which bills are overdue, and upcoming payment obligations.

**Example prompts this tool can answer**

* "What bills are currently unpaid?"
* "How much does the business owe vendors that's more than 30 days overdue?"
* "Show me all open bills for a specific vendor."
* "What's the total accounts payable balance?"


# get_aged_receivables
Source: https://docs.getasset.com/mcp/tools/get-aged-receivables

MCP tool that returns unpaid customer invoices grouped into aging buckets to track accounts receivable, overdue balances, and collection priorities.

Returns a list of unpaid customer invoices grouped by aging buckets (current, 1–30 days, 31–60 days, 61–90 days, and 90+ days past due). Use this tool to answer questions about what customers owe, which invoices are overdue, and how long receivables have been outstanding.

**Example prompts this tool can answer**

* "What invoices are currently outstanding?"
* "How much do customers owe that's more than 60 days overdue?"
* "Which customers have the oldest unpaid balances?"
* "What's the total accounts receivable balance?"


# get_balance_sheet
Source: https://docs.getasset.com/mcp/tools/get-balance-sheet

MCP tool that returns a point-in-time balance sheet with assets, liabilities, and equity to assess net worth, debt levels, and financial position.

Returns a Balance Sheet (statement of financial position) for a business as of a specific date, showing assets, liabilities, and equity. Unlike the P\&L or cash flow reports, the balance sheet is a point-in-time snapshot rather than a period-based report. Use this tool to answer questions about net worth, debt levels, or overall financial health.

**Example prompts this tool can answer**

* "What are the total assets of the business?"
* "What does the balance sheet look like as of year-end?"
* "How much does the business owe in total liabilities?"
* "What is the owner's equity?"


# get_cash_flow
Source: https://docs.getasset.com/mcp/tools/get-cash-flow

MCP tool that returns a cash flow statement covering operating, investing, and financing activities to analyze liquidity and cash movement over a period.

Returns a Cash Flow statement for a business, showing cash movement across operating, investing, and financing activities over a specified period. Use this tool to answer questions about liquidity, cash position, or how cash is being generated and spent.

**Example prompts this tool can answer**

* "How much cash did the business generate last year?"
* "What does the cash flow look like for this quarter?"
* "Is the business cash flow positive or negative?"
* "Show me operating cash flow broken down by month."


# get_customer_credit_balance
Source: https://docs.getasset.com/mcp/tools/get-customer-credit-balance

MCP tool that lists customers with unapplied credit memo balances so you can track outstanding customer credits before issuing new invoices or refunds.

Returns a list of customers who have unapplied credit memo balances — amounts the business owes back to customers that haven't yet been applied to an invoice. Use this tool to answer questions about outstanding customer credits or to check whether a specific customer has credit available before creating an invoice.

**Example prompts this tool can answer**

* "Which customers have outstanding credits?"
* "How much total credit does the business owe to customers?"


# get_general_ledger
Source: https://docs.getasset.com/mcp/tools/get-general-ledger

MCP tool that returns every journal entry across all accounts for a date range, giving a complete view of financial activity for tracing transactions.

Returns the full general ledger for a business — every journal entry across all accounts for the specified period. This is the most comprehensive transaction view available. Use this tool when you need a complete picture of all financial activity, want to trace a specific transaction, or need data that spans multiple accounts at once.

**Example prompts this tool can answer**

* "Show me all financial activity for the month of March."
* "Give me a complete record of every transaction this year."
* "What journal entries were recorded last week?"


# get_ledger_statement
Source: https://docs.getasset.com/mcp/tools/get-ledger-statement

MCP tool that returns transaction history and a running balance for a single ledger account, useful for drilling into bank, expense, or revenue activity.

Returns a detailed statement for a single ledger account (chart of accounts entry), including every transaction that hit the account over the requested period along with a running balance. Use this tool when you need to drill into the activity of a specific account — for example, a bank account, a specific expense category, or a revenue line.

**Example prompts this tool can answer**

* "What activity hit the office supplies expense account this year?"
* "What's the running balance of accounts receivable over the past 6 months?"


# get_profit_and_loss
Source: https://docs.getasset.com/mcp/tools/get-profit-and-loss

MCP tool that returns a profit and loss income statement with revenue, COGS, expenses, and net income to analyze profitability and spending trends.

Returns a Profit & Loss (income statement) for a business, showing revenue, cost of goods sold, gross profit, operating expenses, and net income over a specified period. Use this tool to answer questions about business profitability, income trends, or expense breakdowns.

**Example prompts this tool can answer**

* "How profitable was the business last quarter?"
* "What were total expenses in 2025?"
* "Show me revenue broken down by month for this year."
* "What's the net income for Q1 vs Q2?"