Core concepts

​

One business, one secret key

Almost every route is scoped to a single Adam business. You prove which business with the business API secret (tyms_sk_...) in a header. The API never mixes data across businesses. The only exception on this base URL is Register business, which uses a partner (distributor) API key to create a new business. After registration, all other 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 Adam 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.

​

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.

​

process_type: async vs direct

For AI create endpoints, process_type controls latency versus completeness: 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 Adam app (interactive docs under API reference → Reports):

• Income statement
• Balance sheet
• Trial balance
• 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 and Error handling.