Tax filings

Use GET /taxes to discover your company’s existing income-tax and Delaware franchise-tax filing records. Use GET /taxes/{id} to retrieve one record and refresh its document links. Both require API access: Manage and Taxes: View for the key owner. Your API key selects the company.

Discover records first

Start without filters so you can see the types, years, and jurisdictions Finta has recorded:

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

The response below uses illustrative IDs, timestamps, and a fictional document URL:

{
  "object": "list",
  "url": "/api/v1/taxes",
  "has_more": false,
  "next_cursor": null,
  "data": [
    {
      "id": "tax_income_example1",
      "object": "tax",
      "type": "income",
      "year": 2025,
      "jurisdictions": ["US", "US-CA"],
      "unmapped_jurisdictions": [],
      "filing_status": "review_required",
      "filed_at": null,
      "filed_elsewhere": false,
      "extension_filed_at": null,
      "documents": [
        {
          "type": "draft_return",
          "filename": "2025 Income Tax Draft.pdf",
          "content_type": "application/pdf",
          "download_url": "https://files.example.com/signed-draft.pdf",
          "expires_at": 1791850300
        }
      ],
      "created": 1769000000,
      "updated": 1791850000
    },
    {
      "id": "tax_franchise_example2",
      "object": "tax",
      "type": "franchise",
      "year": 2025,
      "jurisdictions": ["US-DE"],
      "unmapped_jurisdictions": [],
      "filing_status": "filed",
      "filed_at": 1771000000,
      "filed_elsewhere": false,
      "extension_filed_at": null,
      "documents": [],
      "created": 1769000000,
      "updated": 1771000000
    }
  ]
}

The list envelope uses the standard has_more, next_cursor, and data fields. An empty data array means no existing records match the request; it does not establish that the company has no tax obligations. Reading taxes does not create a filing or start filing work.

Understand one tax record

An income record covers federal income tax (US) and its recorded state jurisdictions, such as California (US-CA), under one shared filing workflow and document package. The record has one filing_status, filed_at, and extension_filed_at for that workflow. Filtering for California returns the whole record, including federal and other covered jurisdictions. These fields do not report independent federal and state filing outcomes. A Delaware franchise record has type: "franchise" and jurisdictions: ["US-DE"]. Its filing progress and documents describe the Delaware franchise filing. The year is the recorded tax year, not the calendar year of submission. Jurisdiction codes use US for federal and US- plus the state code for states or the District of Columbia. Washington, D.C. returns uploaded through Finta normalize to US-DC. unmapped_jurisdictions contains stored state names Finta could not normalize. Preserve these values if you need to inspect coverage; do not invent a code for them or assume the jurisdictions array includes every stored state when this array is nonempty. The read API exposes these existing filing workflows and their PDFs. It does not expose tax credits, balances due, or filing submission actions. Vendor 1099 filings have their own read endpoints; see 1099 Filings.

Filter and paginate

Every filter is optional:

Parameter	Meaning
`type`	`income` for an income-tax workflow or `franchise` for a Delaware franchise-tax workflow.
`jurisdiction`	`US` or a supported state code such as `US-CA`, `US-DE`, or `US-DC`. Matches membership in the record’s `jurisdictions`.
`year`	A four-digit recorded tax year, between `1000` and `9999`.
`status`	One of the five filing stages defined below.
`limit`	Page size, from `1` to `500`; defaults to `100`.
`starting_after`	The previous response’s `next_cursor`, passed back unchanged.

For example, find the income workflow covering California for tax year 2025:

curl --get https://app.finta.com/api/v1/taxes \
  -H "Authorization: Bearer finta_your_key_here" \
  --data-urlencode "type=income" \
  --data-urlencode "jurisdiction=US-CA" \
  --data-urlencode "year=2025"

Records sort by created descending, then public ID descending. When has_more is true, pass next_cursor as starting_after and keep the same filters on every page. When has_more is false, next_cursor is null. A cursor must still belong to the filtered company collection. If it is missing or no longer matches the filters, the list returns 404 resource_missing with param: "starting_after". Restart from the first page with the filters you want. See Pagination.

Read filing progress

filing_status describes the recorded workflow stage:

Value	Meaning
`onboarding`	Filing onboarding is not yet recorded as completed.
`preparing`	Onboarding is completed; draft preparation is not yet completed.
`review_required`	Draft preparation is completed; the income return needs review/signing, or the Delaware filing needs payment information.
`filing`	Review/signing is completed; filing completion is pending.
`filed`	The filing workflow is recorded as completed.

Use this status for filing progress. It does not establish tax payment or acceptance by a tax authority. Preserve an unfamiliar status if one is added later, rather than treating it as filed.

Interpret dates and documents

All timestamps are integer Unix seconds. Dates stay null when unavailable:

Field	Meaning
`filed_at`	Recorded workflow completion time, when known. It can be `null` even with `filing_status: "filed"`. For uploaded returns it may describe when Finta recorded completion.
`filed_elsewhere`	`true` for an uploaded income return or a Delaware filing marked already filed outside Finta.
`extension_filed_at`	Recorded income-extension filing time; `null` for franchise records or when no extension is recorded.
`created`	Parent filing record creation time.
`updated`	Parent filing record update time. It is not an incremental-sync watermark for related documents.

Never substitute updated for an unknown filing date. The tax endpoints do not offer an updated_after filter; re-read the record when you need its current status or documents. documents lists available attachments and can be empty even for a filed record:

Document `type`	Meaning
`draft_return`	Income return package before recorded filing completion.
`filed_return`	Income return package after recorded filing completion.
`filing_confirmation`	Available Delaware franchise filing confirmation.

Each document has filename, content_type: "application/pdf", download_url, and expires_at. Download URLs expire after five minutes. Treat each URL as a temporary credential and keep it private. To obtain a fresh link, retrieve the tax again:

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

Replace the illustrative ID with one returned by the list. Retrieval returns the tax object directly, without a list envelope. Use tax_income_ or tax_franchise_ IDs exactly as issued; their suffixes are opaque. Numeric database IDs are not accepted.

Handle errors

Status and code	What to do
`400 invalid_request`	Correct the filter, pagination parameter, or ID named by `error.param`.
`401 invalid_api_key`	Supply a valid bearer credential.
`403 insufficient_permission`	Restore API access: Manage and Taxes: View for the key owner. Other company-access failures also return `403`; use `error.code` to identify the reason.
`404 resource_missing`	Re-list for a visible ID, or restart pagination. Unknown, staff-only, and other-company IDs receive the same response.
`429 rate_limit_exceeded` or `monthly_limit_exceeded`	Follow the code-specific usage limit guidance.
`503 taxes_not_ready`	Retry with bounded exponential backoff; contact support if the error persists. This read does not start any repair or backfill work.

An invalid status filter returns this exchange. Rate-limit headers may also be present; see Usage limits.

GET /api/v1/taxes?status=paid HTTP/1.1
Host: app.finta.com
Authorization: Bearer finta_your_key_here

HTTP/1.1 400 Bad Request
Content-Type: application/json

{
  "error": {
    "type": "invalid_request_error",
    "code": "invalid_request",
    "message": "status is not a supported filing status.",
    "param": "status",
    "doc_url": "https://www.finta.com/docs/api-reference/errors#invalid_request"
  }
}

A well-formed tax ID not visible to the caller returns:

GET /api/v1/taxes/tax_income_absent HTTP/1.1
Host: app.finta.com
Authorization: Bearer finta_your_key_here

HTTP/1.1 404 Not Found
Content-Type: application/json

{
  "error": {
    "type": "invalid_request_error",
    "code": "resource_missing",
    "message": "Tax record not found.",
    "param": "id",
    "doc_url": "https://www.finta.com/docs/api-reference/errors#resource_missing"
  }
}

See Errors for the complete error reference, including taxes_not_ready.

API Reference

Taxes

Company

Team

Categories

Rules

Departments

Integrations

Aggregations

Transactions

Forms

Journal Entries

Invoices

Parties

Reports

Feedback

Discover records first

Understand one tax record

Filter and paginate

Read filing progress

Interpret dates and documents

Handle errors

​Discover records first

​Understand one tax record

​Filter and paginate

​Read filing progress

​Interpret dates and documents

​Handle errors

Discover records first

Understand one tax record

Filter and paginate

Read filing progress

Interpret dates and documents

Handle errors