> ## 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. # 1099 Filings > Read vendor filing progress, yearly summaries, and available documents Use [List 1099s](/docs/api-reference/forms/list-1099s) to answer both "Are our 1099s done?" and "Which vendors still need attention?" in one call. The response contains individual filing records in `data` and complete yearly overviews in `summaries`. Both list and [Retrieve 1099](/docs/api-reference/forms/retrieve-1099) require **API access: Manage** and **Taxes: View**, checked against the key owner's current company permissions. The credential selects the company; there is no company-ID parameter. These are read-only operations. Reading a record does not generate a report, request a W-9, pay for filing, or submit a form. ## Discovering years and records Call `GET /forms/1099` without a year to discover records across every available year. There is no implicit current-year default. The records are paginated, newest reporting year first, and `summaries` includes every existing annual report, including reports with zero required records. Pass `year=2025` for one reporting year, which is independent of the calendar year of submission. To retrieve pending records and the year's full progress together: ```bash theme={null} curl "https://app.finta.com/api/v1/forms/1099?year=2025&pending=true" \ -H "Authorization: Bearer finta_your_key_here" ``` ```json theme={null} { "object": "list", "url": "/api/v1/forms/1099", "has_more": false, "next_cursor": null, "summaries": [ { "year": 2025, "filing_status": "pending", "counts": { "review_required": 0, "required": 2, "pending": 1, "filed": 1 } } ], "data": [ { "id": "f1099_Example123", "object": "form_1099", "year": 2025, "vendor_name": "Example Consulting", "filing_status": "w9_requested", "filed_at": null, "filed_elsewhere": false, "documents": [], "created": 1769000000, "updated": 1769100000 } ] } ``` The summary counts the filed record even though `pending=true` removes it from `data`. **Only `year` scopes summaries.** Vendor and status filters, page size, and cursors affect individual records; they never turn yearly totals into filtered or page totals. ## Individual records and identity A record exists before a PDF is prepared. It can be awaiting review, awaiting W-9 collection, processing, filed, or marked not required. A filed record can still have `documents: []`. Use its stable `f1099_` ID to retrieve it directly: ```bash theme={null} curl "https://app.finta.com/api/v1/forms/1099/f1099_Example123" \ -H "Authorization: Bearer finta_your_key_here" ``` Retrieval returns the individual object directly, without the list envelope or summaries. No year or internal report selector is needed. Numeric database IDs are not accepted. The current filing workflow tracks merchant/category groups, so the same `vendor_name` can appear on multiple records in one year. Names are display labels, not unique recipient identities. Do not merge records by name or treat an `f1099_` ID as a vendor ID. Counts describe tracked filing records, not a deduplicated count of legal recipients or submitted PDFs. ## Filing stages | Individual `filing_status` | Meaning | | - | - | | `review_required` | Whether filing is required for this vendor record needs confirmation. | | `w9_required` | Filing is required; W-9 collection is needed, with no current W-9 request stage recorded through Finta. | | `w9_requested` | Finta recorded a W-9 request and the workflow is awaiting collection. | | `ready_to_file` | Ready for the user to pay and request filing; processing has not started. | | `filing` | Filing has been requested and is processing, not completed. | | `filed` | Recorded as complete through Finta or reported as filed elsewhere. | | `not_required` | The user or Finta marked the record as not requiring filing. | The UI's Filed tab also includes processing records, but the API's filed count does not. A stage describes recorded workflow progress, not IRS acceptance or whether a PDF is available. No separate requirement or W-9 status field is returned. Preserve unrecognized future stage values and treat them as unrecognized rather than claiming completion. Only `filed` establishes tracked completion. ## Yearly progress and counts | Summary `filing_status` | Meaning | | - | - | | `unknown` | No report exists for the explicitly requested year. | | `review_required` | At least one tracked vendor record is unconfirmed; this takes precedence over pending. | | `pending` | No unconfirmed records remain, but required filings remain incomplete. | | `filed` | All tracked required records are complete and at least one is filed. | | `not_required` | An existing report has no required or unconfirmed records, including an empty report. | | Count | Definition | | - | - | | `review_required` | Unconfirmed records, excluded from required and pending. | | `required` | Confirmed required records, including completed ones; always `pending + filed`. | | `pending` | Records in `w9_required`, `w9_requested`, `ready_to_file`, or `filing`. | | `filed` | Completed records through Finta or reported elsewhere; never includes `filing`. | Records marked not required contribute to none of these four counts, but remain in `data` unless filtered out. Summaries are newest year first and complete on every page. ### Empty results * A requested year without a report returns `200`, one `unknown` summary with zero tracked counts, and empty `data`. * An existing report with no required or unconfirmed records has summary status `not_required`. Its `data` may be empty or contain records marked not required. * With no reports and no year, both `summaries` and `data` are empty. * A vendor or status filter matching nothing leaves the yearly summary intact. `unknown` means there is no report to answer from, not that no forms are required. `not_required` summarizes Finta's known records; it is not an independent legal assessment or a guarantee that every relevant transaction has been imported. ## Filters and pagination | Parameter | Meaning | | - | - | | `year` | Exact four-digit reporting year, 1000–9999. Omit to discover all available years. | | `filing_status` | One public record stage or comma-separated stages, combined with OR. | | `pending` | Strict `true` or `false`. True selects confirmed required but incomplete records. False selects all other stages, including unconfirmed and not-required records. | | `vendor_name` | Case-insensitive exact display-name match; surrounding whitespace is ignored on both the query and stored name. A returned name can be reused as a filter. Blank is invalid. No substring or fuzzy matching. | | `filed_elsewhere` | Strict `true` or `false`. True selects filings reported outside Finta. False includes all other records, including pending ones. | | `limit` | Integer 1–500, default 100; applies to individual records only. | | `starting_after` | Previous opaque `next_cursor`, unchanged and URL-encoded. Do not substitute a form ID. | Matching normalizes names only for comparison; returned and stored display names retain their original whitespace. Different filters combine with AND. There is no default hiding not-required records. `pending` is a filter and a summary status, not an individual record stage. Examples, relative to `/api/v1`: ```text theme={null} GET /forms/1099 GET /forms/1099?year=2025&pending=true GET /forms/1099?year=2025&filing_status=review_required GET /forms/1099?year=2025&filing_status=w9_required,w9_requested GET /forms/1099?filing_status=filed&filed_elsewhere=true ``` Records sort by year descending, then stable record creation ID descending, independently of vendor name and workflow stage. Cursors bind the company and normalized record filters. Keep the same filters on later pages; `limit` may change. To change the filter, start a new traversal without a cursor. Malformed, foreign, or differently filtered cursors return [`400 invalid_request`](/docs/api-reference/errors#invalid_request). Pagination is not a frozen snapshot: concurrent changes can change which records match. Empty pages return `has_more: false` and `next_cursor: null`. See [Pagination](/docs/api-reference/pagination). ## Filing dates and documents All timestamps use Unix seconds. `filed_at` is the recorded filing time through Finta, or `null` when unknown, unfiled, or filed outside Finta. The time a user marks filed elsewhere and `updated` are never substituted for the actual filing date. `filed_elsewhere: true` accompanies stage `filed` and contributes to filed totals. It is false at other stages. Each available attachment has this shape; the URL is illustrative: ```json theme={null} { "id": "doc_0123456789abcdef01234567", "type": "form_1099", "filename": "2025 Example Consulting 1099.pdf", "content_type": "application/pdf", "download_url": "https://files.example.com/signed-1099.pdf", "expires_at": 1791850300 } ``` Document types are `w9` and `form_1099`. Signed links work without API authentication for five minutes. `expires_at` describes link expiration, not a filing deadline or when the stored file expires. Retrieve the filing record again to refresh an expired link. Opaque document IDs survive link refresh but change when the file is replaced. Use that identity rather than comparing signed URLs. There is no standalone document endpoint. MIME type is stored metadata, nullable when unknown; do not assume every attachment is a PDF. `created` and `updated` describe the tracked workflow record. `updated` is not a complete vendor-name/attachment-change watermark. These operations offer no `updated_after` filter, incremental-sync mode, or deleted-record feed. ## Errors and usage Invalid filters or malformed IDs return [`400 invalid_request`](/docs/api-reference/errors#invalid_request); `error.param` names the input to correct. Unknown and foreign-company `f1099_` IDs return the same [`404 resource_missing`](/docs/api-reference/errors#resource_missing), so the response does not disclose another company's records. Selected reports with invalid or missing years, missing public identities, or unsupported workflow data return [`503 forms_not_ready`](/docs/api-reference/errors#forms_not_ready), including empty reports with invalid years. Readiness is checked before vendor/status filters, so a filter cannot hide an unready record. A valid year filter excludes unrelated malformed reports. Retry a 503 with bounded exponential backoff. Reading does not start a backfill or repair the condition; contact support if it persists. Repair credentials or permissions before retrying 401/403. Existing [usage limits](/docs/api-reference/usage-limits) apply: honor `Retry-After` for burst-limit 429s, and stop short-term retries for monthly exhaustion, which sends no `Retry-After`. Both list and retrieve consume API calls, including retrieving again to refresh document links. Yearly summaries are included in the list call without an extra request. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.