Skip to main content
Use 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 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:
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:
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

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

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

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

​
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:
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; error.param names the input to correct. Unknown and foreign-company f1099_ IDs return the same 404 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, 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 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.