# Tyms Developer API

## Docs

- [Introduction](https://developer.usetyms.com/introduction.md): Tyms is the AI-Native Accounting Platform — integrate books, banking, and reports over a single REST API.
- [Quickstart](https://developer.usetyms.com/quickstart.md): Validate your API key and call the Tyms Developer API in under five minutes.
- [Core concepts](https://developer.usetyms.com/concepts.md): How the Tyms Developer API models businesses, AI processing, banking, and financial reporting.
- [Authentication](https://developer.usetyms.com/authentication.md): Business API keys, partner keys, headers, and Developer API access requirements.
- [OAuth 2.0](https://developer.usetyms.com/oauth.md): Let Tyms users authorize your integration app to access their business data without sharing secret keys.
- [Partners and Register business](https://developer.usetyms.com/partners-program.md): How referral partners onboard businesses, cover Plus and AI costs from partner credit, and use the partner API surface.
- [AI Prompt Guidelines](https://developer.usetyms.com/guides/ai-prompts.md): Best practices for creating records with AI prompts
- [Error Handling](https://developer.usetyms.com/guides/error-handling.md): Understand API errors and how to handle them
- [Integration Examples](https://developer.usetyms.com/guides/integrations.md): Integrate with Zapier, Make, and other platforms
- [API overview](https://developer.usetyms.com/api-reference/overview.md): Base URL, conventions, errors, rate limits, and identifier rules for the Tyms Developer API.
- [Attachments](https://developer.usetyms.com/api-reference/attachments.md): The attachments array shape for AI create endpoints and bank transaction upload.
- [Validate business](https://developer.usetyms.com/api-reference/authentication/validate-business.md): Validate a **business** `tyms_sk_...` key and return business profile fields.
- [Get authorization URL](https://developer.usetyms.com/api-reference/oauth/get-authorization-url.md): Start the OAuth flow. Returns an HTTPS URL to redirect the user for Tyms sign-in and business selection.
- [Exchange authorization code](https://developer.usetyms.com/api-reference/oauth/exchange-authorization-code.md): Exchange a single-use authorization code for access and refresh tokens. Requires your app **secret key** in `X-API-Key`.
- [Refresh access token](https://developer.usetyms.com/api-reference/oauth/refresh-access-token.md): Obtain a new access token using a refresh token. Requires your app **secret key** in `X-API-Key`.
- [Revoke access](https://developer.usetyms.com/api-reference/oauth/revoke-access.md): Revoke an access or refresh token when a user disconnects your app. Requires your app **secret key** in `X-API-Key`.
- [Validate OAuth session](https://developer.usetyms.com/api-reference/oauth/validate-oauth-session.md): Validate the current OAuth access token and return authorized business profile fields.
- [List accounts](https://developer.usetyms.com/api-reference/chart-of-accounts/list-accounts.md)
- [Get account types](https://developer.usetyms.com/api-reference/chart-of-accounts/get-account-types.md): Returns allowed account `type` and `subtype` values for `POST /create/chart_of_account`. Bank subtype is for reference only — bank accounts are created through banking.
- [Create account](https://developer.usetyms.com/api-reference/chart-of-accounts/create-account.md)
- [Create account (AI)](https://developer.usetyms.com/api-reference/chart-of-accounts/create-account-ai.md)
- [Get account](https://developer.usetyms.com/api-reference/chart-of-accounts/get-account.md)
- [Update account](https://developer.usetyms.com/api-reference/chart-of-accounts/update-account.md)
- [Update account (partial)](https://developer.usetyms.com/api-reference/chart-of-accounts/update-account-partial.md)
- [Delete account](https://developer.usetyms.com/api-reference/chart-of-accounts/delete-account.md)
- [List invoices](https://developer.usetyms.com/api-reference/invoices/list-invoices.md)
- [Create invoice](https://developer.usetyms.com/api-reference/invoices/create-invoice.md)
- [Create invoice (AI)](https://developer.usetyms.com/api-reference/invoices/create-invoice-ai.md)
- [Get invoice](https://developer.usetyms.com/api-reference/invoices/get-invoice.md)
- [Update invoice](https://developer.usetyms.com/api-reference/invoices/update-invoice.md)
- [Update invoice (partial)](https://developer.usetyms.com/api-reference/invoices/update-invoice-partial.md)
- [Delete invoice](https://developer.usetyms.com/api-reference/invoices/delete-invoice.md)
- [Update invoice payments](https://developer.usetyms.com/api-reference/invoices/update-invoice-payments.md)
- [List bills](https://developer.usetyms.com/api-reference/bills/list-bills.md)
- [Create bill](https://developer.usetyms.com/api-reference/bills/create-bill.md)
- [Create bill (AI)](https://developer.usetyms.com/api-reference/bills/create-bill-ai.md)
- [Get bill](https://developer.usetyms.com/api-reference/bills/get-bill.md)
- [Update bill](https://developer.usetyms.com/api-reference/bills/update-bill.md)
- [Update bill (partial)](https://developer.usetyms.com/api-reference/bills/update-bill-partial.md)
- [Delete bill](https://developer.usetyms.com/api-reference/bills/delete-bill.md)
- [Update bill payments](https://developer.usetyms.com/api-reference/bills/update-bill-payments.md)
- [List expenses](https://developer.usetyms.com/api-reference/expenses/list-expenses.md)
- [Create expense](https://developer.usetyms.com/api-reference/expenses/create-expense.md)
- [Create expense (AI)](https://developer.usetyms.com/api-reference/expenses/create-expense-ai.md)
- [Get expense](https://developer.usetyms.com/api-reference/expenses/get-expense.md)
- [Update expense](https://developer.usetyms.com/api-reference/expenses/update-expense.md)
- [Update expense (partial)](https://developer.usetyms.com/api-reference/expenses/update-expense-partial.md)
- [Delete expense](https://developer.usetyms.com/api-reference/expenses/delete-expense.md)
- [List income](https://developer.usetyms.com/api-reference/income/list-income.md)
- [Create income](https://developer.usetyms.com/api-reference/income/create-income.md)
- [Create income (AI)](https://developer.usetyms.com/api-reference/income/create-income-ai.md)
- [Get income](https://developer.usetyms.com/api-reference/income/get-income.md)
- [Update income](https://developer.usetyms.com/api-reference/income/update-income.md)
- [Update income (partial)](https://developer.usetyms.com/api-reference/income/update-income-partial.md)
- [Delete income](https://developer.usetyms.com/api-reference/income/delete-income.md)
- [List journals](https://developer.usetyms.com/api-reference/journals/list-journals.md)
- [Create journal](https://developer.usetyms.com/api-reference/journals/create-journal.md)
- [Create journal (AI)](https://developer.usetyms.com/api-reference/journals/create-journal-ai.md)
- [Get journal](https://developer.usetyms.com/api-reference/journals/get-journal.md)
- [Update journal](https://developer.usetyms.com/api-reference/journals/update-journal.md)
- [Update journal (partial)](https://developer.usetyms.com/api-reference/journals/update-journal-partial.md)
- [Delete journal](https://developer.usetyms.com/api-reference/journals/delete-journal.md)
- [List contacts](https://developer.usetyms.com/api-reference/contacts/list-contacts.md)
- [Create contact](https://developer.usetyms.com/api-reference/contacts/create-contact.md)
- [Create contact (AI)](https://developer.usetyms.com/api-reference/contacts/create-contact-ai.md)
- [Get contact](https://developer.usetyms.com/api-reference/contacts/get-contact.md)
- [Update contact](https://developer.usetyms.com/api-reference/contacts/update-contact.md)
- [Update contact (partial)](https://developer.usetyms.com/api-reference/contacts/update-contact-partial.md)
- [Delete contact](https://developer.usetyms.com/api-reference/contacts/delete-contact.md)
- [List banks](https://developer.usetyms.com/api-reference/banks/list-banks.md)
- [Create bank account](https://developer.usetyms.com/api-reference/banks/create-bank-account.md): Create a new bank or cash account with an opening balance. The `bank_name` becomes the display name used as `payment_category` on transactions. `nuban`, `account_name`, `bank_name`, `opening_balance`, and `opening_balance_date` are required.
- [Get bank](https://developer.usetyms.com/api-reference/banks/get-bank.md)
- [Delete bank account](https://developer.usetyms.com/api-reference/banks/delete-bank-account.md): Delete a bank account. Fails if the bank has non-opening-balance ledger activity or an uncleared opening balance remains.
- [List bank transactions](https://developer.usetyms.com/api-reference/bank-transactions/list-bank-transactions.md)
- [Create bank transaction](https://developer.usetyms.com/api-reference/bank-transactions/create-bank-transaction.md): Manual single transaction. Requires an existing bank on the business.
- [Create bank transactions (AI)](https://developer.usetyms.com/api-reference/bank-transactions/create-bank-transactions-ai.md)
- [Get bank transaction](https://developer.usetyms.com/api-reference/bank-transactions/get-bank-transaction.md)
- [Update bank transaction](https://developer.usetyms.com/api-reference/bank-transactions/update-bank-transaction.md)
- [Update bank transaction (partial)](https://developer.usetyms.com/api-reference/bank-transactions/update-bank-transaction-partial.md)
- [Delete bank transaction](https://developer.usetyms.com/api-reference/bank-transactions/delete-bank-transaction.md)
- [List inventory items](https://developer.usetyms.com/api-reference/inventory/list-inventory-items.md): Return the paginated product and service catalog for the business. Use `search` to filter by item name.
- [Create inventory item (alias)](https://developer.usetyms.com/api-reference/inventory/create-inventory-item-alias.md): Alias for `POST /inventories`. Prefer `/inventories` for new integrations. Same request body and response.
- [Create inventory item (manual or AI)](https://developer.usetyms.com/api-reference/inventory/create-inventory-item-manual-or-ai.md): Create a new product or service item in the Tyms catalog. Set `is_inventory: true` to track stock; omit for non-stocked services. Supports AI create when `prompt` is present.
- [Get inventory item](https://developer.usetyms.com/api-reference/inventory/get-inventory-item.md): Retrieve a single product or service by uuid.
- [Update inventory item](https://developer.usetyms.com/api-reference/inventory/update-inventory-item.md): Full update of an inventory item. Send all fields.
- [Update inventory item (partial)](https://developer.usetyms.com/api-reference/inventory/update-inventory-item-partial.md): Partial update — send only fields you want to change.
- [Delete inventory item](https://developer.usetyms.com/api-reference/inventory/delete-inventory-item.md)
- [Sell stock](https://developer.usetyms.com/api-reference/inventory/sell-stock.md): Create a stock sale document that reduces inventory quantities. The payload follows the same line-item structure as income/invoice (`date`, `customer`, `items[]` with `item_name`, `quantity`, `selling_price`, `category`). COGS is computed automatically from cost_price.
- [Restock inventory](https://developer.usetyms.com/api-reference/inventory/restock-inventory.md): Create a restock document that increases stock quantities. The payload follows the same line-item structure as a bill (`date`, `customer` (vendor), `items[]` with `item_name`, `quantity`, `selling_price` (unit cost), `category`). Stock is updated after save.
- [List fixed assets](https://developer.usetyms.com/api-reference/fixed-assets/list-fixed-assets.md): Return the paginated list of capital assets for the business.
- [Create fixed asset (alias)](https://developer.usetyms.com/api-reference/fixed-assets/create-fixed-asset-alias.md): Alias for `POST /assets`. Prefer `/assets` for new integrations.
- [Create fixed asset](https://developer.usetyms.com/api-reference/fixed-assets/create-fixed-asset.md): Capitalize a new fixed asset. Set `amount_paid` and `payment_category` to record an immediate cash payment. Asset depreciation schedules are managed in-app.
- [Get fixed asset](https://developer.usetyms.com/api-reference/fixed-assets/get-fixed-asset.md)
- [Update fixed asset](https://developer.usetyms.com/api-reference/fixed-assets/update-fixed-asset.md)
- [Update fixed asset (partial)](https://developer.usetyms.com/api-reference/fixed-assets/update-fixed-asset-partial.md)
- [Delete fixed asset](https://developer.usetyms.com/api-reference/fixed-assets/delete-fixed-asset.md)
- [List quotes](https://developer.usetyms.com/api-reference/quotes/list-quotes.md): Return the paginated list of sales quotes. Accepted quotes can be converted to invoices, income, or prepaid income.
- [Create quote (alias)](https://developer.usetyms.com/api-reference/quotes/create-quote-alias.md): Alias for `POST /quotes`. Prefer `/quotes` for new integrations.
- [Create quote (manual or AI)](https://developer.usetyms.com/api-reference/quotes/create-quote-manual-or-ai.md): Create a sales proposal with line items. Supports AI create when `prompt` is present. Use `/quotes/{uuid}/convert-to-invoice` once the customer accepts.
- [Get quote](https://developer.usetyms.com/api-reference/quotes/get-quote.md): Retrieve a single quote with line items.
- [Update quote](https://developer.usetyms.com/api-reference/quotes/update-quote.md)
- [Update quote (partial)](https://developer.usetyms.com/api-reference/quotes/update-quote-partial.md)
- [Delete quote](https://developer.usetyms.com/api-reference/quotes/delete-quote.md)
- [Convert quote to invoice](https://developer.usetyms.com/api-reference/quotes/convert-quote-to-invoice.md): Convert an accepted quote to a posted invoice. The quote items, customer, and amounts are copied to a new invoice. Pass an empty body `{}`.
- [Convert quote to income](https://developer.usetyms.com/api-reference/quotes/convert-quote-to-income.md): Convert an accepted quote to a cash receipt (sales income). The quote items and customer are copied to a new income record. Pass an empty body `{}`.
- [Convert quote to prepaid income](https://developer.usetyms.com/api-reference/quotes/convert-quote-to-prepaid-income.md): Convert an accepted quote to a prepaid income (unearned revenue) record. The amount is deferred and recognized monthly. Pass an empty body `{}`.
- [List purchase orders](https://developer.usetyms.com/api-reference/purchase-orders/list-purchase-orders.md): Return the paginated list of purchase orders. Convert to restock when goods arrive.
- [Create purchase order (alias)](https://developer.usetyms.com/api-reference/purchase-orders/create-purchase-order-alias.md): Alias for `POST /purchase-orders`. Prefer `/purchase-orders` for new integrations.
- [Create purchase order (manual or AI)](https://developer.usetyms.com/api-reference/purchase-orders/create-purchase-order-manual-or-ai.md): Create a buying commitment to a vendor. Supports AI create when `prompt` is present. Use `/purchase-orders/{uuid}/convert-to-restock` when goods arrive.
- [Get purchase order](https://developer.usetyms.com/api-reference/purchase-orders/get-purchase-order.md)
- [Update purchase order](https://developer.usetyms.com/api-reference/purchase-orders/update-purchase-order.md)
- [Update purchase order (partial)](https://developer.usetyms.com/api-reference/purchase-orders/update-purchase-order-partial.md)
- [Delete purchase order](https://developer.usetyms.com/api-reference/purchase-orders/delete-purchase-order.md)
- [Convert purchase order to restock](https://developer.usetyms.com/api-reference/purchase-orders/convert-purchase-order-to-restock.md): Convert a purchase order to an inventory restock document when goods arrive. Stock quantities are increased per line item. Pass an empty body `{}`.
- [List departments](https://developer.usetyms.com/api-reference/departments/list-departments.md): Return all departments for the business. Use `department_uuid` on invoices, bills, expenses, income, and journals to tag transactions.
- [Create department](https://developer.usetyms.com/api-reference/departments/create-department.md): Create a new department dimension. Optionally link to a branch with `branch_uuid`.
- [Update department](https://developer.usetyms.com/api-reference/departments/update-department.md)
- [Update department (partial)](https://developer.usetyms.com/api-reference/departments/update-department-partial.md)
- [Delete department](https://developer.usetyms.com/api-reference/departments/delete-department.md)
- [List projects](https://developer.usetyms.com/api-reference/projects/list-projects.md): Return the paginated list of projects. Tag transactions with `project_uuid` to track job costs.
- [Create project](https://developer.usetyms.com/api-reference/projects/create-project.md): Create a new project for job costing and revenue tracking. Attach to invoices, journals, and other transactions via `project_uuid`.
- [Get project](https://developer.usetyms.com/api-reference/projects/get-project.md)
- [Update project](https://developer.usetyms.com/api-reference/projects/update-project.md)
- [Update project (partial)](https://developer.usetyms.com/api-reference/projects/update-project-partial.md)
- [Delete project](https://developer.usetyms.com/api-reference/projects/delete-project.md)
- [List branches](https://developer.usetyms.com/api-reference/branches/list-branches.md): Return all branches for the business. Tag transactions with `branch_uuid` to track performance by location.
- [Create branch](https://developer.usetyms.com/api-reference/branches/create-branch.md): Create a new branch location. `name`, `address`, `state`, and `country` are required. The default branch cannot be deleted.
- [Update branch](https://developer.usetyms.com/api-reference/branches/update-branch.md)
- [Update branch (partial)](https://developer.usetyms.com/api-reference/branches/update-branch-partial.md)
- [Delete branch](https://developer.usetyms.com/api-reference/branches/delete-branch.md): Delete a non-default branch. The default branch cannot be deleted.
- [Income statement](https://developer.usetyms.com/api-reference/reports/income-statement.md)
- [Balance sheet](https://developer.usetyms.com/api-reference/reports/balance-sheet.md)
- [Trial balance](https://developer.usetyms.com/api-reference/reports/trial-balance.md)
- [Cash flow statement](https://developer.usetyms.com/api-reference/reports/cash-flow-statement.md)
- [General ledger](https://developer.usetyms.com/api-reference/reports/general-ledger.md): Paginated chronological ledger of all posted journal legs across the business — the complete double-entry audit trail. Filter by account name, contact, transaction type, or date range. Each row includes debit/credit amounts in both transaction and base currency.
- [Account ledger](https://developer.usetyms.com/api-reference/reports/account-ledger.md): Running balance ledger for a single chart-of-account or bank account. Pass a COA uuid or bank uuid as `{uuid}`. Returns all movements with opening and closing balance per line, plus the period closing balance and debit/credit side.
- [Contact statement](https://developer.usetyms.com/api-reference/reports/contact-statement.md): Customer or vendor account statement. Returns opening balance, closing balance, total charges, total payments, and each movement (invoice, bill, payment) with running balance. Used for portal statements and collections.
- [Register business](https://developer.usetyms.com/api-reference/partners/register-business.md): Create a new Tyms business using a **partner** API key.
- [List referred businesses](https://developer.usetyms.com/api-reference/partners/list-referred-businesses.md): Paginated list of businesses you referred, with a billing snapshot on each row.
- [Billing status](https://developer.usetyms.com/api-reference/partners/billing-status.md): Subscription state, licensed seats, plan, and AI credit balance for one referred business.
- [Add seats](https://developer.usetyms.com/api-reference/partners/add-seats.md): Grant Plus seats from partner holding. First call activates Plus for the requested period; later calls add prorated seats for the remaining period.
- [Add credits](https://developer.usetyms.com/api-reference/partners/add-credits.md): Transfer AI credits from partner holding to the business at 1:1. Does not require Plus. Transferred credits expire 12 months after grant.
- [Overview](https://developer.usetyms.com/mcp/overview.md): Connect Claude, ChatGPT, Perplexity, and other MCP clients to Tyms so your AI assistant can read — and optionally write — your accounting data securely.
- [Endpoints](https://developer.usetyms.com/mcp/endpoints.md): Tyms MCP URLs for read-only and read + write access.
- [Authentication](https://developer.usetyms.com/mcp/authentication.md): How Tyms MCP OAuth works and which Client ID to use for each platform.
- [Claude.ai](https://developer.usetyms.com/mcp/clients/claude-ai.md): Connect Tyms MCP to Claude on the web so you can ask about your books in chat.
- [Claude Desktop](https://developer.usetyms.com/mcp/clients/claude-desktop.md): Connect Tyms MCP in the Claude Desktop app using custom connectors.
- [Claude Code](https://developer.usetyms.com/mcp/clients/claude-code.md): Add the Tyms remote MCP server to Claude Code over HTTP and complete OAuth.
- [ChatGPT](https://developer.usetyms.com/mcp/clients/chatgpt.md): Connect Tyms MCP to ChatGPT using a custom MCP / Apps connector.
- [Perplexity](https://developer.usetyms.com/mcp/clients/perplexity.md): Connect Tyms MCP to Perplexity using the Perplexity Client ID.
- [Other clients](https://developer.usetyms.com/mcp/clients/other.md): Use Tyms MCP from Cursor and other remote MCP + OAuth clients.
- [What Tyms MCP can do](https://developer.usetyms.com/mcp/capabilities.md): Capabilities by business domain for the read-only and full Tyms MCP endpoints.
- [Read-only vs full](https://developer.usetyms.com/mcp/read-vs-full.md): Choose the right Tyms MCP endpoint for lookups versus bookkeeping.
- [Example prompts](https://developer.usetyms.com/mcp/example-prompts.md): Sample questions and commands to try with Tyms MCP in Claude or ChatGPT.
- [Security & privacy](https://developer.usetyms.com/mcp/security.md): How Tyms MCP keeps access scoped to your business and what you should do to stay safe.
- [FAQ](https://developer.usetyms.com/mcp/faq.md): Common questions about Tyms MCP, Client ID, endpoints, and supported clients.

## OpenAPI Specs

- [adam-v1](https://developer.usetyms.com/openapi/adam-v1.json)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.