Integration APIs #

This document provides basic information about the available integrations in Tofu and the APIs required to activate them.

Overview #

Tofu supports two main types of integrations:

Accounting Integrations - Connect to accounting software for invoice synchronization
Trigger Integrations - Connect to document storage systems for automated document processing

At a minimum integrations of any type require two steps to fully integrate.

OAuth Integration Flow
Integration Setup

Tofu AccountClass Types #

Tofu uses a unified AccountClass enum to categorize all accounting accounts across different providers:

Asset: Assets (current, fixed, inventory, etc.)
Liability: Liabilities (current, non-current, payables, etc.)
Equity: Equity accounts (share capital, retained earnings, etc.)
Revenue: Revenue/Income accounts (sales, other income, etc.)
Expense: Expense accounts (costs, overheads, depreciation, etc.)
Bank: Bank accounts
CreditCard: Credit card accounts

Available Integrations #

Xero (Accounting Integration) #

Xero is a cloud-based accounting software that allows you to sync invoice data and manage your financial records.

Provider Code: XERO

APIs Required for Activation #

Get OAuth Authorization URL
```
POST /api/v1/integrations/oauth/authorize
```
- Parameters:
  - entity_id (required): UUID of the entity
  - provider: XERO
  - redirect_url (required): URL to redirect after OAuth flow
- Response: Returns authorization URL for Xero OAuth flow
Fetch Available Organizations
```
GET /api/v1/integrations/{integrationId}/accounting-organizations
```
- Parameters:
  - integrationId (required): UUID of the integration
  - entity_id (required): UUID of the entity
- Response: List of available Xero organizations/tenants

Setup Integration

PUT /api/v1/integrations/{integrationId}

Parameters:
- integrationId (required): UUID of the integration
- entity_id (required): UUID of the entity

Request Body:

{
  "status": "PENDING",
  "public_metadata": {
    "provider": "XERO",
    "organization_id": "your-xero-org-id",
    "pays_tax": true
  }
}

Additional Xero APIs #

Chart of Accounts: GET /api/v1/integrations/{integrationId}/accounting-accounts
Contacts/Vendors: GET /api/v1/integrations/{integrationId}/accounting-contacts
Tax Rates: GET /api/v1/integrations/{integrationId}/accounting-tax-rates
Currencies: GET /api/v1/integrations/{integrationId}/accounting-currencies

Xero Account Type Mapping #

The following table shows how Xero account types are mapped to Tofu’s internal AccountClass:

Xero Account Type	Description	Tofu AccountClass
BANK	Bank account	Bank
CURRENT	Current Asset account	Asset
CURRLIAB	Current Liability account	Liability
DEPRECIATN	Depreciation account	Expense
DIRECTCOSTS	Direct Costs account	Expense
EQUITY	Equity account	Equity
EXPENSE	Expense account	Expense
FIXED	Fixed Asset account	Asset
INVENTORY	Inventory Asset account	Asset
LIABILITY	Liability account	Liability
NONCURRENT	Non-current Asset account	Asset
OTHERINCOME	Other Income account	Revenue
OVERHEADS	Overhead account	Expense
PREPAYMENT	Prepayment account	Asset
REVENUE	Revenue account	Revenue
SALES	Sale account	Revenue
TERMLIAB	Non-current Liability account	Liability

Note:

Tofu’s AccountClass also includes CreditCard, but Xero doesn’t have a specific credit card account type
Unknown account types default to Expense with a warning logged

Account Type Filtering #

The chart of accounts API supports filtering by account type:

GET /api/v1/integrations/{integrationId}/accounting-accounts?account_types=BANK,EXPENSE

Parameters:
- account_types: Comma-separated list of AccountClass values to filter
- Valid values: ASSET, LIABILITY, EQUITY, REVENUE, EXPENSE, BANK, CREDIT_CARD
- If not provided, returns all account types

QuickBooks Online (Accounting Integration) #

QuickBooks Online is a cloud-based accounting software that allows you to sync invoice data and manage your financial records.

Provider Code: QBO

QuickBooks Account Type Mapping #

QuickBooks Online uses the AccountTypeEnum to categorize accounts:

QBO AccountType	Description	Tofu AccountClass
Bank	Bank accounts	Bank
AccountsReceivable	Accounts receivable	-
OtherCurrentAsset	Other current assets	Asset
FixedAsset	Fixed assets	Asset
OtherAsset	Other assets	Asset
AccountsPayable	Accounts payable	-
CreditCard	Credit card accounts	CreditCard
OtherCurrentLiability	Other current liabilities	Liability
LongTermLiability	Long-term liabilities	Liability
Equity	Equity accounts	Equity
Income	Income/Revenue accounts	Revenue
OtherIncome	Other income accounts	Revenue
CostofGoodsSold	Cost of goods sold	Expense
Expense	Expense accounts	Expense
OtherExpense	Other expense accounts	Expense
NonPosting	Non-posting accounts (not supported)	-

Note:

QBO doesn’t support the “Non-Posting” Account type for API operations
The API returns the original AccountType value in the class field
Filtering uses SQL-like syntax: AccountType = 'Bank'

SharePoint (Trigger Integration) #

SharePoint integration allows you to monitor specific SharePoint sites and document libraries for new documents.

Provider Code: SHAREPOINT

APIs Required for Activation #

Get OAuth Authorization URL
```
POST /api/v1/integrations/oauth/authorize
```
- Parameters:
  - entity_id (required): UUID of the entity
  - provider: SHAREPOINT
  - redirect_url (required): URL to redirect after OAuth flow
- Response: Returns authorization URL for SharePoint OAuth flow
Fetch Available Sources
```
GET /api/v1/integrations/{integrationId}/trigger-sources
```
- Parameters:
  - integrationId (required): UUID of the integration
  - entity_id (required): UUID of the entity
- Response: List of available SharePoint sites
Fetch Sub-sources (Document Libraries)
```
GET /api/v1/integrations/{integrationId}/trigger-sources/{sourceId}/sub-sources
```
- Parameters:
  - integrationId (required): UUID of the integration
  - sourceId (required): SharePoint site ID
  - entity_id (required): UUID of the entity
- Response: List of document libraries in the specified site

Setup Integration

PUT /api/v1/integrations/{integrationId}

Parameters:
- integrationId (required): UUID of the integration
- entity_id (required): UUID of the entity

Request Body:

{
  "status": "PENDING",
  "public_metadata": {
    "provider": "SHAREPOINT",
    "source_id": "sharepoint-site-id",
    "sub_source_id": "document-library-id",
    "directories": ["path/to/watch", "another/path"]
  }
}

Google Drive (Trigger Integration) #

Google Drive integration allows you to monitor specific Google Drive folders for new documents.

Provider Code: GOOGLE_DRIVE

APIs Required for Activation #

Get OAuth Authorization URL
```
POST /api/v1/integrations/oauth/authorize
```
- Parameters:
  - entity_id (required): UUID of the entity
  - provider: GOOGLE_DRIVE
  - redirect_url (required): URL to redirect after OAuth flow
- Response: Returns authorization URL for Google Drive OAuth flow
Fetch Available Sources
```
GET /api/v1/integrations/{integrationId}/trigger-sources
```
- Parameters:
  - integrationId (required): UUID of the integration
  - entity_id (required): UUID of the entity
- Response: List of available Google Drive folders
Fetch Sub-sources (Sub-folders)
```
GET /api/v1/integrations/{integrationId}/trigger-sources/{sourceId}/sub-sources
```
- Parameters:
  - integrationId (required): UUID of the integration
  - sourceId (required): Google Drive folder ID
  - entity_id (required): UUID of the entity
- Response: List of sub-folders in the specified folder

Setup Integration

PUT /api/v1/integrations/{integrationId}

Parameters:
- integrationId (required): UUID of the integration
- entity_id (required): UUID of the entity

Request Body:

{
  "status": "PENDING",
  "public_metadata": {
    "provider": "GOOGLE_DRIVE",
    "source_id": "google-drive-folder-id",
    "sub_source_id": "sub-folder-id",
    "directories": ["path/to/watch", "another/path"]
  }
}

Complete API Documentation #

For detailed API specifications, request/response schemas, and additional endpoints, refer to the OpenAPI documentation.