# Attachments
Source: https://developer.usetyms.com/api-reference/attachments
The attachments array shape for AI create endpoints and bank transaction upload.
Several **create** endpoints accept an optional **`attachments`** field: a JSON **array of objects** (not raw strings or bare URLs). Each object describes one file for the AI pipeline.
Endpoints that use this shape include (non-exhaustive): **invoices**, **bills**, **expenses**, **income**, **journals**, **contacts**, **chart of accounts** (`POST /accounts`), and **`POST /bank-transactions/upload`**.
## Attachment object
| Field | Required | Type | Description |
| ------ | ----------- | ------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `file` | Yes | string | Content interpreted per `type` — must be non-empty |
| `type` | Yes | string | One of `base64`, `url`, or `raw`. **Always required** — for Base64 file bytes you must send `"type": "base64"`; the API does **not** treat a bare string in `file` as Base64 when `type` is missing |
| `name` | Recommended | string | Original filename **including extension** (e.g. `statement-jan.pdf`, `export.csv`). Used for type detection (PDF, CSV, Excel, images). If omitted, a generic name may break detection |
### `type` values for `file`
| `type` | Meaning |
| -------- | --------------------------------------------------------------------------------------------------------------------------- |
| `base64` | Standard Base64-encoded file bytes (**no** `data:...;base64,` prefix). You **must** set `"type": "base64"` alongside `file` |
| `url` | Public `https://` URL the server fetches once (timeout and HTTP success required) |
| `raw` | Raw binary as string (uncommon in JSON; prefer `base64`) |
## Examples
### One PDF as Base64
```json theme={null}
"attachments": [
{
"name": "invoice-scan.pdf",
"type": "base64",
"file": "JVBERi0xLjQKJeLjz9MKMyAwIG9iago8PC9MZW5ndGggNCAwIFIvRmlsdGVyL0ZsYXRlRGVjb2RlPj4Kc3RyZWFtCnic..."
}
]
```
### File hosted at a URL
```json theme={null}
"attachments": [
{
"name": "statement.csv",
"type": "url",
"file": "https://cdn.example.com/statements/jan-2024.csv"
}
]
```
## Usage notes
* **Base64:** never omit `type`. Sending only a long string in `file` without `"type": "base64"` is invalid for Base64 content.
* **Multiple attachments:** each object is processed; for async jobs, processing is often **one job per attachment**.
* **Omit or empty array:** use `[]` or omit `attachments` when you only send `prompt` and optional `text_attachment`.
* **Bank statement files:** for `POST /bank-transactions/upload`, supported types follow the filename extension: **pdf**, **csv**, **xlsx**, **xls**, and common images (**jpg**, **jpeg**, **png**, **webp**, **gif**, **bmp**). Other AI pipelines may accept different formats per their service rules.
## Related
* [Create bank transactions (AI)](/api-reference/bank-transactions/create-bank-transactions-ai)
* [API overview](/api-reference/overview)
# Validate business
Source: https://developer.usetyms.com/api-reference/authentication/validate-business
/openapi/adam-v1.json get /auth/validate
Validate a **business** `tyms_sk_...` key and return business profile fields.
Use a **business** `tyms_sk_...` key, not a partner key. After [Register business](/api-reference/partners/register-business), validate with that business's secret.
# Create bank transaction
Source: https://developer.usetyms.com/api-reference/bank-transactions/create-bank-transaction
/openapi/adam-v1.json post /bank-transactions
Manual single transaction. Requires an existing bank on the business.
# Create bank transactions (AI)
Source: https://developer.usetyms.com/api-reference/bank-transactions/create-bank-transactions-ai
/openapi/adam-v1.json post /bank-transactions/upload
# Delete bank transaction
Source: https://developer.usetyms.com/api-reference/bank-transactions/delete-bank-transaction
/openapi/adam-v1.json delete /bank-transactions/{uuid}
# Get bank transaction
Source: https://developer.usetyms.com/api-reference/bank-transactions/get-bank-transaction
/openapi/adam-v1.json get /bank-transactions/{uuid}
# List bank transactions
Source: https://developer.usetyms.com/api-reference/bank-transactions/list-bank-transactions
/openapi/adam-v1.json get /bank-transactions
Bank transactions are individual statement lines — debits (money out) and credits (money in).
# Update bank transaction
Source: https://developer.usetyms.com/api-reference/bank-transactions/update-bank-transaction
/openapi/adam-v1.json put /bank-transactions/{uuid}
# Update bank transaction (partial)
Source: https://developer.usetyms.com/api-reference/bank-transactions/update-bank-transaction-partial
/openapi/adam-v1.json patch /bank-transactions/{uuid}
# Create bank account
Source: https://developer.usetyms.com/api-reference/banks/create-bank-account
/openapi/adam-v1.json post /banks
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.
# Delete bank account
Source: https://developer.usetyms.com/api-reference/banks/delete-bank-account
/openapi/adam-v1.json delete /banks/{uuid}
Delete a bank account. Fails if the bank has non-opening-balance ledger activity or an uncleared opening balance remains.
# Get bank
Source: https://developer.usetyms.com/api-reference/banks/get-bank
/openapi/adam-v1.json get /banks/{uuid}
# List banks
Source: https://developer.usetyms.com/api-reference/banks/list-banks
/openapi/adam-v1.json get /banks
# Create bill
Source: https://developer.usetyms.com/api-reference/bills/create-bill
/openapi/adam-v1.json post /create/bill
# Create bill (AI)
Source: https://developer.usetyms.com/api-reference/bills/create-bill-ai
/openapi/adam-v1.json post /bills
# Delete bill
Source: https://developer.usetyms.com/api-reference/bills/delete-bill
/openapi/adam-v1.json delete /bills/{uuid}
# Get bill
Source: https://developer.usetyms.com/api-reference/bills/get-bill
/openapi/adam-v1.json get /bills/{uuid}
# List bills
Source: https://developer.usetyms.com/api-reference/bills/list-bills
/openapi/adam-v1.json get /bills
Bills are vendor invoices your business owes. On bills, `customer` refers to the vendor.
# Update bill
Source: https://developer.usetyms.com/api-reference/bills/update-bill
/openapi/adam-v1.json put /bills/{uuid}
# Update bill (partial)
Source: https://developer.usetyms.com/api-reference/bills/update-bill-partial
/openapi/adam-v1.json patch /bills/{uuid}
# Update bill payments
Source: https://developer.usetyms.com/api-reference/bills/update-bill-payments
/openapi/adam-v1.json post /bills/{uuid}/payments
# Create branch
Source: https://developer.usetyms.com/api-reference/branches/create-branch
/openapi/adam-v1.json post /branches
Create a new branch location. `name`, `address`, `state`, and `country` are required. The default branch cannot be deleted.
# Delete branch
Source: https://developer.usetyms.com/api-reference/branches/delete-branch
/openapi/adam-v1.json delete /branches/{uuid}
Delete a non-default branch. The default branch cannot be deleted.
# List branches
Source: https://developer.usetyms.com/api-reference/branches/list-branches
/openapi/adam-v1.json get /branches
Return all branches for the business. Tag transactions with `branch_uuid` to track performance by location.
# Update branch
Source: https://developer.usetyms.com/api-reference/branches/update-branch
/openapi/adam-v1.json put /branches/{uuid}
# Update branch (partial)
Source: https://developer.usetyms.com/api-reference/branches/update-branch-partial
/openapi/adam-v1.json patch /branches/{uuid}
# Create account
Source: https://developer.usetyms.com/api-reference/chart-of-accounts/create-account
/openapi/adam-v1.json post /create/chart_of_account
# Create account (AI)
Source: https://developer.usetyms.com/api-reference/chart-of-accounts/create-account-ai
/openapi/adam-v1.json post /accounts
# Delete account
Source: https://developer.usetyms.com/api-reference/chart-of-accounts/delete-account
/openapi/adam-v1.json delete /accounts/{uuid}
# Get account
Source: https://developer.usetyms.com/api-reference/chart-of-accounts/get-account
/openapi/adam-v1.json get /accounts/{uuid}
# Get account types
Source: https://developer.usetyms.com/api-reference/chart-of-accounts/get-account-types
/openapi/adam-v1.json get /accounts/types
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.
# List accounts
Source: https://developer.usetyms.com/api-reference/chart-of-accounts/list-accounts
/openapi/adam-v1.json get /accounts
The chart of accounts is the complete list of ledger accounts your business uses — assets, liabilities, equity, revenue, and expenses.
# Update account
Source: https://developer.usetyms.com/api-reference/chart-of-accounts/update-account
/openapi/adam-v1.json put /accounts/{uuid}
# Update account (partial)
Source: https://developer.usetyms.com/api-reference/chart-of-accounts/update-account-partial
/openapi/adam-v1.json patch /accounts/{uuid}
# Create contact
Source: https://developer.usetyms.com/api-reference/contacts/create-contact
/openapi/adam-v1.json post /create/contact
# Create contact (AI)
Source: https://developer.usetyms.com/api-reference/contacts/create-contact-ai
/openapi/adam-v1.json post /contacts
# Delete contact
Source: https://developer.usetyms.com/api-reference/contacts/delete-contact
/openapi/adam-v1.json delete /contacts/{uuid}
# Get contact
Source: https://developer.usetyms.com/api-reference/contacts/get-contact
/openapi/adam-v1.json get /contacts/{uuid}
# List contacts
Source: https://developer.usetyms.com/api-reference/contacts/list-contacts
/openapi/adam-v1.json get /contacts
Contacts are customers and vendors used on invoices, bills, and other transactions.
# Update contact
Source: https://developer.usetyms.com/api-reference/contacts/update-contact
/openapi/adam-v1.json put /contacts/{uuid}
# Update contact (partial)
Source: https://developer.usetyms.com/api-reference/contacts/update-contact-partial
/openapi/adam-v1.json patch /contacts/{uuid}
# Create department
Source: https://developer.usetyms.com/api-reference/departments/create-department
/openapi/adam-v1.json post /departments
Create a new department dimension. Optionally link to a branch with `branch_uuid`.
# Delete department
Source: https://developer.usetyms.com/api-reference/departments/delete-department
/openapi/adam-v1.json delete /departments/{uuid}
# List departments
Source: https://developer.usetyms.com/api-reference/departments/list-departments
/openapi/adam-v1.json get /departments
Return all departments for the business. Use `department_uuid` on invoices, bills, expenses, income, and journals to tag transactions.
# Update department
Source: https://developer.usetyms.com/api-reference/departments/update-department
/openapi/adam-v1.json put /departments/{uuid}
# Update department (partial)
Source: https://developer.usetyms.com/api-reference/departments/update-department-partial
/openapi/adam-v1.json patch /departments/{uuid}
# Create expense
Source: https://developer.usetyms.com/api-reference/expenses/create-expense
/openapi/adam-v1.json post /create/expense
# Create expense (AI)
Source: https://developer.usetyms.com/api-reference/expenses/create-expense-ai
/openapi/adam-v1.json post /expenses
# Delete expense
Source: https://developer.usetyms.com/api-reference/expenses/delete-expense
/openapi/adam-v1.json delete /expenses/{uuid}
# Get expense
Source: https://developer.usetyms.com/api-reference/expenses/get-expense
/openapi/adam-v1.json get /expenses/{uuid}
# List expenses
Source: https://developer.usetyms.com/api-reference/expenses/list-expenses
/openapi/adam-v1.json get /expenses
Expenses are cash outflows paid immediately from cash or bank. They default to `status: paid`.
# Update expense
Source: https://developer.usetyms.com/api-reference/expenses/update-expense
/openapi/adam-v1.json put /expenses/{uuid}
# Update expense (partial)
Source: https://developer.usetyms.com/api-reference/expenses/update-expense-partial
/openapi/adam-v1.json patch /expenses/{uuid}
# Create fixed asset
Source: https://developer.usetyms.com/api-reference/fixed-assets/create-fixed-asset
/openapi/adam-v1.json post /assets
Capitalize a new fixed asset. Set `amount_paid` and `payment_category` to record an immediate cash payment. Asset depreciation schedules are managed in-app.
# Create fixed asset (alias)
Source: https://developer.usetyms.com/api-reference/fixed-assets/create-fixed-asset-alias
/openapi/adam-v1.json post /create/asset
Alias for `POST /assets`. Prefer `/assets` for new integrations.
# Delete fixed asset
Source: https://developer.usetyms.com/api-reference/fixed-assets/delete-fixed-asset
/openapi/adam-v1.json delete /assets/{uuid}
# Get fixed asset
Source: https://developer.usetyms.com/api-reference/fixed-assets/get-fixed-asset
/openapi/adam-v1.json get /assets/{uuid}
# List fixed assets
Source: https://developer.usetyms.com/api-reference/fixed-assets/list-fixed-assets
/openapi/adam-v1.json get /assets
Return the paginated list of capital assets for the business.
# Update fixed asset
Source: https://developer.usetyms.com/api-reference/fixed-assets/update-fixed-asset
/openapi/adam-v1.json put /assets/{uuid}
# Update fixed asset (partial)
Source: https://developer.usetyms.com/api-reference/fixed-assets/update-fixed-asset-partial
/openapi/adam-v1.json patch /assets/{uuid}
# Create income
Source: https://developer.usetyms.com/api-reference/income/create-income
/openapi/adam-v1.json post /create/income
# Create income (AI)
Source: https://developer.usetyms.com/api-reference/income/create-income-ai
/openapi/adam-v1.json post /income
# Delete income
Source: https://developer.usetyms.com/api-reference/income/delete-income
/openapi/adam-v1.json delete /income/{uuid}
# Get income
Source: https://developer.usetyms.com/api-reference/income/get-income
/openapi/adam-v1.json get /income/{uuid}
# List income
Source: https://developer.usetyms.com/api-reference/income/list-income
/openapi/adam-v1.json get /income
Income records (sales receipts) are cash sales received without an open invoice. They default to `status: paid`. `document_number` is returned as `receipt_no`.
# Update income
Source: https://developer.usetyms.com/api-reference/income/update-income
/openapi/adam-v1.json put /income/{uuid}
# Update income (partial)
Source: https://developer.usetyms.com/api-reference/income/update-income-partial
/openapi/adam-v1.json patch /income/{uuid}
# Create inventory item (alias)
Source: https://developer.usetyms.com/api-reference/inventory/create-inventory-item-alias
/openapi/adam-v1.json post /create/inventory
Alias for `POST /inventories`. Prefer `/inventories` for new integrations. Same request body and response.
# Create inventory item (manual or AI)
Source: https://developer.usetyms.com/api-reference/inventory/create-inventory-item-manual-or-ai
/openapi/adam-v1.json post /inventories
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.
# Delete inventory item
Source: https://developer.usetyms.com/api-reference/inventory/delete-inventory-item
/openapi/adam-v1.json delete /inventories/{uuid}
# Get inventory item
Source: https://developer.usetyms.com/api-reference/inventory/get-inventory-item
/openapi/adam-v1.json get /inventories/{uuid}
Retrieve a single product or service by uuid.
# List inventory items
Source: https://developer.usetyms.com/api-reference/inventory/list-inventory-items
/openapi/adam-v1.json get /inventories
Return the paginated product and service catalog for the business. Use `search` to filter by item name.
# Restock inventory
Source: https://developer.usetyms.com/api-reference/inventory/restock-inventory
/openapi/adam-v1.json post /inventories/restock
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.
# Sell stock
Source: https://developer.usetyms.com/api-reference/inventory/sell-stock
/openapi/adam-v1.json post /inventories/sell
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.
# Update inventory item
Source: https://developer.usetyms.com/api-reference/inventory/update-inventory-item
/openapi/adam-v1.json put /inventories/{uuid}
Full update of an inventory item. Send all fields.
# Update inventory item (partial)
Source: https://developer.usetyms.com/api-reference/inventory/update-inventory-item-partial
/openapi/adam-v1.json patch /inventories/{uuid}
Partial update — send only fields you want to change.
# Create invoice
Source: https://developer.usetyms.com/api-reference/invoices/create-invoice
/openapi/adam-v1.json post /create/invoice
# Create invoice (AI)
Source: https://developer.usetyms.com/api-reference/invoices/create-invoice-ai
/openapi/adam-v1.json post /invoices
# Delete invoice
Source: https://developer.usetyms.com/api-reference/invoices/delete-invoice
/openapi/adam-v1.json delete /invoices/{uuid}
# Get invoice
Source: https://developer.usetyms.com/api-reference/invoices/get-invoice
/openapi/adam-v1.json get /invoices/{uuid}
# List invoices
Source: https://developer.usetyms.com/api-reference/invoices/list-invoices
/openapi/adam-v1.json get /invoices
Invoices are amounts you bill customers for goods or services, creating accounts receivable until paid.
# Update invoice
Source: https://developer.usetyms.com/api-reference/invoices/update-invoice
/openapi/adam-v1.json put /invoices/{uuid}
# Update invoice (partial)
Source: https://developer.usetyms.com/api-reference/invoices/update-invoice-partial
/openapi/adam-v1.json patch /invoices/{uuid}
# Update invoice payments
Source: https://developer.usetyms.com/api-reference/invoices/update-invoice-payments
/openapi/adam-v1.json post /invoices/{uuid}/payments
# Create journal
Source: https://developer.usetyms.com/api-reference/journals/create-journal
/openapi/adam-v1.json post /create/journal
# Create journal (AI)
Source: https://developer.usetyms.com/api-reference/journals/create-journal-ai
/openapi/adam-v1.json post /journals
# Delete journal
Source: https://developer.usetyms.com/api-reference/journals/delete-journal
/openapi/adam-v1.json delete /journals/{uuid}
# Get journal
Source: https://developer.usetyms.com/api-reference/journals/get-journal
/openapi/adam-v1.json get /journals/{uuid}
# List journals
Source: https://developer.usetyms.com/api-reference/journals/list-journals
/openapi/adam-v1.json get /journals
Journal entries are debit-and-credit postings. Total debits must equal total credits.
# Update journal
Source: https://developer.usetyms.com/api-reference/journals/update-journal
/openapi/adam-v1.json put /journals/{uuid}
# Update journal (partial)
Source: https://developer.usetyms.com/api-reference/journals/update-journal-partial
/openapi/adam-v1.json patch /journals/{uuid}
# Exchange authorization code
Source: https://developer.usetyms.com/api-reference/oauth/exchange-authorization-code
/openapi/adam-v1.json post /oauth/access/token
Exchange a single-use authorization code for access and refresh tokens. Requires your app **secret key** in `X-API-Key`.
Send your integration app `tyms_sk_...` in `X-API-Key` (or `api-key` / `sk`). Access tokens expire after **60 minutes**.
# Get authorization URL
Source: https://developer.usetyms.com/api-reference/oauth/get-authorization-url
/openapi/adam-v1.json get /oauth/authorization
Start the OAuth flow. Returns an HTTPS URL to redirect the user for Tyms sign-in and business selection.
Guide: [OAuth 2.0](/oauth). No API key on this request — only query parameters.
# Refresh access token
Source: https://developer.usetyms.com/api-reference/oauth/refresh-access-token
/openapi/adam-v1.json post /oauth/refresh/token
Obtain a new access token using a refresh token. Requires your app **secret key** in `X-API-Key`.
# Revoke access
Source: https://developer.usetyms.com/api-reference/oauth/revoke-access
/openapi/adam-v1.json post /oauth/revoke/token
Revoke an access or refresh token when a user disconnects your app. Requires your app **secret key** in `X-API-Key`.
# Validate OAuth session
Source: https://developer.usetyms.com/api-reference/oauth/validate-oauth-session
/openapi/adam-v1.json get /oauth/token/validate
Validate the current OAuth access token and return authorized business profile fields.
Send **both** `X-API-Key` (your app `tyms_sk_...`) and `Authorization: Bearer `. Same requirement applies to all other business-scoped endpoints when using OAuth.
# API overview
Source: https://developer.usetyms.com/api-reference/overview
Base URL, conventions, errors, rate limits, and identifier rules for the Tyms Developer API.
## Environments
| Environment | Base URL |
| -------------- | ----------------------------------------- |
| **Production** | `https://api.usetyms.com/v1/adam` |
| **Sandbox** | `https://staging-api.usetyms.com/v1/adam` |
All paths below are **relative** to whichever base URL you use. Example: `GET /auth/validate` → `https://api.usetyms.com/v1/adam/auth/validate` in production, or `https://staging-api.usetyms.com/v1/adam/auth/validate` in sandbox.
Request a **sandbox account** and staging credentials from [developer@usetyms.com](mailto:developer@usetyms.com) before pre-production testing. Do not point production keys at the sandbox host (or sandbox keys at production).
## Try the API
On each page under **API reference**, you can:
* Choose **Production** or **Sandbox** as the server (sandbox requires credentials from [developer@usetyms.com](mailto:developer@usetyms.com))
* See the full **`https://api.usetyms.com/v1/adam/...`** or **`https://staging-api.usetyms.com/v1/adam/...`** URL for the operation
* Use the **interactive request** panel to set query, path, and body fields and send a request
* Copy **sample code** (cURL, Python, JavaScript); many endpoints include **example** request bodies you can adjust and run
* **Authenticate** with your **`X-API-Key`**: business key `tyms_sk_...` for most routes, or a **partner** key for **Partners** routes (register, list, billing, seat/credit grants)
Use [Attachments](/api-reference/attachments) for the `attachments` object shape (`file` + **`type`** required, including `"type": "base64"` for Base64 files).
## Authentication summary
| Credential | Header(s) | Used on |
| --------------------------------------------- | --------------------------------------------- | ----------------------------------------------------------------------------------------------- |
| Business secret `tyms_sk_...` | `X-API-Key`, `api-key`, or `sk` | All routes **except** partner distributor routes and OAuth steps that document their own auth |
| Partner secret (e.g. `adam_partner_sk_...`) | Same headers | **Partners** group — register, list referred businesses, billing status, add seats, add credits |
| OAuth (app `tyms_sk_...` + user Bearer token) | `X-API-Key` **and** `Authorization: Bearer …` | Business-scoped routes after [OAuth authorization](/oauth) |
Conceptual guides: [Authentication](/authentication), [OAuth 2.0](/oauth).
## Subscription gate
For business-scoped routes, the account must meet Tyms’s **Developer API subscription** requirements. Otherwise the API returns **403 Forbidden**.
## Success envelope (typical)
Successful responses use a consistent JSON shape (see `USEADAM_DEVELOPER_API.md` in this repo for the full narrative):
```json theme={null}
{
"status": "success",
"message": "…",
"data": {}
}
```
* **Lists** usually return **`data` as an array** and often include **`meta`** for pagination (`page`, `limit`, `total`).
* **Financial reports** add **`meta.from`** and **`meta.to`** (and cash flow may include **`meta.previous_period_end`**).
* **AI creates** with **`process_type`: `async`** (the default on most routes) typically return job-style fields inside **`data`**; use **`direct`** when you need the created resource in the same response.
Where we document them, success responses include **`example`** payloads so you see realistic JSON—not a bare `OK`.
## Error responses
Failures use a consistent JSON shape:
```json theme={null}
{
"status": "failed",
"message": "Error description"
}
```
### Common HTTP status codes
| Code | Meaning |
| ----- | --------------------------------------------------------------------------------- |
| `200` | Success |
| `201` | Created (when applicable) |
| `400` | Invalid parameters or body (e.g. missing required `prompt` on bank upload) |
| `401` | Invalid or missing API key |
| `402` | Payment required (e.g. insufficient partner credit holding on seat/credit grants) |
| `403` | Forbidden (e.g. Developer API not allowed for this business) |
| `404` | Resource not found |
| `500` | Server error |
Chart-of-accounts **delete** may return **400** when the account is default, in use, or blocked by cashbook rules — the `message` explains why.
## Rate limiting
Rate limits may apply. Check response headers:
* `X-RateLimit-Limit` — max requests per window
* `X-RateLimit-Remaining` — remaining in the current window
* `X-RateLimit-Reset` — when the window resets
Implement backoff if you receive **429 Too Many Requests**.
## UUID resolution
For **update** and **delete** operations, path identifiers may be either:
* the record **`uuid`**, or
* the record **`source_uuid`**
The API resolves both to the same row when present.
**Example:** if `uuid` is `abc-123` and `source_uuid` is `xyz-789`, either value may appear in the path segment `{uuid}`.
**Get** endpoints for specific records also accept whichever identifier your integration stores, where documented per resource.
## Pagination and ordering
List endpoints commonly support:
* `page` — page number
* `limit` — page size
* `date_order` — `asc` or `desc` (default **`desc`** where documented)
Some lists support extra filters (e.g. `schema`, `search`, `bank`, `status`). See each resource page.
## AI create body pattern
Typical fields on **POST** creates:
| Field | Required | Description |
| ----------------- | -------------------- | --------------------------------------------------------------------------------------------------- |
| `prompt` | Yes (for AI creates) | Natural-language instructions |
| `attachments` | No | Array of objects (`file` + **`type`** required on each) — [Attachments](/api-reference/attachments) |
| `text_attachment` | No | Extra plain text merged into AI context |
| `process_type` | No | `async` (default on most routes) or `direct` |
**Exception:** `POST /bank-transactions/upload` always requires `prompt`; see [Create bank transactions (AI)](/api-reference/bank-transactions/create-bank-transactions-ai) in the **API reference** tab.
## Support
* Email: [developer@usetyms.com](mailto:developer@usetyms.com)
# Add credits
Source: https://developer.usetyms.com/api-reference/partners/add-credits
/openapi/adam-v1.json post /referred-businesses/{business_uuid}/add-credits
Transfer AI credits from partner holding to the business at 1:1. Does not require Plus. Transferred credits expire 12 months after grant.
1:1 transfer from holding to the business ledger. Use when plan credits run low or you prefer pay-as-you-go top-ups instead of [Add seats](/api-reference/partners/add-referred-business-seats). Blocked when `credit_from_referral_partner` is `true`.
# Add seats
Source: https://developer.usetyms.com/api-reference/partners/add-seats
/openapi/adam-v1.json post /referred-businesses/{business_uuid}/add-seats
Grant Plus seats from partner holding. First call activates Plus for the requested period; later calls add prorated seats for the remaining period.
Requires `credit_from_referral_partner: false` at registration. Holding cost: **150 × seats × months** on first grant (default 150 credits per seat per month). Adding seats mid-period is prorated. Fails if the business already has its own active Plus subscription.
# Billing status
Source: https://developer.usetyms.com/api-reference/partners/billing-status
/openapi/adam-v1.json get /referred-businesses/{business_uuid}/billing-status
Subscription state, licensed seats, plan, and AI credit balance for one referred business.
`available_seats` counts only **partner-provided** Plus seats — `0` even if the business pays for Plus themselves. Call before [Add seats](/api-reference/partners/add-referred-business-seats) or [Add credits](/api-reference/partners/add-referred-business-credits).
# List referred businesses
Source: https://developer.usetyms.com/api-reference/partners/list-referred-businesses
/openapi/adam-v1.json get /referred-businesses
Paginated list of businesses you referred, with a billing snapshot on each row.
Partner key only. Each item includes identity fields plus the same billing snapshot as [Billing status](/api-reference/partners/get-referred-business-billing-status).
# Register business
Source: https://developer.usetyms.com/api-reference/partners/register-business
/openapi/adam-v1.json post /register-business
Create a new Tyms business using a **partner** API key.
Call with your **partner** API key in `X-API-Key`. Do not use a business `tyms_sk_` key. After success, use the returned **`api_secret_key`** for all other endpoints.
# Create project
Source: https://developer.usetyms.com/api-reference/projects/create-project
/openapi/adam-v1.json post /projects
Create a new project for job costing and revenue tracking. Attach to invoices, journals, and other transactions via `project_uuid`.
# Delete project
Source: https://developer.usetyms.com/api-reference/projects/delete-project
/openapi/adam-v1.json delete /projects/{uuid}
# Get project
Source: https://developer.usetyms.com/api-reference/projects/get-project
/openapi/adam-v1.json get /projects/{uuid}
# List projects
Source: https://developer.usetyms.com/api-reference/projects/list-projects
/openapi/adam-v1.json get /projects
Return the paginated list of projects. Tag transactions with `project_uuid` to track job costs.
# Update project
Source: https://developer.usetyms.com/api-reference/projects/update-project
/openapi/adam-v1.json put /projects/{uuid}
# Update project (partial)
Source: https://developer.usetyms.com/api-reference/projects/update-project-partial
/openapi/adam-v1.json patch /projects/{uuid}
# Convert purchase order to restock
Source: https://developer.usetyms.com/api-reference/purchase-orders/convert-purchase-order-to-restock
/openapi/adam-v1.json post /purchase-orders/{uuid}/convert-to-restock
Convert a purchase order to an inventory restock document when goods arrive. Stock quantities are increased per line item. Pass an empty body `{}`.
# Create purchase order (alias)
Source: https://developer.usetyms.com/api-reference/purchase-orders/create-purchase-order-alias
/openapi/adam-v1.json post /create/purchase_order
Alias for `POST /purchase-orders`. Prefer `/purchase-orders` for new integrations.
# Create purchase order (manual or AI)
Source: https://developer.usetyms.com/api-reference/purchase-orders/create-purchase-order-manual-or-ai
/openapi/adam-v1.json post /purchase-orders
Create a buying commitment to a vendor. Supports AI create when `prompt` is present. Use `/purchase-orders/{uuid}/convert-to-restock` when goods arrive.
# Delete purchase order
Source: https://developer.usetyms.com/api-reference/purchase-orders/delete-purchase-order
/openapi/adam-v1.json delete /purchase-orders/{uuid}
# Get purchase order
Source: https://developer.usetyms.com/api-reference/purchase-orders/get-purchase-order
/openapi/adam-v1.json get /purchase-orders/{uuid}
# List purchase orders
Source: https://developer.usetyms.com/api-reference/purchase-orders/list-purchase-orders
/openapi/adam-v1.json get /purchase-orders
Return the paginated list of purchase orders. Convert to restock when goods arrive.
# Update purchase order
Source: https://developer.usetyms.com/api-reference/purchase-orders/update-purchase-order
/openapi/adam-v1.json put /purchase-orders/{uuid}
# Update purchase order (partial)
Source: https://developer.usetyms.com/api-reference/purchase-orders/update-purchase-order-partial
/openapi/adam-v1.json patch /purchase-orders/{uuid}
# Convert quote to income
Source: https://developer.usetyms.com/api-reference/quotes/convert-quote-to-income
/openapi/adam-v1.json post /quotes/{uuid}/convert-to-income
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 invoice
Source: https://developer.usetyms.com/api-reference/quotes/convert-quote-to-invoice
/openapi/adam-v1.json post /quotes/{uuid}/convert-to-invoice
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 prepaid income
Source: https://developer.usetyms.com/api-reference/quotes/convert-quote-to-prepaid-income
/openapi/adam-v1.json post /quotes/{uuid}/convert-to-prepaid-income
Convert an accepted quote to a prepaid income (unearned revenue) record. The amount is deferred and recognized monthly. Pass an empty body `{}`.
# Create quote (alias)
Source: https://developer.usetyms.com/api-reference/quotes/create-quote-alias
/openapi/adam-v1.json post /create/quote
Alias for `POST /quotes`. Prefer `/quotes` for new integrations.
# Create quote (manual or AI)
Source: https://developer.usetyms.com/api-reference/quotes/create-quote-manual-or-ai
/openapi/adam-v1.json post /quotes
Create a sales proposal with line items. Supports AI create when `prompt` is present. Use `/quotes/{uuid}/convert-to-invoice` once the customer accepts.
# Delete quote
Source: https://developer.usetyms.com/api-reference/quotes/delete-quote
/openapi/adam-v1.json delete /quotes/{uuid}
# Get quote
Source: https://developer.usetyms.com/api-reference/quotes/get-quote
/openapi/adam-v1.json get /quotes/{uuid}
Retrieve a single quote with line items.
# List quotes
Source: https://developer.usetyms.com/api-reference/quotes/list-quotes
/openapi/adam-v1.json get /quotes
Return the paginated list of sales quotes. Accepted quotes can be converted to invoices, income, or prepaid income.
# Update quote
Source: https://developer.usetyms.com/api-reference/quotes/update-quote
/openapi/adam-v1.json put /quotes/{uuid}
# Update quote (partial)
Source: https://developer.usetyms.com/api-reference/quotes/update-quote-partial
/openapi/adam-v1.json patch /quotes/{uuid}
# Account ledger
Source: https://developer.usetyms.com/api-reference/reports/account-ledger
/openapi/adam-v1.json get /reports/account-ledger/{uuid}
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.
# Balance sheet
Source: https://developer.usetyms.com/api-reference/reports/balance-sheet
/openapi/adam-v1.json get /reports/balance-sheet
# Cash flow statement
Source: https://developer.usetyms.com/api-reference/reports/cash-flow-statement
/openapi/adam-v1.json get /reports/cash-flow-statement
# Contact statement
Source: https://developer.usetyms.com/api-reference/reports/contact-statement
/openapi/adam-v1.json get /reports/contact-statement/{uuid}
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.
# General ledger
Source: https://developer.usetyms.com/api-reference/reports/general-ledger
/openapi/adam-v1.json get /reports/general-ledger
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.
# Income statement
Source: https://developer.usetyms.com/api-reference/reports/income-statement
/openapi/adam-v1.json get /reports/income-statement
# Trial balance
Source: https://developer.usetyms.com/api-reference/reports/trial-balance
/openapi/adam-v1.json get /reports/trial-balance
# Authentication
Source: https://developer.usetyms.com/authentication
Business API keys, partner keys, headers, and Developer API access requirements.
Most Tyms Developer API routes use a **business API key** in a header. You pass a secret, and the server enforces **which business** (or **partner program**) the credential belongs to.
Building an integration app for **many** Tyms customers? Use [OAuth 2.0](/oauth) instead of asking each user for their business secret key.
## Production vs sandbox
Credentials are **environment-specific**. Production keys from the Tyms app authenticate against `https://api.usetyms.com/v1/adam`; sandbox keys authenticate against `https://staging-api.usetyms.com/v1/adam`. See [Environments](/introduction#environments) for the full table.
To test integrations before production, email [developer@usetyms.com](mailto:developer@usetyms.com) for **sandbox account setup**. Tyms provisions staging businesses and issues keys that match the sandbox host.
## Two kinds of credentials
### Business secret key (`tyms_sk_...`)
Used for **every** `v1/adam` route **except** partner distributor routes and OAuth steps that document their own auth.
* Issued per business from the Tyms app (**Settings** → **Business settings** → **API**).
* Grants access **only** to that business’s data.
* Public key (`tyms_pk_...`) is not used as the Bearer-style secret for these REST calls; integrations use the **secret** key.
### Partner API key (`adam_partner_sk_...` or equivalent)
Used for **partner distributor** routes under **API reference** → **Partners** (full URLs under [Environments](/introduction#environments)):
* `POST /register-business`
* `GET /referred-businesses`
* `GET /referred-businesses/{business_uuid}/billing-status`
* `POST /referred-businesses/{business_uuid}/add-seats`
* `POST /referred-businesses/{business_uuid}/add-credits`
* Issued when Tyms onboards you as a **referral business partner** (distributor).
* Creates a **new** business and optionally returns that business’s Developer API keys when `grant_access` is `admin`.
* Seat and credit grants debit your **partner credit holding** (see [Partners](/partners-program)).
* After registration, use the returned **`tyms_sk_...`** for that customer’s day-to-day bookkeeping API calls — not the partner key.
Partner **program** onboarding (admin registration, contract terms, commission or prepaid structures) is handled outside this reference. If you are integrating as a partner, complete Tyms’s partner onboarding first so you receive partner credentials. Start with the [Partners guide](/partners-program) and **API reference** → **Partners**.
## Accepted header names
Send the key in **any one** of these headers (same value):
* `X-API-Key`
* `api-key`
* `sk`
## Developer API subscription
On protected routes, the business must meet Tyms’s **Developer API subscription** rules. If not, the API responds with **403 Forbidden** and an explanatory `message`.
## Validate a business key
To confirm a key and load business metadata, call **`GET /auth/validate`**. Request/response fields are documented on [Validate business](/api-reference/authentication/validate-business).
## Security practices
* Store **`tyms_sk_...`** and partner secrets in a **secret manager** or environment variables — never in client-side code or public repos.
* Rotate keys from the Tyms app if a secret is exposed.
* Prefer **TLS** only (`https://api.usetyms.com` or `https://staging-api.usetyms.com` for sandbox).
## Related reference
* [OAuth 2.0](/oauth) — third-party integration apps connecting Tyms users
* [API overview](/api-reference/overview) — errors, rate limits, UUID rules
* [Partners](/partners-program) — onboarding, billing models, and distributor routes
# Core concepts
Source: https://developer.usetyms.com/concepts
How the Tyms Developer API models businesses, AI processing, banking, and financial reporting.
## One business, one secret key
Almost every route is scoped to a **single Tyms business**. You prove which business with the **business API secret** (`tyms_sk_...`) in a header. The API never mixes data across businesses.
Business-scoped routes use a **business API secret** (`tyms_sk_...`). **Partner distributor** routes (register, list, billing, grants) use a **partner API key** instead. After registration, day-to-day calls for that customer use the **new business’s** `tyms_sk_...` returned when `grant_access` is `admin`.
## AI-assisted creation vs REST updates
**Creates** for invoices, bills, expenses, income, journals, contacts, chart-of-accounts entries, and **bank transactions (upload)** are built around a natural-language **`prompt`** (and optional **attachments**). That mirrors how Tyms works in the product: the backend interprets language and files, then writes structured records.
**Reads, updates, and deletes** use conventional REST patterns: list and get with query parameters; **PUT**/**PATCH**/**DELETE** with identifiers in the path. Update/delete paths accept **`uuid`** or **`source_uuid`** where documented in the [API overview](/api-reference/overview#uuid-resolution).
## Attachments and files
Several **POST** bodies accept an **`attachments`** array. Each element must be an **object** with required **`file`** and **`type`** (`base64`, `url`, or `raw`), and optional **`name`**. Base64 payloads must include **`"type": "base64"`** explicitly — the API does not infer encoding from the `file` string alone. This is required for correct handling and for bank-statement extraction.
Full field-level documentation: [Attachments](/api-reference/attachments).
## `process_type`: async vs direct
For AI create endpoints, **`process_type`** controls latency versus completeness:
| Value | Behavior |
| -------- | ---------------------------------------------------------------------------------------------------------------------- |
| `async` | **Default** for the Developer API on most creates. The request returns quickly while work continues in the background. |
| `direct` | Processing runs in the same request; you wait for the AI pipeline to finish. |
Bank transaction upload defaults to **`async`** on the Developer API unless you set `direct`.
## Banking and bank transactions
**Banks** are listed and fetched by UUID. **Bank transactions** can be listed, fetched, updated, and deleted like other resources.
**`POST /bank-transactions/upload`** is **not** a bulk JSON importer for arbitrary transaction arrays. It is the same **AI-assisted** flow as the product: a required **`prompt`** (and optional statement **attachments** and **`bank`** UUID) drives extraction and creation of statement lines.
## Financial reports and the in-app engine
These endpoints return financial reports **consistent with the Tyms app** (interactive docs under **API reference** → **Reports**):
* [Income statement](/api-reference/reports/income-statement)
* [Balance sheet](/api-reference/reports/balance-sheet)
* [Trial balance](/api-reference/reports/trial-balance)
* [Cash flow statement](/api-reference/reports/cash-flow-statement)
Responses are structured for dashboards and exports (headings, nested `content`, totals). Date ranges and optional journal filters are query parameters on each **GET**.
## Dates, amounts, and timezone
* Dates in your prompts can be natural language; dates in **structured** JSON bodies use **ISO 8601** dates (`YYYY-MM-DD`) unless an endpoint documents a different format (e.g. `date_format` on bank upload).
* Monetary amounts in **structured** JSON should be **numeric** (no currency symbols in the JSON value).
* The API uses **UTC** by default; the validated business profile exposes **`timezone`** for display and business context.
## Error model and limits
Failures return JSON with **`status: "failed"`** and a **`message`**. Rate limit metadata may appear in **`X-RateLimit-*`** headers. Details: [API overview](/api-reference/overview) and [Error handling](/guides/error-handling).
# AI Prompt Guidelines
Source: https://developer.usetyms.com/guides/ai-prompts
Best practices for creating records with AI prompts
When creating records using AI prompts, follow these guidelines for best results.
## Best Practices
### Be Specific
Include all relevant details in your prompts:
* Dates (e.g., "dated January 15, 2024" or "dated today")
* Amounts (e.g., "\$1,000" or "500.00")
* Contacts (e.g., "for customer ABC Company")
* Descriptions (e.g., "for web development services")
### Use Natural Language
Describe what you want in plain English. The AI understands natural language descriptions.
### Include Context
Mention related information to help the AI understand the full context of the record.
### Specify Dates
Always include dates in your prompts. Use formats like:
* "dated today"
* "dated January 15, 2024"
* "due in 30 days"
## Good Examples
```json Invoice theme={null}
{
"prompt": "Create an invoice for ABC Company for $1,000 for web development services, dated today, due in 30 days"
}
```
```json Bill theme={null}
{
"prompt": "Create a bill from XYZ Supplier for $500 for office supplies, dated January 15, 2024"
}
```
```json Expense theme={null}
{
"prompt": "Create an expense for $50 for lunch meeting with John Doe on January 20, 2024"
}
```
```json Contact theme={null}
{
"prompt": "Create a contact for John Smith, email john@example.com, phone +1234567890, customer type"
}
```
```json Bank transactions (upload) theme={null}
{
"prompt": "Import: 01/15/2024 -45.99 Uber; 01/16/2024 +2000.00 ACH Payroll ACME; include dates, amounts, debit/credit or +/-, narration, and references",
"bank": "your-bank-uuid"
}
```
## Bad Examples
Avoid vague prompts that lack essential information.
```json Too Vague theme={null}
{
"prompt": "Create invoice"
}
```
```json Missing Details theme={null}
{
"prompt": "Bill"
}
```
```json Incomplete theme={null}
{
"prompt": "Expense $50"
}
```
## Tips
* **Amounts in prompts**: Natural language can include `$` or plain numbers; in **structured** JSON bodies (e.g. payments), send **numeric** amounts without currency symbols unless an endpoint documents otherwise.
* **Dates**: Be explicit in prompts; structured bodies use `YYYY-MM-DD` where required.
* **Contacts**: Include names, emails, or phone numbers when relevant.
* **Bank upload**: `POST /bank-transactions/upload` **requires** `prompt` — describe or paste lines clearly. Optional [attachments](/api-reference/attachments) carry statement files.
* **`process_type`**: Use `async` for background processing (default on most AI creates) or `direct` when you need the result in the same HTTP response — see [Concepts](/concepts).
# Error Handling
Source: https://developer.usetyms.com/guides/error-handling
Understand API errors and how to handle them
For HTTP status summaries, subscription gates, and rate-limit headers, see [API overview](/api-reference/overview).
## Error Response Format
All errors follow a consistent format:
```json theme={null}
{
"status": "failed",
"message": "Error description"
}
```
## HTTP Status Codes
Request successful
Resource created successfully
Invalid request parameters or malformed request body
Invalid or missing API key
Business does not have an active subscription required for the Developer API
Resource not found
Server error. Please contact support if this persists.
## Common Errors
### Invalid API Key
```json theme={null}
{
"status": "failed",
"message": "Invalid API key. Please check your API key and try again."
}
```
**Solution**: Verify your API key is correct and included in the request header.
### No Active Subscription
```json theme={null}
{
"status": "failed",
"message": "Your business must have an active subscription to use the Developer API. Please upgrade your subscription to continue."
}
```
**Solution**: The Developer API requires a paid subscription. Upgrade your subscription plan to continue using the API.
### Resource Not Found
```json theme={null}
{
"status": "failed",
"message": "Invoice not found"
}
```
**Solution**: Check that the UUID or source\_uuid exists and is correct.
### Invalid Request Body
```json theme={null}
{
"status": "failed",
"message": "Invalid request body. Missing required field: prompt"
}
```
**Solution**: Ensure all required fields are included in your request body.
## Rate Limiting
API rate limits may apply. Check response headers for rate limit information:
* `X-RateLimit-Limit`: Maximum requests per time window
* `X-RateLimit-Remaining`: Remaining requests in current window
* `X-RateLimit-Reset`: Time when rate limit resets
If you exceed rate limits, you'll receive a 429 Too Many Requests response. Implement exponential backoff in your integration.
## UUID Resolution
All update and delete operations support both `uuid` and `source_uuid` for record identification. The API automatically checks both fields when looking up records.
**Example:**
* If you have a record with `uuid: "abc-123"` and `source_uuid: "xyz-789"`
* You can use either `abc-123` or `xyz-789` in the endpoint URL
* Both will resolve to the same record
## Best Practices
1. **Always check status codes** before processing responses
2. **Handle errors gracefully** with appropriate user feedback
3. **Implement retry logic** for transient errors (5xx status codes)
4. **Respect rate limits** by implementing request throttling
5. **Log errors** for debugging and monitoring
# Integration Examples
Source: https://developer.usetyms.com/guides/integrations
Integrate with Zapier, Make, and other platforms
Examples below use the **production** base URL (`https://api.usetyms.com/v1/adam`). For pre-production testing, use `https://staging-api.usetyms.com/v1/adam` with sandbox keys — see [Environments](/introduction#environments). Email [developer@usetyms.com](mailto:developer@usetyms.com) to request sandbox access.
## Zapier Integration
### Setup
1. **Create a Zapier App**: Use the HTTP Request action
2. **Authentication**: Configure API key in Zapier's authentication settings
3. **Triggers**: Use webhooks or polling to detect new records
4. **Actions**: Create records using POST endpoints with AI prompts
### Example: Create Invoice Trigger
```javascript Zapier Code theme={null}
const response = await fetch('https://api.usetyms.com/v1/adam/invoices', {
method: 'POST',
headers: {
'X-API-Key': bundle.authData.api_key,
'Content-Type': 'application/json'
},
body: JSON.stringify({
prompt: `Create an invoice for ${bundle.inputData.customer} for $${bundle.inputData.amount} for ${bundle.inputData.description}`
})
});
return response.json();
```
## Make (Integromat) Integration
### Setup
1. **HTTP Module**: Configure with base URL `https://api.usetyms.com/v1/adam`
2. **Authentication**: Add API key header (`X-API-Key`)
3. **Data Mapping**: Map your data to API request format
4. **Error Handling**: Handle API errors appropriately
### Example: HTTP Request Configuration
* **Method**: POST
* **URL**: `https://api.usetyms.com/v1/adam/invoices`
* **Headers**:
* `X-API-Key`: Your API key
* `Content-Type`: `application/json`
* **Body**:
```json theme={null}
{
"prompt": "{{1.prompt}}"
}
```
## cURL Examples
### Create Invoice
```bash cURL theme={null}
curl -X POST "https://api.usetyms.com/v1/adam/invoices" \
-H "X-API-Key: your_secret_key" \
-H "Content-Type: application/json" \
-d '{
"prompt": "Create an invoice for ABC Company for $1,000 for consulting services"
}'
```
### Update Invoice Payment
```bash cURL theme={null}
curl -X POST "https://api.usetyms.com/v1/adam/invoices/invoice-uuid/payments" \
-H "X-API-Key: your_secret_key" \
-H "Content-Type: application/json" \
-d '{
"payments": [
{
"amount_paid": 500.00,
"category": "Bank Transfer",
"date": "2024-01-20"
}
]
}'
```
### Get Contacts
```bash cURL theme={null}
curl -X GET "https://api.usetyms.com/v1/adam/contacts?page=1&limit=20" \
-H "X-API-Key: your_secret_key"
```
## JavaScript/Node.js Example
```javascript Node.js theme={null}
const axios = require('axios');
const apiClient = axios.create({
baseURL: 'https://api.usetyms.com/v1/adam',
headers: {
'X-API-Key': 'your_secret_key',
'Content-Type': 'application/json'
}
});
// Create invoice
async function createInvoice(prompt) {
try {
const response = await apiClient.post('/invoices', {
prompt: prompt
});
return response.data;
} catch (error) {
console.error('Error creating invoice:', error.response?.data || error.message);
throw error;
}
}
// Get invoices
async function getInvoices(page = 1, limit = 20) {
try {
const response = await apiClient.get('/invoices', {
params: { page, limit }
});
return response.data;
} catch (error) {
console.error('Error fetching invoices:', error.response?.data || error.message);
throw error;
}
}
```
## Python Example
```python Python theme={null}
import requests
class TymsAPI:
def __init__(self, api_key):
self.base_url = 'https://api.usetyms.com/v1/adam'
self.headers = {
'X-API-Key': api_key,
'Content-Type': 'application/json'
}
def create_invoice(self, prompt):
response = requests.post(
f'{self.base_url}/invoices',
headers=self.headers,
json={'prompt': prompt}
)
response.raise_for_status()
return response.json()
def get_invoices(self, page=1, limit=20):
response = requests.get(
f'{self.base_url}/invoices',
headers=self.headers,
params={'page': page, 'limit': limit}
)
response.raise_for_status()
return response.json()
# Usage
api = TymsAPI('your_secret_key')
invoice = api.create_invoice('Create an invoice for ABC Company for $1,000')
```
## Important Notes
* **Dates**: Use ISO 8601 (`YYYY-MM-DD`) in structured JSON where an endpoint requires a date field.
* **Amounts**: In structured JSON, use numeric amounts without currency symbols.
* **Timezone**: Defaults are documented in [Concepts](/concepts); validated business profile includes `timezone`.
* **AI creates**: Invoice, bill, expense, income, journal, contact, chart-of-accounts, and **`POST /bank-transactions/upload`** all use natural-language **`prompt`** (bank upload **requires** it — not a raw `transactions[]` bulk JSON importer). See [Create bank transactions (AI)](/api-reference/bank-transactions/create-bank-transactions-ai).
* **Partners**: New businesses are provisioned with [Register business](/api-reference/partners/register-business); day-to-day calls use each business’s `tyms_sk_...`.
* **UUID resolution**: Updates and deletes accept `uuid` or `source_uuid` where documented ([Overview](/api-reference/overview#uuid-resolution)).
# Introduction
Source: https://developer.usetyms.com/introduction
Tyms is the AI-Native Accounting Platform — integrate books, banking, and reports over a single REST API.
**Tyms** is the AI-Native Accounting Platform for small and medium-sized businesses across service, consulting, retail, and manufacturing. It automates bookkeeping workflows, understands natural language, and keeps financial data consistent with what business owners see in the product.
The **Tyms Developer API** is a REST surface on a single base URL so you can integrate Tyms into your own stack, marketplaces, or automation tools (Zapier, Make, internal ETL, partner onboarding flows, and more).
The Developer API is available when your business meets Tyms’s **Developer API subscription** rules. Without an active qualifying subscription, protected routes return **403 Forbidden**.
## Who this documentation is for
Product and engineering teams connecting **their** Tyms business to internal tools, billing systems, or workflows. You use the business **secret key** (`tyms_sk_...`) from Settings → API.
**Referral business partners** (distributors) who onboard **new** Tyms businesses and may grant Plus or credits from partner holding. You use a **partner** key for routes under **API reference** → **Partners**, then each business’s **secret key** for all other endpoints.
## What you can build
* **AI-assisted creates** — Invoices, bills, expenses, income, journals, contacts, chart-of-accounts lines, and **bank statement lines** from prompts plus optional files (see [Attachments](/api-reference/attachments)).
* **CRUD and reads** — List, get, update, and delete the same record types the app manages, scoped to one business per key.
* **Banking** — List banks and bank transactions; upload and categorize activity through the same AI-assisted pipeline as the app.
* **Financial reports** — Income statement, balance sheet, trial balance, and cash flow aligned with **in-app** Tyms reports ([Income statement](/api-reference/reports/income-statement) and sibling endpoints under **Reports**).
## Environments
The Developer API runs in **production** and **sandbox**. Paths, request bodies, and headers are the same in both environments — only the **host** and your **API keys** change.
| Environment | Base URL | Use for |
| -------------- | ----------------------------------------- | --------------------------------------- |
| **Production** | `https://api.usetyms.com/v1/adam` | Live businesses and real financial data |
| **Sandbox** | `https://staging-api.usetyms.com/v1/adam` | Pre-production integration and testing |
**Sandbox access is not self-service.** Email [developer@usetyms.com](mailto:developer@usetyms.com) to request a sandbox account and credentials before calling the staging host. Sandbox keys work **only** on the sandbox base URL; production keys from the Tyms app work **only** on production.
All paths in this reference are relative to the base URL for the environment you are using. Example: `GET /auth/validate` on production is `https://api.usetyms.com/v1/adam/auth/validate`; on sandbox it is `https://staging-api.usetyms.com/v1/adam/auth/validate`.
## Where to go next
Validate a key and send your first request in minutes.
How AI creates, async vs direct processing, and how reports relate to the product.
Business keys, partner keys, headers, and subscription expectations.
Connect Tyms users to your integration app without sharing secret keys.
Complete endpoint documentation lives under the **API reference** tab — start from the overview.
Connect Claude or ChatGPT to your Tyms business with the hosted MCP server — no local package to install.
# Authentication
Source: https://developer.usetyms.com/mcp/authentication
How Tyms MCP OAuth works and which Client ID to use for each platform.
Tyms MCP uses **OAuth**. You sign in with your Tyms account and approve access for a specific business. You do **not** paste API secret keys into Claude or ChatGPT.
## Client ID by platform
When an MCP client asks for a **Client ID** after you enter the MCP URL, use the ID that matches your platform:
| Platform | Client ID |
| --------------------------------------------------- | ------------------------ |
| **Claude** (Claude.ai, Claude Desktop, Claude Code) | `usetyms-mcp-claude` |
| **ChatGPT** | `usetyms-mcp-chatgpt` |
| **Perplexity** | `usetyms-mcp-perplexity` |
| **Any other client** (Cursor, etc.) | `usetyms-mcp-client` |
Enter the Client ID for **your** platform exactly as shown. Do not invent a different value. If your app is not Claude, ChatGPT, or Perplexity, use `usetyms-mcp-client`.
| Field | Value |
| -------------------- | ------------------------------ |
| **Auth type** | OAuth |
| **Read-only URL** | `https://mcp.usetyms.com` |
| **Read + write URL** | `https://mcp.usetyms.com/full` |
## How authentication works
Your MCP client connects to the Tyms MCP URL ([read-only or full](/mcp/endpoints)).
Enter the Client ID for your platform from the table above.
The client opens Tyms’ OAuth flow. You sign in and approve access for a business.
Tyms issues a short-lived connection for that client. Tool calls run as that connected business.
## What is shared (and what is not)
* Your Tyms credentials are **not** shared with Claude, ChatGPT, or Perplexity as raw API keys.
* The client receives a bridge token; Tyms keeps the upstream business tokens server-side.
* The assistant only sees data for the **business you approved** during OAuth.
## Tips
* Prefer the [read-only endpoint](/mcp/endpoints) unless you need write tools.
* Review tool calls before approving writes in your MCP client.
* If a client should no longer be connected, revoke access from your Tyms / integration settings.
For client-specific setup, see [Claude.ai](/mcp/clients/claude-ai), [Claude Desktop](/mcp/clients/claude-desktop), [Claude Code](/mcp/clients/claude-code), [ChatGPT](/mcp/clients/chatgpt), and [Perplexity](/mcp/clients/perplexity).
# What Tyms MCP can do
Source: https://developer.usetyms.com/mcp/capabilities
Capabilities by business domain for the read-only and full Tyms MCP endpoints.
Capabilities are grouped by business domain.
* On **`/mcp`** (read-only URL): only **read** tools are available.
* On **`/full`**: **read + write** tools are available.
Tools marked *(full)* require the [read + write endpoint](/mcp/endpoints).
## Chart of accounts
The business ledger. Includes all supported account types, including bank accounts.
* List / get accounts
* List allowed account types
* Create / update / delete accounts *(full)*
* Create account from a plain-language description via Adam *(full)*
## Banks
Bank account management.
* List / get banks
* Create / delete bank accounts *(full)*
## Bank transactions
Transactions from bank statements.
* List / get bank transactions
* Record or import transactions *(full)*
* Update / delete bank transactions *(full)*
## Contacts
Customers and vendors.
* List / get / search contacts
* Create / update / delete contacts *(full)*
* Create contact from a description via Adam *(full)*
## Invoices (accounts receivable)
Money customers owe you. May be unpaid, partly paid, or fully paid.
* List / get invoices
* Create / update / delete invoices *(full)*
* Record invoice payments *(full)*
* Create invoice from a description via Adam *(full)*
## Bills (accounts payable)
Regular payables. May be unpaid, partly paid, or fully paid.
* List / get bills
* Create / update / delete bills *(full)*
* Record bill payments *(full)*
* Create bill from a description via Adam *(full)*
## Expenses
Fully paid business expenses.
* List / get expenses
* Create / update / delete expenses *(full)*
* Create expense from a description via Adam *(full)*
## Income
Fully received income.
* List / get income
* Create / update / delete income *(full)*
* Create income from a description via Adam *(full)*
## Journals
Advanced / non-routine accounting (loans, investments, adjustments, etc.).
* List / get journal entries
* Create / update / delete journals *(full)*
* Create journal from a description via Adam *(full)*
## Inventory
Stock items, sales, and restocks.
* List / get inventory items
* Create / update / delete inventory *(full)*
* Sell stock / restock *(full)*
## Fixed assets
* List / get assets
* Create / update / delete assets *(full)*
## Quotes
* List / get quotes
* Create / update / delete quotes *(full)*
* Convert quote → invoice / income / prepaid income *(full)*
## Purchase orders
* List / get purchase orders
* Create / update / delete purchase orders *(full)*
* Convert purchase order → restock *(full)*
## Branches, departments, projects
Organization dimensions used across transactions and reporting.
* List / get (where available)
* Create / update / delete *(full)*
## Reports
Available on both endpoints (read-only tools):
* Balance sheet
* Income statement (P\&L)
* Cash flow statement
* Trial balance
* General ledger
* Account ledger
* Contact statement
## Adam vs manual tools
**Tyms** is the accounting platform. **Adam** is Tyms’ AI agent used on AI create tools (for example: “create invoice from a description”). Manual create/update tools talk to the Tyms API directly.
For prompt tips when asking Adam to create records, the same idea as the Developer API applies: be specific about dates, amounts, contacts, and descriptions. See also [AI Prompt Guidelines](/guides/ai-prompts) in the Documentation tab.
# ChatGPT
Source: https://developer.usetyms.com/mcp/clients/chatgpt
Connect Tyms MCP to ChatGPT using a custom MCP / Apps connector.
ChatGPT can connect to Tyms through custom MCP connectors (available on supported ChatGPT plans). UI labels may say **Connectors** or **Apps** depending on your plan and product updates.
## Before you start
| Field | Value |
| ----------------------------- | ------------------------------ |
| **Server URL (read-only)** | `https://mcp.usetyms.com` |
| **Server URL (read + write)** | `https://mcp.usetyms.com/full` |
| **Auth** | OAuth |
| **Client ID** | `usetyms-mcp-chatgpt` |
## Steps
Open ChatGPT settings for **Connectors** / custom MCP connectors.
Create a connector with:
* **Server URL:** `https://mcp.usetyms.com` (read-only) or `https://mcp.usetyms.com/full` (read + write)
* **Auth:** OAuth
* **Client ID** (when requested): `usetyms-mcp-chatgpt`
Sign in to Tyms when prompted and approve the business.
Turn the connector on in a chat before asking accounting questions.
## Domain verification (if asked)
If ChatGPT asks for a domain verification challenge, Tyms serves it at\
`https://mcp.usetyms.com/.well-known/openai-apps-challenge`.
## Example prompts
> Show expenses for March and highlight the top 5 categories.
> Pull the trial balance and flag any accounts that look unusual.
More: [Example prompts](/mcp/example-prompts).
## Tips
* Start on **read-only** unless you need ChatGPT to create or change records.
* Keep human confirmation on for write actions when using `/full`.
* For other platforms, see [Claude](/mcp/clients/claude-ai), [Perplexity](/mcp/clients/perplexity), or [Other clients](/mcp/clients/other).
# Claude.ai
Source: https://developer.usetyms.com/mcp/clients/claude-ai
Connect Tyms MCP to Claude on the web so you can ask about your books in chat.
Use Claude.ai when you want to work with Tyms from a browser chat.
## Before you start
Decide which URL to use:
| Access | URL |
| -------------------------------- | ------------------------------ |
| Read-only (recommended to start) | `https://mcp.usetyms.com` |
| Read + write | `https://mcp.usetyms.com/full` |
If Claude asks for a **Client ID**, enter:
```text theme={null}
usetyms-mcp-claude
```
## Steps
In Claude.ai, go to **Settings → Connectors**.
Click **Add custom connector**.
* **Name:** `Tyms` (or `Tyms Full` if you are using write access)
* **URL:** `https://mcp.usetyms.com` for read-only, or `https://mcp.usetyms.com/full` for read + write
Enter exactly: `usetyms-mcp-claude`
Click **Add**, then complete the Tyms OAuth login and approve the business you want Claude to use.
In a chat, open the attachments / tools menu and enable the Tyms connector.
## Try asking
> Show me unpaid invoices from last month and summarize cash on hand.
More ideas: [Example prompts](/mcp/example-prompts).
## Tips
* Prefer **read-only** until you are comfortable with what Claude can see and do.
* Keep confirmation prompts on before approving writes on `/full`.
* Using Claude on your computer instead? See [Claude Desktop](/mcp/clients/claude-desktop).
# Claude Code
Source: https://developer.usetyms.com/mcp/clients/claude-code
Add the Tyms remote MCP server to Claude Code over HTTP and complete OAuth.
Claude Code can connect to Tyms MCP over HTTP. Other MCP-compatible CLI clients that support remote MCP + OAuth can use the same URLs; labels in the UI may differ.
## Add the server
```bash theme={null}
# Read-only
claude mcp add --transport http tyms https://mcp.usetyms.com
# Read + write
claude mcp add --transport http tyms-full https://mcp.usetyms.com/full
```
## Complete OAuth
1. In a Claude Code session, run `/mcp`.
2. Follow the prompts to connect and authorize.
3. If the client asks for a **Client ID**, enter:
```text theme={null}
usetyms-mcp-claude
```
4. Sign in to Tyms and approve the business.
## Which URL should I use?
| Goal | Command / URL |
| ------------------------------------- | ------------------------------ |
| Lookups and reports only | `https://mcp.usetyms.com` |
| Create, update, delete, post payments | `https://mcp.usetyms.com/full` |
`/full` can change real business data. Prefer read-only unless you need write tools, and keep confirmation / approval on for destructive actions.
## After connecting
Ask accounting questions in natural language, for example:
> List unpaid invoices over 30 days and group them by customer.
See [Example prompts](/mcp/example-prompts) and [Capabilities](/mcp/capabilities).
# Claude Desktop
Source: https://developer.usetyms.com/mcp/clients/claude-desktop
Connect Tyms MCP in the Claude Desktop app using custom connectors.
Claude Desktop uses the same connector flow as Claude on the web. Once connected, you can ask about your Tyms books from the desktop app.
## Before you start
| Access | URL |
| -------------------------------- | ------------------------------ |
| Read-only (recommended to start) | `https://mcp.usetyms.com` |
| Read + write | `https://mcp.usetyms.com/full` |
**Client ID** (when asked):
```text theme={null}
usetyms-mcp-claude
```
## Steps
In Claude Desktop, open **Settings**, then go to **Connectors**.
Click **Add custom connector**.
* **Name:** `Tyms` (or `Tyms Full` for write access)
* **URL:**
* Read-only: `https://mcp.usetyms.com`
* Read + write: `https://mcp.usetyms.com/full`
Enter exactly: `usetyms-mcp-claude`
Click **Add**, sign in to Tyms, and approve the business.
Open a chat, open the attachments / tools menu, and enable the Tyms connector.
## Example
> What does our balance sheet look like as of today?
## Related
* Prefer the browser? See [Claude.ai](/mcp/clients/claude-ai).
* Working in the terminal? See [Claude Code](/mcp/clients/claude-code).
* Access levels: [Endpoints](/mcp/endpoints).
# Other clients
Source: https://developer.usetyms.com/mcp/clients/other
Use Tyms MCP from Cursor and other remote MCP + OAuth clients.
Dedicated Client IDs exist for:
* **Claude** → `usetyms-mcp-claude` ([Claude.ai](/mcp/clients/claude-ai), [Desktop](/mcp/clients/claude-desktop), [Code](/mcp/clients/claude-code))
* **ChatGPT** → `usetyms-mcp-chatgpt` ([setup](/mcp/clients/chatgpt))
* **Perplexity** → `usetyms-mcp-perplexity` ([setup](/mcp/clients/perplexity))
For **any other** MCP-compatible client (for example **Cursor**), use the generic Client ID below — if the client supports **remote MCP** (Streamable HTTP) and **OAuth**. Client UI labels vary.
## Values to enter
| Field | Value |
| ----------------------------- | ------------------------------ |
| **Server URL (read-only)** | `https://mcp.usetyms.com` |
| **Server URL (read + write)** | `https://mcp.usetyms.com/full` |
| **Client ID** (when asked) | `usetyms-mcp-client` |
| **Auth** | OAuth |
## Typical flow
1. Add a remote / custom MCP server in your client.
2. Paste the Tyms URL for the access level you want.
3. If asked for a Client ID, enter `usetyms-mcp-client`.
4. Complete Tyms OAuth and approve a business.
5. Enable the server / tools for the session, then ask questions.
If a client only supports local stdio MCP servers (and not remote HTTPS + OAuth), it will not work with Tyms MCP as documented here. Tyms MCP is a **hosted remote** server — there is no local package to install.
## If something looks wrong
* You only see list/get tools → you are on the read-only URL; switch to `/full` for write tools. See [FAQ](/mcp/faq).
* Auth fails on Client ID → confirm you used `usetyms-mcp-client` for unknown clients (or the platform-specific ID if you are on Claude, ChatGPT, or Perplexity).
* Wrong business data → reconnect and approve the correct business during OAuth.
# Perplexity
Source: https://developer.usetyms.com/mcp/clients/perplexity
Connect Tyms MCP to Perplexity using the Perplexity Client ID.
Perplexity can connect to Tyms MCP if it supports remote MCP connectors with OAuth. Use the Perplexity-specific Client ID below — not the Claude, ChatGPT, or generic IDs.
## Before you start
| Field | Value |
| ----------------------------- | ------------------------------ |
| **Server URL (read-only)** | `https://mcp.usetyms.com` |
| **Server URL (read + write)** | `https://mcp.usetyms.com/full` |
| **Auth** | OAuth |
| **Client ID** | `usetyms-mcp-perplexity` |
## Steps
In Perplexity, open the settings where you add custom MCP servers or connectors.
Create a connector with:
* **Server URL:** `https://mcp.usetyms.com` (read-only) or `https://mcp.usetyms.com/full` (read + write)
* **Auth:** OAuth
* **Client ID** (when requested): `usetyms-mcp-perplexity`
Sign in to Tyms when prompted and approve the business.
Turn the connector on before asking accounting questions.
## Example prompts
> What does our balance sheet look like as of today?
> List unpaid invoices over 30 days and group them by customer.
More: [Example prompts](/mcp/example-prompts).
## Tips
* Prefer **read-only** unless you need write access.
* Keep confirmation prompts on for writes when using `/full`.
* Client IDs are platform-specific — see [Authentication](/mcp/authentication) if you also connect Claude or ChatGPT.
# Endpoints
Source: https://developer.usetyms.com/mcp/endpoints
Tyms MCP URLs for read-only and read + write access.
Tyms exposes two MCP endpoints so you can choose the right access level.
| Endpoint | Access | Use when |
| ------------------------------ | ---------------- | ------------------------------------------------------------------------------- |
| `https://mcp.usetyms.com` | **Read-only** | You want the assistant to look up data and run reports, but not change anything |
| `https://mcp.usetyms.com/full` | **Read + write** | You want the assistant to create, update, delete, and post transactions |
## URL notes
* Pasting `https://mcp.usetyms.com` is enough for read-only access (it routes to the MCP transport).
* You can also use `https://mcp.usetyms.com/mcp` for the same read-only server.
* Use `https://mcp.usetyms.com/full` only when you intentionally want write access.
The **/full** endpoint can create, update, and delete real business data. Prefer read-only unless you need write access, and keep confirmation prompts enabled in your MCP client.
## Connection details
Use these values when configuring any MCP client:
| Field | Value |
| ----------------------------- | ------------------------------ |
| **Server URL (read-only)** | `https://mcp.usetyms.com` |
| **Server URL (read + write)** | `https://mcp.usetyms.com/full` |
| **Auth** | OAuth |
| **Client ID (Claude)** | `usetyms-mcp-claude` |
| **Client ID (ChatGPT)** | `usetyms-mcp-chatgpt` |
| **Client ID (Perplexity)** | `usetyms-mcp-perplexity` |
| **Client ID (other clients)** | `usetyms-mcp-client` |
When a client asks for a **Client ID**, use the ID for that platform. Full list: [Authentication](/mcp/authentication).
## Read-only vs full at a glance
| Need | Use |
| ---------------------------------------------------------------- | ------------------------------ |
| Ask questions, analyze books, pull reports | `https://mcp.usetyms.com` |
| Bookkeep, create invoices/bills, post payments, manage inventory | `https://mcp.usetyms.com/full` |
Recommended pattern for teams:
1. Start everyone on **read-only**.
2. Enable **/full** only for trusted workflows.
3. Keep tool confirmation / human approval on for destructive actions (delete, payment posting, conversions).
See [Read-only vs full](/mcp/read-vs-full) for more guidance, and [Capabilities](/mcp/capabilities) for which tools appear on each endpoint.
# Example prompts
Source: https://developer.usetyms.com/mcp/example-prompts
Sample questions and commands to try with Tyms MCP in Claude or ChatGPT.
Use these as starting points. Be specific about dates, amounts, customers, and accounts for better results.
## Read-only
Works with `https://mcp.usetyms.com`:
> What does our balance sheet look like as of today?
> List unpaid invoices over 30 days and group them by customer.
> Show expenses for March and highlight the top 5 categories.
> Pull the trial balance and flag any accounts that look unusual.
> Show me unpaid invoices from last month and summarize cash on hand.
## Full (write)
Requires `https://mcp.usetyms.com/full`. Review each tool call before approving.
> Create an invoice for Acme Ltd for \$1,200 consulting, due in 14 days.
> Record that we paid the MTN bill of \$85 today from our main bank account.
> Add a new expense account called “Software subscriptions”.
> Restock 20 units of SKU-104 and then create a quote for the customer who asked about it.
> Convert quote Q-102 into an invoice.
## Tips for better answers
* Name the period clearly (“March 2026”, “last 30 days”, “as of today”).
* Name the customer, vendor, or account when you know it.
* On **/full**, say what you want created in one clear sentence (who, what, amount, due date).
* For AI-assisted creates, see [AI Prompt Guidelines](/guides/ai-prompts).
More on what each endpoint can do: [Capabilities](/mcp/capabilities).
# FAQ
Source: https://developer.usetyms.com/mcp/faq
Common questions about Tyms MCP, Client ID, endpoints, and supported clients.
## What Client ID should I use?
It depends on the platform:
| Platform | Client ID |
| --------------------------------- | ------------------------ |
| Claude (Claude.ai, Desktop, Code) | `usetyms-mcp-claude` |
| ChatGPT | `usetyms-mcp-chatgpt` |
| Perplexity | `usetyms-mcp-perplexity` |
| Any other MCP client | `usetyms-mcp-client` |
Enter the matching ID whenever the platform asks for a Client ID after you provide the MCP URL. See [Authentication](/mcp/authentication).
## Can I use sandbox?
This documentation covers **production** MCP: `https://mcp.usetyms.com` and `https://mcp.usetyms.com/full`.
## What’s the difference between Tyms and Adam?
**Tyms** is the accounting platform. **Adam** is Tyms’ AI agent used on AI create tools (for example: “create invoice from a description”). Manual create/update tools talk to the Tyms API directly.
## Why do I only see list/get tools?
You’re connected to the read-only endpoint (`/mcp`). Switch the connector URL to `/full` for write tools. See [Read-only vs full](/mcp/read-vs-full).
## Does MCP replace the Tyms API?
No. MCP is an assistant-friendly layer over Tyms business operations. Developers building custom apps should still use the [Tyms Developer API](/introduction).
## Which clients are officially supported today?
**Claude**, **ChatGPT**, and **Perplexity** each have a dedicated Client ID. Other MCP clients may work with `usetyms-mcp-client` if they support remote Streamable HTTP + OAuth. See [Other clients](/mcp/clients/other).
## Do I need to install a package?
No. Tyms MCP is a **hosted remote** server. You connect over HTTPS with OAuth — there is no local MCP package to install.
## Quick reference
```text theme={null}
Read-only URL: https://mcp.usetyms.com
Read + write URL: https://mcp.usetyms.com/full
Auth: OAuth
Client ID (Claude): usetyms-mcp-claude
Client ID (ChatGPT): usetyms-mcp-chatgpt
Client ID (Perplexity): usetyms-mcp-perplexity
Client ID (other): usetyms-mcp-client
```
# Overview
Source: https://developer.usetyms.com/mcp/overview
Connect Claude, ChatGPT, Perplexity, and other MCP clients to Tyms so your AI assistant can read — and optionally write — your accounting data securely.
The **Tyms MCP server** lets AI assistants work directly with your Tyms business through the [Model Context Protocol (MCP)](https://modelcontextprotocol.io).
Once connected, your assistant can:
* Look up accounts, contacts, invoices, bills, expenses, income, inventory, and more
* Run financial reports (balance sheet, P\&L, cash flow, trial balance, ledgers)
* With the **full** endpoint: create, update, and delete records — including AI-assisted creation powered by **Adam**, Tyms’ AI agent
Tyms MCP is a **hosted remote MCP server**. You do not install a local package. Your client connects over HTTPS and authenticates with OAuth against your Tyms business.
MCP access is available in **production**. Use the [production endpoints](/mcp/endpoints) below.
## Who this is for
Connect Claude, ChatGPT, or Perplexity to ask questions about your books, pull reports, or (with care) bookkeep in plain language.
Start on **read-only**, then enable write access only for trusted workflows that need to create or change records.
## What you need
1. A Tyms business you can sign into
2. An MCP client that supports **remote MCP** and **OAuth** (Claude, ChatGPT, and Perplexity are supported with dedicated Client IDs)
3. The correct [MCP URL](/mcp/endpoints) and the **Client ID for your platform**
## Quick start
Use **read-only** for lookups and reports, or **/full** only if you need the assistant to create, update, or delete data. See [Endpoints](/mcp/endpoints).
Follow the guide for [Claude.ai](/mcp/clients/claude-ai), [Claude Desktop](/mcp/clients/claude-desktop), [Claude Code](/mcp/clients/claude-code), [ChatGPT](/mcp/clients/chatgpt), or [Perplexity](/mcp/clients/perplexity).
Use the Client ID for **your** platform (Claude, ChatGPT, Perplexity, or the generic ID for other apps). See [Authentication](/mcp/authentication).
Sign in, choose the business, and finish OAuth. Then enable the Tyms connector in a chat and start asking questions.
## Connection details (quick reference)
| Field | Value |
| ----------------------------- | ------------------------------ |
| **Server URL (read-only)** | `https://mcp.usetyms.com` |
| **Server URL (read + write)** | `https://mcp.usetyms.com/full` |
| **Auth** | OAuth |
| **Client ID (Claude)** | `usetyms-mcp-claude` |
| **Client ID (ChatGPT)** | `usetyms-mcp-chatgpt` |
| **Client ID (Perplexity)** | `usetyms-mcp-perplexity` |
| **Client ID (other clients)** | `usetyms-mcp-client` |
When your MCP client asks for a **Client ID**, use the ID that matches that platform. Do not mix them up — for example, Claude should use `usetyms-mcp-claude`, not the ChatGPT or generic ID.
## Where to go next
Read-only vs full URLs and when to use each.
How OAuth works and which Client ID to use.
Step-by-step setup for Claude, ChatGPT, Perplexity, and more.
Tools by domain — accounts, invoices, reports, and more.
# Read-only vs full
Source: https://developer.usetyms.com/mcp/read-vs-full
Choose the right Tyms MCP endpoint for lookups versus bookkeeping.
| Need | Use |
| ---------------------------------------------------------------- | ------------------------------ |
| Ask questions, analyze books, pull reports | `https://mcp.usetyms.com` |
| Bookkeep, create invoices/bills, post payments, manage inventory | `https://mcp.usetyms.com/full` |
## Read-only
Best when you want Claude or ChatGPT to:
* Answer questions about your books
* List invoices, bills, expenses, contacts, and inventory
* Run financial reports
The assistant **cannot** create, update, or delete records on this endpoint.
## Full (read + write)
Best when you intentionally want the assistant to:
* Create or update invoices, bills, expenses, income, journals, and more
* Record payments
* Manage inventory (sell / restock)
* Convert quotes and purchase orders
* Use Adam to create records from plain-language descriptions
The **/full** endpoint can create, update, and delete real business data. Prefer read-only unless you need write access.
## Recommended pattern for teams
1. Start everyone on **read-only**.
2. Enable **/full** only for trusted workflows.
3. Keep tool confirmation / human approval on for destructive actions (delete, payment posting, conversions).
## Switching access
If you only see list/get tools, you are connected to the read-only endpoint. To get write tools, update the connector URL to `https://mcp.usetyms.com/full` and reconnect (complete OAuth again if your client requires it).
See [Endpoints](/mcp/endpoints) and [Capabilities](/mcp/capabilities).
# Security & privacy
Source: https://developer.usetyms.com/mcp/security
How Tyms MCP keeps access scoped to your business and what you should do to stay safe.
## How access is scoped
* OAuth connects a **specific Tyms business**; the assistant only sees that business’s data.
* Your Tyms credentials are **not** shared with Claude, ChatGPT, or Perplexity as raw API keys. The client receives a bridge token; Tyms keeps upstream business tokens server-side.
## Practical guidelines
* Use **[read-only](/mcp/endpoints)** unless write access is required.
* Review tool calls before approving writes in your MCP client.
* Revoke access from your Tyms / integration settings if a client should no longer be connected.
* Do **not** paste API secrets into chat; MCP OAuth is the supported path.
On `https://mcp.usetyms.com/full`, approved tool calls can create, update, and delete real records — including payments and conversions. Keep confirmation prompts enabled.
## Client ID
When asked for a Client ID, use the one for your platform:
| Platform | Client ID |
| ------------- | ------------------------ |
| Claude | `usetyms-mcp-claude` |
| ChatGPT | `usetyms-mcp-chatgpt` |
| Perplexity | `usetyms-mcp-perplexity` |
| Other clients | `usetyms-mcp-client` |
See [Authentication](/mcp/authentication).
# OAuth 2.0
Source: https://developer.usetyms.com/oauth
Let Tyms users authorize your integration app to access their business data without sharing secret keys.
Use OAuth when you build an **integration app** (Zapier, Make, a marketplace connector, or your own product) and need **Tyms users** to grant **your app** access to **their** business — instead of asking them to paste a long-lived `tyms_sk_...` secret.
Tyms issues your app a **public key** (`tyms_pk_...`) and **secret key** (`tyms_sk_...`). End users sign in through the Tyms consent screen, pick a business, and your app receives short-lived tokens scoped to that connection.
## When to use OAuth vs a business key
| Approach | Best for |
| -------------------------- | ---------------------------------------------------------------------------------------------------- |
| **Business `tyms_sk_...`** | Automating **your own** Tyms business ([Authentication](/authentication), [Quickstart](/quickstart)) |
| **OAuth** | Apps used by **many** Tyms customers, each connecting their own business |
Partner distributors still use a **partner key** for routes under **API reference** → **Partners**; OAuth is separate from that flow.
For pre-production testing, business-scoped API calls can use the [sandbox](/introduction#environments) host (`https://staging-api.usetyms.com/v1/adam`). Email [developer@usetyms.com](mailto:developer@usetyms.com) for sandbox integration app credentials.
## Credentials
| Credential | Who holds it | Used for |
| -------------------------------- | ----------------------------------------- | --------------------------------------------------------------------------------------------------- |
| `client_id` (`tyms_pk_...`) | Your integration app | Starting authorization; shown to users as your app identity |
| App `secret_key` (`tyms_sk_...`) | Your integration app (server-side only) | Exchanging codes, refreshing tokens, and authenticating API calls alongside the user's access token |
| `access_token` / `refresh_token` | Your integration app (per connected user) | Calling business-scoped endpoints on behalf of the user who authorized access |
Store the app **secret key** and all user tokens in a secret manager or secure server storage — never in client-side code or public repos.
## End-to-end flow
Call [Get authorization URL](/api-reference/oauth/get-authorization-url) with `client_id`, `redirect_uri`, `reference`, `privacy_url`, and `terms_url`.
Send the user to the `authorization_url` in the response. Tyms hosts sign-in and business selection at `https://app.usetyms.com/auth/oauth/self`.
After consent, the user lands on your `redirect_uri` with `reference`, `authorization_code`, and `business_id` as query parameters.
Call [Exchange authorization code](/api-reference/oauth/exchange-authorization-code) with your app `secret_key` and the code. Store `access_token`, `refresh_token`, `expires_at`, and `business_id`.
Send **both** your app `secret_key` and `Authorization: Bearer ` on every business-scoped request. See [Call with OAuth tokens](#call-business-endpoints-with-oauth).
`reference` is your correlation id for the connection attempt — generate a unique value per authorization and verify it matches on callback.
### Callback URL shape
```
https://yourapp.com/oauth/callback?reference=conn_abc123&authorization_code=AD...&business_id=...
```
Authorization codes expire in **10 minutes** and are **single-use**.
## Call business endpoints with OAuth
Every business-scoped request requires **both** credentials:
```bash cURL theme={null}
curl -sS -X GET "https://api.usetyms.com/v1/adam/invoices" \
-H "X-API-Key: tyms_sk_your_app_secret_key" \
-H "Authorization: Bearer access_token_from_exchange"
```
The Bearer token selects **which authorized business** the call acts on. Your app `secret_key` identifies your integration to Tyms.
Use [Validate OAuth session](/api-reference/oauth/validate-oauth-session) to confirm a token and read business profile fields (including `authentication_method: "oauth"` and expiry).
## Token lifetime and refresh
* **Access tokens** expire after **60 minutes** (`expires_at` in the exchange response).
* Call [Refresh access token](/api-reference/oauth/refresh-access-token) with your app `secret_key`, `refresh_token`, and `business_id` to obtain a new access token without sending the user through consent again.
* Call [Revoke access](/api-reference/oauth/revoke-access) when a user disconnects your app. Provide `business_id` and either `access_token` or `refresh_token`.
## Subscription requirement
The connected business must have an **active Tyms subscription** eligible for Developer API access. Businesses without a qualifying subscription cannot complete authorization; API calls return **403** if subscription lapses after connect.
## Common errors
| Situation | HTTP | What to do |
| ------------------------------------ | ----- | ------------------------------------------------- |
| Invalid `client_id` | `400` | Check `tyms_pk_...` from Tyms |
| No businesses on the account | `400` | User must belong to at least one business |
| Business without active subscription | `403` | User must pick a subscribed business or upgrade |
| Expired or reused authorization code | `400` | Start a new authorization |
| Bearer token without app secret | `401` | Send `X-API-Key` with your app `secret_key` |
| Invalid or expired access token | `401` | Refresh or re-authorize |
| Subscription lapsed after connect | `403` | Prompt user to restore subscription or disconnect |
| User lost business access | `403` | Treat as revoked; remove stored tokens |
## Related reference
* [API overview](/api-reference/overview) — errors, rate limits, response envelope
* [Authentication](/authentication) — business and partner API keys (non-OAuth)
* OAuth endpoints under **API reference** → **OAuth**
# Partners and Register business
Source: https://developer.usetyms.com/partners-program
How referral partners onboard businesses, cover Plus and AI costs from partner credit, and use the partner API surface.
Tyms works with **referral business partners** (distributors): organizations or individuals who introduce small and medium-sized businesses in service, consulting, retail, and manufacturing to the platform. Partners may earn **commissions** or work on **prepaid** commercial terms on behalf of those businesses—commercial terms are agreed during **partner onboarding** with Tyms, not via this public API.
This page explains the **integration story**. Request and response fields for each partner route are in **API reference** → **Partners**.
## Becoming a partner
1. **Apply and onboard** through Tyms’s partner program (sales or partner operations). Tyms registers you as a referral business partner and issues **partner API credentials** (partner secret key, often prefixed like `adam_partner_sk_...`).
2. **Agree commercial terms** (revenue share, prepaid wallets, support expectations, branding, etc.). Those details are **not** exposed on the Developer API; they are contractual.
3. **Top up partner credit** in the partner portal when you plan to grant Plus seats or transfer AI credits to referred businesses (see [Covering costs](#covering-costs-for-referred-businesses)).
4. **Integrate** using your partner key for partner routes (register, list, billing, grants), then each business’s **`tyms_sk_...`** for day-to-day bookkeeping API calls.
Partner routes expect a **partner** credential (`adam_partner_sk_...`), not a business `tyms_sk_` key. Send the partner secret in `X-API-Key` (or `api-key` / `sk`).
## Why Register business exists
Partners often need to:
* **Create** the Tyms business and owner account in one step.
* Optionally become an **admin** on that business so they can finish setup or support the owner.
* Optionally receive that business’s **Developer API keys** in the response so they can automate bookkeeping **on behalf of** the business they referred.
Only businesses created through this **partner** flow are attributed to you as referrer in Tyms’s systems. You receive **`api_secret_key`** in the success payload **only** when registration succeeds **and** you requested `grant_access: admin` (see reference).
## Covering costs for referred businesses
After Tyms onboards you, you purchase **partner credit** into your holding balance (partner portal — not this API). That balance is what seat grants and credit transfers draw from. You resell or bundle access to businesses you referred however your commercial terms allow.
When registering a business, `credit_from_referral_partner` (default `false`) controls who pays for **ongoing AI usage**:
| Registration flag | What it means |
| ----------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `false` | The business has its own credit ledger. You **grant** Plus seats and/or transfer credits from your holding when you want to cover their costs. |
| `true` | Tyms bills that business’s AI usage to **your** partner holding automatically. **Seat and credit grant endpoints are blocked** for that business — you are already managing usage centrally. |
If `credit_from_referral_partner` is `false`, you have two ways to put value on a referred business from your holding:
### Plus seats (recommended)
Use [Add seats](/api-reference/partners/add-referred-business-seats) to activate **Tyms Plus** for a period and license a seat count. Tyms debits your holding at **150 credits × seats × months** (150 AI credits per seat per month by default). The business receives matching AI credits on their ledger.
* **First call** — starts Plus for the requested `months` (default 1) and sets seat count.
* **Later calls** while that partner grant is still active — add seats for the **remaining** period only; holding cost and AI credits are **prorated**.
This is the approach we recommend: fixed seats, a clear subscription window, and predictable spend. The business can still cancel Plus from their own billing page; partner holding is not refunded.
### Transaction credits (pay as you go)
Use [Add credits](/api-reference/partners/add-referred-business-credits) to move AI credits from your holding to the business at **1:1** (100 holding credits → 100 usable AI credits). No Plus subscription required. Handy when plan-included credits run out, or when you prefer topping up usage instead of licensing seats.
Transferred credits expire **12 months** after the grant.
Seat grants and credit transfers only work for businesses **you referred** with `credit_from_referral_partner: false`. Check [Billing status](/api-reference/partners/get-referred-business-billing-status) before granting, and [List referred businesses](/api-reference/partners/list-referred-businesses) to reconcile your portal.
## End-to-end integration flow
Obtain your **partner secret** from Tyms after partner onboarding. Use it for all routes under **API reference** → **Partners** (`adam_partner_sk_...` in `X-API-Key`, `api-key`, or `sk`).
[Register business](/api-reference/partners/register-business) — owner profile, `business_name`, `password` (at least 8 characters, including a letter, a number, and a special character such as `!@#$%^&*`), optional locale fields, `credit_from_referral_partner`, and `grant_access` (`admin` | `editor` | `viewer`). On success you receive `business_uuid`; with `grant_access: admin` you also receive `api_public_key` and `api_secret_key`.
When `credit_from_referral_partner` is `false`, use [Add seats](/api-reference/partners/add-referred-business-seats) to subscribe the business to Plus from your holding, or [Add credits](/api-reference/partners/add-referred-business-credits) for a pay-as-you-go top-up. [Billing status](/api-reference/partners/get-referred-business-billing-status) shows seats, plan, and credit balance before and after.
Call **`GET /auth/validate`**, **`POST /invoices`**, **`GET /reports/income-statement`**, etc., with **`X-API-Key: tyms_sk_...`** from the registration response — **not** the partner key.
## API surface
All partner routes live on the same **`v1/adam`** base URL as the rest of the Developer API:
| Route | Purpose |
| --------------------------------------------------------- | --------------------------------------------------------- |
| `POST /register-business` | Create a referred business and optional admin API keys |
| `GET /referred-businesses` | Paginated list of businesses you referred |
| `GET /referred-businesses/{business_uuid}/billing-status` | Subscription, seats, and credit snapshot for one business |
| `POST /referred-businesses/{business_uuid}/add-seats` | Grant or extend Plus seats from partner holding |
| `POST /referred-businesses/{business_uuid}/add-credits` | Transfer AI credits from partner holding (1:1) |
## Sandbox testing
Partners can exercise partner routes and subsequent business-scoped calls against the [sandbox environment](/introduction#environments) (`https://staging-api.usetyms.com/v1/adam`) before production. Email [developer@usetyms.com](mailto:developer@usetyms.com) for sandbox partner and business credentials — staging keys are separate from production partner secrets.
## Support
* **API support:** [developer@usetyms.com](mailto:developer@usetyms.com)
* **Partner program enrollment:** contact your Tyms partner representative or [developer@usetyms.com](mailto:developer@usetyms.com) if you do not yet have partner credentials.
* **Sandbox access:** [developer@usetyms.com](mailto:developer@usetyms.com) for pre-production account setup.
# Quickstart
Source: https://developer.usetyms.com/quickstart
Validate your API key and call the Tyms Developer API in under five minutes.
This guide assumes you already have a **business secret key** (`tyms_sk_...`) from the [Tyms app](https://app.usetyms.com) → **Settings** → **Business settings** → **API**. Partners provisioning new businesses should start with [Partners](/partners-program) and [Register business](/api-reference/partners/register-business).
**Integrating before go-live?** Use the [sandbox environment](/introduction#environments) at `https://staging-api.usetyms.com/v1/adam`. Email [developer@usetyms.com](mailto:developer@usetyms.com) to get a sandbox account and staging keys — app-issued production keys are not valid on staging.
## Prerequisites
* A qualifying Developer API subscription for the business (see [Authentication](/authentication)).
* `curl`, or any HTTP client that can set custom headers.
## Step 1: Validate your key
Confirm the key is valid and read back business profile fields (currency, country, timezone, etc.).
```bash cURL theme={null}
curl -sS -X GET "https://api.usetyms.com/v1/adam/auth/validate" \
-H "X-API-Key: YOUR_TYMS_SK_SECRET"
```
```javascript JavaScript theme={null}
const res = await fetch('https://api.usetyms.com/v1/adam/auth/validate', {
headers: { 'X-API-Key': 'YOUR_TYMS_SK_SECRET' },
});
const body = await res.json();
console.log(body);
```
```python Python theme={null}
import requests
r = requests.get(
"https://api.usetyms.com/v1/adam/auth/validate",
headers={"X-API-Key": "YOUR_TYMS_SK_SECRET"},
)
print(r.json())
```
**Success** responses use the shape documented on [Validate business](/api-reference/authentication/validate-business). **401** means the key is wrong or missing; **403** usually means the business is not allowed to use the Developer API yet.
## Step 2: Create a record with AI (optional)
Most **create** routes expect a JSON body with at least `prompt`. By default, processing is **async**; set `process_type` to `direct` if you need the work to finish in the same HTTP round-trip (slower).
```bash cURL theme={null}
curl -sS -X POST "https://api.usetyms.com/v1/adam/invoices" \
-H "X-API-Key: YOUR_TYMS_SK_SECRET" \
-H "Content-Type: application/json" \
-d '{
"prompt": "Create an invoice for ACME LLC for $250 for consulting, dated today, due in 14 days"
}'
```
See [AI prompt guidelines](/guides/ai-prompts), [Create invoice (AI)](/api-reference/invoices/create-invoice-ai) in the **API reference** tab, and [Attachments](/api-reference/attachments).
## Step 3: Pull structured data
List resources with pagination and ordering, then **get** by `uuid` or `source_uuid` where supported.
```bash theme={null}
curl -sS -G "https://api.usetyms.com/v1/adam/invoices" \
-H "X-API-Key: YOUR_TYMS_SK_SECRET" \
--data-urlencode "page=1" \
--data-urlencode "limit=20"
```
## Next steps
* Read [Concepts](/concepts) for the mental model (AI vs REST, reports, identifiers).
* Use the **API reference** tab for every endpoint, query parameter, and body field.
* Partners: [Partners](/partners-program) → [Register business](/api-reference/partners/register-business).