Supplemental operations guide

This supplemental collects operational checks and future product ideas that are useful alongside the main API guide but are not part of the endpoint walkthrough.

Pre-publish and pre-submit checklist

Before publishing statements or submitting filings, confirm that:

the correct environment and credential are in use
the filer name/TIN pair is matched
a person reviewed missing, pending, or unmatched recipient TINs
every recipient has a usable delivery address or compliant electronic-delivery setup
the forms use the intended tax year and form type
prepareSnapshot completed and every intended filing is AWAITING_FILING
all errors were fixed and all warnings were reviewed
prepared recipient statements were downloaded and inspected
the prepared snapshot contains the intended tax-year data
the team is prepared to monitor authority responses and corrections after submission.

Prepare, publish, and submit actions may be run repeatedly, but they cannot overlap within the same tax year. Wait for the current operation to finish before starting another.

Preparation establishes what will be published or submitted. Changes and deletions made after prepareSnapshot do not change the latest prepared snapshot. Run prepareSnapshot again when those changes should be included. Publish and submit the prepared snapshot before preparing a newer one when recipient statements and filings must use exactly the same data.

Once a publish or submit action is accepted, a form included in that prepared snapshot can no longer be deleted. This restriction applies while the operation runs, after it finishes, and after later updates to the form. A form created after the protected snapshot remains deletable until a publish or submit action is accepted for a snapshot containing it.

Updating existing records

Retrieve the current filer, recipient, or form before changing it, then send the complete updated resource with PUT. A PUT replaces the writable fields, so include every writable value that should remain after the update rather than sending only the changed field.

Advanced conditional-update controls are documented in the OpenAPI specification.

Reconstructing what happened

The audit trail is distributed across operations, resource history, and statements. Use their shared generations to reconstruct what the platform processed:

Operation generation
  ├── Form current version or history
  │     ├── input used for that generation
  │     ├── federal and state filing statuses
  │     └── validation or authority problems
  └── Statement
        ├── preparation or publication status
        ├── published_at
        └── forms[].generation → exact form version

What action ran?

List operations under the applicable tax year. Each operation records whether it prepared, published, or submitted; the snapshot generation it used; its processing status; and its timestamps. A successful submission operation means Nutshell sent the eligible filings from that generation. It does not mean the taxing authorities accepted them.

What filing input was submitted?

Retrieve the form. Its top-level fields describe the current version, and history contains earlier generations in newest-first order. Each generation retains its own federal_filing_status, state_filings, and problems. A status of FILED shows that filing was submitted; later authority errors may move that generation to AWAITING_CORRECTION and add details to problems.

Filer and recipient reads also include history, allowing the client to recover the party data associated with an earlier generation.

What statement was created or published?

List statements for the tax year or recipient. PREPARED means the statement is available for review, PUBLISHED means it was furnished to the recipient, and published_at records when publication occurred. Retrieve a single statement to see its forms array. Each entry identifies the form and the exact form generation used to build the document.

Published statements are permanent historical records and accumulate when corrections are published. A later form update or snapshot does not rewrite an earlier published statement.

Product framing

Nutshell takes a filer's customer and tax data through four controlled steps: load, validate, deliver, and file. It keeps the recipient statement, government filing, status history, and correction workflow connected to the same underlying form.

Future scenario-based developer playground

A scenario-based developer playground could provide two guided journeys:

Digital-asset broker: one 1099-DA disposition, including basis, statement preview, and IRS submission states.
Business payer: one 1099-MISC rent or royalty payment.

Each scenario should explain the business event first, generate valid request data from the OpenAPI schema, show simulated responses, and visualize status changes. Live publishing and submission should remain disabled until the developer deliberately selects an environment and confirms the action.

Supplemental Operations Guide