API Introduction

The Finta API gives you programmatic access to your company’s financial data: transactions and the source accounts and cards behind them, split lines and spreads, journal entries, categories, departments, tags, automation rules, integration status, what the company’s Finta inbox is asking for, financial reports, key metrics such as cash, runway and revenue growth, R&D tax credits, tax filing progress and PDFs, vendor 1099 filing progress, and your team directory, plus the plans Finta offers and their limits, your company’s own plan and what it pays, and how much of each limit it has used. Most endpoints are read-only. Supported writes include: editing one transaction, editing up to 5,000 in one bulk update, creating a manual bank or credit account, adding a standard category template, creating, renaming or deleting a tag, uploading transactions from a bank or card file, the four operations on a team invitation (create, change its access, resend it, revoke it), the three on an automation rule (create, update, delete), starting an integration connection, the two ways to upload a tax PDF (a multipart request or a direct upload URL), and recording an income tax return or a Delaware franchise tax report the company already filed outside Finta. Invoices and departments are in early access. You can also generate PDF, CSV or Excel financial reports with the asynchronous report export API. It returns a job ID to poll and a download link when ready; generating a file does not edit your books.

To work with Finta from Claude or another AI tool, connect the MCP server. It signs in with your Finta account instead of an API key.

You can also create, list, read and edit spreadsheet documents, search authored cells, and permanently delete a document using its current revision. Create blank documents, use financial templates, or supply worksheets with values, formulas, formatting and charts. Read calls require Forecast: View; creation, editing and deletion require Forecast: Manage. PATCH edits cells, formulas, formatting, structure, worksheets and embedded charts in an ordered atomic batch at a known base_revision. An agent can request signup with only the user’s email through POST /signups, without an API key, company or OAuth grant. The user activates a one-hour email link in their browser and connects the MCP with Allow. The same 202 response is returned for every account state; existing accounts get no email. Follow next_step.message rather than treating success as proof of delivery. Signup is always available through REST and the signed-out MCP sign_up tool. See Agent signup for the flow, privacy, activation, and retry guidance.

Onboard a company

A new company can complete onboarding through the API or MCP: answer the company questions, submit them after confirmation, connect approved banks, follow the first import, and request a ready email. New OAuth and Plaid connections, including Chase and SVB, use the same API endpoints after approval; the user approves on the returned provider or Plaid Hosted Link page. For Plaid reconnects before or during the first import, follow the web get-started instructions in next_step.message, then send an empty-answer onboarding update. OAuth reconnects still use the API. Setup finishes automatically for API-started onboarding. Start with GET /onboarding and follow next_step.message. Saved drafts can resume in the web app, and unchanged answers saved on the web can be replayed through the API. After web bank connections, start_import requires an empty-answer PATCH. A finished web-started import returns finish_in_web: switch to the company named in the message, open the returned URL and choose See dashboard. Until the company is onboarded, other endpoints return 403 onboarding_incomplete, apart from the onboarding exceptions. Onboarding calls are free, and no API or MCP call consumes the monthly allowance before setup is complete.

Get your API key

Go to API Keys

Create a key

Click Create API key.

Copy the key

Copy the key immediately. It starts with finta_ and is only shown once. You cannot retrieve it later.

Each API key is tied to the user who created it and scoped to a single company. There is no company ID parameter; the key already knows which company it belongs to. If you manage multiple companies, create a separate key for each. If you are removed from a company, your key automatically loses access.

Permissions

A key acts as its owner rather than carrying scopes of its own. Company endpoints require the owner to currently hold API access: Manage, plus the permission the endpoint requires (for example Reports: View for reports, key metrics and journal entries, Taxes: View for tax-credit, tax-filing, and 1099 filing reads, Taxes: Manage to upload a tax PDF and record a return filed outside Finta, Transactions: View to read transactions, accounts, cards, and the company’s usage against its limits, Transactions: Manage to edit transactions, including assigning or removing a tag, create a manual account, upload transactions, match or unmatch a transfer, split a transaction or change or remove its split, or read a bulk update job, Accounting setup: View to read automation rules and tags, Accounting setup: Manage to add a category template or create, rename or delete a tag, Billing: View to read the company’s plan and what it pays, the Admin role to create or resend invitations, Team & access: Manage to edit or revoke them, Integrations: Manage and Transactions: Manage to connect an integration, Invoices: Manage and Transactions: Manage to match a deposit to one or more invoices, Reconciliation: View to read account reconciliations and their statement PDFs, or Reconciliation: Manage to reconcile or unreconcile a period or upload a bank statement PDF to attach). Because permissions are read live on every request, granting or revoking one takes effect on the very next call. There is nothing to reissue. See Permissions for the full endpoint-to-permission table and the 403 you get when something is missing. Both onboarding endpoints require Company: Manage and Integrations: Manage, in addition to API access. The shared onboarding service enforces these permissions on reads as well as writes.

Base URL

All requests go to:

https://app.finta.com/api/v1

Environments

There is no sandbox or test environment. Every request runs against your real company data, and every response reflects live production data. Write requests, such as categorizing a transaction, modify your live books.

Authentication

Company endpoints use your API key in the Authorization header as a Bearer token:

curl https://app.finta.com/api/v1/company \
  -H "Authorization: Bearer finta_your_key_here"

The public signup endpoint is the exception and needs no credential.

Key prefix convention

Every Finta credential is prefixed so it can be recognized at a glance in logs, error messages, and secret scanners. Today there is one credential type and its prefix is finta_. As additional credential or token types are introduced (for example restricted keys or webhook signing secrets), each will have its own distinct prefix that stacks on the brand prefix (e.g. finta_<type>_...). Treat the prefix as load-bearing: do not strip it before sending, and do not assume a missing or unknown prefix is still a Finta credential.

Content type

API endpoint responses are returned as JSON. Generated report files are downloaded from signed URLs returned in those responses. List and JSON report filters are passed as query strings. Most writes accept JSON request bodies. Sheet updates send base_revision and a name and/or operations in a JSON body. Sheet deletion takes base_revision in the query and accepts no body; success is HTTP 204 with no JSON body.

Pagination

List endpoints (/sheets, /sheets/{id}/cells, /accounts, /cards, /transactions, /journal_entries, /parties/merchants, /rules, /taxes, /tax_credits, /forms/1099, and /aggregations/totals) use cursor-based pagination. Responses are wrapped in a list envelope:

{
  "object": "list",
  "url": "/api/v1/transactions",
  "has_more": true,
  "next_cursor": "txn_h8i9j0k1l2m3n4",
  "data": [...]
}

Pass limit (default 100, max 500) to control page size, and starting_after with the next_cursor value to fetch the next page. Treat next_cursor as opaque and pass it back unchanged. There is no offset or page-number parameter. The url field carries the canonical path of the collection and is useful for logging and generic pagination helpers. /categories, /departments, /tags, /integrations, and /inbox are list endpoints too, but their result sets are small and bounded, so they always return everything in one response and omit has_more and next_cursor entirely. POST /transactions/{id}/match_invoices returns a list envelope with every invoice on the payment in one response: has_more: false and next_cursor: null. It does not paginate. /team is not a list endpoint at all. It returns a single team document with its own members and invitations arrays and no list envelope, so there is no object: "list", url, or data to read. If you keep a local copy of transactions, GET /transactions also has an incremental sync mode: pass updated_after and it returns only what changed since your last run, including deletions, plus a watermark to sync from next time. See Incremental Sync. GET /forms/1099 also includes complete yearly summaries on every page. Only the year filter scopes them; vendor/status filters and pagination affect individual records. See 1099 Filings for stages, counts, and empty states. GET /taxes likewise includes a summary of every tax year and type on every page, including years with no filing record (not_started). Only year and type scope them. See Tax filings. See Pagination for full parameters and an example fetch-all loop.

Monetary amounts

Financial-resource monetary fields follow two rules:

Integer cents. Monetary values are integers, never floats and never formatted strings. \$499.00 is 49900. \$1,500.00 is 150000. Divide by 100 to get dollars.
_cents suffix. The field name always ends in _cents (e.g. amount_cents, balance_cents, total_cents). If a field name does not end in _cents, it is not a monetary value.

Financial resources have no “summary” or “display” sibling that returns the same amount in dollars or as a string. Generic spreadsheet cell arrays are a scoped exception: they preserve worksheet units, so a cell amount of $20,000 is 20000, not 2000000. Formatting does not convert it to cents. See Sheets. Sign conventions:

Income statement: revenue/income amounts are positive, expense amounts are negative. Summing every section’s total_cents yields net income without sign-flipping.
Balance sheet: balance_cents carries the natural-sign cumulative balance for that account at the report date.
Cash flow: amount_cents is positive for cash inflows and negative for cash outflows.

Tax credit amounts can be null when unknown. Do not convert null to zero or interpret a payroll credit allocation as a refund received. See Tax credits for amount sources and the separate claim and payroll-submission statuses.

Reporting dates and freshness

The notes below describe JSON report reads. File exports can contain month/quarter/year columns, follow the company’s existing calendar/fiscal report settings, and read the books when the worker generates the file. Reports and category totals use exact inclusive calendar dates in America/Los_Angeles (Pacific Time). Use YYYY-MM-DD dates and determine today in Pacific Time, not from the UTC calendar date. Category-grouped income statements, balance sheets, cash flow, and category totals use fast rollups for whole months; and month-aligned ranges ending today use fresh MTD rollups. Other partial-month boundaries, including a midmonth start, read live journal entries and are slower. Full-date category totals previously selected whole months; they now honor the day. Report amounts remain day-exact. Response dates identify the boundaries actually used, and refreshed_at covers the whole answer, including MTD and live portions. Department-grouped income statements read the full range directly and return refreshed_at: null because that report path supplies no freshness timestamp. See Date sources and freshness for the fallback and legacy month rules.

Errors

The Finta API uses conventional HTTP status codes and returns every error in a consistent JSON envelope. Branch on error.type and error.code to handle errors programmatically; treat error.message as human-readable only and do not parse it. Export retrieval is a resource read: it returns HTTP 200 even for a terminal failed job. Inspect status, then its embedded error.code/error.message; those job details are separate from the HTTP error envelope below. See Report Exports.

{
  "error": {
    "type": "invalid_request_error",
    "code": "parameter_missing",
    "message": "Missing required parameter: start_date.",
    "param": "start_date",
    "doc_url": "https://www.finta.com/docs/api-reference/errors#parameter_missing"
  }
}

Status	Description
`200`	The request succeeded. A retrieved export may still have failed job status; inspect its resource state. Selected sheet reads can report calculation errors or unavailable results; inspect `calculation.status`.
`201`	Created. Usually a new record was saved; report-export replays are an exception. Returned by `POST /team/invitations` (note that its `changed` flag is `false`; the status code is what tells you the record is new), by `POST /rules` (where it confirms the rule is saved, not that historical application has finished), by `POST /integrations/{key}/connect` (a new connect request; calling again while one is open returns it with `200`), by `POST /accounts` (a new manual account; a matching manual account that already exists is returned with `200`), by `POST /transaction_uploads` (the call that opened a new upload; later calls on the same upload return `200`), by `POST /invoices`, by `POST /tags`, and by `POST /sheets`. Sheet creation saves the document before calculating optional return ranges; inspect `calculation.status` separately. Report-export creation and same-key replays both return 201; inspect the returned export status rather than assuming the job is new.
`202`	Accepted. `POST /transactions/bulk/update` accepts a job; read it at the `Location` header for its outcome. Public `POST /signups` returns identical verification instructions for every account state and confirms neither account creation nor email delivery.
`204`	No content. The request succeeded and there is no response body. Returned by `DELETE /team/invitations/{id}` and `DELETE /rules/{id}`, including when the record was already gone, and by successful `DELETE /sheets/{id}`. Successful `DELETE /tags/{id}` also returns `204`; repeating a tag or sheet deletion returns `404`.
`400`	Bad request. A required parameter is missing or invalid. Onboarding submission can return `answers_incomplete`; valid answers were saved and `missing` names what remains.
`401`	Unauthorized. The bearer credential is missing, malformed, or unrecognized. The fix is to obtain a valid API key.
`403`	Forbidden. The API key is valid, but the caller does not have permission to access the resource (deactivated user, removed from company, closed company, expired subscription, or a missing product-area permission). The fix is to regain access, not to get a new key. An early access endpoint or input, such as a department, that the company doesn’t have yet also returns `403`, with `feature_disabled`, or with `plan_upgrade_required` when a request names a department and the company’s plan doesn’t include departments. An unfinished company gets `onboarding_incomplete` outside the onboarding exceptions.
`404`	Not found. The endpoint path does not exist, or a requested resource is missing, hidden, or unsupported for that operation.
`409`	Conflict. Onboarding returns `onboarding_locked` for a change to a decided answer and `onboarding_complete` after setup finishes. Returned by `POST /tags` or `PATCH /tags/{id}` when the name already exists ignoring case (`tag_already_exists`). Also returned by `POST /rules` and `PATCH /rules/{id}` when the definition exactly matches an existing rule; the error message names that rule’s ID. Also returned by `POST /integrations/{key}/connect` when the integration is already connected or another user holds its open connection link, by `POST /transactions/bulk/update` when its `Idempotency-Key` was already used with a different body, by `POST /transaction_uploads` when the upload is already committed, and by the invoice endpoints when an invoice already exists, its status or payment doesn’t allow the change, or the change would break a bookkeeping rule. The reconciliation endpoints return it when a period is already reconciled or isn’t, isn’t the account’s latest reconciliation, belongs to a closed account, or the account’s transactions changed while reconciling. Report exports also return this when an Idempotency-Key identifies different inputs. Sheets return `revision_conflict` for a stale edit/deletion revision or changed search-pagination revision: reread and replan before retrying, rather than blindly replacing the revision. PATCH also returns `revision_history_mismatch` when legacy operation history needs support reconciliation; retrying does not fix it.
`422`	Unprocessable entity. The request was syntactically valid, but a business validation rejected the change. Reconciling returns `balance_mismatch` when Finta’s balance doesn’t match the statement balance.
`429`	A burst limit, signup email allowance, monthly call limit, or company export-capacity limit was reached. Branch on `error.code`; burst and signup email limits supply `Retry-After`. See Usage Limits.
`5xx`	Server error. Something went wrong on our end. The cases below carry stable codes to branch on. On the invitation endpoints: `invitation_create_failed`, `permissions_update_failed`, `invitation_resend_failed`, and `invitation_revoke_failed`, all safe to retry except the resend, which sends another email each time. On the rules endpoints: `rules_not_ready` and `rule_busy` (both `503`) and `rule_deletion_failed` (`500`), all retryable with backoff. On tag deletion or transaction tagging: `tag_busy` (`503`), retryable with the same request and backoff; a failed transaction PATCH changes no fields. On tag deletion: `tag_deletion_failed` (`500`), retryable with backoff. On `POST /integrations/{key}/connect`: `connect_link_failed` (`500`), retryable with backoff. On `GET /taxes`: `taxes_not_ready` (`503`), retryable with bounded backoff. On the 1099 endpoints: `forms_not_ready` (`503`), retryable with backoff. On `POST /accounts`: `account_create_failed` (`500`), retryable with the same body. On the reconciliation writes: `reconciliation_failed` and `unreconcile_failed` (`500`); read the period before retrying, since the change may have been saved. On `POST /categories`: `category_create_failed` (`500`), retryable with the same body. On `POST /transaction_uploads`: `upload_commit_failed` (`503`), retryable by committing again with the `upload_id` in the message. On the tax uploads: `tax_upload_failed` (`500`), retryable with the same `file_id`. For report exports, `503 report_export_failed` is retryable with the identical body and Idempotency-Key; a job may already exist.

See Errors for the full list of error codes with resolution steps.

Making your first request

For a company still setting up, begin with GET /onboarding and follow the onboarding guide. GET /company is gated until setup completes. For an onboarded company, verify your API key by pulling its metadata:

curl https://app.finta.com/api/v1/company \
  -H "Authorization: Bearer finta_your_key_here"

{
  "id": "comp_a1b2c3d4e5f6g7",
  "object": "company",
  "name": "Acme Corp",
  "legal_name": "Acme Corp Inc.",
  "entity_type": "c_corp",
  "federal_ein_last4": "6789",
  "incorporation": {
    "date": "2022-10-21",
    "state": "DE"
  },
  "legal_address": {
    "line_1": "548 Market Street",
    "line_2": "PMB 39381",
    "city": "San Francisco",
    "state": "CA",
    "postal_code": "94104",
    "country": "US"
  },
  "created": 1688053841
}

The full schema, including all field types and enum values (e.g. the closed set of entity_type values), is in the Retrieve Company reference. The id is included so you can cross-reference the company from other API responses, and as the disambiguator for the planned multi-company-keys feature; the endpoint is a singleton, so there is no GET /v1/company/{id}. To discover income-tax and Delaware franchise-tax workflows, call GET /taxes without filters first, then retrieve a record by its public ID. See Tax filings for the shared income workflow, statuses, and document links. To record a return filed outside Finta, see Tax uploads. The income statement accepts group_by=category (the default) or group_by=department for the . Both return one period with the same date parameters. See income statement grouping for response layouts and department access requirements. From here, try pulling one category total, the top merchants or month-by-month totals behind it, your income statement, key metrics such as runway and burn, or the journal entries behind a report. GET /integrations is another good first call: it takes no parameters and tells you whether the data behind everything else is still flowing. For integrations with a connection method whose connect_via is api, POST /integrations/{key}/connect returns a link a person opens to connect it, or reconnect an OAuth provider. The six supported Plaid banks use Plaid Hosted Link, with a private 30-minute link and no Finta sign-in; Plaid reconnect stays in the web app. GET /team also takes no parameters and returns the company’s members and pending invitations, and POST /team/invitations adds a new one. A pending invitation can then be changed with PATCH /team/invitations/{id}, sent again with POST /team/invitations/{id}/resend, or withdrawn with DELETE /team/invitations/{id}. The company’s categorization automations are readable and writable too: GET /rules lists them, and POST /rules saves a new one, optionally applying it to existing transactions. To understand how journal entries, transactions, aggregations, and reports fit together, see Data Model.

API Reference

Onboarding

Sheets

Taxes

Files

Company

Plans & billing

Team

Categories

Rules

Tags

Departments

Integrations

Inbox

Aggregations

Transactions

Forms

Reconciliation

Journal Entries

Invoices

Parties

Metrics

Reports

Feedback

Tax Credits

API Introduction

Onboard a company

Get your API key

Permissions

Base URL

Environments

Authentication

Key prefix convention

Content type

Monetary amounts

Reporting dates and freshness

Errors

Making your first request

​Agent signup

​Onboard a company

​Get your API key

​Permissions

​Base URL

​Environments

​Authentication

​Key prefix convention

​Content type

​Pagination

​Monetary amounts

​Reporting dates and freshness

​Errors

​Making your first request

Agent signup

Onboard a company

Get your API key

Permissions

Base URL

Environments

Authentication

Key prefix convention

Content type

Pagination

Monetary amounts

Reporting dates and freshness

Errors

Making your first request