> ## Documentation Index
> Fetch the complete documentation index at: https://developer.tyms.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Core 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`.

## Branches, departments, and projects

These are labels you can put on a transaction so reports can be split by location, team, or job. List them with `GET /branches`, `GET /departments`, and `GET /projects`. Create one first with `POST /branches`, `POST /departments`, or `POST /projects` when you already know the id you want to reuse.

On **invoices, bills, expenses, income, quotes, and purchase orders**, you can send either an id or a name when you create the document:

| What you are tagging | Id keys | Name key | If you leave it off | If the name is new |
| - | - | - | - | - |
| Branch | `branch` or `branch_uuid` | Not accepted | The business default branch is used | A branch is not created. Add it with `POST /branches`, then send its id. |
| Department | `department` or `department_uuid` | `department_name` | No department | Capitalization is ignored. If no department has that name, Tyms adds one and tags the document with it. |
| Project | `project_uuid` | `project_name` | No project | The name must match exactly, including capital letters. If none exists, Tyms adds an active project that starts today and ends in one month, then tags the document with it. |
| Team member | `employee` or `employee_uuid` | `employee_name` | No team member | If the full name is not already a team member, Tyms adds them. |

When both an id and a name are sent, the id is used and the name is ignored. An id that is not in this business is stored as you sent it. It does not create a branch, department, project, or team member, and it will not line up with one in reports.

Updates take ids only: `branch_uuid` (invoices, bills, expenses, and income also accept `branch`), `department_uuid` (those four also accept `department`), and `project_uuid`. A name on an update is ignored. Leave a field out to keep what is already on the document. An id that is not in this business is saved as sent and does not create anything.

**Journals** take ids on the journal itself: `branch` or `branch_uuid`, `department_uuid`, and `project_uuid`. Names are not accepted there, and a missing id does not create a department or project. Each journal line can set its own branch with `branch`, `branch_uuid`, or `branch_name`. The name is matched without regard to capital letters and must already be a branch. If it is not, the journal is not saved and no branch is created. A line with no branch uses the journal's branch.

**Contacts** accept `branch` or `branch_uuid`, and `department` or `department_uuid`. You can also send `branch_name` or `department_name` when creating a contact. Capitalization does not matter. If you send a name, that name is used even when an id is also present. A name that is not already a branch or department is added. On an update, `department_name` works the same way. Set the branch on an update with `branch` or `branch_uuid`.

**Assets**, when created, accept an id or a name: `branch_uuid` or `branch_name`, `department_uuid` or `department_name`, `project_uuid` or `project_name`, and `employee_uuid` or `employee_name`. Names are matched without regard to capital letters. A name that is not already on file is left blank — nothing is created. If the branch name is new, the asset uses the default branch instead. If you send an id, that id is kept even when it does not match an existing record. Updates take `branch_uuid`, `department_uuid`, and `project_uuid` only.

**Bank transactions** can be tagged on update with `branch_uuid`, `department_uuid`, and `project_uuid`. These are ids. Creating a bank line does not take these labels.

**Reports** filter with the query parameters `branch`, `department`, and `project`. Each value is the id, not the name. A value that does not match is simply left out of the report.

Invoice, bill, expense, and income lists accept `branch_uuid` and `department_uuid` as query parameters, using the same ids.

## 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](https://developer.tyms.io/api-reference/overview.md#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](https://developer.tyms.io/api-reference/attachments.md).

## `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](https://developer.tyms.io/api-reference/reports/income-statement.md)
* [Balance sheet](https://developer.tyms.io/api-reference/reports/balance-sheet.md)
* [Trial balance](https://developer.tyms.io/api-reference/reports/trial-balance.md)
* [Cash flow statement](https://developer.tyms.io/api-reference/reports/cash-flow-statement.md)

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](https://developer.tyms.io/api-reference/overview.md) and [Error handling](https://developer.tyms.io/guides/error-handling.md).


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