Home/API Documentation

API Reference

Programmatic access to the Tomas Financial platform. Manage companies, documents, financial data, and more through our REST API.

Base URL: https://api.tomas.financial/v1Version: v1

Authentication

All API requests require an API key passed in the Authorization header. Create API keys in your Settings → API Keys page.

Request Header

Authorization: Bearer tf_live_YOUR_API_KEY_HERE
Content-Type: application/json

API Key Scopes

readRead-only access to your companies, documents, financial data, and reports.

writeRead and write access. Create documents, update records, and trigger exports.

adminFull access including team management and billing operations.

Security: Never expose your API key in client-side code, public repositories, or browser requests. Use server-side code or environment variables to store keys. Keys are shown only once at creation.

Rate Limits

API requests are rate-limited per key. Exceeding limits returns a 429 Too Many Requests response.

Scope	Limit	Window
Read	100 requests	per minute
Write	30 requests	per minute
Data Export	3 requests	per hour

Rate limit headers are included in every response: X-RateLimit-Remaining and X-RateLimit-Reset.

Error Handling

The API uses standard HTTP status codes. All error responses include a JSON body with a success field and an error message.

Error Response

{
  "success": false,
  "error": "Company not found"
}

Code	Meaning
`200`	Success
`400`	Bad request — invalid parameters or missing fields
`401`	Unauthorized — invalid or missing API key
`403`	Forbidden — API key lacks required scope
`404`	Not found — resource does not exist or is not accessible
`429`	Rate limit exceeded
`500`	Internal server error

Companies

Manage your companies and retrieve company details.

GET/v1/companiesread

List all companies associated with your account.

Response

{
  "success": true,
  "data": [
    {
      "id": "uuid",
      "name": "Acme Corp",
      "dba": null,
      "entity_type": "llc",
      "ein": "XX-XXXXXXX",
      "state": "CO",
      "industry": "Technology",
      "is_active": true,
      "created_at": "2024-01-15T00:00:00Z"
    }
  ]
}

GET/v1/companies/:idread

Get detailed information about a specific company, including subscription and service plan.

Parameters

iduuidrequiredCompany ID

GET/v1/companies/:id/financial-snapshotread

Get the latest financial summary for a company including revenue, expenses, net income, and key ratios.

Parameters

iduuidrequiredCompany ID

periodstringPeriod filter: "monthly", "quarterly", "yearly"

Documents

Upload, download, and manage documents for your companies.

GET/v1/companies/:id/documentsread

List all documents for a company. Supports pagination and filtering by type or status.

Parameters

iduuidrequiredCompany ID

typestringFilter by document type

statusstringFilter: "pending", "approved", "rejected"

limitnumberResults per page (default: 20, max: 100)

offsetnumberPagination offset

POST/v1/companies/:id/documentswrite

Upload a new document for a company. Send as multipart/form-data.

Parameters

filefilerequiredThe document file (max 10MB)

namestringrequiredDocument display name

typestringrequired"tax_return", "receipt", "bank_statement", "invoice", "other"

Financial Data

Access bookkeeping data including chart of accounts, journal entries, and bank transactions.

GET/v1/companies/:id/chart-of-accountsread

Retrieve the full chart of accounts for a company.

Response

{
  "success": true,
  "data": [
    {
      "id": "uuid",
      "account_number": "1000",
      "name": "Cash",
      "type": "asset",
      "sub_type": "current_asset",
      "balance": 50000.00,
      "is_active": true
    }
  ]
}

GET/v1/companies/:id/journal-entriesread

List journal entries with optional date range filtering.

Parameters

start_dateISO dateStart of date range (YYYY-MM-DD)

end_dateISO dateEnd of date range (YYYY-MM-DD)

limitnumberResults per page (default: 50, max: 500)

GET/v1/companies/:id/bank-transactionsread

Retrieve bank transactions with pagination. Ordered by date descending.

Parameters

start_dateISO dateStart of date range

end_dateISO dateEnd of date range

account_iduuidFilter by bank account

limitnumberResults per page (default: 50, max: 500)

offsetnumberPagination offset

GET/v1/companies/:id/vendorsread

List all vendors for a company.

Invoices & Bills

GET/v1/companies/:id/invoicesread

List invoices for a company with optional status filtering.

Parameters

statusstring"draft", "sent", "paid", "overdue", "void"

GET/v1/companies/:id/billsread

List bills for a company with optional status filtering.

Parameters

statusstring"pending", "approved", "paid", "void"

Tax

Access tax filings, checklist items, and calendar events.

GET/v1/companies/:id/tax/filingsread

List tax filings for a company.

Parameters

yearnumberFilter by tax year

GET/v1/companies/:id/tax/calendarread

Get upcoming tax deadlines and calendar events.

Reports

POST/v1/companies/:id/reports/generatewrite

Generate a financial report (PDF). Returns the report download URL.

Parameters

typestringrequired"profit_loss", "balance_sheet", "cash_flow", "trial_balance"

start_dateISO daterequiredReport period start

end_dateISO daterequiredReport period end

formatstring"pdf" (default) or "csv"

POST/v1/exportadmin

Export all your account data as a comprehensive JSON file. Rate-limited to 3 per hour.

Response

{
  "success": true,
  "data": {
    "exportedAt": "2024-03-15T10:30:00Z",
    "exportVersion": "2.0",
    "companies": [...],
    "documents": [...],
    "bankTransactions": [...],
    ...
  }
}

Quick Start

Example: Fetch your companies using cURL or JavaScript.

cURL

curl -X GET https://api.tomas.financial/v1/companies \
  -H "Authorization: Bearer tf_live_YOUR_API_KEY" \
  -H "Content-Type: application/json"

JavaScript (Node.js)

const response = await fetch('https://api.tomas.financial/v1/companies', {
  headers: {
    'Authorization': 'Bearer ' + process.env.TOMAS_API_KEY,
    'Content-Type': 'application/json',
  },
});

const { success, data } = await response.json();
if (success) {
  console.log('Companies:', data);
}

Python

import requests

headers = {
    "Authorization": f"Bearer {os.environ['TOMAS_API_KEY']}",
    "Content-Type": "application/json",
}

response = requests.get(
    "https://api.tomas.financial/v1/companies",
    headers=headers,
)
data = response.json()
print(data["data"])

Need help? Contact support@tomas.financial

API Version 1.0 — Last updated March 2026

Manage API Keys