Introduction

The Finta API gives you programmatic access to your company’s financial data: transactions, journal entries, categories, departments, integration status, financial reports, and your team directory. Most endpoints are read-only. There are five narrow writes: editing one transaction, and the four operations on a team invitation (create, change its access, resend it, revoke it).

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. Every request requires the owner to currently hold API access: Manage, plus the permission the endpoint requires (for example Reports: View for reports and journal entries, Transactions: Manage to edit a transaction, or Team & access: Manage for any of the invitation operations). 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.

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

Include 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"

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

All responses are returned as JSON. List and report filters are passed as query strings. Write endpoints accept JSON request bodies.

Pagination

List endpoints (/transactions, /journal_entries, and /parties/merchants) 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, and /integrations 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. /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. See Pagination for full parameters and an example fetch-all loop.

Monetary amounts

Every monetary field in the API follows two non-negotiable 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.

There are no exceptions and no “summary” or “display” sibling field that returns the same amount in dollars or as a string. If you encounter a field that appears to hold a monetary value but does not end in _cents, or whose value is not an integer, treat it as a bug and report it. 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.

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.

{
  "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`	Success.
`201`	Created. A new invitation was saved. Returned only by `POST /team/invitations`. Note that its `changed` flag is `false`; the status code is what tells you the record is new.
`204`	No content. The request succeeded and there is no response body. Returned only by `DELETE /team/invitations/{id}`, including when the invitation was already gone.
`400`	Bad request. A required parameter is missing or invalid.
`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.
`404`	Not found. The endpoint path does not exist, or a requested resource is missing, hidden, or unsupported for that operation.
`422`	Unprocessable entity. The request was syntactically valid, but a business validation rejected the change.
`429`	Rate limited. Either the per-minute burst limit (retryable, with `Retry-After`) or the monthly per-company call limit (not retryable in the short term, no `Retry-After`). Branch on `error.code` to distinguish the two.
`5xx`	Server error. Something went wrong on our end. The invitation endpoints are the four cases with a stable code to branch on: `invitation_create_failed`, `permissions_update_failed`, `invitation_resend_failed`, and `invitation_revoke_failed`. All are safe to retry except the resend, which sends another email each time.

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

Making your first request

Verify your API key by pulling your company’s 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}. From here, try pulling one category total, your income statement, 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. 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}. To understand how journal entries, transactions, aggregations, and reports fit together, see Data Model.

API Reference

Company

Team

Categories

Departments

Integrations

Aggregations

Transactions

Journal Entries

Parties

Reports

Introduction

Get your API key

Permissions

Base URL

Environments

Authentication

Key prefix convention

Content type

Monetary amounts

Errors

Making your first request

​Get your API key

​Permissions

​Base URL

​Environments

​Authentication

​Key prefix convention

​Content type

​Pagination

​Monetary amounts

​Errors

​Making your first request

Get your API key

Permissions

Base URL

Environments

Authentication

Key prefix convention

Content type

Pagination

Monetary amounts

Errors

Making your first request