> ## 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.

# Tax filings

> Discover income-tax and Delaware franchise-tax filing progress and available PDFs

Use [`GET /taxes`](/docs/api-reference/taxes/list-taxes) to discover your company's existing income-tax and Delaware franchise-tax filing records. Use [`GET /taxes/{id}`](/docs/api-reference/taxes/retrieve-tax) 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:

```bash theme={null}
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:

```json theme={null}
{
  "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](/docs/api-reference/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:

```bash theme={null}
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`](/docs/api-reference/errors#resource_missing) with `param: "starting_after"`. Restart from the first page with the filters you want. See [Pagination](/docs/api-reference/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 <Tooltip tip="Portable Document Format">PDF</Tooltip> 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:

```bash theme={null}
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](/docs/api-reference/usage-limits). |
| `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](/docs/api-reference/usage-limits).

```http theme={null}
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:

```http theme={null}
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](/docs/api-reference/errors) for the complete error reference, including [`taxes_not_ready`](/docs/api-reference/errors#taxes_not_ready).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.