> ## Documentation Index > Fetch the complete documentation index at: https://www.finta.com/docs/llms.txt > Use this file to discover all available pages before exploring further. # Retrieve balance sheet > Returns the balance sheet as of the given date. Defaults to today. The balance sheet is a point-in-time snapshot ("what do my balances look like as of this date?"), unlike the income statement and cash flow which measure activity over a range. The full statement is always returned. You cannot filter to a single section. ## OpenAPI ````yaml /openapi.yaml get /reports/balance_sheet openapi: 3.0.3 info: title: Finta API version: '1.0' description: > The Finta API provides programmatic access to your company's financial data, including transactions, journal entries, categories, and financial reports. ## Authentication Each API key is scoped to a single company. There is no company ID parameter. The key already knows which company it belongs to. If you have access to multiple companies, create a separate key for each. Authenticate by including your API key in the `Authorization` header: ``` Authorization: Bearer finta_... ``` ### 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__...`). 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. ## Rate Limits The API enforces two independent limits. Both surface as `429 Too Many Requests`, but they are distinct error codes with different retry guidance. ### Per-minute burst limit Authenticated requests are limited to **6,000 requests per 60 seconds** (100 per second) per API key. Unauthenticated requests (missing or invalid key) are limited to **120 requests per 60 seconds** per IP address. The window is **fixed**, not rolling. Each 60-second wall-clock interval is its own counter; all requests within that interval share it, and the counter resets to 0 in a single step at the next boundary. Available budget jumps from `0` back to the full bucket size (`6000` for authenticated API keys, `120` for unauthenticated IP buckets) instantaneously at the boundary, rather than aging out one slot at a time. Trust `X-RateLimit-Reset` for the exact reset timestamp. Every authenticated response (including 429s for this case) includes: | Header | Description | |--------|-------------| | `X-RateLimit-Limit` | Maximum requests per window (`6000` for authenticated requests, `120` for unauthenticated). | | `X-RateLimit-Remaining` | Requests remaining in the current window. | | `X-RateLimit-Reset` | Unix timestamp when the window resets. | On a 429 for this case, an additional header is included: | Header | Description | |--------|-------------| | `Retry-After` | Number of seconds until the next request is safe. | The error body is `type: rate_limit_error` / `code: rate_limit_exceeded`. **Retry guidance:** This case is retryable. Honor `Retry-After` as the minimum wait, then apply exponential backoff with jitter for any retries beyond the first (cap at a few minutes; abandon after a small number of attempts to avoid retry storms). Do not retry tighter than `Retry-After`. ### Monthly per-company limit Each company has a monthly cap on total API calls, independent of the per-minute burst: | Plan | Monthly cap | |------|-------------| | Formation | 10 | | Startup | 300 | | Growth | 30,000 | Counts reset at **midnight Pacific Time (US & Canada)** on the 1st of each month. This is the Finta application's configured time zone; the cap is computed in that zone, not in UTC. Consumers in other time zones should convert the local-midnight Pacific boundary to their own clock; note that the absolute UTC offset shifts by one hour twice a year for daylight saving (PST is UTC-8, PDT is UTC-7). Blocked requests are not counted toward the limit. The error body is `type: limit_error` / `code: monthly_limit_exceeded`, and the `message` field includes the reset date in human-readable form. **Retry guidance:** This case is **not retryable in the short term.** No `Retry-After` header is sent, deliberately, because the only meaningful remediation is to upgrade the plan (Settings -> Plans at app.finta.com) or wait until the 1st of the next month. Naive retry loops should branch on `error.code` and stop retrying when they see `monthly_limit_exceeded`. SDKs that auto-retry on 429 should look at `error.code` (or the absence of `Retry-After`) before re-issuing. ## Pagination List endpoints use cursor-based pagination. Pass `limit` to control page size (default 100, max 500). To fetch the next page, pass `starting_after` with the `next_cursor` value from the previous response. Responses include `object: "list"`, `url` (the canonical path of the collection, relative to the API host), `has_more` (whether more results exist), `next_cursor` (the ID to pass as `starting_after`), and `data` (the page of items). ## Amounts Every monetary field in the API follows two non-negotiable rules: 1. **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. This avoids floating-point precision errors in financial calculations. 2. **`_cents` suffix.** The field name always ends in `_cents` (e.g. `amount_cents`, `balance_cents`, `total_cents`, `net_income_cents`, `change_in_cash_cents`, `cash_cents`). If a field name does not end in `_cents`, it is not a monetary value. These rules apply to every monetary field across every endpoint (transactions, journal entries, income statement, balance sheet, cash flow). There are no exceptions and there is 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 Errors return a consistent JSON structure: ```json { "error": { "type": "invalid_request_error", "code": "resource_missing", "message": "The requested resource was not found.", "doc_url": "https://www.finta.com/docs/api-reference/errors#resource_missing" } } ``` ### Status codes | Status | Meaning | |--------|---------| | `200 OK` | Request succeeded. | | `400 Bad Request` | Request was malformed or had invalid parameters. | | `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. The fix is to regain access (reactivate the user, restore company access, restore an active subscription), not to get a new key. See the `Forbidden` response component for the four specific codes. | | `404 Not Found` | The requested resource, or the endpoint itself, does not exist. Unknown or renamed paths (for example an old hyphenated report path like `/reports/income-statement` instead of `/reports/income_statement`) return this same envelope with `type: invalid_request_error` and `code: resource_missing`, as JSON, regardless of the `Accept` header. | | `429 Too Many Requests` | Either the per-minute burst rate limit (retryable, with `Retry-After`) or the monthly per-company API call limit (not retryable in the short term, no `Retry-After`). Branch on `error.code` to distinguish the two and avoid retry storms on monthly exhaustion. See the Rate Limits section for the full retry guidance. | | `5xx` | An unexpected error on Finta's side. Retry with exponential backoff. | The `error.type` and `error.code` fields are stable identifiers safe to switch on programmatically. The `error.message` is human-readable and may change without notice. servers: - url: https://app.finta.com/api/v1 description: Production security: - bearerAuth: [] tags: - name: Company description: Retrieve company metadata - name: Categories description: List your chart of accounts categories - name: Transactions description: > Transactions are what your bank shows you: a single line like "AWS charged you $499." Most API consumers want transactions. For accounting-level detail, see Journal Entries. Amounts are in cents (e.g. `amount_cents: 49900` = $499.00). - name: Journal Entries description: > Journal entries are the accounting records that transactions create. A single $499 AWS charge becomes two journal entries: debit Software $499, credit Cash $499 (double-entry bookkeeping). Use journal entries when you need accounting-level detail. Amounts are in cents (e.g. `amount_cents: 49900` = $499.00). - name: Reports description: > Financial statements: income statement, balance sheet, and cash flow. Each report returns the complete statement for a single period. You cannot filter to one category or request multiple periods in one call. paths: /reports/balance_sheet: get: tags: - Reports summary: Retrieve balance sheet description: > Returns the balance sheet as of the given date. Defaults to today. The balance sheet is a point-in-time snapshot ("what do my balances look like as of this date?"), unlike the income statement and cash flow which measure activity over a range. The full statement is always returned. You cannot filter to a single section. operationId: getBalanceSheet parameters: - name: date in: query description: >- The as-of date for the balance sheet (YYYY-MM-DD). Defaults to today. schema: type: string format: date responses: '200': description: The balance sheet content: application/json: schema: $ref: '#/components/schemas/BalanceSheet' example: object: balance_sheet date: '2026-02-28' currency: USD cash_cents: 9800000 assets: total_cents: 12500000 categories: - category_id: cat_c2l3m4n5o6p7q8 name: Cash balance_cents: 9800000 position: 1 parent_category_id: null - category_id: cat_c3x4y5z6a7b8c9 name: Brex (Primary business account) balance_cents: 6500000 position: 1 parent_category_id: cat_c2l3m4n5o6p7q8 - category_id: cat_c4y5z6a7b8c9d0 name: Mercury (Checking) balance_cents: 2100000 position: 2 parent_category_id: cat_c2l3m4n5o6p7q8 - category_id: cat_c5z6a7b8c9d0e1 name: Brex (Treasury) balance_cents: 800000 position: 3 parent_category_id: cat_c2l3m4n5o6p7q8 - category_id: cat_c6a7b8c9d0e1f2 name: Stripe (Stripe) balance_cents: 400000 position: 4 parent_category_id: cat_c2l3m4n5o6p7q8 - category_id: cat_d3m4n5o6p7q8r9 name: Accounts Receivable balance_cents: 1500000 position: 2 parent_category_id: null - category_id: cat_e4n5o6p7q8r9s0 name: Prepaid Expenses balance_cents: 450000 position: 3 parent_category_id: null - category_id: cat_f5o6p7q8r9s0t1 name: Security Deposit balance_cents: 500000 position: 4 parent_category_id: null - category_id: cat_g6p7q8r9s0t1u2 name: Intangible Assets balance_cents: 250000 position: 5 parent_category_id: null liabilities: total_cents: 850000 categories: - category_id: cat_h7q8r9s0t1u2v3 name: Credit Cards balance_cents: 620000 position: 1 parent_category_id: null - category_id: cat_h8a9b0c1d2e3f4 name: Brex (Credit) balance_cents: 420000 position: 1 parent_category_id: cat_h7q8r9s0t1u2v3 - category_id: cat_h9b0c1d2e3f4g5 name: Ramp (Credit) balance_cents: 200000 position: 2 parent_category_id: cat_h7q8r9s0t1u2v3 - category_id: cat_i8r9s0t1u2v3w4 name: Accounts Payable balance_cents: 230000 position: 2 parent_category_id: null equity: total_cents: 11650000 categories: - category_id: cat_j9s0t1u2v3w4x5 name: Common Stock balance_cents: 10000 position: 1 parent_category_id: null - category_id: cat_k0t1u2v3w4x5y6 name: SAFE balance_cents: 5000000 position: 2 parent_category_id: null retained_earnings: beginning_balance_cents: 3315000 net_income_cents: 3325000 ending_balance_cents: 6640000 liabilities_and_equity_cents: 12500000 '400': $ref: '#/components/responses/InvalidDate' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '429': $ref: '#/components/responses/RateLimited' components: schemas: BalanceSheet: type: object required: - object - date - currency - cash_cents - assets - liabilities - equity - liabilities_and_equity_cents properties: object: type: string enum: - balance_sheet date: type: string format: date example: '2026-03-16' currency: type: string example: USD cash_cents: type: integer description: >- Total cash balance in cents. Same value as the Cash category in assets, elevated for convenience. example: 9800000 assets: $ref: '#/components/schemas/BalanceSheetSection' liabilities: $ref: '#/components/schemas/BalanceSheetSection' equity: $ref: '#/components/schemas/BalanceSheetEquity' liabilities_and_equity_cents: type: integer description: >- Sum of liabilities and equity in cents. Must equal assets.total_cents (accounting equation check). example: 12500000 BalanceSheetSection: type: object required: - total_cents - categories properties: total_cents: type: integer description: >- Total balance in cents for this section. Equals the sum of root-level categories (those with parent_category_id null). Do not sum all entries, as parent categories contain subtotals of their children. example: 12500000 categories: type: array items: $ref: '#/components/schemas/BalanceSheetCategoryEntry' BalanceSheetEquity: type: object required: - total_cents - categories - retained_earnings properties: total_cents: type: integer description: Total equity in cents. example: 11650000 categories: type: array items: $ref: '#/components/schemas/BalanceSheetCategoryEntry' retained_earnings: $ref: '#/components/schemas/RetainedEarnings' Error: type: object required: - error properties: error: type: object required: - type - code - message - doc_url properties: type: type: string enum: - authentication_error - permission_error - invalid_request_error - rate_limit_error - limit_error description: >- The error category. `authentication_error` (401) means the bearer credential was missing, malformed, or unrecognized. `permission_error` (403) means the credential was valid but the caller is not allowed to access the resource. `rate_limit_error` is for per-minute burst limits (retry shortly). `limit_error` is for monthly API call limits per company (upgrade or wait for reset). code: type: string enum: - invalid_api_key - user_inactive - user_removed_from_company - company_closed - subscription_required - resource_missing - parameter_missing - category_update_failed - rate_limit_exceeded - monthly_limit_exceeded - invalid_date_range - invalid_date description: A specific error code. message: type: string description: A human-readable description of the error. doc_url: type: string format: uri description: A link to documentation about this error. example: https://www.finta.com/docs/api-reference/errors#invalid_api_key param: type: string nullable: true description: The parameter that caused the error, if applicable. BalanceSheetCategoryEntry: type: object required: - category_id - name - balance_cents - position - parent_category_id properties: category_id: type: string description: Prefixed ID of the category. example: cat_c2l3m4n5o6p7q8 name: type: string description: Display name of the category. example: Cash balance_cents: type: integer description: >- Cumulative balance in cents as of the report date. Parent categories contain the subtotal of their children. To compute the section total, sum only root-level entries (those with parent_category_id null). example: 9800000 position: type: integer description: Sort order among siblings that share the same parent_category_id. example: 1 parent_category_id: type: string nullable: true description: >- Prefixed ID of the parent category within this section. Null means this is a top-level category in the section. When non-null, the referenced parent also appears in the same categories array with its own subtotal. Use this field to reconstruct the display hierarchy (e.g. Cash as a parent with individual bank accounts as children). example: null RetainedEarnings: type: object required: - beginning_balance_cents - net_income_cents - shareholder_dividends_cents - ending_balance_cents properties: beginning_balance_cents: type: integer description: Retained earnings balance at the start of the period. example: 3315000 net_income_cents: type: integer description: Net income for the period. example: 3325000 shareholder_dividends_cents: type: integer description: >- Dividends paid to shareholders during the period. Negative when dividends were paid (a reduction in retained earnings); zero when no dividends were paid. example: 0 ending_balance_cents: type: integer description: >- Retained earnings balance at the end of the period. Equals beginning_balance_cents + net_income_cents + shareholder_dividends_cents. example: 6640000 responses: InvalidDate: description: >- A date query parameter was present but could not be parsed as a date, so the request was rejected instead of silently defaulting. `param` names the offending query parameter. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: type: invalid_request_error code: invalid_date message: >- The `date` value "banana" is not a valid date. Use ISO 8601 format, for example 2025-12-31. doc_url: https://www.finta.com/docs/api-reference/errors#invalid_date param: date Unauthorized: description: >- Authentication failed. Returned when the bearer credential itself is missing, malformed, or unrecognized. The consumer should obtain a valid API key and retry. This is distinct from `403 Forbidden`, which is returned when the credential is valid but the caller is not allowed to access the resource. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: type: authentication_error code: invalid_api_key message: >- Invalid API key provided. Check that your API key is correct and active. doc_url: https://www.finta.com/docs/api-reference/errors#invalid_api_key Forbidden: description: >- The API key was successfully authenticated, but the caller is not allowed to access this resource. The fix is not "get a new key" (that returns 401) but "regain access" (reactivate the user, restore company access, restore an active subscription). Four codes can be returned, distinguished by `error.code`: - `user_inactive` - the user that owns the API key has been deactivated. - `user_removed_from_company` - the user no longer has access to the company the key was created for. - `company_closed` - the company is closed, closing, or deleted. - `subscription_required` - the company does not have an active subscription. content: application/json: schema: $ref: '#/components/schemas/Error' examples: user_inactive: summary: User has been deactivated value: error: type: permission_error code: user_inactive message: >- The user associated with this API key is no longer active. Reactivate the user or create a new API key under an active user. doc_url: >- https://www.finta.com/docs/api-reference/errors#user_inactive user_removed_from_company: summary: User no longer has access to this company value: error: type: permission_error code: user_removed_from_company message: >- The user associated with this API key no longer has access to this company. Ask a company admin to re-grant access, then create a new API key. doc_url: >- https://www.finta.com/docs/api-reference/errors#user_removed_from_company company_closed: summary: Company is closed value: error: type: permission_error code: company_closed message: >- This company is closed. The API is not available for closed companies. doc_url: >- https://www.finta.com/docs/api-reference/errors#company_closed subscription_required: summary: Company subscription is not active value: error: type: permission_error code: subscription_required message: >- This company does not have an active subscription. Visit Settings -> Plans at app.finta.com to resolve, then retry. doc_url: >- https://www.finta.com/docs/api-reference/errors#subscription_required RateLimited: description: >- Too many requests. Two distinct limits can trigger a 429: (1) Per-minute burst limit (6,000 requests per 60 seconds per API key) returns `rate_limit_error` / `rate_limit_exceeded` with `Retry-After` header. (2) Monthly API call limit per company returns `limit_error` / `monthly_limit_exceeded` with the reset date in the message. Monthly limits vary by plan: Formation (10/month), Startup (300/month), Growth (30,000/month). Blocked requests do not count toward the limit. headers: Retry-After: schema: type: integer description: >- Seconds until the burst rate limit resets. Only present for rate_limit_error responses. X-RateLimit-Limit: schema: type: integer description: >- Maximum requests per burst window. Only present for rate_limit_error responses. X-RateLimit-Remaining: schema: type: integer description: >- Requests remaining in burst window (0 when rate limited). Only present for rate_limit_error responses. X-RateLimit-Reset: schema: type: integer description: >- Unix timestamp when the burst window resets. Only present for rate_limit_error responses. content: application/json: schema: $ref: '#/components/schemas/Error' examples: burst_rate_limit: summary: Per-minute burst rate limit exceeded value: error: type: rate_limit_error code: rate_limit_exceeded message: >- Too many requests. Please retry after the Retry-After period. doc_url: >- https://www.finta.com/docs/api-reference/errors#rate_limit_exceeded monthly_limit: summary: Monthly API call limit exceeded value: error: type: limit_error code: monthly_limit_exceeded message: >- Monthly API limit reached. Your plan allows 300 calls per company per month. Resets on April 1, 2026. Upgrade in Settings -> Plans at app.finta.com. doc_url: >- https://www.finta.com/docs/api-reference/errors#monthly_limit_exceeded securitySchemes: bearerAuth: type: http scheme: bearer description: API key prefixed with `finta_` ````