openapi: 3.1.0 info: title: Nutshell Tax API version: v2.1.0 summary: The Nutshell Labs Tax API. description: | The key words "must", "must not", "should", "should not" and "may" are to be interpreted as described in [RFC 2119](https://datatracker.ietf.org/doc/html/rfc2119). They appear in lower case throughout. ## Conventions ### Snapshots and Generations Each resource carries a `generation`: a monotonically increasing integer identifying its input version. New and updated resources share a generation until you request `prepareSnapshot`. Subsequent creations and edits receive a higher generation; unchanged resources retain their existing generation. Use `prepareSnapshot` to capture all your filers, recipients and forms for a tax year and prepare them for filing and delivery. Review the resulting filings and recipient statements, then use `filings/submit` to send returns to the taxing authorities and `statements/publish` to deliver statements to recipients. Each operation identifies the snapshot it works with through its `generation`. Submission and publication use the latest prepared snapshot, including when you have edited or deleted resources since preparing it. For example, after preparing generation 3 and editing forms at generation 8, submitting the prepared filings still returns an operation at generation 3. Prepare another snapshot to use the edits. You can run one action at a time for a given tax year. Wait for its operation to finish before requesting the next action. ### Optimistic Concurrency Control Supply `If-Generation-Match` on a `PUT` or `DELETE` to require a particular resource generation. Use the value returned on the resource, for example `If-Generation-Match: 3`. A mismatch returns `412 Precondition Failed`; a missing resource returns `404 Not Found`. The header is optional. Multiple edits between snapshots share a generation. Among updates that match that same generation, the last update wins. ### Resource History A singular JSON GET for a filer, recipient or form returns its current fields and a top-level `history` array of earlier generations, newest first. Each entry contains the last input saved in that generation and its processing results. For example, a form's history shows the filing status and problems for a previously submitted version while you edit a correction. Later authority responses update that entry. Each generation has one entry, even if you edited the resource several times before preparing a snapshot. A resource with its first generation has an empty history. ### Client-Provided Attributes Clients often track their own metadata about filers, recipients, and forms—internal IDs, categories, or group labels. The Nutshell Tax API allows clients to attach this data to any of these resources via the _client attribute, which accepts an arbitrary JSON object up to 1 KB in size. Because filtering uses CEL expressions, _client values—including nested fields and arrays—can be used as filter criteria when listing these resources. For example, you might choose to store your own `batch_id` or `tags` attributes within the `_client` object associated with a recipient: ```jsonc { "_client": { "batch_id": "123xyz", "tags": ["SPECIAL"], } } ``` and find all recipients matching those criteria later by constructing a CEL `filter` expression ``` (_client.batch_id == "123xyz") && ("SPECIAL" in _client.tags) ``` and using it as a `filter` (note: URL-encoded) when listing recipients: ``` GET /api/v2/{tax_year}/filers/{filer_id}/recipients?filter=%28_client.batch_id%20%3D%3D%20%22123xyz%22%29%20%26%26%20%28%22SPECIAL%22%20in%20_client.tags%29 ``` - Nutshell Labs strongly recommends that clients use consistent object schemas to maintain query performance. Failure to do so will result in slower processing. For example: | Expression | Selects | |---|---| | `_client.customer_id == "8827"` | Resources carrying a client's customer identifier | | `has(_client.batch_id) && _client.batch_id.startsWith("2026-Q4")` | Resources whose batch identifier falls in a quarter, where one was supplied at all | | `_client.routing.region == "us-west"` | A value nested within `_client` | | `updated_at > timestamp("2026-08-01T00:00:00Z") && _client.region == "us-west"` | A resource field and a client attribute together | **The serialized object is limited to 1KB (1024 bytes)**, and a larger one is a `400 Bad Request` reporting the size it was measured at. The limit applies to the object as a whole rather than to any attribute within it. **Keys used consistently filter better.** Clients are strongly encouraged to spell an attribute the same way on every resource that carries it, because filtering and query performance depend on it. `_client` is returned with the resource and is available in list filters. Updating it follows the same generation rules as other resource edits and preserves the resource's filing and TIN-matching statuses. ### Collections Every collection endpoint (e.g. `/api/v2/{tax_year}/forms`) returns its resources one page at a time and accepts a `filter` expression (see _Filtering_, below) that narrows results. Both mechanisms behave identically across the API. #### Filtering The `filter` query parameter accepts a [Common Expression Language](https://cel.dev/) (CEL) expression. The expression is evaluated once per resource in the collection; the response contains exactly the resources for which the expression evaluates to `true`. The client may omit the parameter, in which case the collection is returned in full. **The resource is the evaluation context.** A resource's own fields are the variables of the expression, addressed by unqualified name (for example, `created_at`, `tax_year`, and `filer_id`). **Client-provided attributes are addressed under `_client`.** For example, a resource carrying a `_client.batch_id` assigned by the client is retrieved with `_client.batch_id == "8827"` See [Client-Provided Attributes](#section/Client-Provided-Attributes) for more information. **A field carries the type it has in the resource.** The client must compare each field against a literal of that type: | Field type | Compares against | Example | |---|---|---| | Integer | An integer literal | `tax_year == 2026` | | Boolean | A boolean literal | `foreign_entity == true` | | Timestamp | `timestamp()` | `created_at > timestamp("2026-01-01T00:00:00Z")` | | String | A string literal | `filer_id == "acme-payroll-west"` | `tax_year` is an integer and must not be compared against `"2026"`. Dates are strings within an expression, `date_of_birth` included: it is a date on the resource, but in a filter it is compared as a string, and its ISO 8601 format orders correctly under string comparison. **The CEL standard library is available in full**: the comparison and boolean operators, `in`, `has()`, the string functions, the timestamp and duration built-ins, and the comprehension macros. Two properties of CEL warrant attention from clients accustomed to other query syntaxes. First, equality is expressed with `==`; a single `=` is a syntax error, not a comparison. Second, the expression must evaluate to a boolean: `filter=created_at` is a valid CEL expression and is not a valid filter. **A filter sent in a query string is an ordinary parameter value** and must be percent-encoded as one; an unencoded `&&` terminates the parameter and truncates the filter. **An invalid filter produces an error rather than an empty page.** The filter is validated before the collection is read. Exactly three cases return `400 Bad Request` with the problem type `invalid-filter` and the position of the fault in `detail`: an expression that does not parse, an expression naming a field on which the collection may not be filtered, and an expression whose result is not a boolean. | Expression | Selects | |---|---| | `created_at > timestamp("2026-01-01T00:00:00Z")` | Resources created since the start of the tax year | | `updated_at > created_at` | Resources changed since they were created | | `_client.customer_id == "8827"` | Resources carrying a client's customer identifier | | `updated_at > timestamp("2026-08-01T00:00:00Z") && _client.region == "us-west"` | A resource field and a client attribute together | #### Pagination Pagination follows [AIP-158](https://google.aip.dev/158). A `list` request takes `page_size` and `page_token`; the response carries `next_page_token` alongside the page. `page_size` is the maximum number of resources in one page. Omit it to accept the server's default of 50; a value above 250 is coerced down to 250 rather than rejected. The server can return fewer resources than asked for even where further pages remain, so a short page is not the end of the collection. `next_page_token` is sent back unchanged as the `page_token` of the next request. Tokens are opaque and are not constructed by clients; one the server does not recognize, or one that has expired, returns `400 Bad Request`. An empty `next_page_token` is the only signal that the collection has been exhausted. ### Error Responses When a request fails, this API returns a machine-readable error body following [RFC 9457, *Problem Details for HTTP APIs*](https://www.rfc-editor.org/rfc/rfc9457.html), served with the `application/problem+json` media type. Each problem document identifies the error condition with a `type` code, a short human-readable `title`, the HTTP `status` code, a `detail` string describing this particular occurrence, and an `instance` URI identifying the specific failed request. Because RFC 9457 permits extension members, some error types add fields carrying condition-specific data — for example, a validation failure may include a list of offending parameters. Clients should key their handling off the `type` code rather than the `title` or `detail` text, both of which may change; unrecognised `type` values should be treated according to the `status` code alone, and unrecognised extension members ignored. license: name: Proprietary identifier: LicenseRef-Proprietary contact: name: Nutshell Labs x-logo: url: data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHZpZXdCb3g9IjAuMjYyIDAuOTQxIDExOC4yMDMgMjEuMzE3IiByb2xlPSJpbWciIGFyaWEtbGFiZWxsZWRieT0idC1saWdodCI+CiAgPHRpdGxlIGlkPSJ0LWxpZ2h0Ij5OdXRzaGVsbCBMYWJzPC90aXRsZT4KICA8ZGVmcz4KICAgIDxsaW5lYXJHcmFkaWVudCBpZD0iZ2EtbGlnaHQiIHgxPSIwLjEzMjgiIHgyPSIwLjg2NzIiIHkxPSIxIiB5Mj0iMCI+CiAgICAgIDxzdG9wIG9mZnNldD0iMCIgc3RvcC1jb2xvcj0iIzUyMzlFRSIvPjxzdG9wIG9mZnNldD0iMSIgc3RvcC1jb2xvcj0iIzg5NzhGOCIvPgogICAgPC9saW5lYXJHcmFkaWVudD4KICAgIDxsaW5lYXJHcmFkaWVudCBpZD0iZ2ItbGlnaHQiIHgxPSIwIiB4Mj0iMSIgeTE9IjAuOTM0NCIgeTI9IjAuMDY1NiI+CiAgICAgIDxzdG9wIG9mZnNldD0iMCIgc3RvcC1jb2xvcj0iIzUyMzlFRSIvPjxzdG9wIG9mZnNldD0iMSIgc3RvcC1jb2xvcj0iIzg5NzhGOCIvPgogICAgPC9saW5lYXJHcmFkaWVudD4KICA8L2RlZnM+CiAgPGcgdHJhbnNmb3JtPSJ0cmFuc2xhdGUoMC4yNjIgMC45NDEpIj4KICAgIDxwYXRoIGZpbGw9InVybCgjZ2EtbGlnaHQpIiBkPSJNIDE3LjQzIDUuNTQ4IEMgMTUuNzc4IDIuNTg2IDEyLjMzOSAxLjU4MSA5LjE1NSAxLjg4NyBDIDguOTg0IDEuNDI4IDguNzEyIDEuMDE5IDguMzU1IDAuNzEzIEMgNy45OTcgMC4zODkgNy41NTQgMC4xNjggNy4wNzggMC4wNjYgQyA2LjYwMSAtMC4wMzYgNi4xMDcgLTAuMDE5IDUuNjQ3IDAuMTE3IEMgNS4xODggMC4yNTMgNC43NjIgMC41MDggNC40MjEgMC44NDkgQyA0Ljg4MSAwLjkgNS4zNDEgMS4wODcgNS43MTUgMS4zNDMgQyA2LjEwNyAxLjYxNSA2LjQxNCAxLjk3MyA2LjYxOCAyLjM5OCBDIDMuNzkxIDMuMTk5IDEuMDY3IDQuOTY5IDAuMjE2IDcuODY0IEMgMC4wOCA4LjMyMyAtMC40MzEgMTAuOTQ1IDAuODQ2IDEwLjI5OCBDIDAuOTMxIDEwLjI0NyAxLjAxNiAxMC4xNzkgMS4xMDEgMTAuMTExIEMgMi4yMjUgOS4wOSAzLjQ4NSA4LjIyMSA0Ljg0NyA3LjU1NyBDIDguNTI1IDUuNzUyIDEyLjc4MSA1LjM5NSAxNi43NjYgNi4zMzEgQyAxNi44NjggNi4zNjUgMTYuOTUzIDYuMzY1IDE3LjA1NSA2LjM2NSBDIDE3LjE3NCA2LjM2NSAxNy4yOTMgNi4yOTcgMTcuMzk1IDYuMjEyIEMgMTcuNDgxIDYuMTI3IDE3LjUzMiA1Ljk5MSAxNy41NDkgNS44NzIgQyAxNy41NDkgNS44MzggMTcuNTQ5IDUuODA0IDE3LjU0OSA1Ljc3IEMgMTcuNTMyIDUuNjg0IDE3LjQ5OCA1LjYxNiAxNy40NjQgNS41NDggWiIvPgogICAgPHBhdGggZmlsbD0idXJsKCNnYi1saWdodCkiIGQ9Ik0gMTYuOTk4IDcuODYyIEMgMTYuOTY0IDcuNzk0IDE2LjkzIDcuNzI2IDE2Ljg3OSA3LjY3NSBDIDE2LjgyOCA3LjYwNyAxNi43NzcgNy41NTYgMTYuNzI2IDcuNTA1IEMgMTYuNjQxIDcuNDM3IDE2LjUzOSA3LjQwMyAxNi40MzcgNy4zNjggQyAxNi4zNjggNy4zNTEgMTYuMyA3LjMxNyAxNi4yMzIgNy4zIEMgMTUuNzIxIDcuMTQ3IDE1LjIxMSA3LjAyOCAxNC42ODMgNi45NzcgTCAxNC42NDkgNi45NzcgQyAxNC40MjcgNi45NiAxNC4yMDYgNi45NDMgMTMuOTg1IDYuOTI2IEMgMTMuNTkzIDYuOTI2IDEzLjE4NSA2Ljk0MyAxMi43OTMgNi45OTQgTCAxMi43NDIgNi45OTQgTCAxMi42MDYgNy4wMjggQyAxMS43NTQgNy4xNjQgMTAuOTM3IDcuNDU0IDEwLjE4OCA3Ljg3OSBDIDEyLjEyOSA5LjI3NSAxMy42MSAxMS4yODQgMTQuMjkxIDEzLjY1MSBDIDE0LjM1OSAxMy44OSAxNC40MSAxNC4xMTEgMTQuNDYxIDE0LjM0OSBDIDE0LjQ2MSAxNC40IDE0LjQ5NiAxNC40NjggMTQuNDk2IDE0LjUxOSBDIDE0LjUzIDE0LjcwNyAxNC41NjQgMTQuOTExIDE0LjU5OCAxNS4xMTUgQyAxNC42MzIgMTUuMzM3IDE0LjY0OSAxNS41NzUgMTQuNjY2IDE1Ljc5NiBMIDguOTc5IDguMTM1IEMgOC44NiA4LjEzNSA4Ljc0MSA4LjEzNSA4LjYyMSA4LjEzNSBDIDguNDg1IDguMTM1IDguMzQ5IDguMTY5IDguMjEzIDguMTg2IEMgOC4xOTYgOC4xODYgOC4xNjIgOC4xODYgOC4xNDUgOC4xODYgTCA3Ljk3NCA4LjE4NiBDIDcuODcyIDguMjIgNy43NyA4LjIzNyA3LjY2OCA4LjI1NCBMIDcuNTMyIDguMjU0IEMgNy41MzIgOC4yNzEgNy40NDcgOC4yODggNy40NDcgOC4yODggQyA3LjMxIDguMzA1IDcuMTkxIDguMzM5IDcuMDU1IDguMzczIEwgNi45NTMgOC4zNzMgQyA2LjkwMiA4LjQwNyA2Ljg2OCA4LjQyNCA2LjgxNyA4LjQyNCBDIDYuNzMyIDguNDQxIDYuNjQ2IDguNDc1IDYuNTQ0IDguNDkyIEwgNi41MSA4LjQ5MiBDIDYuMzIzIDguNTYgNi4xMTkgOC42MTEgNS45MzEgOC42NzkgQyA1LjcxIDguNzQ4IDUuNTA2IDguODMzIDUuMjg0IDguOTE4IEwgNS4yMzMgOC45MTggQyA1LjIzMyA4LjkzNSA1LjE5OSA4Ljk1MiA1LjE5OSA4Ljk1MiBDIDQuNzIyIDkuMTM5IDQuMjYzIDkuMzYxIDMuODIgOS41OTkgQyAzLjA3MSAxMC4wMDggMi4zNzMgMTAuNTAxIDEuNzI2IDExLjA0NiBDIDEuNjA3IDExLjE0OCAxLjUwNCAxMS4yNjcgMS40MzYgMTEuNDA0IEMgMS4zODUgMTEuNTQgMS4zNjggMTEuNjkzIDEuMzg1IDExLjg0NiBDIDEuMzg1IDEyLjIzOCAxLjM4NSAxMi42MyAxLjQzNiAxMy4wMDQgQyAxLjUwNCAxMy42NTEgMS42NDEgMTQuMjgxIDEuODQ1IDE0Ljg5NCBDIDIuMSAxNS42NDMgMi40NDEgMTYuMzQxIDIuODg0IDE2Ljk4OCBDIDMuMzA5IDE3LjYzNSAzLjgyIDE4LjIxNCA0LjM5OSAxOC43NDIgQyA1LjQ4OSAxOS43MTMgNi44IDIwLjQyOCA4LjE5NiAyMC44NTMgQyA4LjcwNyAyMS4wMDcgOS4yMzQgMjEuMTQzIDkuNzYyIDIxLjIxMSBDIDEwLjQwOSAyMS4yOTYgMTEuMDczIDIxLjMzIDExLjczNyAyMS4zMTMgQyAxMS45OTMgMjEuMzEzIDEyLjIzMSAyMS4yOTYgMTIuNDg2IDIxLjI2MiBDIDExLjQ5OSAyMC43NjggMTAuNjMxIDIwLjEwNCA5Ljg4MSAxOS4yODcgQyA4LjE3OSAxNy40MzEgNy4yNTkgMTQuOTc5IDcuMjkzIDEyLjQ1OSBDIDcuMjkzIDEyLjQyNSA3LjI5MyAxMi4zNzQgNy4yOTMgMTIuMzQgTCA3LjM3OSAxMi40NDIgTCAxMy42NzggMjAuOTU1IEwgMTMuNzEyIDIwLjk5IEMgMTMuNzYzIDIwLjk5IDEzLjgzMiAyMC45NTUgMTMuOTUxIDIwLjkwNCBDIDE0LjM1OSAyMC43MTcgMTQuNzM0IDIwLjQxMSAxNS4wNzQgMjAuMTM4IEMgMTUuMzk4IDE5Ljg4MyAxNS42ODcgMTkuNTkzIDE1Ljk3NyAxOS4yODcgQyAxNi4yMTUgMTkuMDMxIDE2LjQyIDE4Ljc1OSAxNi42MjQgMTguNDg3IEMgMTcuMjIgMTcuNjM1IDE3LjY2MiAxNi42ODIgMTcuOTUyIDE1LjY3NyBDIDE3Ljk1MiAxNS42NzcgMTcuOTUyIDE1LjY2IDE3Ljk1MiAxNS42NDMgQyAxNy45NjkgMTUuNTc1IDE3Ljk4NiAxNS41MDcgMTguMDAzIDE1LjQ1NiBDIDE4LjAwMyAxNS40NTYgMTguMDAzIDE1LjQzOSAxOC4wMDMgMTUuNDIyIEMgMTguMDIgMTUuMzM3IDE4LjAzNyAxNS4yNjkgMTguMDU0IDE1LjE4NCBDIDE4LjM0NCAxMy43ODcgMTguMzQ0IDEyLjM0IDE4LjA1NCAxMC45NDQgQyAxNy44MzMgOS44NTQgMTcuNDQxIDguODE2IDE2LjkxMyA3LjgyOCBaIi8+CiAgPC9nPgogIDxwYXRoIGZpbGw9IiMwQjBCMEYiIGQ9Ik0yNS42NSAxNi44MlY2LjM4SDI3LjE0TDMyLjQ3IDE0LjM4VjYuMzhIMzMuOTZWMTYuODJIMzIuNDdMMjcuMTQgOC44MlYxNi44MlpNMzguODMgMTdRMzcuOTUgMTcgMzcuMyAxNi42NVEzNi42NSAxNi4yOSAzNi4zIDE1LjU3UTM1Ljk1IDE0Ljg1IDM1Ljk1IDEzLjc2VjkuMzFIMzcuNDRWMTMuNjFRMzcuNDQgMTQuNjYgMzcuOSAxNS4yUTM4LjM2IDE1LjczIDM5LjIzIDE1LjczUTM5LjgyIDE1LjczIDQwLjI5IDE1LjQ1UTQwLjc2IDE1LjE3IDQxLjAzIDE0LjYzUTQxLjMgMTQuMSA0MS4zIDEzLjMyVjkuMzFINDIuNzlWMTYuODJINDEuNDVMNDEuMzUgMTUuNTRRNDEuMDEgMTYuMjIgNDAuMzUgMTYuNjFRMzkuNjkgMTcgMzguODMgMTdaTTQ3LjkyIDE2LjgyUTQ3LjIyIDE2LjgyIDQ2LjY5IDE2LjZRNDYuMTcgMTYuMzggNDUuODkgMTUuODZRNDUuNiAxNS4zMyA0NS42IDE0LjQ0VjEwLjU2SDQ0LjNWOS4zMUg0NS42TDQ1Ljc5IDcuNDFINDcuMVY5LjMxSDQ5LjIyVjEwLjU2SDQ3LjFWMTQuNDRRNDcuMSAxNS4wOSA0Ny4zNiAxNS4zMlE0Ny42MiAxNS41NSA0OC4yOSAxNS41NUg0OS4xNVYxNi44MlpNNTMuNzggMTdRNTIuODMgMTcgNTIuMTEgMTYuNjlRNTEuMzkgMTYuMzcgNTAuOTggMTUuOFE1MC41NiAxNS4yMyA1MC40NyAxNC40OEg1MS45OFE1Mi4wNiAxNC44NCA1Mi4yOCAxNS4xNFE1Mi41IDE1LjQzIDUyLjg4IDE1LjYxUTUzLjI2IDE1Ljc5IDUzLjc5IDE1Ljc5UTU0LjI4IDE1Ljc5IDU0LjU5IDE1LjY1UTU0LjkxIDE1LjUgNTUuMDYgMTUuMjZRNTUuMjIgMTUuMDIgNTUuMjIgMTQuNzRRNTUuMjIgMTQuMzIgNTUuMDEgMTQuMVE1NC44MSAxMy44OCA1NC40MSAxMy43NlE1NC4wMiAxMy42MyA1My40NiAxMy41MlE1Mi45NSAxMy40MyA1Mi40NiAxMy4yN1E1MS45OCAxMy4xMiA1MS42IDEyLjg4UTUxLjIxIDEyLjY0IDUwLjk5IDEyLjI3UTUwLjc2IDExLjkxIDUwLjc2IDExLjM4UTUwLjc2IDEwLjczIDUxLjEgMTAuMjJRNTEuNDUgOS43MSA1Mi4wOCA5LjQyUTUyLjcxIDkuMTMgNTMuNTkgOS4xM1E1NC44NCA5LjEzIDU1LjYgOS43MlE1Ni4zNyAxMC4zMSA1Ni40OSAxMS40SDU1LjA1UTU0Ljk4IDEwLjkgNTQuNiAxMC42MlE1NC4yMiAxMC4zNCA1My41NyAxMC4zNFE1Mi45MiAxMC4zNCA1Mi41OCAxMC42UTUyLjI0IDEwLjg1IDUyLjI0IDExLjI3UTUyLjI0IDExLjU0IDUyLjQ0IDExLjc1UTUyLjYzIDExLjk2IDUzLjAxIDEyLjFRNTMuNCAxMi4yNSA1My45NSAxMi4zNlE1NC43NCAxMi41MSA1NS4zNiAxMi43M1E1NS45OCAxMi45NSA1Ni4zNiAxMy4zOVE1Ni43NCAxMy44MiA1Ni43MyAxNC42M1E1Ni43NCAxNS4zNCA1Ni4zOCAxNS44N1E1Ni4wMSAxNi40MSA1NS4zNSAxNi43UTU0LjY5IDE3IDUzLjc4IDE3Wk01OC41IDE2LjgyVjYuMDhINTkuOTlWMTAuNTNRNjAuMzcgOS44NyA2MS4wMyA5LjVRNjEuNjkgOS4xMyA2Mi41IDkuMTNRNjMuMzkgOS4xMyA2NC4wMyA5LjQ5UTY0LjY3IDkuODUgNjUuMDEgMTAuNThRNjUuMzUgMTEuMyA2NS4zNSAxMi40VjE2LjgySDYzLjg4VjEyLjU1UTYzLjg4IDExLjQ5IDYzLjQzIDEwLjk0UTYyLjk4IDEwLjQgNjIuMTEgMTAuNFE2MS41MSAxMC40IDYxLjAzIDEwLjY5UTYwLjU1IDEwLjk3IDYwLjI3IDExLjUxUTU5Ljk5IDEyLjA2IDU5Ljk5IDEyLjg0VjE2LjgyWk03MC42OCAxN1E2OS42IDE3IDY4Ljc2IDE2LjUxUTY3LjkzIDE2LjAyIDY3LjQ2IDE1LjE0UTY2Ljk4IDE0LjI2IDY2Ljk4IDEzLjA5UTY2Ljk4IDExLjkgNjcuNDUgMTEuMDFRNjcuOTIgMTAuMTMgNjguNzYgOS42M1E2OS41OSA5LjEzIDcwLjcgOS4xM1E3MS44MSA5LjEzIDcyLjYgOS42MlE3My4zOSAxMC4xMSA3My44MiAxMC45MlE3NC4yNSAxMS43MyA3NC4yNSAxMi43MlE3NC4yNSAxMi44NyA3NC4yNCAxMy4wNFE3NC4yNCAxMy4yMSA3NC4yMiAxMy40MUg2OC4wOFYxMi4zNkg3Mi43NlE3Mi43MiAxMS40MyA3Mi4xNCAxMC45UTcxLjU1IDEwLjM3IDcwLjY4IDEwLjM3UTcwLjA4IDEwLjM3IDY5LjU3IDEwLjY0UTY5LjA2IDEwLjkxIDY4Ljc1IDExLjQ0UTY4LjQ1IDExLjk4IDY4LjQ1IDEyLjc4VjEzLjJRNjguNDUgMTQuMDMgNjguNzUgMTQuNlE2OS4wNiAxNS4xOCA2OS41NyAxNS40N1E3MC4wNyAxNS43NiA3MC42NyAxNS43NlE3MS4zOSAxNS43NiA3MS44NiAxNS40NVE3Mi4zMiAxNS4xMyA3Mi41NCAxNC41OUg3NC4wM1E3My44NCAxNS4yOCA3My4zOCAxNS44M1E3Mi45MiAxNi4zNyA3Mi4yNCAxNi42OVE3MS41NiAxNyA3MC42OCAxN1pNNzUuOTEgMTYuODJWNi4wOEg3Ny40MVYxNi44MlpNNzkuNDUgMTYuODJWNi4wOEg4MC45NFYxNi44MlpNODYuODcgMTYuODJWNi4zOEg4OC4zN1YxNS42NEg5My4xNFYxNi44MlpNOTcuMyAxN1E5Ni4zOCAxNyA5NS43NyAxNi42OVE5NS4xNiAxNi4zNyA5NC44NiAxNS44NFE5NC41NyAxNS4zMiA5NC41NyAxNC43UTk0LjU3IDEzLjk2IDk0Ljk1IDEzLjQzUTk1LjMzIDEyLjkgOTYuMDUgMTIuNjJROTYuNzcgMTIuMzQgOTcuNzggMTIuMzRIOTkuNzJROTkuNzIgMTEuNjggOTkuNTMgMTEuMjRROTkuMzQgMTAuODEgOTguOTYgMTAuNTlROTguNTcgMTAuMzcgOTggMTAuMzdROTcuMzMgMTAuMzcgOTYuODQgMTAuNjlROTYuMzYgMTEuMDIgOTYuMjUgMTEuNjVIOTQuNzZROTQuODQgMTAuODUgOTUuMyAxMC4yOVE5NS43NSA5LjczIDk2LjQ3IDkuNDNROTcuMTggOS4xMyA5OCA5LjEzUTk5LjA1IDkuMTMgOTkuNzYgOS41UTEwMC40OCA5Ljg3IDEwMC44NSAxMC41NVExMDEuMjEgMTEuMjMgMTAxLjIxIDEyLjE2VjE2LjgySDk5LjkxTDk5Ljc5IDE1LjU1UTk5LjY0IDE1Ljg1IDk5LjQxIDE2LjEyUTk5LjE4IDE2LjM4IDk4Ljg4IDE2LjU4UTk4LjU3IDE2Ljc4IDk4LjE4IDE2Ljg5UTk3Ljc5IDE3IDk3LjMgMTdaTTk3LjU4IDE1Ljc5UTk4LjA3IDE1Ljc5IDk4LjQ1IDE1LjU5UTk4Ljg0IDE1LjQgOTkuMTIgMTUuMDZROTkuMzkgMTQuNzMgOTkuNTQgMTQuMzFROTkuNjggMTMuODkgOTkuNyAxMy40M1YxMy4zOUg5Ny45MlE5Ny4yOCAxMy4zOSA5Ni44OCAxMy41NVE5Ni40OSAxMy43IDk2LjMxIDEzLjk3UTk2LjEzIDE0LjI1IDk2LjEzIDE0LjZROTYuMTMgMTQuOTcgOTYuMyAxNS4yM1E5Ni40NyAxNS41IDk2LjggMTUuNjRROTcuMTMgMTUuNzkgOTcuNTggMTUuNzlaTTEwNy4yMyAxN1ExMDYuNjEgMTcgMTA2LjEyIDE2LjgzUTEwNS42MiAxNi42NiAxMDUuMjQgMTYuMzZRMTA0Ljg3IDE2LjA2IDEwNC42MiAxNS42N0wxMDQuNDcgMTYuODJIMTAzLjEzVjYuMDhIMTA0LjYyVjEwLjQ4UTEwNC45OCA5LjkxIDEwNS42MyA5LjUyUTEwNi4yOCA5LjEzIDEwNy4yMyA5LjEzUTEwOC4zMSA5LjEzIDEwOS4xMyA5LjY0UTEwOS45NCAxMC4xNSAxMTAuNCAxMS4wNFExMTAuODYgMTEuOTMgMTEwLjg2IDEzLjA3UTExMC44NiAxNC4yIDExMC40IDE1LjA5UTEwOS45NCAxNS45OCAxMDkuMTMgMTYuNDlRMTA4LjMxIDE3IDEwNy4yMyAxN1pNMTA2Ljk5IDE1LjdRMTA3LjY4IDE1LjcgMTA4LjIxIDE1LjM3UTEwOC43NCAxNS4wNCAxMDkuMDQgMTQuNDVRMTA5LjM0IDEzLjg2IDEwOS4zNCAxMy4wN1ExMDkuMzQgMTIuMjggMTA5LjA0IDExLjY4UTEwOC43NCAxMS4wOSAxMDguMjEgMTAuNzZRMTA3LjY4IDEwLjQzIDEwNi45OSAxMC40M1ExMDYuMjkgMTAuNDMgMTA1Ljc2IDEwLjc2UTEwNS4yMiAxMS4wOSAxMDQuOTMgMTEuNjhRMTA0LjYzIDEyLjI3IDEwNC42MyAxMy4wN1ExMDQuNjMgMTMuODYgMTA0LjkzIDE0LjQ1UTEwNS4yMiAxNS4wNCAxMDUuNzYgMTUuMzdRMTA2LjI5IDE1LjcgMTA2Ljk5IDE1LjdaTTExNS41MiAxN1ExMTQuNTYgMTcgMTEzLjg0IDE2LjY5UTExMy4xMiAxNi4zNyAxMTIuNzEgMTUuOFExMTIuMjkgMTUuMjMgMTEyLjIgMTQuNDhIMTEzLjcxUTExMy43OSAxNC44NCAxMTQuMDEgMTUuMTRRMTE0LjIzIDE1LjQzIDExNC42MSAxNS42MVExMTQuOTkgMTUuNzkgMTE1LjUyIDE1Ljc5UTExNi4wMSAxNS43OSAxMTYuMzIgMTUuNjVRMTE2LjY0IDE1LjUgMTE2Ljc5IDE1LjI2UTExNi45NSAxNS4wMiAxMTYuOTUgMTQuNzRRMTE2Ljk1IDE0LjMyIDExNi43NSAxNC4xUTExNi41NCAxMy44OCAxMTYuMTUgMTMuNzZRMTE1Ljc1IDEzLjYzIDExNS4xOSAxMy41MlExMTQuNjggMTMuNDMgMTE0LjIgMTMuMjdRMTEzLjcxIDEzLjEyIDExMy4zMyAxMi44OFExMTIuOTQgMTIuNjQgMTEyLjcyIDEyLjI3UTExMi40OSAxMS45MSAxMTIuNDkgMTEuMzhRMTEyLjQ5IDEwLjczIDExMi44NCAxMC4yMlExMTMuMTggOS43MSAxMTMuODEgOS40MlExMTQuNDUgOS4xMyAxMTUuMzIgOS4xM1ExMTYuNTcgOS4xMyAxMTcuMzMgOS43MlExMTguMSAxMC4zMSAxMTguMjMgMTEuNEgxMTYuNzhRMTE2LjcxIDEwLjkgMTE2LjMzIDEwLjYyUTExNS45NSAxMC4zNCAxMTUuMzEgMTAuMzRRMTE0LjY1IDEwLjM0IDExNC4zMiAxMC42UTExMy45OCAxMC44NSAxMTMuOTggMTEuMjdRMTEzLjk4IDExLjU0IDExNC4xNyAxMS43NVExMTQuMzYgMTEuOTYgMTE0Ljc1IDEyLjFRMTE1LjEzIDEyLjI1IDExNS42OCAxMi4zNlExMTYuNDcgMTIuNTEgMTE3LjA5IDEyLjczUTExNy43MiAxMi45NSAxMTguMDkgMTMuMzlRMTE4LjQ3IDEzLjgyIDExOC40NiAxNC42M1ExMTguNDggMTUuMzQgMTE4LjExIDE1Ljg3UTExNy43NCAxNi40MSAxMTcuMDggMTYuN1ExMTYuNDIgMTcgMTE1LjUyIDE3WiIvPgo8L3N2Zz4K altText: Nutshell Labs servers: - url: https://api.nutshelllabs.io description: Production security: - bearerAuth: [] tags: - name: Filers description: Organizations that submit forms. - name: Recipients description: The people and businesses that forms are issued to. - name: Forms description: Note that form fields are marked `required` _only_ when a form cannot be filled or submitted without it. - name: Statements description: The documents a filer furnishes to a recipient, each covering one or more of the forms the filer issued to it. - name: Actions description: Actions allow the client to perform actions globally across all data or subsets of their data in the system. - name: Operations description: Operations allow clients to track the progress of long-running operations. paths: /api/v2/{tax_year}/filers: parameters: - $ref: "#/components/parameters/TaxYear" get: operationId: listFilers summary: List filers description: | Returns a page of the filers visible to the credential — all of them, unless a `filter` narrows the collection. The client may filter the filer collection on `id`, `entity_id`, `foreign_entity`, `phone_number`, `email_address`, `routing_transit_number`, `created_at`, `updated_at`, `generation`, and any attribute under `_client`. A filer's `tin`, `name`, `mailing_address`, `contact`, `offices`, `state_registrations`, `withholding_agent` and `payment_settlement` are nested and contribute no variables. See [Collections › Filtering](#section/Collections/Filtering) and [Client-Provided Attributes](#section/Client-Provided-Attributes). tags: - Filers parameters: - $ref: "#/components/parameters/Filter" - $ref: "#/components/parameters/PageSize" - $ref: "#/components/parameters/PageToken" responses: "200": description: A page of filers. content: application/json: schema: $ref: "#/components/schemas/FilerPage" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "403": $ref: "#/components/responses/Forbidden" post: operationId: createFiler summary: Create a filer description: Creates the filer and assigns it an `entity_id`. The client may supply an `id` to address the filer by an identifier of its own; where the client omits it, the filer's `entity_id` becomes its `id`. An `id` already in use by another filer is a `409`. tags: - Filers requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/FilerInput" responses: "201": description: The created filer. headers: Location: description: The URL of the newly created filer. schema: type: string format: uri-reference content: application/json: schema: $ref: "#/components/schemas/Filer" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "403": $ref: "#/components/responses/Forbidden" "409": $ref: "#/components/responses/Conflict" /api/v2/{tax_year}/filers/{filer_id}: parameters: - $ref: "#/components/parameters/TaxYear" - $ref: "#/components/parameters/FilerId" get: operationId: getFiler summary: Retrieve a filer description: Returns the current filer, its generation, and all earlier generations in `history`. tags: - Filers responses: "200": description: The filer. content: application/json: schema: $ref: "#/components/schemas/FilerWithHistory" "401": $ref: "#/components/responses/Unauthorized" "403": $ref: "#/components/responses/Forbidden" "404": $ref: "#/components/responses/NotFound" put: operationId: updateFiler summary: Update a filer description: | Replaces the mutable fields of the filer with those the client supplies. `id` is not among them — it is fixed at creation, so the client must either omit it or supply the one the filer already has; a different one is a `409`. Supply `If-Generation-Match` to condition the update on the resource's current generation. The response includes the updated resource and its generation; earlier generations remain available in `history`. See [Optimistic Concurrency Control](#section/Conventions/Optimistic-Concurrency-Control). tags: - Filers parameters: - $ref: "#/components/parameters/IfGenerationMatch" requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/FilerInput" responses: "200": description: The updated filer. content: application/json: schema: $ref: "#/components/schemas/Filer" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "403": $ref: "#/components/responses/Forbidden" "404": $ref: "#/components/responses/NotFound" "409": $ref: "#/components/responses/Conflict" "412": $ref: "#/components/responses/PreconditionFailed" delete: operationId: deleteFiler summary: Delete a filer description: | Deletes the filer. A parent with any undeleted children returns `409 Conflict`. Deletion retires the filer's `id` and `entity_id`: neither is issued to a later filer, and a create that supplies the deleted filer's `id` draws the same `409` as one that supplies an `id` in use. `If-Generation-Match` is optional and is checked against the current resource generation. tags: - Filers parameters: - $ref: "#/components/parameters/IfGenerationMatch" responses: "204": description: The server deleted the filer. "401": $ref: "#/components/responses/Unauthorized" "403": $ref: "#/components/responses/Forbidden" "404": $ref: "#/components/responses/NotFound" "400": $ref: "#/components/responses/BadRequest" "409": $ref: "#/components/responses/Conflict" "412": $ref: "#/components/responses/PreconditionFailed" /api/v2/{tax_year}/filers/{filer_id}/recipients: parameters: - $ref: "#/components/parameters/TaxYear" - $ref: "#/components/parameters/FilerId" get: operationId: listRecipients summary: List recipients description: | Returns a page of the filer's recipients — all of them, unless a `filter` narrows the collection. The client may filter the collection on `id`, `entity_id`, `filer_id`, `additional_name`, `date_of_birth`, `created_at`, `updated_at`, `generation`, and any attribute under `_client` — for example, `_client.customer_id == "8827"`. A recipient's `tin`, `name`, `mailing_address` and `foreign_status` are nested and contribute no variables, and the account number is a field of each form rather than of the recipient. See [Collections › Filtering](#section/Collections/Filtering) and [Client-Provided Attributes](#section/Client-Provided-Attributes). tags: - Recipients parameters: - $ref: "#/components/parameters/Filter" - $ref: "#/components/parameters/PageSize" - $ref: "#/components/parameters/PageToken" responses: "200": description: A page of recipients. content: application/json: schema: $ref: "#/components/schemas/RecipientPage" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "403": $ref: "#/components/responses/Forbidden" "404": $ref: "#/components/responses/NotFound" post: operationId: createRecipient summary: Create a recipient description: Creates the recipient and assigns it an `entity_id`. The client may supply an `id` to address the recipient by an identifier of its own; where the client omits it, the recipient's `entity_id` becomes its `id`. The server rejects an `id` already in use by another recipient with `409 Conflict`. tags: - Recipients requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/RecipientInput" responses: "201": description: The server created the recipient. headers: Location: description: The URL of the newly created recipient. schema: type: string format: uri-reference content: application/json: schema: $ref: "#/components/schemas/Recipient" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "403": $ref: "#/components/responses/Forbidden" "404": $ref: "#/components/responses/NotFound" "409": $ref: "#/components/responses/Conflict" /api/v2/{tax_year}/filers/{filer_id}/recipients/{recipient_id}: parameters: - $ref: "#/components/parameters/TaxYear" - $ref: "#/components/parameters/FilerId" - $ref: "#/components/parameters/RecipientId" get: operationId: getRecipient summary: Retrieve a recipient description: Returns the current recipient, its generation, and all earlier generations in `history`. tags: - Recipients responses: "200": description: The recipient. content: application/json: schema: $ref: "#/components/schemas/RecipientWithHistory" "401": $ref: "#/components/responses/Unauthorized" "403": $ref: "#/components/responses/Forbidden" "404": $ref: "#/components/responses/NotFound" put: operationId: updateRecipient summary: Update a recipient description: | Replaces the mutable fields of the recipient with the values the client supplies. `id` is not among them — creation settles it, so the client either omits it or supplies the one the recipient already has; the server rejects a different one with `409 Conflict`. Supply `If-Generation-Match` to condition the update on the resource's current generation. The response includes the updated resource and its generation; earlier generations remain available in `history`. See [Optimistic Concurrency Control](#section/Conventions/Optimistic-Concurrency-Control). tags: - Recipients parameters: - $ref: "#/components/parameters/IfGenerationMatch" requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/RecipientInput" responses: "200": description: The updated recipient. content: application/json: schema: $ref: "#/components/schemas/Recipient" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "403": $ref: "#/components/responses/Forbidden" "404": $ref: "#/components/responses/NotFound" "409": $ref: "#/components/responses/Conflict" "412": $ref: "#/components/responses/PreconditionFailed" delete: operationId: deleteRecipient summary: Delete a recipient description: | Deletes the recipient. A parent with any undeleted children returns `409 Conflict`. Deletion retires the recipient's `id` and `entity_id`: neither is issued to a later recipient, and a create that supplies the deleted recipient's `id` under any filer draws the same `409` as one that supplies an `id` in use. `If-Generation-Match` is optional and is checked against the current resource generation. tags: - Recipients parameters: - $ref: "#/components/parameters/IfGenerationMatch" responses: "204": description: The server deleted the recipient. "401": $ref: "#/components/responses/Unauthorized" "403": $ref: "#/components/responses/Forbidden" "404": $ref: "#/components/responses/NotFound" "400": $ref: "#/components/responses/BadRequest" "409": $ref: "#/components/responses/Conflict" "412": $ref: "#/components/responses/PreconditionFailed" /api/v2/{tax_year}/filers/{filer_id}/recipients/{recipient_id}/forms: parameters: - $ref: "#/components/parameters/TaxYear" - $ref: "#/components/parameters/FilerId" - $ref: "#/components/parameters/RecipientId" get: operationId: listForms summary: List forms description: | Returns a page of the recipient's forms. An optional `filter` may be supplied, including comparisons on `generation` and `_client` (see [Collections › Filtering](#section/Collections/Filtering)). tags: - Forms parameters: - $ref: "#/components/parameters/Filter" - $ref: "#/components/parameters/PageSize" - $ref: "#/components/parameters/PageToken" responses: "200": description: A page of forms. content: application/json: schema: $ref: "#/components/schemas/FormPage" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "403": $ref: "#/components/responses/Forbidden" "404": $ref: "#/components/responses/NotFound" post: operationId: createForm summary: Create a form description: Creates the form and assigns it an `entity_id`. The client may supply an `id` to address the form by an identifier of its own; where the client omits it, the form's `entity_id` becomes its `id`. An `id` already in use by another form — under any filer or recipient — is a `409`. The `type` of `data` settles which IRS form this resource is for the rest of its life. tags: - Forms requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/FormInput" responses: "201": description: The form was created. headers: Location: description: The URL of the newly created form. schema: type: string format: uri-reference content: application/json: schema: $ref: "#/components/schemas/Form" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "403": $ref: "#/components/responses/Forbidden" "404": $ref: "#/components/responses/NotFound" "409": $ref: "#/components/responses/Conflict" /api/v2/{tax_year}/filers/{filer_id}/recipients/{recipient_id}/forms/{form_id}: parameters: - $ref: "#/components/parameters/TaxYear" - $ref: "#/components/parameters/FilerId" - $ref: "#/components/parameters/RecipientId" - $ref: "#/components/parameters/FormId" get: operationId: getForm summary: Retrieve a form description: | Returns the current form, its generation, and all earlier generations in `history`. Historical entries retain the filing statuses and problems of those versions. tags: - Forms responses: "200": description: The current form and its history. content: application/json: schema: $ref: "#/components/schemas/FormWithHistory" "401": $ref: "#/components/responses/Unauthorized" "403": $ref: "#/components/responses/Forbidden" "404": $ref: "#/components/responses/NotFound" "406": $ref: "#/components/responses/NotAcceptable" put: operationId: updateForm summary: Update a form description: | Replaces the mutable fields of the form. Earlier generations and their filing results remain available in `history`. Supply `If-Generation-Match` to condition the update on the resource's current generation. The response includes the updated form and its generation. Changing `data` returns federal and state filing statuses to `AWAITING_PREPARATION` and clears `problems`. To correct a previously filed return or delivered statement, update the form, call `prepareSnapshot`, and submit or publish the correction. Updating only `_client` preserves filing statuses and problems. `updated_at` records the last change to the form. `id`, `tax_year` and the `type` of `data` are fixed at creation; changing one returns `409 Conflict`. An omitted `id` retains its existing value. tags: - Forms parameters: - $ref: "#/components/parameters/IfGenerationMatch" requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/FormInput" responses: "200": description: The updated form. content: application/json: schema: $ref: "#/components/schemas/Form" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "403": $ref: "#/components/responses/Forbidden" "404": $ref: "#/components/responses/NotFound" "409": $ref: "#/components/responses/Conflict" "412": $ref: "#/components/responses/PreconditionFailed" delete: operationId: deleteForm summary: Delete a form description: | Deletes the form unless a publish or submit operation has been accepted for a prepared snapshot containing it. In that case, the server responds with `409`, including while the operation is pending or processing. This restriction continues to apply after the operation finishes and after the form is updated: an earlier generation's inclusion still protects the form. A form first created after that snapshot remains eligible for deletion until a publish or submit operation is accepted for a snapshot containing it. Deletion retires the form's `id` and `entity_id`: neither is issued to a later form, and a create that supplies the deleted form's `id` — under any filer or recipient — draws the same `409` as one that supplies an `id` in use. `If-Generation-Match` is optional and is checked against the current resource generation. tags: - Forms parameters: - $ref: "#/components/parameters/IfGenerationMatch" responses: "204": description: The form was deleted. "401": $ref: "#/components/responses/Unauthorized" "403": $ref: "#/components/responses/Forbidden" "404": $ref: "#/components/responses/NotFound" "409": $ref: "#/components/responses/Conflict" "400": $ref: "#/components/responses/BadRequest" "412": $ref: "#/components/responses/PreconditionFailed" /api/v2/{tax_year}/statements: parameters: - $ref: "#/components/parameters/TaxYear" get: operationId: listStatements summary: List statements description: | Returns a page of the statements visible to the credential — all of them, unless a `filter` narrows the collection. The collection spans every filer the credential can see, as `/api/v2/{tax_year}/operations` does. A `filter` on `filer_id` (e.g., `filer_id == "acme-payroll-west"`) narrows it to one filer, and `listRecipientStatements` narrows it to one recipient. Each statement in the page carries every field but `forms`. A statement covers any number of forms, so `forms` is the one field without a bound, and omitting it keeps the size of a page a function of `page_size` alone. The client retrieves a statement (`getStatement`) to see the forms it covers. The client may filter the statement collection on `id`, `filer_id`, `recipient_id`, `tax_year`, `kind`, `status`, `created_at`, `updated_at` and `published_at`. For example, `status == "PUBLISHED" && published_at > timestamp("2026-08-01T00:00:00Z")` selects what has gone to recipients since the start of the month. `forms` and `problem` are nested and contribute no variables, so the client can filter on neither the forms a statement covers nor the reason one failed: an expression that reaches into either — for example, `forms.exists(f, f.type == "1099-NEC")` — returns `400` rather than filtering on the form type. See [Collections › Filtering](#section/Collections/Filtering). Statements carry no [client-provided attributes](#section/Client-Provided-Attributes), so `_client` names nothing here, and a filter that mentions it returns `400` rather than an empty page. tags: - Statements parameters: - $ref: "#/components/parameters/Filter" - $ref: "#/components/parameters/PageSize" - $ref: "#/components/parameters/PageToken" responses: "200": description: A page of statements. content: application/json: schema: $ref: "#/components/schemas/StatementPage" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "403": $ref: "#/components/responses/Forbidden" /api/v2/{tax_year}/statements/{statement_id}: parameters: - $ref: "#/components/parameters/TaxYear" - $ref: "#/components/parameters/StatementId" get: operationId: getStatement summary: Retrieve a statement description: | Returns the statement as it stands: which forms it covers, whether it has gone to the recipient, and — where preparation failed — why there is no document. `forms` names each form the statement covers, by `id` and by type, and this read is where it appears: the list operations omit `forms`, so retrieving the statement is how the client sees it. The grouping belongs to the server: preparing a recipient produces statements covering a partition of that recipient's forms, and neither the count nor the partition is a documented function of the input. The client lists `listRecipientStatements` and retrieves each statement it names to see everything a filer furnished to one recipient. The document itself lives at `{statement_id}/document` rather than on this resource. It is available as soon as preparation succeeds, so the client may inspect it before publishing. `download_ttl_s` asks the read to also return presigned URLs for the document: the response then carries `presigned_urls`, one URL per representation the document has, each downloadable without credentials until it expires `download_ttl_s` seconds after this read generated it. A `FAILED` statement has no document, so its response omits `presigned_urls` whether or not the parameter was supplied. tags: - Statements parameters: - $ref: "#/components/parameters/DownloadTtl" responses: "200": description: The statement. content: application/json: schema: $ref: "#/components/schemas/Statement" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "403": $ref: "#/components/responses/Forbidden" "404": $ref: "#/components/responses/NotFound" /api/v2/{tax_year}/statements/{statement_id}/document: parameters: - $ref: "#/components/parameters/TaxYear" - $ref: "#/components/parameters/StatementId" get: operationId: getStatementDocument summary: Download a statement document description: | Returns the document the statement furnishes. The client selects a representation with the `Accept` header. | Media type | `STANDARD` | `SUBSTITUTE` | |---|:-:|:-:| | `application/pdf` | yes | yes | | `application/vnd.nutshell.statement+zip` | — | yes | | `application/vnd.nutshell.statement+json` | — | yes | Every statement has the PDF, which is the document as the recipient receives it. A consolidated 1099 is a substitute statement; all other statements are standard filled forms. Substitute statements also offer archive and JSON representations with Nutshell-defined contents. This reference defines neither layout. **The document is available as soon as preparation succeeds.** Review it after `prepareSnapshot` finishes, then use `statements/publish` to deliver it to the recipient. The server answers `406` when `Accept` matches no representation this statement has — for example, a request for the archive from a `STANDARD` statement — and `detail` names the media types the statement does have. A `FAILED` statement has no document at all, and the server answers `404`: the statement resolves, and the document does not. This endpoint requires the client's credentials. To hand a download to something that cannot send an `Authorization` header, the client retrieves the statement with `download_ttl_s` and uses the presigned URLs that read returns — see `getStatement`. tags: - Statements responses: "200": $ref: "#/components/responses/StatementDocument" "401": $ref: "#/components/responses/Unauthorized" "403": $ref: "#/components/responses/Forbidden" "404": $ref: "#/components/responses/NotFound" "406": $ref: "#/components/responses/NotAcceptable" /api/v2/{tax_year}/filers/{filer_id}/recipients/{recipient_id}/statements: parameters: - $ref: "#/components/parameters/TaxYear" - $ref: "#/components/parameters/FilerId" - $ref: "#/components/parameters/RecipientId" get: operationId: listRecipientStatements summary: List a recipient's statements description: | Returns a page of one recipient's statements — all of them, unless a `filter` narrows the collection. This is `listStatements` restricted to the recipient in the path, and it filters on the same fields: `id`, `filer_id`, `recipient_id`, `tax_year`, `kind`, `status`, `created_at`, `updated_at` and `published_at`. `forms` and `problem` are nested and contribute no variables, and statements carry no [client-provided attributes](#section/Client-Provided-Attributes), so `_client` names nothing here. See [Collections › Filtering](#section/Collections/Filtering). As in `listStatements`, each statement in the page carries every field but `forms`; the client retrieves a statement (`getRecipientStatement`) to see the forms it covers. Published statements accumulate. A correction is a further prepare-and-publish that adds a statement; it does not supersede or replace an earlier one, and nothing on the resource links the two. Every `PUBLISHED` statement in this collection stands as a document that went to the recipient. tags: - Statements parameters: - $ref: "#/components/parameters/Filter" - $ref: "#/components/parameters/PageSize" - $ref: "#/components/parameters/PageToken" responses: "200": description: A page of the recipient's statements. content: application/json: schema: $ref: "#/components/schemas/StatementPage" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "403": $ref: "#/components/responses/Forbidden" "404": $ref: "#/components/responses/NotFound" /api/v2/{tax_year}/filers/{filer_id}/recipients/{recipient_id}/statements/{statement_id}: parameters: - $ref: "#/components/parameters/TaxYear" - $ref: "#/components/parameters/FilerId" - $ref: "#/components/parameters/RecipientId" - $ref: "#/components/parameters/StatementId" get: operationId: getRecipientStatement summary: Retrieve a recipient's statement description: | Returns the statement, `forms` included, which is what `getStatement` returns for the same `id`. An `id` is unique across every filer, so this path addresses exactly what the global one does. It exists so that a client that walked down from a recipient reads what it found without changing URL shape. The server answers `404` for a statement whose `filer_id` and `recipient_id` are not the ones in the path. `download_ttl_s` works here as it does on `getStatement`: supplying it makes the response carry `presigned_urls`, one URL per representation of the document, each expiring that many seconds after this read generated it. tags: - Statements parameters: - $ref: "#/components/parameters/DownloadTtl" responses: "200": description: The statement. content: application/json: schema: $ref: "#/components/schemas/Statement" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "403": $ref: "#/components/responses/Forbidden" "404": $ref: "#/components/responses/NotFound" /api/v2/{tax_year}/filers/{filer_id}/recipients/{recipient_id}/statements/{statement_id}/document: parameters: - $ref: "#/components/parameters/TaxYear" - $ref: "#/components/parameters/FilerId" - $ref: "#/components/parameters/RecipientId" - $ref: "#/components/parameters/StatementId" get: operationId: getRecipientStatementDocument summary: Download a recipient's statement document description: | Returns the document the statement furnishes, which is what `getStatementDocument` returns for the same `id`. The client selects a representation with the `Accept` header: `application/pdf` from any statement, and `application/vnd.nutshell.statement+zip` or `application/vnd.nutshell.statement+json` from a `SUBSTITUTE` statement. The responses are the same ones `getStatementDocument` gives: the server answers `406` when `Accept` matches no representation this statement has, `404` for a `FAILED` statement, which has no document, and `404` for a statement whose `filer_id` and `recipient_id` are not the ones in the path. tags: - Statements responses: "200": $ref: "#/components/responses/StatementDocument" "401": $ref: "#/components/responses/Unauthorized" "403": $ref: "#/components/responses/Forbidden" "404": $ref: "#/components/responses/NotFound" "406": $ref: "#/components/responses/NotAcceptable" /api/v2/{tax_year}/actions/prepareSnapshot: parameters: - $ref: "#/components/parameters/TaxYear" post: operationId: prepareSnapshot summary: Prepare a snapshot description: | Creates a snapshot of all your filers, recipients and forms for the tax year, validates the forms, and prepares tax returns and recipient statements for review. The returned operation identifies the snapshot's generation. Subsequent resource creations and edits receive a higher generation and belong to your next snapshot. When the operation finishes, review each form's filing statuses and `problems`, and inspect the recipient's statements. Use `filings/submit` to send the prepared returns to taxing authorities and `statements/publish` to deliver the statements. Previously prepared results may be reused when the input is unchanged. Preparation may replace unpublished statements and unsubmitted filings. Published statements and submitted records remain available. If preparation fails or is canceled, inspect the available results, resolve the reported problems, and prepare a new snapshot before submitting or publishing. tags: - Actions requestBody: $ref: "#/components/requestBodies/Action" responses: "202": $ref: "#/components/responses/ActionAccepted" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "403": $ref: "#/components/responses/Forbidden" "409": $ref: "#/components/responses/ActionConflict" /api/v2/{tax_year}/actions/statements/publish: parameters: - $ref: "#/components/parameters/TaxYear" post: operationId: publishStatements summary: Publish statements description: | Delivers all eligible recipient statements from the latest prepared snapshot. The returned operation carries that snapshot's generation. Review statements before publishing: delivery is irreversible. The latest `prepareSnapshot` operation must have succeeded; otherwise the request returns `409 Conflict`. Each delivered statement becomes `PUBLISHED` and records the delivery time in `published_at`. Published statements remain available as delivered for the period specified in your operating agreement. To make a correction, update the source form, prepare a new snapshot, and publish its statements. The correction is an additional statement alongside the original. tags: - Actions requestBody: $ref: "#/components/requestBodies/Action" responses: "202": $ref: "#/components/responses/ActionAccepted" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "403": $ref: "#/components/responses/Forbidden" "409": $ref: "#/components/responses/ActionConflict" /api/v2/{tax_year}/actions/filings/submit: parameters: - $ref: "#/components/parameters/TaxYear" post: operationId: submitFilings summary: Submit filings description: | Sends all eligible tax returns from the latest prepared snapshot to the taxing authorities. The returned operation carries that snapshot's generation. The latest `prepareSnapshot` operation must have succeeded; otherwise the request returns `409 Conflict`. Eligible filings move from `AWAITING_FILING` through `SUBMITTING` to `FILED`. For a filing in `AWAITING_CORRECTION`, resolve its problems and prepare a new snapshot before submitting. A successful operation confirms submission. Taxing authorities respond afterwards; their responses update the submitted form version, which may appear in `history` if you have since edited the form. Errors appear in that version's `problems` and move the filing to `AWAITING_CORRECTION`. Warnings appear alongside its existing filing status. tags: - Actions requestBody: $ref: "#/components/requestBodies/Action" responses: "202": $ref: "#/components/responses/ActionAccepted" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "403": $ref: "#/components/responses/Forbidden" "409": $ref: "#/components/responses/ActionConflict" /api/v2/{tax_year}/operations: parameters: - $ref: "#/components/parameters/TaxYear" get: operationId: listOperations summary: List operations description: | Returns a page of the operations visible to the credential, most recent first — all of them, unless a `filter` narrows the collection. The client may filter the collection on `id`, `type`, `status`, `created_at`, `updated_at`, `completed_at` and `generation`. `details` is nested and contributes no filter variables. See [Collections › Filtering](#section/Collections/Filtering). The client most often reads this collection to determine whether anything is in flight. Use `status in ["PENDING", "PROCESSING"]` to find actions waiting to begin or currently running. Operations carry no [client-provided attributes](#section/Client-Provided-Attributes), so `_client` names nothing here; the server rejects a filter that references it with `400 Bad Request` rather than returning an empty page. tags: - Operations parameters: - $ref: "#/components/parameters/Filter" - $ref: "#/components/parameters/PageSize" - $ref: "#/components/parameters/PageToken" responses: "200": description: A page of operations. content: application/json: schema: $ref: "#/components/schemas/OperationPage" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "403": $ref: "#/components/responses/Forbidden" /api/v2/{tax_year}/operations/{operation_id}: parameters: - $ref: "#/components/parameters/TaxYear" - $ref: "#/components/parameters/OperationId" get: operationId: getOperation summary: Retrieve an operation description: | Returns the operation's status, snapshot generation and processing results. The `Location` header of an action's `202` response points to this resource. Poll while the status is `PENDING` or `PROCESSING`. `SUCCEEDED`, `FAILED` and `CANCELED` are final. Statistics are available once processing finishes. Inspect statements and forms for individual results. When a form has been edited since preparation, the version used by the operation appears in its `history`, with that version's filing statuses and problems. tags: - Operations responses: "200": description: The operation. content: application/json: schema: $ref: "#/components/schemas/Operation" "401": $ref: "#/components/responses/Unauthorized" "403": $ref: "#/components/responses/Forbidden" "404": $ref: "#/components/responses/NotFound" components: securitySchemes: bearerAuth: type: http scheme: bearer description: | Requests are authenticated with a bearer token in the `Authorization` header. All requests must use TLS; non-TLS requests are rejected. Deployments additionally require mTLS and can restrict access by source IP. parameters: TaxYear: name: tax_year in: path required: true description: The tax year containing the requested resource. schema: type: integer format: int32 minimum: 1900 maximum: 9999 Filter: name: filter in: query required: false description: | A [Common Expression Language](https://cel.dev/) expression that narrows the collection, evaluated once per resource: the resources it returns `true` for are the ones returned. Omit it — the usual case — and the collection is returned in full. The available variables are the collection's own top-level fields — its identifiers, the timestamps every resource carries, and whichever of its other fields hold a single value. When a resource supports client-provided attributes ()`_client`), they may be filtered upon. Nested objects contribute no variables. The `list` operation this parameter appears on names the fields its own collection can be filtered on. The expression must be URL-encoded when included in a URL's query parameters. See [Collections › Filtering](#section/filtering) and [Client-Provided Attributes](#section/Client-Provided-Attributes) for more detail. schema: type: string examples: byCreatedAt: summary: Resources created since the start of the tax year value: created_at > timestamp("2026-01-01T00:00:00Z") byClientCustomer: summary: Resources carrying a client's customer identifier value: _client.customer_id == "8827" byConjunction: summary: A resource field and a client attribute together value: updated_at > timestamp("2026-08-01T00:00:00Z") && _client.region == "us-west" PageSize: name: page_size in: query required: false description: | The maximum number of resources to return in a single page. Omit it to accept the server's default of 50; a value above 250 is coerced down to 250 rather than rejected. The server never returns more than this, and can return fewer even when further pages remain — a short page is not the end of the collection. See [Collections › Pagination](#section/Collections/Pagination). schema: type: integer format: int64 minimum: 1 default: 50 PageToken: name: page_token in: query required: false description: The `next_page_token` value from a previous page. Omit it to fetch the first page. A token the server does not recognize, or one that has expired, returns `400 Bad Request`. schema: $ref: "#/components/schemas/PageToken" FilerId: name: filer_id in: path required: true description: "The filer's `id`: the identifier the client supplies at creation, or the filer's `entity_id` where the client supplies none." schema: $ref: "#/components/schemas/ResourceId" IfGenerationMatch: name: If-Generation-Match in: header required: false description: | Perform the update or deletion only if the resource has this generation. Send the integer returned on the resource, for example `3`. A mismatch returns `412`; a missing resource returns `404`; a malformed value returns `400`. Among updates that match the same generation, the last update wins. schema: type: integer format: int64 examples: - 3 RecipientId: name: recipient_id in: path required: true description: "The recipient's `id`: the identifier the client supplied at creation, or its `entity_id` where the client supplied none." schema: $ref: "#/components/schemas/ResourceId" examples: - "8827" FormId: name: form_id in: path required: true description: "The form's `id`: the identifier the client supplied at creation, or its `entity_id` where the client supplied none." schema: $ref: "#/components/schemas/ResourceId" examples: - 6b3f0c2e-8d4a-4f1b-9e57-a2c81d0f3b64 StatementId: name: statement_id in: path required: true description: The identifier of the statement. schema: $ref: "#/components/schemas/StatementId" DownloadTtl: name: download_ttl_s in: query required: false description: | The lifetime, in seconds, of the presigned URLs the client asks this read to generate. Supplying it makes the response carry `presigned_urls` — one URL per representation of the statement's document, each generated by this read and expiring this many seconds later. Omit it — the usual case — and the response carries no `presigned_urls`. The value must be an integer between 1 and 604800 (seven days); the server answers `400` to anything else. schema: type: integer minimum: 1 maximum: 604800 examples: - 300 OperationId: name: operation_id in: path required: true description: The operation's `id`, from the `Location` of the `202` that began it. schema: $ref: "#/components/schemas/OperationId" schemas: PageToken: type: string description: A page token produced by the server. Pass it back unchanged; clients do not construct these. examples: - cGFnZTp2MTpmbHJfMDFIWjhL ResourceId: type: string title: Resource identifier description: | The identifier a resource is addressed by in a URL. The client may supply its own value when the resource is created — an identifier from the client's own systems — and every later request then addresses the resource by it. Where the client supplies none, the resource's server-assigned `entity_id` becomes its `id`. Deleting a resource retires its `id`. Creating a resource with a retired identifier returns `409`, just as using an identifier already in use does. The value is written into the URL path as it stands, so it is limited to the characters that need no escaping there: letters, digits, `-`, `.`, `_` and `~`, beginning with a letter or a digit. Up to 255 of them, compared exactly — `Acme` and `acme` are two identifiers rather than one. minLength: 1 maxLength: 255 pattern: ^[A-Za-z0-9][A-Za-z0-9._~-]*$ examples: - acme-payroll-west TinType: type: string title: TIN type description: "Which kind of number the accompanying `taxpayer_id` is. `UNKNOWN` is not a synonym for absence: it says the filer holds a number but cannot say what kind it is." enum: - INDIVIDUAL - BUSINESS - UNKNOWN TinMatchStatus: type: string title: TIN match status description: | Whether the number and the name it belongs to have been confirmed against IRS records. Matching is on the **pair**, not the number alone, so this is a statement about the TIN and the party's `name` together. Changing either returns the status to `AWAITING_MATCHING`: a number confirmed against one name proves nothing about another. enum: - AWAITING_MATCHING - MATCHED - UNMATCHED x-enumDescriptions: AWAITING_MATCHING: Not yet checked, or checked and awaiting a result. The state every TIN starts in. MATCHED: The IRS confirmed this number against this name. UNMATCHED: "The IRS was asked and did not confirm the pair. For a recipient this is a warning to act on rather than a bar to filing — it is what leads to a notice, and in time to `RecipientTin.second_notice`. For a filer it is fatal: `SMF017` and `SMF018` reject the whole submission." Tin: type: object title: TIN description: | A taxpayer identification number, together with what is known about it. The number alone is not the whole of what a filing needs. The IRS matches a TIN against the name it is paired with: a mismatch on the filer's own pair stops the filing, and a mismatch on a recipient's is reported back as an error. That outcome is a fact about the number which outlives any one form, so it is held with it rather than restated per filing. properties: taxpayer_id: type: string description: Nine digits, unpunctuated. An EIN, SSN, ITIN and ATIN are all carried this way; `type` says which was supplied. pattern: ^[0-9]{9}$ examples: - "001234567" type: $ref: "#/components/schemas/TinType" status: readOnly: true description: Server-assigned; see `TinMatchStatus`. $ref: "#/components/schemas/TinMatchStatus" required: - taxpayer_id - type PersonPartyName: type: object title: Person name description: "Note how narrow the name parts are: twenty characters each, letters and hyphens only. `O'Brien` and `Nguyễn` have to be spelled without the apostrophe and without the diacritics." properties: type: type: string const: PERSON first_name: type: string maxLength: 20 pattern: ^([A-Za-z\-] ?)*[A-Za-z\-]$ examples: - Elizabeth middle_name: type: string maxLength: 20 pattern: ^([A-Za-z\-] ?)*[A-Za-z\-]$ last_name: type: string maxLength: 20 pattern: ^([A-Za-z\-] ?)*[A-Za-z\-]$ examples: - Barker suffix: type: string maxLength: 20 pattern: ^([A-Za-z\-] ?)*[A-Za-z\-]$ examples: - Jr required: - type - first_name - last_name BusinessPartyName: type: object title: Business name properties: type: type: string const: BUSINESS line1: type: string maxLength: 75 pattern: ^(([A-Za-z0-9#\-()]|&|') ?)*([A-Za-z0-9#\-()]|&|')$ examples: - Nutshell Payroll Services Inc line2: type: string description: A continuation of the name, or a name the business does business as. maxLength: 75 pattern: ^(([A-Za-z0-9#/%\-()]|&|') ?)*([A-Za-z0-9#/%\-()]|&|')$ required: - type - line1 PartyName: description: A party's name, which is either a person's or a business's. oneOf: - $ref: "#/components/schemas/PersonPartyName" - $ref: "#/components/schemas/BusinessPartyName" discriminator: propertyName: type mapping: PERSON: "#/components/schemas/PersonPartyName" BUSINESS: "#/components/schemas/BusinessPartyName" StateCode: type: string title: State code description: |- A US state, federal district, territory, freely associated state, or military post (`AA` Armed Forces Americas, `AE` Europe, `AP` Pacific). Transcribed from the published IRS code list. enum: - AL - AK - AS - AZ - AR - CA - CO - MP - CT - DE - DC - FM - FL - GA - GU - HI - ID - IL - IN - IA - KS - KY - LA - ME - MH - MD - MA - MI - MN - MS - MO - MT - NE - NV - NH - NJ - NM - NY - NC - ND - OH - OK - OR - PW - PA - PR - RI - SC - SD - TN - TX - VI - UT - VT - VA - WA - WV - WI - WY - AA - AE - AP x-enumDescriptions: AL: Alabama AK: Alaska AS: American Samoa AZ: Arizona AR: Arkansas CA: California CO: Colorado MP: Commonwealth of the Northern Mariana Islands CT: Connecticut DE: Delaware DC: District of Columbia FM: Federated States of Micronesia FL: Florida GA: Georgia GU: Guam HI: Hawaii ID: Idaho IL: Illinois IN: Indiana IA: Iowa KS: Kansas KY: Kentucky LA: Louisiana ME: Maine MH: Marshall Islands MD: Maryland MA: Massachusetts MI: Michigan MN: Minnesota MS: Mississippi MO: Missouri MT: Montana NE: Nebraska NV: Nevada NH: New Hampshire NJ: New Jersey NM: New Mexico NY: New York NC: North Carolina ND: North Dakota OH: Ohio OK: Oklahoma OR: Oregon PW: Palau PA: Pennsylvania PR: Puerto Rico RI: Rhode Island SC: South Carolina SD: South Dakota TN: Tennessee TX: Texas VI: U.S. Virgin Islands UT: Utah VT: Vermont VA: Virginia WA: Washington WV: West Virginia WI: Wisconsin WY: Wyoming AA: Armed Forces the Americas AE: Armed Forces Europe AP: Armed Forces Pacific UsAddress: type: object title: US address properties: type: type: string const: US line1: type: string description: "Alphanumerics, single spaces, hyphens and solidi. Note what is missing: the period, the comma and the number sign. `1234 N. Main St., Apt 5` is supplied as `1234 N Main St Apt 5`." maxLength: 35 pattern: ^[A-Za-z0-9]( ?[A-Za-z0-9\-/])*$ examples: - 876 Arch Rd line2: type: string maxLength: 35 pattern: ^[A-Za-z0-9]( ?[A-Za-z0-9\-/])*$ city: type: string description: Letters and single spaces only. maxLength: 40 pattern: ^([A-Za-z] ?)*[A-Za-z]$ examples: - Cary state: $ref: "#/components/schemas/StateCode" zip_code: type: string description: Five, nine, or twelve digits, unpunctuated. pattern: ^[0-9]{5}(([0-9]{4})|([0-9]{7}))?$ examples: - "275130000" required: - type - line1 - city - state - zip_code IsoCountry: type: object title: ISO 3166-1 country description: A country identified by its ISO 3166-1 alpha-2 code. properties: representation: type: string const: ISO_3166_1_ALPHA2 description: Names the ISO 3166-1 alpha-2 list. identifier: type: string description: The country's ISO 3166-1 alpha-2 code. The server maps it to the corresponding IRS country code; a code with no IRS counterpart is rejected. pattern: ^[A-Z]{2}$ examples: - DE required: - representation - identifier CountryCode: type: string title: Country code description: |- A two-letter country code from the IRS's own list. **These are IRS country codes, not ISO 3166-1.** The two lists overlap enough to be dangerous and disagree on individual codes: `AG` is Algeria here and Antigua and Barbuda in ISO, `AS` is Australia here and American Samoa in ISO, `AA` is Aruba here and unassigned in ISO. A country is therefore supplied together with a `representation` naming the list its code is drawn from; this list is the one named `IRS`. Transcribed from the published IRS code list. enum: - AF - AX - AL - AG - AQ - AN - AO - AV - AY - AC - AR - AM - AA - AT - AS - AU - AJ - BF - BA - FQ - BG - BB - BO - BE - BH - BN - BD - BT - BL - BK - BC - BV - BR - IO - VI - BX - BU - UV - BM - BY - CB - CM - CA - CV - CJ - CT - CD - CI - CH - KT - IP - CK - CO - CN - CF - CG - CW - CR - CS - IV - HR - CU - UC - CY - EZ - DA - DX - DJ - DO - DR - TT - EC - EG - ES - EK - ER - EN - ET - FK - FO - FM - FJ - FI - FR - FP - FS - GB - GA - GG - GM - GH - GI - GR - GL - GJ - GQ - GT - GK - GV - PU - GY - HA - HM - VT - HO - HK - HQ - HU - IC - IN - ID - IR - IZ - EI - IS - IT - JM - JN - JA - DQ - JE - JQ - JO - KZ - KE - KQ - KR - KN - KS - KV - KU - KG - LA - LG - LE - LT - LI - LY - LS - LH - LU - MC - MK - MA - MI - MY - MV - ML - MT - IM - RM - MR - MP - MX - MQ - MD - MN - MG - MJ - MH - MO - MZ - WA - NR - BQ - NP - NL - NC - NZ - NU - NG - NI - NE - NF - CQ - "NO" - MU - OC - PK - PS - LQ - PM - PP - PF - PA - PE - RP - PC - PL - PO - RQ - QA - RO - RS - RW - TB - RN - WS - SM - TP - SA - SG - RI - SE - SL - SN - NN - LO - SI - BP - SO - SF - SX - OD - SP - PG - CE - SH - SC - ST - SB - VC - SU - NS - SV - WZ - SW - SZ - SY - TW - TI - TZ - TH - TO - TL - TN - TD - TS - TU - TX - TK - TV - UG - UP - AE - UK - UY - UZ - NH - VE - VM - VQ - WQ - WF - WI - YM - ZA - ZI x-enumDescriptions: AF: Afghanistan AX: Akrotiri AL: Albania AG: Algeria AQ: American Samoa AN: Andorra AO: Angola AV: Anguilla AY: Antarctica AC: Antigua and Barbuda AR: Argentina AM: Armenia AA: Aruba AT: Ashmore and Cartier Islands AS: Australia AU: Austria AJ: Azerbaijan BF: Bahamas BA: Bahrain FQ: Baker Island BG: Bangladesh BB: Barbados BO: Belarus BE: Belgium BH: Belize BN: Benin BD: Bermuda BT: Bhutan BL: Bolivia BK: Bosnia-Herzegovina BC: Botswana BV: Bouvet Island BR: Brazil IO: British Indian Ocean Territory VI: British Virgin Islands BX: Brunei BU: Bulgaria UV: Burkina Faso BM: Burma BY: Burundi CB: Cambodia CM: Cameroon CA: Canada CV: Cape Verde CJ: Cayman Islands CT: Central African Republic CD: Chad CI: Chile CH: China KT: Christmas Island IP: Clipperton Island CK: Cocos (Keeling) Islands CO: Colombia CN: Comoros CF: Congo (Brazzaville) CG: Congo (Kinshasa) CW: Cook Islands CR: Coral Sea Islands CS: Costa Rica IV: Cote D'Ivoire (Ivory Coast) HR: Croatia CU: Cuba UC: Curacao CY: Cyprus EZ: Czech Republic DA: Denmark DX: Dhekelia DJ: Djibouti DO: Dominica DR: Dominican Republic TT: East Timor EC: Ecuador EG: Egypt ES: El Salvador EK: Equatorial Guinea ER: Eritrea EN: Estonia ET: Ethiopia FK: Falkland Islands (Islas Malvinas) FO: Faroe Islands FM: Federated States of Micronesia FJ: Fiji FI: Finland FR: France FP: French Polynesia FS: French Southern and Antarctic Lands GB: Gabon GA: The Gambia GG: Georgia GM: Germany GH: Ghana GI: Gibraltar GR: Greece GL: Greenland GJ: Grenada GQ: Guam GT: Guatemala GK: Guernsey GV: Guinea PU: Guinea-Bissau GY: Guyana HA: Haiti HM: Heard Island and McDonald Islands VT: Holy See HO: Honduras HK: Hong Kong HQ: Howland Island HU: Hungary IC: Iceland IN: India ID: Indonesia IR: Iran IZ: Iraq EI: Ireland IS: Israel IT: Italy JM: Jamaica JN: Jan Mayen JA: Japan DQ: Jarvis Island JE: Jersey JQ: Johnston Atoll JO: Jordan KZ: Kazakhstan KE: Kenya KQ: Kingman Reef KR: Kiribati KN: Korea, Democratic People's Republic of (North) KS: Korea, Republic of (South) KV: Kosovo KU: Kuwait KG: Kyrgyzstan LA: Laos LG: Latvia LE: Lebanon LT: Lesotho LI: Liberia LY: Libya LS: Liechtenstein LH: Lithuania LU: Luxembourg MC: Macau MK: Macedonia MA: Madagascar MI: Malawi MY: Malaysia MV: Maldives ML: Mali MT: Malta IM: Man, Isle of RM: Marshall Islands MR: Mauritania MP: Mauritius MX: Mexico MQ: Midway Islands MD: Moldova MN: Monaco MG: Mongolia MJ: Montenegro MH: Montserrat MO: Morocco MZ: Mozambique WA: Namibia NR: Nauru BQ: Navassa Island NP: Nepal NL: Netherlands NC: New Caledonia NZ: New Zealand NU: Nicaragua NG: Niger NI: Nigeria NE: Niue NF: Norfolk Island CQ: Northern Mariana Islands "NO": Norway MU: Oman OC: Other Country PK: Pakistan PS: Palau LQ: Palmyra Atoll PM: Panama PP: Papua-New Guinea PF: Paracel Islands PA: Paraguay PE: Peru RP: Philippines PC: Pitcairn Islands PL: Poland PO: Portugal RQ: Puerto Rico QA: Qatar RO: Romania RS: Russia RW: Rwanda TB: Saint Barthelemy RN: Saint Martin WS: Samoa SM: San Marino TP: Sao Tome and Principe SA: Saudi Arabia SG: Senegal RI: Serbia SE: Seychelles SL: Sierra Leone SN: Singapore NN: Sint Maarten LO: Slovakia SI: Slovenia BP: Solomon Islands SO: Somalia SF: South Africa SX: South Georgia and the South Sandwich Islands OD: South Sudan SP: Spain PG: Spratly Islands CE: Sri Lanka SH: St. Helena SC: St. Kitts and Nevis ST: St. Lucia Island SB: St. Pierre and Miquelon VC: St. Vincent and the Grenadines SU: Sudan NS: Suriname SV: Svalbard WZ: Swaziland SW: Sweden SZ: Switzerland SY: Syria TW: Taiwan TI: Tajikistan TZ: Tanzania TH: Thailand TO: Togo TL: Tokelau TN: Tonga TD: Trinidad and Tobago TS: Tunisia TU: Turkey TX: Turkmenistan TK: Turks and Caicos Islands TV: Tuvalu UG: Uganda UP: Ukraine AE: United Arab Emirates UK: United Kingdom (England, Northern Ireland, Scotland, and Wales) UY: Uruguay UZ: Uzbekistan NH: Vanuatu VE: Venezuela VM: Vietnam VQ: Virgin Islands WQ: Wake Island WF: Wallis and Futuna WI: Western Sahara YM: Yemen (Aden) ZA: Zambia ZI: Zimbabwe IrsCountry: type: object title: IRS-coded country description: A country identified by the IRS's own two-letter code, used as it stands. properties: representation: type: string const: IRS description: Names the IRS country code list. identifier: description: The country's code from the IRS list. $ref: "#/components/schemas/CountryCode" required: - representation - identifier Country: description: |- A country, as a two-letter code paired with the code list the code is drawn from. `representation` names the list — `ISO_3166_1_ALPHA2` for ISO 3166-1 alpha-2, or `IRS` for the IRS's own country code list — and `identifier` is the code itself. The client may supply whichever representation its records already hold; the server maps an ISO code to the IRS code the filing carries. The list is named explicitly because the two disagree on individual codes while looking alike: `AG` is Antigua and Barbuda in ISO 3166-1 and Algeria in the IRS list, and `AS` is American Samoa in one and Australia in the other. A bare two-letter code cannot say which was meant. oneOf: - $ref: "#/components/schemas/IsoCountry" - $ref: "#/components/schemas/IrsCountry" discriminator: propertyName: representation mapping: ISO_3166_1_ALPHA2: "#/components/schemas/IsoCountry" IRS: "#/components/schemas/IrsCountry" examples: - representation: ISO_3166_1_ALPHA2 identifier: DE ForeignAddress: type: object title: Foreign address properties: type: type: string const: FOREIGN line1: type: string maxLength: 35 pattern: ^[A-Za-z0-9]( ?[A-Za-z0-9\-/])*$ line2: type: string maxLength: 35 pattern: ^[A-Za-z0-9]( ?[A-Za-z0-9\-/])*$ city: type: string maxLength: 50 pattern: ^([A-Za-z] ?)*[A-Za-z]$ province_or_state: type: string maxLength: 17 country: $ref: "#/components/schemas/Country" postal_code: type: string maxLength: 16 required: - type - line1 - country Address: description: A mailing address, either domestic or foreign. oneOf: - $ref: "#/components/schemas/UsAddress" - $ref: "#/components/schemas/ForeignAddress" discriminator: propertyName: type mapping: US: "#/components/schemas/UsAddress" FOREIGN: "#/components/schemas/ForeignAddress" PhoneNumber: type: string description: Digits only, ten to thirty of them. A comma separates an extension from the number it belongs to; supply no other punctuation. minLength: 10 maxLength: 30 pattern: ^[0-9,]+$ examples: - "8594678343" EmailAddress: type: string format: email maxLength: 75 pattern: ^.+@.+$ examples: - filings@nutshelllabs.io ContactPerson: type: object title: Contact person description: The person the IRS calls about a filing — the same four values Form 8809 prints as its contact name, telephone number and email address. properties: name: type: string description: A whole name on one line, rather than the parts of one. maxLength: 35 pattern: ^([A-Za-z0-9'\-] ?)*[A-Za-z0-9'\-]$ examples: - Alice Brown phone_number: $ref: "#/components/schemas/PhoneNumber" email_address: $ref: "#/components/schemas/EmailAddress" fax_number: $ref: "#/components/schemas/PhoneNumber" required: - name FilerOffice: type: object title: Filer office description: One of a filer's reporting offices. properties: code: type: string description: The filer's own office code. Exactly four characters — a length, not a maximum. minLength: 4 maxLength: 4 examples: - "0001" description: type: string description: A human-readable label, which appears on no form. maxLength: 255 examples: - Western region payroll required: - code StateRegistration: type: object title: State registration description: A filer's withholding registration number in one state. properties: state: $ref: "#/components/schemas/StateCode" id_number: type: string maxLength: 25 examples: - WA-4471902 required: - state - id_number Chapter3Status: type: string title: Chapter 3 status description: |- The chapter 3 status of a party to a Form 1042-S — a withholding agent, a recipient, an intermediary or a payer. The list begins at `05`, which is not an omission: codes `01` through `04` belong to the chapter 4 table, and `33` and `34` are unassigned in chapter 3. A code valid in one chapter means something different in the other, so the two are never interchangeable. Read out of Appendix B of the Form 1042-S instructions. enum: - US_BRANCH_TREATED_AS_US_PERSON - US_BRANCH_NOT_TREATED_AS_US_PERSON - US_BRANCH_ECI_PRESUMPTION_APPLIED - PARTNERSHIP_OTHER - WITHHOLDING_FOREIGN_PARTNERSHIP - TRUST_OTHER_THAN_WT - WITHHOLDING_FOREIGN_TRUST - QUALIFIED_INTERMEDIARY - QSL_QI - QSL_OTHER - CORPORATION - INDIVIDUAL - ESTATE - PRIVATE_FOUNDATION - INTERNATIONAL_ORGANIZATION - TAX_EXEMPT_ORGANIZATION_501C - UNKNOWN_RECIPIENT - ARTIST_OR_ATHLETE - PENSION - FOREIGN_CENTRAL_BANK_OF_ISSUE - NONQUALIFIED_INTERMEDIARY - HYBRID_ENTITY_MAKING_TREATY_CLAIM - WITHHOLDING_RATE_POOL_GENERAL - WITHHOLDING_RATE_POOL_EXEMPT_ORG - PAI_WITHHOLDING_RATE_POOL_GENERAL - PAI_WITHHOLDING_RATE_POOL_EXEMPT_ORG - AGENCY_WITHHOLDING_RATE_POOL_GENERAL - AGENCY_WITHHOLDING_RATE_POOL_EXEMPT_ORG - QUALIFIED_DERIVATIVES_DEALER - FOREIGN_GOVERNMENT_INTEGRAL_PART - FOREIGN_GOVERNMENT_CONTROLLED_ENTITY - PUBLICLY_TRADED_PARTNERSHIP - DISCLOSING_QUALIFIED_INTERMEDIARY - PARTNERSHIP_QDD - US_GOVERNMENT_OR_TAX_EXEMPT_OTHER x-enumDescriptions: US_BRANCH_TREATED_AS_US_PERSON: 05 — U.S. branch—treated as U.S. person US_BRANCH_NOT_TREATED_AS_US_PERSON: 06 — U.S. branch—not treated as U.S. person US_BRANCH_ECI_PRESUMPTION_APPLIED: 07 — U.S. branch—ECI presumption applied PARTNERSHIP_OTHER: 08 — Partnership other than withholding foreign partnership, publicly traded partnership, or partnership QDD WITHHOLDING_FOREIGN_PARTNERSHIP: 09 — Withholding foreign partnership TRUST_OTHER_THAN_WT: 10 — Trust other than withholding foreign trust WITHHOLDING_FOREIGN_TRUST: 11 — Withholding foreign trust QUALIFIED_INTERMEDIARY: 12 — Qualified intermediary QSL_QI: 13 — Qualified securities lender—qualified intermediary QSL_OTHER: 14 — Qualified securities lender—other CORPORATION: 15 — Corporation INDIVIDUAL: 16 — Individual ESTATE: 17 — Estate PRIVATE_FOUNDATION: 18 — Private foundation INTERNATIONAL_ORGANIZATION: 19 — International organization TAX_EXEMPT_ORGANIZATION_501C: 20 — Tax exempt organization (section 501(c) entities) UNKNOWN_RECIPIENT: 21 — Unknown recipient ARTIST_OR_ATHLETE: 22 — Artist or athlete PENSION: 23 — Pension FOREIGN_CENTRAL_BANK_OF_ISSUE: 24 — Foreign central bank of issue NONQUALIFIED_INTERMEDIARY: 25 — Nonqualified intermediary HYBRID_ENTITY_MAKING_TREATY_CLAIM: 26 — Hybrid entity making treaty claim WITHHOLDING_RATE_POOL_GENERAL: 27 — Withholding rate pool—general (pooled reporting code) WITHHOLDING_RATE_POOL_EXEMPT_ORG: 28 — Withholding rate pool—exempt organization (pooled reporting code) PAI_WITHHOLDING_RATE_POOL_GENERAL: 29 — PAI withholding rate pool—general (pooled reporting code) PAI_WITHHOLDING_RATE_POOL_EXEMPT_ORG: 30 — PAI withholding rate pool—exempt organization (pooled reporting code) AGENCY_WITHHOLDING_RATE_POOL_GENERAL: 31 — Agency withholding rate pool—general (pooled reporting code) AGENCY_WITHHOLDING_RATE_POOL_EXEMPT_ORG: 32 — Agency withholding rate pool—exempt organization (pooled reporting code) QUALIFIED_DERIVATIVES_DEALER: 35 — Qualified derivatives dealer FOREIGN_GOVERNMENT_INTEGRAL_PART: 36 — Foreign government—integral part FOREIGN_GOVERNMENT_CONTROLLED_ENTITY: 37 — Foreign government—controlled entity PUBLICLY_TRADED_PARTNERSHIP: 38 — Publicly traded partnership DISCLOSING_QUALIFIED_INTERMEDIARY: 39 — Disclosing qualified intermediary PARTNERSHIP_QDD: 40 — Partnership QDD US_GOVERNMENT_OR_TAX_EXEMPT_OTHER: 41 — U.S. government entity or tax exempt entity (other than section 501(c) entities) Chapter4Status: type: string title: Chapter 4 status description: |- The chapter 4 (FATCA) status of a party to a Form 1042-S — a withholding agent, a recipient, an intermediary or a payer. Runs `01` to `50` without gaps. Do not read a chapter 4 code as a chapter 3 one: `05` is a participating FFI here and a U.S. branch treated as a U.S. person there. Read out of Appendix B of the Form 1042-S instructions. enum: - US_WITHHOLDING_AGENT_FI - US_WITHHOLDING_AGENT_OTHER - TERRITORY_FI_NOT_TREATED_AS_US_PERSON - TERRITORY_FI_TREATED_AS_US_PERSON - PARTICIPATING_FFI_OTHER - PARTICIPATING_FFI_MODEL2 - RDC_FFI_MODEL1 - RDC_FFI_SPONSORED_ENTITY - RDC_FFI_OTHER - CERTIFIED_DC_FFI_OTHER - CERTIFIED_DC_FFI_LOW_VALUE_ACCOUNTS - CERTIFIED_DC_FFI_NONREGISTERING_LOCAL_BANK - CERTIFIED_DC_FFI_SPONSORED_ENTITY - CERTIFIED_DC_FFI_INVESTMENT_ENTITY_NO_ACCOUNTS - NONPARTICIPATING_FFI - OWNER_DOCUMENTED_FFI - US_BRANCH_TREATED_AS_US_PERSON - US_BRANCH_NOT_TREATED_REPORTING_1471 - PASSIVE_NFFE_IDENTIFYING_SUBSTANTIAL_US_OWNERS - PASSIVE_NFFE_NO_SUBSTANTIAL_US_OWNERS - PUBLICLY_TRADED_NFFE_OR_AFFILIATE - ACTIVE_NFFE - INDIVIDUAL - SECTION_501C_ENTITIES - EXCEPTED_TERRITORY_NFFE - EXCEPTED_NFFE_OTHER - EXEMPT_BENEFICIAL_OWNER - ENTITY_WHOLLY_OWNED_BY_EXEMPT_BENEFICIAL_OWNERS - UNKNOWN_RECIPIENT - RECALCITRANT_ACCOUNT_HOLDER - NONREPORTING_IGA_FFI - DIRECT_REPORTING_NFFE - US_REPORTABLE_ACCOUNT - NONCONSENTING_US_ACCOUNT - SPONSORED_DIRECT_REPORTING_NFFE - EXCEPTED_INTER_AFFILIATE_FFI - UNDOCUMENTED_PREEXISTING_OBLIGATION - US_BRANCH_ECI_PRESUMPTION_APPLIED - ACCOUNT_HOLDER_EXCLUDED_FINANCIAL_ACCOUNT - PASSIVE_NFFE_REPORTED_BY_FFI - NFFE_SUBJECT_TO_1472_WITHHOLDING - RECALCITRANT_POOL_NO_US_INDICIA - RECALCITRANT_POOL_US_INDICIA - RECALCITRANT_POOL_DORMANT_ACCOUNT - RECALCITRANT_POOL_US_PERSONS - RECALCITRANT_POOL_PASSIVE_NFFES - NONPARTICIPATING_FFI_POOL - US_PAYEES_POOL - QI_RECALCITRANT_POOL_GENERAL - US_WITHHOLDING_AGENT_FOREIGN_BRANCH x-enumDescriptions: US_WITHHOLDING_AGENT_FI: 01 — U.S. withholding agent—FI US_WITHHOLDING_AGENT_OTHER: 02 — U.S. withholding agent—other TERRITORY_FI_NOT_TREATED_AS_US_PERSON: 03 — Territory FI—not treated as U.S. person TERRITORY_FI_TREATED_AS_US_PERSON: 04 — Territory FI—treated as U.S. person PARTICIPATING_FFI_OTHER: 05 — Participating FFI—other PARTICIPATING_FFI_MODEL2: 06 — Participating FFI—reporting Model 2 FFI RDC_FFI_MODEL1: 07 — Registered deemed-compliant FFI—reporting Model 1 FFI RDC_FFI_SPONSORED_ENTITY: 08 — Registered deemed-compliant FFI—sponsored entity RDC_FFI_OTHER: 09 — Registered deemed-compliant FFI—other CERTIFIED_DC_FFI_OTHER: 10 — Certified deemed-compliant FFI—other CERTIFIED_DC_FFI_LOW_VALUE_ACCOUNTS: 11 — Certified deemed-compliant FFI—FFI with low value accounts CERTIFIED_DC_FFI_NONREGISTERING_LOCAL_BANK: 12 — Certified deemed-compliant FFI—nonregistering local bank CERTIFIED_DC_FFI_SPONSORED_ENTITY: 13 — Certified deemed-compliant FFI—sponsored entity CERTIFIED_DC_FFI_INVESTMENT_ENTITY_NO_ACCOUNTS: 14 — Certified deemed-compliant FFI—investment entity that does not maintain financial accounts NONPARTICIPATING_FFI: 15 — Nonparticipating FFI OWNER_DOCUMENTED_FFI: 16 — Owner-documented FFI US_BRANCH_TREATED_AS_US_PERSON: 17 — U.S. branch—treated as U.S. person US_BRANCH_NOT_TREATED_REPORTING_1471: 18 — U.S. branch—not treated as U.S. person (reporting under section 1471); used when the branch certifies it applies Regulations section 1.1471-4(d)(2)(iii)(C) to avoid chapter 4 withholding. PASSIVE_NFFE_IDENTIFYING_SUBSTANTIAL_US_OWNERS: 19 — Passive NFFE identifying substantial U.S. owners PASSIVE_NFFE_NO_SUBSTANTIAL_US_OWNERS: 20 — Passive NFFE with no substantial U.S. owners PUBLICLY_TRADED_NFFE_OR_AFFILIATE: 21 — Publicly traded NFFE or affiliate of publicly traded NFFE ACTIVE_NFFE: 22 — Active NFFE INDIVIDUAL: 23 — Individual SECTION_501C_ENTITIES: 24 — Section 501(c) entities EXCEPTED_TERRITORY_NFFE: 25 — Excepted territory NFFE EXCEPTED_NFFE_OTHER: 26 — Excepted NFFE—other EXEMPT_BENEFICIAL_OWNER: 27 — Exempt beneficial owner ENTITY_WHOLLY_OWNED_BY_EXEMPT_BENEFICIAL_OWNERS: 28 — Entity wholly owned by exempt beneficial owners UNKNOWN_RECIPIENT: 29 — Unknown recipient RECALCITRANT_ACCOUNT_HOLDER: 30 — Recalcitrant account holder NONREPORTING_IGA_FFI: 31 — Nonreporting IGA FFI DIRECT_REPORTING_NFFE: 32 — Direct reporting NFFE US_REPORTABLE_ACCOUNT: 33 — U.S. reportable account NONCONSENTING_US_ACCOUNT: 34 — Nonconsenting U.S. account SPONSORED_DIRECT_REPORTING_NFFE: 35 — Sponsored direct reporting NFFE EXCEPTED_INTER_AFFILIATE_FFI: 36 — Excepted inter-affiliate FFI UNDOCUMENTED_PREEXISTING_OBLIGATION: 37 — Undocumented preexisting obligation US_BRANCH_ECI_PRESUMPTION_APPLIED: 38 — U.S. branch—ECI presumption applied ACCOUNT_HOLDER_EXCLUDED_FINANCIAL_ACCOUNT: 39 — Account holder of excluded financial account PASSIVE_NFFE_REPORTED_BY_FFI: 40 — Passive NFFE reported by FFI NFFE_SUBJECT_TO_1472_WITHHOLDING: 41 — NFFE subject to 1472 withholding RECALCITRANT_POOL_NO_US_INDICIA: 42 — Recalcitrant pool—no U.S. indicia RECALCITRANT_POOL_US_INDICIA: 43 — Recalcitrant pool—U.S. indicia RECALCITRANT_POOL_DORMANT_ACCOUNT: 44 — Recalcitrant pool—dormant account RECALCITRANT_POOL_US_PERSONS: 45 — Recalcitrant pool—U.S. persons RECALCITRANT_POOL_PASSIVE_NFFES: 46 — Recalcitrant pool—passive NFFEs NONPARTICIPATING_FFI_POOL: 47 — Nonparticipating FFI pool US_PAYEES_POOL: 48 — U.S. payees pool QI_RECALCITRANT_POOL_GENERAL: 49 — QI-recalcitrant pool—general US_WITHHOLDING_AGENT_FOREIGN_BRANCH: 50 — U.S. withholding agent—foreign branch of FI WithholdingAgentProfile: type: object title: Withholding agent profile description: What Form 1042-S asks of a withholding agent and no other form asks of anyone (boxes 12b, 12c, 12e, 12f and 12g). Box 12a, the withholding agent's EIN, is the filer's own `tin`, and box 12d its `name`, so this object repeats neither. A filer that does not file Form 1042-S omits this object entirely. properties: chapter_3_status: description: Box 12b, which the form prints as the IRS two-digit code. The same table the recipient draws box 13f from — Appendix B describes it as identifying "the type of Withholding Agent, Recipient, Intermediary, or Payer", so one enumeration serves all four roles. $ref: "#/components/schemas/Chapter3Status" chapter_4_status: description: Box 12c, which the form prints as the IRS two-digit code. Chapter 3 and chapter 4 are separate tables whose codes overlap, which is precisely what naming the statuses avoids — for example, `US_BRANCH_TREATED_AS_US_PERSON` is `05` in chapter 3 and `17` in chapter 4. $ref: "#/components/schemas/Chapter4Status" giin: type: string description: Global intermediary identification number, box 12e. maxLength: 19 country: description: Box 12f. $ref: "#/components/schemas/Country" foreign_tin: type: string description: Box 12g. maxLength: 50 PaymentSettlementProfile: type: object title: Payment settlement profile description: "What Form 1099-K asks about the filer: which kind of settlement entity it is, and — where the filer is a facilitator rather than the settlement entity itself — the name and telephone number of the payment settlement entity behind it. A filer that does not file Form 1099-K omits this object entirely." properties: role: type: string description: Whether the filer is the payment settlement entity, or an electronic payment facilitator or other third party acting for one. enum: - PSE - EPF_OR_OTHER_THIRD_PARTY pse_name: type: string description: The payment settlement entity's name, where the filer's `role` is `EPF_OR_OTHER_THIRD_PARTY`. maxLength: 35 pattern: ^([A-Za-z0-9'\-] ?)*[A-Za-z0-9'\-]$ pse_phone_number: description: The payment settlement entity's telephone number, where the filer's `role` is `EPF_OR_OTHER_THIRD_PARTY`. $ref: "#/components/schemas/PhoneNumber" required: - role ClientAttributes: type: object title: Client-Provided Attributes description: | An arbitrary object of client-owned attributes carried alongside the resource. It is never interpreted by the API, and is intended for the client's own identifiers and groupings, such as an internal customer ID or a batch ID. Attributes are returned on resource reads and available in filer, recipient and form list filters. Use the `_client` prefix, for example `_client.customer_id == "8827"`. The object is replaced in full by each update, and its serialized representation is limited to 1KB (1024 bytes); a larger object returns `400 Bad Request`. See [Client-Provided Attributes](#section/Client-Provided-Attributes). additionalProperties: true examples: - customer_id: "8827" batch_id: 2026-Q4-run-3 FilerInput: type: object title: Filer (writable fields) description: | The party with the filing requirement. Every form in the corpus has one, under a different name on each: the paper forms call it the PAYER, FILER, LENDER, CREDITOR, DONEE, ISSUER, TRUSTEE, CORPORATION, TRANSFEROR or ACQUIRER, and Form 1042-S calls it the withholding agent. One crossover warrants attention: on Forms 1098 and 1098-F the party labelled PAYER is the *recipient*, not the filer. Every paper form prints the filer in the upper-left block of every copy. properties: id: description: | Optional. The client may supply its own identifier for the filer at creation — a value from the client's own identifier space — and every later request then addresses the filer by it (e.g., `/api/v2/{tax_year}/filers/acme-payroll-west`), with no table on the client's side mapping its identifiers to Nutshell's. Where the client omits it, the server uses the filer's server-assigned `entity_id` as its `id`. It must be unique among the client's filers, and one already in use is a `409`. It is fixed at creation: an update that supplies a different one is a `409` as well, and an update that omits it leaves the identifier alone. $ref: "#/components/schemas/ResourceId" tin: description: The server returns it in full on read. The IRS matches `tin.taxpayer_id` against the `name` below and rejects a pair it does not know, so a filer whose `tin.status` is `UNMATCHED` fails all of its forms rather than one of them — unlike a recipient, where the IRS reports the mismatch and the form proceeds. For test filings the number must begin with `000`. $ref: "#/components/schemas/Tin" foreign_entity: type: boolean default: false description: "Whether the filer is a foreign entity. The client states the flag rather than the API inferring it from the address, because the intake record requires it of a filer outright — but the two must agree: the API rejects at write time a filer whose `mailing_address` is a `FOREIGN` one and whose `foreign_entity` is false." name: description: The IRS matches it against `tin.taxpayer_id` in its database; a mismatch fails this filer's forms. Changing it returns `tin.status` to `AWAITING_MATCHING`, because the match is of the pair. $ref: "#/components/schemas/PartyName" mailing_address: $ref: "#/components/schemas/Address" phone_number: description: Required. Every paper form prints it inside the filer block ("… and telephone no."), and Form W-2G gives it a box of its own. $ref: "#/components/schemas/PhoneNumber" email_address: description: Form 8809 prints it; no other form does. $ref: "#/components/schemas/EmailAddress" contact: description: The person the IRS contacts about this filer's returns. $ref: "#/components/schemas/ContactPerson" offices: type: array description: The filer's reporting offices. The four-character office code is the filer's own and optional — Pub. 1220 asks only that a filer with multiple locations "enter the office code of the issuer", to identify the location filing the returns, and the IRS then reproduces it on any backup withholding notice it sends about them. Each form names the office it belongs to. The client may leave the list empty for a filer that reports as a single office. items: $ref: "#/components/schemas/FilerOffice" state_registrations: type: array description: | The filer's state withholding registration numbers, one per state. These are what the forms print as "State/Payer's state no." (1099-MISC box 17, 1099-NEC box 6, 1099-R box 15, W-2G box 13), "State identification no." (1099-B box 15, 1099-DIV box 15, 1099-DA box 15, 1099-OID box 13) and "Payer's state tax no." (1042-S box 17b). Holding the number here means a form that supplies the state amounts inherits the number, and may still override it. items: $ref: "#/components/schemas/StateRegistration" routing_transit_number: type: string description: The filer's routing transit number, which Form 1099-INT prints as "Payer's RTN (optional)". That form alone uses it. pattern: ^[0-9]{9}$ examples: - "021000021" withholding_agent: $ref: "#/components/schemas/WithholdingAgentProfile" payment_settlement: $ref: "#/components/schemas/PaymentSettlementProfile" _client: $ref: "#/components/schemas/ClientAttributes" required: - tin - name - mailing_address - phone_number EntityId: type: string format: uuid title: Entity identifier description: | The identifier the API assigns the resource when it is created. It is a UUID, assigned once and fixed for the life of the resource, and it is never reused — deletion retires it along with the resource. Where the resource was created without an `id` supplied by the client, this value is also its `id` and is what addresses it in a URL. It is always present either way, so it is the identifier to record where one is needed that nothing on the client's side chose. readOnly: true examples: - 018f3c7a-9b2e-7c31-8a4d-2f6b91c05e7d Generation: type: integer format: int64 readOnly: true title: Generation description: | A monotonically increasing integer identifying the resource's input version. Edits between snapshots share a generation. After `prepareSnapshot`, new and updated resources receive a higher generation; unchanged resources retain theirs. examples: - 3 Filer: allOf: - $ref: "#/components/schemas/FilerInput" - type: object properties: generation: $ref: "#/components/schemas/Generation" entity_id: description: The identifier the server assigns the filer at creation. Where the client supplies no `id`, this is the filer's `id` as well. $ref: "#/components/schemas/EntityId" created_at: type: string format: date-time readOnly: true description: The time of the filer's creation. updated_at: type: string format: date-time readOnly: true description: The time of the filer's last modification. required: - generation - id - entity_id - created_at - updated_at FilerWithHistory: title: Filer with history allOf: - $ref: "#/components/schemas/Filer" - type: object properties: history: type: array readOnly: true description: | Earlier versions, newest generation first. Each entry contains the last input saved in that generation and its processing results. An empty array means the resource is at its first generation. items: $ref: "#/components/schemas/Filer" required: - history NextPageToken: allOf: - $ref: "#/components/schemas/PageToken" description: "The token to send as `page_token` to retrieve the next page, or the empty string once the end of the collection has been reached. An empty token is the only end-of-collection signal: a page holding fewer resources than `page_size` can still be followed by more." examples: - cGFnZTp2MTpmbHJfMDFIWjhL - "" FilerPage: type: object title: Filer Page properties: resources: type: array description: The filers in this page; the array can be empty. items: $ref: "#/components/schemas/Filer" next_page_token: $ref: "#/components/schemas/NextPageToken" required: - resources - next_page_token Problem: type: object title: Problem Details description: | An error returned with any non-2xx response, as described by [RFC 9457](https://datatracker.ietf.org/doc/html/rfc9457). Responses carrying this body use the `application/problem+json` media type. properties: type: type: string description: A code identifying the problem type. `about:blank` means the problem type is defined entirely by the HTTP status code. examples: - invalid-filter title: type: string description: A short, human-readable summary of the problem type. examples: - Client attributes too large status: type: integer format: int32 minimum: 100 maximum: 599 description: The HTTP status code of this response. examples: - 400 detail: type: string description: A human-readable explanation specific to this occurrence. examples: - "`_client` was 2114 bytes; the limit is 1024 bytes." instance: type: string format: uri-reference description: A URI reference identifying this specific occurrence of the problem. examples: - /api/v2/2026/filers/acme-payroll-west required: - type - title - status RecipientTin: title: Recipient TIN description: | A recipient's TIN, which carries one field a filer's own cannot: `second_notice`, a fact about the pairing of this filer with this recipient. allOf: - $ref: "#/components/schemas/Tin" - type: object properties: second_notice: type: boolean default: false description: | The "2nd TIN not." box printed on Forms 1099-B, DIV, INT, K, MISC, NEC, OID and PATR: whether the IRS has notified this filer twice within three calendar years that this recipient's number is wrong. Notices arrive on paper and the API cannot reconstruct them, so the value is supplied by the client. Set it when migrating a filer whose notice history predates this API. A form issued for the recipient afterwards takes its box from here by default, and may override it. LobCategory: type: string title: LOB category description: |- The limitation-on-benefits treaty category a Form 1042-S recipient claims benefits under. The list begins at `02`; there is no `01`. Read out of Appendix B of the Form 1042-S instructions. enum: - GOVERNMENT_CONTRACTING_STATE - TAX_EXEMPT_PENSION_TRUST_FUND - TAX_EXEMPT_CHARITABLE_ORGANIZATION - PUBLICLY_TRADED_CORPORATION - SUBSIDIARY_OF_PUBLICLY_TRADED_CORPORATION - OWNERSHIP_AND_BASE_EROSION_TEST - DERIVATIVE_BENEFITS_TEST - ACTIVE_TRADE_OR_BUSINESS_TEST - DISCRETIONARY_DETERMINATION - OTHER - NO_LOB_ARTICLE_IN_TREATY x-enumDescriptions: GOVERNMENT_CONTRACTING_STATE: 02 — Government—contracting state/political subdivision/local authority TAX_EXEMPT_PENSION_TRUST_FUND: 03 — Tax exempt pension trust/pension fund TAX_EXEMPT_CHARITABLE_ORGANIZATION: 04 — Tax exempt/charitable organization PUBLICLY_TRADED_CORPORATION: 05 — Publicly traded corporation SUBSIDIARY_OF_PUBLICLY_TRADED_CORPORATION: 06 — Subsidiary of publicly traded corporation OWNERSHIP_AND_BASE_EROSION_TEST: 07 — Company that meets the ownership and base erosion test DERIVATIVE_BENEFITS_TEST: 08 — Company that meets the derivative benefits test ACTIVE_TRADE_OR_BUSINESS_TEST: 09 — Company with an item of income that meets the active trade or business test DISCRETIONARY_DETERMINATION: 10 — Discretionary determination OTHER: 11 — Other NO_LOB_ARTICLE_IN_TREATY: 12 — No LOB article in treaty RecipientForeignStatus: type: object title: Recipient foreign status description: What Form 1042-S asks about a recipient beyond its name, address and TIN (boxes 13b, 13f, 13g, 13h, 13i and 13j). No other form in the corpus asks for any of it, so the client should omit this object entirely for a recipient that receives no Form 1042-S. properties: country: description: The recipient's country of residence for tax purposes, box 13b. Required unless `chapter_3_status` is one of a listed set, and must be a treaty country where the chapter 3 exemption code is `04`; both conditions depend on the form, and the API enforces them there. $ref: "#/components/schemas/Country" chapter_3_status: description: Box 13f, which the form prints as the IRS two-digit code. Certain statuses make the recipient's `tin` mandatory, and certain statuses require it to begin with `98`. $ref: "#/components/schemas/Chapter3Status" chapter_4_status: description: Box 13g, which the form prints as the IRS two-digit code. Chapter 3 and chapter 4 are separate tables whose codes overlap, which is precisely what naming the statuses avoids — for example, `US_BRANCH_TREATED_AS_US_PERSON` is `05` in chapter 3 and `17` in chapter 4. $ref: "#/components/schemas/Chapter4Status" giin: type: string description: Global intermediary identification number, box 13h. maxLength: 19 foreign_tin: type: string description: Box 13i. maxLength: 50 lob_category: description: The limitation-on-benefits treaty category, box 13j, which the form prints as the IRS two-digit code. $ref: "#/components/schemas/LobCategory" RecipientInput: type: object title: Recipient (writable fields) description: | The party a filer issues a form to. As with the filer, every form names it differently: RECIPIENT, BORROWER, DEBTOR, DONOR, STUDENT, PARTICIPANT, BENEFICIARY, EMPLOYEE, SHAREHOLDER, WINNER, SELLER, TRANSFEROR, POLICYHOLDER, PAYMENT RECIPIENT — and, on Forms 1098 and 1098-F, PAYER. All of them are this shape. Paper forms print it beneath the filer block. properties: id: description: | Optional. The client may supply its own identifier for the recipient at creation — for example, the customer or account-holder number the client already knows the party by — and every later request then addresses the recipient by it, with no table on the client's side mapping its identifiers to Nutshell's. Where the client omits it, the server uses the recipient's server-assigned `entity_id` as its `id`. It must be unique across the client's recipients, including those under different filers; the server rejects one already in use with `409 Conflict`. Creation settles it: the server rejects an update that supplies a different one with `409 Conflict` as well, and an update that omits it leaves the identifier alone. $ref: "#/components/schemas/ResourceId" examples: - "8827" tin: description: | The server returns it in full on read. Optional; Nutshell Labs recommends that the client supply it, since the IRS asks for a TIN on every return, and a return that lacks one can draw a penalty notice. Where the client supplies it, the server matches `tin.taxpayer_id` against `name` in the IRS database and reports the outcome on `tin.status`. For test filings, the client supplies a number beginning with `000`. `tin.second_notice` records repeated notices that the number is wrong, and it defaults the "2nd TIN not." box on every form the filer issues to this recipient. $ref: "#/components/schemas/RecipientTin" name: description: The server matches it against `tin.taxpayer_id` in the IRS database where both are present. Changing it returns `tin.status` to `AWAITING_MATCHING`, because the match is of the pair. $ref: "#/components/schemas/PartyName" additional_name: type: string description: A second party on the account. The paper forms have no box for it and run it on after the name. maxLength: 75 pattern: ^(([A-Za-z0-9#\-()]|&|') ?)*([A-Za-z0-9#\-()]|&|')$ mailing_address: description: Required. Every paper form prints it, and the statement must reach the recipient. $ref: "#/components/schemas/Address" date_of_birth: type: string format: date description: Only Form 1042-S prints it, in box 13l, which renders it `YYYYMMDD`. foreign_status: $ref: "#/components/schemas/RecipientForeignStatus" _client: $ref: "#/components/schemas/ClientAttributes" required: - name - mailing_address Recipient: allOf: - $ref: "#/components/schemas/RecipientInput" - type: object properties: generation: $ref: "#/components/schemas/Generation" entity_id: description: The identifier the server assigns the recipient at creation. Where the client supplies no `id`, this is its `id` as well. $ref: "#/components/schemas/EntityId" filer_id: type: string readOnly: true description: The `id` of the filer this recipient belongs to. examples: - acme-payroll-west created_at: type: string format: date-time readOnly: true description: The time of the recipient's creation. updated_at: type: string format: date-time readOnly: true description: The time of the recipient's last modification. required: - generation - id - entity_id - filer_id - created_at - updated_at RecipientWithHistory: title: Recipient with history allOf: - $ref: "#/components/schemas/Recipient" - type: object properties: history: type: array readOnly: true description: | Earlier versions, newest generation first. Each entry contains the last input saved in that generation and its processing results. An empty array means the resource is at its first generation. items: $ref: "#/components/schemas/Recipient" required: - history RecipientPage: type: object title: Recipient Page properties: resources: type: array description: The recipients in this page; the array can be empty. items: $ref: "#/components/schemas/Recipient" next_page_token: $ref: "#/components/schemas/NextPageToken" required: - resources - next_page_token Form1098: type: object title: Form 1098 description: | Mortgage interest of $600 or more received in the course of the filer's trade or business from an individual, including a sole proprietor. One instance is one printed form. properties: account_number: type: string description: The filer's own account number for this borrower, printed as "Account number (see instructions)". A field of the form rather than of the borrower, who can hold more than one mortgage with this lender. Where the filer issues more than one Form 1098 to the same TIN, each form needs a distinct value. maxLength: 30 pattern: ^([!-~£§ÁÉÍÑÓ×ÚÜáéíñóúü] ?)*[!-~£§ÁÉÍÑÓ×ÚÜáéíñóúü]$ examples: - 4471902-01 mortgage_interest_received: type: string format: decimal description: Box 1. Mortgage interest, not counting points, received from the payer(s)/borrower(s) during the calendar year, in US dollars. Report 0.00 for a year whose only reportable item is the box 4 refund. pattern: ^[0-9]+(\.[0-9]{2})?$ examples: - "12480.55" outstanding_mortgage_principal: type: string format: decimal description: Box 2. Principal outstanding as of 1 January of the calendar year, in US dollars, or as of the origination date for a mortgage originated during the year. Report 0.00 where the mortgage originated during the year and the borrower has already repaid it. pattern: ^[0-9]+(\.[0-9]{2})?$ mortgage_origination_date: type: string format: date description: Box 3. The date the mortgage was originated. Supply as `YYYY-MM-DD`; the recipient copies print it in the form's own layout. pattern: ^[1-9][0-9]{3}-(0[1-9]|1[0-2])-(0[1-9]|[1-2][0-9]|3[0-1])$ examples: - "2026-03-14" refund_of_overpaid_interest: type: string format: decimal description: Box 4. Interest overpaid in a prior year and refunded or credited to the borrower this year, in US dollars. Reportable when it reaches $600 for the year, and reportable even where no interest was received — the borrower can be required to add it back to income. pattern: ^[0-9]+(\.[0-9]{2})?$ mortgage_insurance_premiums: type: string format: decimal description: Box 5. Mortgage insurance premiums received, in US dollars, where reportable for the year. pattern: ^[0-9]+(\.[0-9]{2})?$ points_paid_on_principal_residence: type: string format: decimal description: Box 6. Points paid directly by the borrower on the purchase of a principal residence, in US dollars. Points on a refinancing, on a second home or on business property do not belong here. pattern: ^[0-9]+(\.[0-9]{2})?$ property_address_same_as_borrower: type: boolean default: false description: Box 7. Whether the address of the property securing the mortgage is the same as the payer's/borrower's address. If this is false, supply either `property_address` or `property_description`. If it is true, leave both empty — the borrower's own address is what prints in box 8. property_address: description: Box 8, where the property securing the mortgage has a street address. Supply this or `property_description`, not both. $ref: "#/components/schemas/Address" property_description: type: string description: Box 8, where the property has no street address — the section, lot and block, or a like description that identifies it. Supply this or `property_address`, not both. maxLength: 1000 pattern: ^([!-~£§ÁÉÍÑÓ×ÚÜáéíñóúü] ?)*[!-~£§ÁÉÍÑÓ×ÚÜáéíñóúü]$ examples: - Lot 14 Block 3 Cedar Ridge Subdivision Wake County NC number_of_properties_securing_mortgage: type: integer description: Box 9. How many properties secure the mortgage, where that is more than one. Leave it empty for a single property; the IRS reads an empty box as one. minimum: 0 maximum: 9999999999 examples: - 2 other: type: string description: Box 10. Free text for anything else the filer wishes to report to the borrower, such as real estate taxes or insurance paid from escrow. The IRS does not parse it. maxLength: 150 pattern: ^([!-~£§ÁÉÍÑÓ×ÚÜáéíñóúü] ?)*[!-~£§ÁÉÍÑÓ×ÚÜáéíñóúü]$ examples: - Real estate taxes paid from escrow 3418.00 mortgage_acquisition_date: type: string format: date description: Box 11. The date the filer acquired the mortgage, where it was acquired during the calendar year. Supply as `YYYY-MM-DD`. pattern: ^[1-9][0-9]{3}-(0[1-9]|1[0-2])-(0[1-9]|[1-2][0-9]|3[0-1])$ filer_office_code: type: string description: The filer's reporting office for this form. Defaults to the filer's single office; set it only where the filer has more than one and this form belongs to other than the default. minLength: 4 maxLength: 4 pattern: ^([!-~£§ÁÉÍÑÓ×ÚÜáéíñóúü] ?)*[!-~£§ÁÉÍÑÓ×ÚÜáéíñóúü]$ examples: - "0001" required: - mortgage_interest_received Form1098Body: title: Form 1098 allOf: - type: object properties: type: type: string const: "1098" required: - type - $ref: "#/components/schemas/Form1098" Form3921OtherCorporation: type: object title: Form 3921 other corporation description: The corporation whose stock was transferred, where it is not the transferor. Box 6 prints its name, address and TIN together on one line. properties: name: type: object title: Corporation name properties: line1: type: string maxLength: 75 pattern: ^(([A-Za-z0-9#\-()]|&|') ?)*([A-Za-z0-9#\-()]|&|')$ examples: - Bellwether Holdings Inc line2: type: string description: A continuation of the name, or a name the corporation does business as. maxLength: 75 pattern: ^(([A-Za-z0-9#/%\-()]|&|') ?)*([A-Za-z0-9#/%\-()]|&|')$ required: - line1 mailing_address: $ref: "#/components/schemas/Address" taxpayer_id: type: string description: The corporation's EIN, nine digits unpunctuated. Printed in box 6 after the address. pattern: ^[0-9]{9}$ examples: - "001234567" required: - name Form3921: type: object title: Form 3921 description: | One transfer of stock acquired through the exercise of an incentive stock option described in section 422(b). A separate form is required for each exercise, and for each employee — a corporation that transfers stock on two exercises in one year files two forms. The employee needs every box on this form to compute the alternative minimum tax adjustment for the year of exercise and the basis of the shares on a later sale, so boxes 1 through 5 — the boxes the IRS treats as the substance of the return — are all required here. properties: date_option_granted: type: string format: date description: "Box 1: the date the incentive stock option was granted. Required — the holding period that decides whether the eventual sale is a qualifying disposition runs from this date. Supply as `YYYY-MM-DD`." examples: - "2021-03-15" date_option_exercised: type: string format: date description: "Box 2: the date the option was exercised and the stock transferred. Required. It fixes both the second holding period and the date on which the fair market value in box 4 is measured. Supply as `YYYY-MM-DD`." examples: - "2026-06-02" exercise_price_per_share: type: string format: decimal description: "Box 3: the price per share the employee paid to exercise, in US dollars. Not a total — multiply by box 5 for the amount paid. Required: the employee's AMT adjustment is the excess of box 4 over box 3, and a form without it cannot be used for the purpose it is furnished for." pattern: ^[0-9]+(\.[0-9]{2})?$ examples: - "4.50" fair_market_value_per_share: type: string format: decimal description: "Box 4: the fair market value of one share on the exercise date, in US dollars. Required for the same reason as box 3. Where the option was granted under a plan whose terms allow it, this can differ from the exercise price by a great deal; report the value actually determined on the exercise date rather than a plan valuation from another date." pattern: ^[0-9]+(\.[0-9]{2})?$ examples: - "31.75" shares_transferred: type: integer description: "Box 5: how many shares were transferred on this exercise. Required. Whole shares only — the IRS admits no fractional count here." minimum: 0 maximum: 9999999999 examples: - 1200 other_corporation: description: "Box 6: the corporation whose stock was transferred, where that is not the transferor filing this form — as when the stock is that of a parent or subsidiary of the employer. Omit the whole object when the transferor is the corporation, which is the ordinary case; the paper box is then left blank." $ref: "#/components/schemas/Form3921OtherCorporation" account_number: type: string description: The transferor's own identifier for this employee's account, printed above box 1. A field of the form rather than of the employee, who can exercise more than once. Where more than one Form 3921 is filed for the same employee, give each form a distinct value — an account number is required on every such form after the first. maxLength: 30 pattern: ^(([!-~£§ÁÉÍÑÓ×ÚÜáéíñóúü]) ?)*[!-~£§ÁÉÍÑÓ×ÚÜáéíñóúü]$ examples: - ISO-2025-0417 filer_office_code: type: string description: The transferor's reporting office for this form. Defaults to the filer's single office; supply it only where the filer has more than one and this form belongs to a particular one of them. Exactly four characters. minLength: 4 maxLength: 4 examples: - "0001" required: - date_option_granted - date_option_exercised - exercise_price_per_share - fair_market_value_per_share - shares_transferred Form3921Body: title: Form 3921 allOf: - type: object properties: type: type: string const: "3921" required: - type - $ref: "#/components/schemas/Form3921" Form3922: type: object title: Form 3922 description: | One transfer of legal title to shares the employee acquired under a section 423(c) employee stock purchase plan, where the exercise price was less than the value of the stock on the grant date or was not fixed or determinable on that date. One form per transfer: a corporation that transfers title to the same employee's shares on two occasions files two of these. Where the same recipient TIN appears on more than one form, set a distinct `account_number` on each. properties: date_option_granted: type: string format: date description: Box 1. The date the option was granted to the employee — the start of the offering period, not the date of purchase. The employee's holding period and the box 3 valuation are both taken from this date. date_option_exercised: type: string format: date description: Box 2. The date the option was exercised, which for a typical plan is the purchase date at the end of the offering period. fair_market_value_on_grant_date: type: string format: decimal description: Box 3. Fair market value of one share on the date in box 1, in US dollars. Per share, not for the whole block. Never negative. pattern: ^[0-9]+(\.[0-9]{2})?$ examples: - "21.40" fair_market_value_on_exercise_date: type: string format: decimal description: Box 4. Fair market value of one share on the date in box 2, in US dollars. With box 5 this is what determines the discount the employee reports as ordinary income. Never negative. pattern: ^[0-9]+(\.[0-9]{2})?$ examples: - "25.05" exercise_price_paid_per_share: type: string format: decimal description: Box 5. What the employee actually paid for one share, in US dollars. Where the price was not fixed or determinable on the grant date this is the price computed under the plan on the exercise date, and box 8 must then also be completed. Never negative. pattern: ^[0-9]+(\.[0-9]{2})?$ examples: - "21.29" shares_transferred: type: integer description: Box 6. The number of whole shares whose legal title was transferred. Supply a whole number of at most ten digits; fractional shares cannot be reported. minimum: 0 maximum: 9999999999 examples: - 143 date_legal_title_transferred: type: string format: date description: Box 7. The date legal title to the shares was first transferred to the employee. This field is optional; we recommend supplying it, since the statement is of little use to the employee without it. exercise_price_per_share_on_grant_date: type: string format: decimal description: Box 8. The exercise price per share as it would have been had the option been exercised on the grant date in box 1, in US dollars. Completed only where the exercise price was not fixed or determinable on the grant date — for a plan with a fixed price, leave it out rather than repeating box 5. Never negative. pattern: ^[0-9]+(\.[0-9]{2})?$ examples: - "18.19" account_number: type: string description: 'The corporation''s own identifier for this employee''s plan account, printed under "Account number (see instructions)". A field of the form rather than of the employee: where the same recipient TIN appears on more than one form, each needs a distinct value.' maxLength: 30 pattern: ^([!-~£§ÁÉÍÑÓ×ÚÜáéíñóúü] ?)*[!-~£§ÁÉÍÑÓ×ÚÜáéíñóúü]$ examples: - ESPP-4471902-01 filer_office_code: type: string description: The reporting office this form belongs to. Exactly four characters. Defaults to the filer's single office; supply it only for a filer with more than one. minLength: 4 maxLength: 4 pattern: ^([!-~£§ÁÉÍÑÓ×ÚÜáéíñóúü] ?)*[!-~£§ÁÉÍÑÓ×ÚÜáéíñóúü]$ examples: - "0001" required: - date_option_granted - date_option_exercised - shares_transferred Form3922Body: title: Form 3922 allOf: - type: object properties: type: type: string const: "3922" required: - type - $ref: "#/components/schemas/Form3922" Form5498PostponedOrLateContribution: type: object title: Postponed or late contribution description: A contribution reported in boxes 13a to 13c, with the reason it is late. properties: amount: type: string format: decimal description: Box 13a, in US dollars. Required within this group; omit the whole group rather than sending it empty. pattern: ^[0-9]+(\.[0-9]{2})?$ year: type: string description: "Box 13b: the year the contribution is for, which is earlier than the tax year of the form. Left empty for a late rollover or a plan loan offset rollover, where the contribution belongs to no particular earlier year." pattern: ^[1-9][0-9]{3}$ examples: - "2023" reason: type: string title: Postponed or late contribution reason description: "Box 13c: why the contribution is postponed or late. Required within this group." enum: - FEDERALLY_DESIGNATED_DISASTER - PUBLIC_LAW - EXECUTIVE_ORDER - QUALIFIED_PLAN_LOAN_OFFSET_ROLLOVER - SELF_CERTIFIED_LATE_ROLLOVER x-enumDescriptions: FEDERALLY_DESIGNATED_DISASTER: "`FD` — federally designated disaster area: the participant is an affected taxpayer described in an IRS news release." PUBLIC_LAW: "`PL` — public law authorizing the postponed contribution for service in a combat zone, hazardous duty area, or direct support area." EXECUTIVE_ORDER: "`EO` — executive order authorizing the postponed contribution for service in a combat zone, hazardous duty area, or direct support area." QUALIFIED_PLAN_LOAN_OFFSET_ROLLOVER: "`PO` — rollover of a qualified plan loan offset amount." SELF_CERTIFIED_LATE_ROLLOVER: "`SC` — the participant self-certified that the rollover contribution is late for one of the circumstances listed in Rev. Proc. 2020-46." reason_detail: type: string description: The number identifying the authority named by `reason`, printed after the code in box 13c. Required with `EXECUTIVE_ORDER`, where it must be `13239`, `12744` or `13119`, and with `PUBLIC_LAW`, where it must be `115-97` or `106-21`. Leave it empty for the other three reasons. maxLength: 20 examples: - 115-97 required: - amount - reason Form5498SpecifiedAssetType: type: string title: Specified asset type description: One kind of asset with no readily available fair market value, as listed in box 15b. enum: - NON_TRADABLE_CORPORATE_STOCK - NON_TRADED_DEBT_OBLIGATION - LLC_INTEREST - REAL_ESTATE - PARTNERSHIP_OR_TRUST_INTEREST - NON_EXCHANGE_TRADED_OPTION - OTHER_ASSET_WITHOUT_READILY_AVAILABLE_FMV - MORE_THAN_TWO_ASSET_TYPES x-enumDescriptions: NON_TRADABLE_CORPORATE_STOCK: "`A` — stock or other ownership interest in a corporation that is not readily tradable on an established securities market." NON_TRADED_DEBT_OBLIGATION: "`B` — short- or long-term debt obligation that is not traded on an established securities market." LLC_INTEREST: "`C` — ownership interest in a limited liability company or similar entity, unless the interest is traded on an established securities market." REAL_ESTATE: "`D` — real estate." PARTNERSHIP_OR_TRUST_INTEREST: "`E` — ownership interest in a partnership, trust, or similar entity, unless the interest is traded on an established securities market." NON_EXCHANGE_TRADED_OPTION: "`F` — option contract or similar product that is not offered for trade on an established option exchange." OTHER_ASSET_WITHOUT_READILY_AVAILABLE_FMV: "`G` — other asset that does not have a readily available fair market value." MORE_THAN_TWO_ASSET_TYPES: "`H` — more than two of the types above are held in this IRA. Not combinable with any other entry." Form5498StateLocalTax: type: object title: State and local tax description: One state's figures for this account, and optionally one locality's within it. None of it prints on the paper form. properties: state: description: The state the entry is for. $ref: "#/components/schemas/StateCode" state_id_number: type: string description: The filer's withholding registration number in this state. Defaults to the filer's `state_registrations` entry for `state`; set it here only to override that. maxLength: 25 state_tax_withheld: type: string format: decimal description: State income tax withheld on the account, in US dollars. pattern: ^[0-9]+(\.[0-9]{2})?$ state_income: type: string format: decimal description: The amount reportable to this state as income, in US dollars. Rarely used on a 5498, whose boxes report contributions and account value rather than income. pattern: ^[0-9]+(\.[0-9]{2})?$ state_distribution: type: string format: decimal description: The amount distributed and reportable to this state, in US dollars. pattern: ^[0-9]+(\.[0-9]{2})?$ local_tax_withheld: type: string format: decimal description: Local income tax withheld on the account, in US dollars. pattern: ^[0-9]+(\.[0-9]{2})?$ local_income: type: string format: decimal description: The amount reportable to the locality as income, in US dollars. pattern: ^[0-9]+(\.[0-9]{2})?$ locality: type: string description: The name of the locality the local figures belong to. maxLength: 20 locality_code: type: string description: The locality's own abbreviation or code, where it has one. maxLength: 10 local_distribution: type: string format: decimal description: The amount distributed and reportable to the locality, in US dollars. pattern: ^[0-9]+(\.[0-9]{2})?$ special_data_entries: type: string description: Free text the filer and the state have agreed on between themselves. The IRS passes it through and does nothing with it. maxLength: 60 required: - state Form5498: type: object title: Form 5498 description: | IRA Contribution Information: what a trustee or issuer reports for each traditional IRA, SEP IRA, SIMPLE IRA or Roth IRA it maintained during the year. Note that nothing on this form is a payment to the participant — the amounts are contributions to, and the value of, an account. Distributions from the same account are reported on Form 1099-R instead. One form covers one account. A trustee that maintains both a traditional IRA and a Roth IRA for the same participant files two forms, distinguished by `account_number`. properties: ira_contributions: type: string format: decimal description: "Box 1, in US dollars: traditional IRA contributions made for this tax year, including any recharacterized *into* this IRA. Excludes everything reported in boxes 2, 3, 4, 8, 9, 10, 13a and 14a — a rollover, conversion, recharacterization out, SEP, SIMPLE or Roth contribution, postponed or late contribution and repayment each has its own box, and none is added in here." pattern: ^[0-9]+(\.[0-9]{2})?$ examples: - "7000.00" rollover_contributions: type: string format: decimal description: "Box 2, in US dollars: all rollover contributions received during the calendar year, including a late rollover reported in box 13a and a qualified plan loan offset rollover." pattern: ^[0-9]+(\.[0-9]{2})?$ roth_ira_conversion: type: string format: decimal description: "Box 3, in US dollars: amounts converted from a traditional, SEP or SIMPLE IRA to a Roth IRA during the year. Reported by the trustee of the *Roth* IRA that received the conversion; the distributing trustee reports the same movement on Form 1099-R." pattern: ^[0-9]+(\.[0-9]{2})?$ recharacterized_contributions: type: string format: decimal description: "Box 4, in US dollars: contributions recharacterized out of this IRA into another kind of IRA, reported by the trustee of the IRA the amount left." pattern: ^[0-9]+(\.[0-9]{2})?$ fair_market_value_of_account: type: string format: decimal description: "Box 5, in US dollars: the fair market value of the account on 31 December of the tax year. Required — the trustee owes a value for every account it maintained, and the participant's required minimum distribution for the following year is computed from it." pattern: ^[0-9]+(\.[0-9]{2})?$ examples: - "148230.55" life_insurance_cost: type: string format: decimal description: "Box 6, in US dollars: the cost of life insurance included in box 1, reported for an endowment contract only. It is part of `ira_contributions` and must not exceed it, so supply box 1 alongside it." pattern: ^[0-9]+(\.[0-9]{2})?$ account_type: type: string title: Account type description: "Box 7: which kind of IRA this form reports. Required, because the box selects mutually exclusive treatments and the boxes that can then be filled differ." enum: - IRA - SEP - SIMPLE - ROTH_IRA x-enumDescriptions: IRA: "`IRAInd` = 1 — IRA: a traditional IRA, including one holding a deemed IRA." SEP: "`SEPInd` = 1 — SEP: a simplified employee pension IRA." SIMPLE: "`SIMPLEInd` = 1 — SIMPLE: a SIMPLE IRA, but not a SIMPLE 401(k)." ROTH_IRA: "`RothIRAInd` = 1 — Roth IRA." sep_contributions: type: string format: decimal description: "Box 8, in US dollars: employer contributions to a SEP IRA received during the calendar year, including salary-reduction contributions to a SARSEP. Reported on a cash basis for the year received, not the year they are for, which is why this box is not part of box 1." pattern: ^[0-9]+(\.[0-9]{2})?$ simple_contributions: type: string format: decimal description: "Box 9, in US dollars: SIMPLE IRA contributions received during the calendar year, employer and salary-reduction alike. Also on a cash basis." pattern: ^[0-9]+(\.[0-9]{2})?$ roth_ira_contributions: type: string format: decimal description: "Box 10, in US dollars: Roth IRA contributions made for this tax year, including amounts recharacterized into the Roth IRA. Excludes conversions, which belong in box 3." pattern: ^[0-9]+(\.[0-9]{2})?$ rmd_required: type: boolean default: false description: 'Box 11: whether a required minimum distribution is due from this account for the year after the tax year — printed on the form as "Check if RMD for" the following year. Check it for a participant who reaches the applicable age, and for a beneficiary account subject to annual distributions.' rmd_date: type: string format: date description: "Box 12a: the date by which the required minimum distribution named in box 12b must be taken. For a participant taking a first RMD it is 1 April of the year after the year the age is reached; otherwise 31 December. Fill boxes 12a and 12b only where `rmd_required` is true; alternatively the trustee can send the participant a separate RMD statement and leave both empty." examples: - "2027-12-31" rmd_amount: type: string format: decimal description: "Box 12b, in US dollars: the required minimum distribution the trustee computes for the following year. Zero is a meaningful value here — it says the trustee computed the figure and it came to nothing, which is not the same as leaving the box empty." pattern: ^[0-9]+(\.[0-9]{2})?$ postponed_or_late_contribution: description: "Boxes 13a to 13c: a contribution made in this calendar year but attributable to an earlier year — a postponed contribution for service in a combat zone or for a federally declared disaster, a late rollover, or a qualified plan loan offset rollover. Only one such contribution fits on one form; a participant with two needs two forms." $ref: "#/components/schemas/Form5498PostponedOrLateContribution" repayments: type: string format: decimal description: "Box 14a, in US dollars: repayments of a distribution the law allows to be repaid to the IRA. Supply `repayment_type` with it." pattern: ^[0-9]+(\.[0-9]{2})?$ repayment_type: type: string title: Repayment type description: "Box 14b: which kind of distribution the amount in box 14a repays. Required whenever `repayments` is greater than zero." enum: - QUALIFIED_RESERVIST - QUALIFIED_DISASTER - BIRTH_OR_ADOPTION - EMERGENCY_PERSONAL_EXPENSE - DOMESTIC_ABUSE_VICTIM - TERMINALLY_ILL x-enumDescriptions: QUALIFIED_RESERVIST: "`QR` — qualified reservist distribution." QUALIFIED_DISASTER: "`DD` — qualified disaster distribution." BIRTH_OR_ADOPTION: "`BA` — qualified birth or adoption distribution." EMERGENCY_PERSONAL_EXPENSE: "`EP` — emergency personal expense distribution." DOMESTIC_ABUSE_VICTIM: "`DA` — eligible distribution to a domestic abuse victim." TERMINALLY_ILL: "`TI` — distribution to a terminally ill individual." specified_assets_fair_market_value: type: string format: decimal description: "Box 15a, in US dollars: the fair market value of those assets in the account that have no readily available value — the subset of box 5, not an addition to it." pattern: ^[0-9]+(\.[0-9]{2})?$ specified_asset_types: type: array description: "Box 15b: which kinds of hard-to-value asset the box 15a figure covers. List at most two; where the account holds more than two, list `MORE_THAN_TWO_ASSET_TYPES` alone. Fill this whenever `specified_assets_fair_market_value` is present." items: $ref: "#/components/schemas/Form5498SpecifiedAssetType" minItems: 1 maxItems: 2 uniqueItems: true state_and_local_taxes: type: array description: State and local figures for this account. Form 5498 prints no state boxes, so none of this reaches the participant's copy; supply it for states served through combined federal/state filing, and for a state's own reporting of amounts withheld from or distributed on the account. items: $ref: "#/components/schemas/Form5498StateLocalTax" combined_federal_state_filing_states: type: array description: The states this form is to be forwarded to under the Combined Federal/State Filing program, so that the filer need not send it to them directly. Name only participating states — AL, AZ, AR, CA, CT, CO, DC, DE, GA, HI, ID, IN, KS, LA, MA, MD, ME, MI, MN, MS, MT, NE, NJ, NM, NC, ND, OH, OK, OR, PA, RI, SC and WI. items: $ref: "#/components/schemas/StateCode" maxItems: 62 uniqueItems: true account_number: type: string description: "The trustee's or issuer's own number for the account, printed above box 1. It names the IRA this form reports rather than the participant: someone with more than one IRA at the same trustee receives one form per account, and each form filed for that participant must carry a distinct account number." maxLength: 30 examples: - IRA-4471902-01 filer_office_code: type: string description: Which of the filer's reporting offices this form belongs to. Defaults to the filer's single office. Exactly four characters. minLength: 4 maxLength: 4 examples: - "0001" required: - fair_market_value_of_account - account_type Form5498Body: title: Form 5498 allOf: - type: object properties: type: type: string const: "5498" required: - type - $ref: "#/components/schemas/Form5498" Form1042SIncomeCode: type: string title: Income code description: Box 1, printed as the IRS two-digit code. Codes `59`, `60` and `61` are optional for 2026 reporting and are accepted here for filers that adopt them early. enum: - INTEREST_PAID_BY_US_OBLIGORS_GENERAL - INTEREST_ON_REAL_PROPERTY_MORTGAGES - INTEREST_TO_CONTROLLING_FOREIGN_CORPORATIONS - INTEREST_BY_FOREIGN_CORPORATIONS - INTEREST_TAX_FREE_COVENANT_BONDS - DIVIDENDS_US_CORPORATIONS_GENERAL - DIVIDENDS_DIRECT_DIVIDEND_RATE - DIVIDENDS_FOREIGN_CORPORATIONS - CAPITAL_GAINS - INDUSTRIAL_ROYALTIES - MOTION_PICTURE_TV_COPYRIGHT_ROYALTIES - OTHER_ROYALTIES - ROYALTIES_PUBLICLY_OFFERED_SECURITIES - REAL_PROPERTY_INCOME_AND_ROYALTIES - PENSIONS_ANNUITIES_ALIMONY_INSURANCE - SCHOLARSHIP_FELLOWSHIP_GRANTS - COMPENSATION_INDEPENDENT_PERSONAL_SERVICES - COMPENSATION_DEPENDENT_PERSONAL_SERVICES - COMPENSATION_FOR_TEACHING - COMPENSATION_DURING_STUDYING_TRAINING - INTEREST_DEPOSIT_FOREIGN_BRANCH - OTHER_INCOME - QIE_DISTRIBUTIONS_CAPITAL_GAINS - TRUST_DISTRIBUTIONS_1445 - UNSEVERED_GROWING_CROPS_TIMBER_1445 - PTP_DISTRIBUTIONS_1446A - GAMBLING_WINNINGS - DEPOSIT_INTEREST - ORIGINAL_ISSUE_DISCOUNT_OID - SHORT_TERM_OID - NOTIONAL_PRINCIPAL_CONTRACT_INCOME - SUBSTITUTE_PAYMENT_INTEREST - SUBSTITUTE_PAYMENT_DIVIDENDS - SUBSTITUTE_PAYMENT_OTHER - CAPITAL_GAINS_DISTRIBUTIONS - RETURN_OF_CAPITAL - ELIGIBLE_DEFERRED_COMPENSATION_877A_D1 - NONGRANTOR_TRUST_DISTRIBUTIONS_877A_F1 - OTHER_DIVIDEND_EQUIVALENTS_871M - GUARANTEE_OF_INDEBTEDNESS - ARTIST_ATHLETE_NO_CENTRAL_WITHHOLDING_AGREEMENT - ARTIST_ATHLETE_CENTRAL_WITHHOLDING_AGREEMENT - SPECIFIED_FEDERAL_PROCUREMENT_PAYMENTS - INCOME_PREVIOUSLY_REPORTED_ESCROW_PROCEDURE - INTEREST_ACTIVELY_TRADED_SECURITIES - DIVIDENDS_ACTIVELY_TRADED_SECURITIES - SUBSTITUTE_DIVIDENDS_ACTIVELY_TRADED_SECURITIES - SUBSTITUTE_INTEREST_ACTIVELY_TRADED_SECURITIES - TAXABLE_DEATH_BENEFITS_LIFE_INSURANCE - DIVIDEND_EQUIVALENTS_COMBINED_TRANSACTION_RULES - AMOUNT_REALIZED_1446F - PTP_DISTRIBUTIONS_UNDETERMINED - CONSENT_FEES - LOAN_SYNDICATION_FEES - SETTLEMENT_PAYMENTS x-enumDescriptions: INTEREST_PAID_BY_US_OBLIGORS_GENERAL: "`01` — interest paid by U.S. obligors, general." INTEREST_ON_REAL_PROPERTY_MORTGAGES: "`02` — interest paid on real property mortgages." INTEREST_TO_CONTROLLING_FOREIGN_CORPORATIONS: "`03` — interest paid to controlling foreign corporations." INTEREST_BY_FOREIGN_CORPORATIONS: "`04` — interest paid by foreign corporations." INTEREST_TAX_FREE_COVENANT_BONDS: "`05` — interest on tax-free covenant bonds." DIVIDENDS_US_CORPORATIONS_GENERAL: "`06` — dividends paid by U.S. corporations, general, including deemed dividends such as those under section 305(c). Use another code for dividends on actively traded securities and for dividend equivalents." DIVIDENDS_DIRECT_DIVIDEND_RATE: "`07` — dividends qualifying for the direct dividend rate." DIVIDENDS_FOREIGN_CORPORATIONS: "`08` — dividends paid by foreign corporations." CAPITAL_GAINS: "`09` — capital gains, including gains on disposal of timber, coal or domestic iron ore with a retained economic interest, and gains on contingent payments from the sale of patents, copyrights and the like." INDUSTRIAL_ROYALTIES: "`10` — industrial royalties." MOTION_PICTURE_TV_COPYRIGHT_ROYALTIES: "`11` — motion picture or television copyright royalties." OTHER_ROYALTIES: "`12` — other royalties, for example copyright, software, broadcasting and endorsement payments." ROYALTIES_PUBLICLY_OFFERED_SECURITIES: "`13` — royalties paid on certain publicly offered securities; used only if the income is described in Regulations section 1.1441-6(c)(2) and the withholding agent reduced the rate under a treaty without a U.S. TIN or FTIN." REAL_PROPERTY_INCOME_AND_ROYALTIES: "`14` — real property income and natural resources royalties." PENSIONS_ANNUITIES_ALIMONY_INSURANCE: "`15` — pensions, annuities, alimony and/or insurance premiums." SCHOLARSHIP_FELLOWSHIP_GRANTS: "`16` — scholarship or fellowship grants." COMPENSATION_INDEPENDENT_PERSONAL_SERVICES: "`17` — compensation for independent personal services; if directly attributable to the recipient's occupation as an artist or athlete, use `42` or `43` instead." COMPENSATION_DEPENDENT_PERSONAL_SERVICES: "`18` — compensation for dependent personal services; if attributable to an artist or athlete occupation, use `42` or `43` instead." COMPENSATION_FOR_TEACHING: "`19` — compensation for teaching; if attributable to an artist or athlete occupation, use `42` or `43` instead." COMPENSATION_DURING_STUDYING_TRAINING: "`20` — compensation during studying and training; if attributable to an artist or athlete occupation, use `42` or `43` instead." INTEREST_DEPOSIT_FOREIGN_BRANCH: "`22` — interest paid on a deposit with a foreign branch of a domestic corporation or partnership." OTHER_INCOME: "`23` — other income." QIE_DISTRIBUTIONS_CAPITAL_GAINS: "`24` — qualified investment entity distributions of capital gains." TRUST_DISTRIBUTIONS_1445: "`25` — trust distributions subject to section 1445." UNSEVERED_GROWING_CROPS_TIMBER_1445: "`26` — unsevered growing crops and timber distributions by a trust subject to section 1445." PTP_DISTRIBUTIONS_1446A: "`27` — publicly traded partnership distributions subject to section 1446(a)." GAMBLING_WINNINGS: "`28` — gambling winnings, subject to a 30% rate unless the recipient is from a treaty country listed in Pub. 515." DEPOSIT_INTEREST: "`29` — deposit interest." ORIGINAL_ISSUE_DISCOUNT_OID: "`30` — original issue discount." SHORT_TERM_OID: "`31` — short-term original issue discount." NOTIONAL_PRINCIPAL_CONTRACT_INCOME: "`32` — notional principal contract income; use the appropriate interest income code where a nonperiodic payment is treated as a loan." SUBSTITUTE_PAYMENT_INTEREST: "`33` — substitute payment, interest." SUBSTITUTE_PAYMENT_DIVIDENDS: "`34` — substitute payment, dividends." SUBSTITUTE_PAYMENT_OTHER: "`35` — substitute payment, other." CAPITAL_GAINS_DISTRIBUTIONS: "`36` — capital gains distributions." RETURN_OF_CAPITAL: "`37` — return of capital; report these nondividend payments with chapter 4 exemption code `21`." ELIGIBLE_DEFERRED_COMPENSATION_877A_D1: "`38` — eligible deferred compensation items subject to section 877A(d)(1)." NONGRANTOR_TRUST_DISTRIBUTIONS_877A_F1: "`39` — distributions from a nongrantor trust subject to section 877A(f)(1)." OTHER_DIVIDEND_EQUIVALENTS_871M: "`40` — other dividend equivalents under section 871(m)." GUARANTEE_OF_INDEBTEDNESS: "`41` — guarantee of indebtedness." ARTIST_ATHLETE_NO_CENTRAL_WITHHOLDING_AGREEMENT: "`42` — earnings as an artist or athlete, no central withholding agreement." ARTIST_ATHLETE_CENTRAL_WITHHOLDING_AGREEMENT: "`43` — earnings as an artist or athlete under a central withholding agreement; use only if Letter 4492 (Venue Notification) has been issued, otherwise use `42`." SPECIFIED_FEDERAL_PROCUREMENT_PAYMENTS: "`44` — specified federal procurement payments, subject to withholding under section 5000C." INCOME_PREVIOUSLY_REPORTED_ESCROW_PROCEDURE: "`50` — income previously reported under the escrow procedure; use only to report gross income whose tax is being deposited in the current year because it was escrowed under chapters 3 and 4 and reported in a prior year with box 7b checked." INTEREST_ACTIVELY_TRADED_SECURITIES: "`51` — interest paid on certain actively traded or publicly offered securities; used only where the income is described in Regulations section 1.1441-6(c)(2) and a reduced treaty rate was applied without a U.S. TIN or FTIN." DIVIDENDS_ACTIVELY_TRADED_SECURITIES: "`52` — dividends paid on certain actively traded or publicly offered securities, under the same limited-use condition as `51`." SUBSTITUTE_DIVIDENDS_ACTIVELY_TRADED_SECURITIES: "`53` — substitute payments, dividends from certain actively traded or publicly offered securities, under the same limited-use condition as `51`." SUBSTITUTE_INTEREST_ACTIVELY_TRADED_SECURITIES: "`54` — substitute payments, interest from certain actively traded or publicly offered securities, under the same limited-use condition as `51`." TAXABLE_DEATH_BENEFITS_LIFE_INSURANCE: "`55` — taxable death benefits on life insurance contracts." DIVIDEND_EQUIVALENTS_COMBINED_TRANSACTION_RULES: "`56` — dividend equivalents under section 871(m) resulting from the combined transaction rules." AMOUNT_REALIZED_1446F: "`57` — amount realized under section 1446(f)." PTP_DISTRIBUTIONS_UNDETERMINED: "`58` — publicly traded partnership distributions, undetermined." CONSENT_FEES: "`59` — consent fees (optional code for 2026 reporting)." LOAN_SYNDICATION_FEES: "`60` — loan syndication fees (optional code for 2026 reporting)." SETTLEMENT_PAYMENTS: "`61` — settlement payments (optional code for 2026 reporting)." Form1042SChapterIndicator: type: string title: Chapter indicator description: Box 3, printed as the single digit "3" or "4". enum: - CHAPTER_3 - CHAPTER_4 x-enumDescriptions: CHAPTER_3: "`3` — amounts were withheld, or paid by the withholding agent, under chapter 3." CHAPTER_4: "`4` — amounts were withheld, or paid by the withholding agent, under chapter 4." Form1042SChapter3ExemptionCode: type: string title: Chapter 3 exemption code description: Box 3a, printed as the IRS two-digit code. enum: - WITHHELD_NOT_EXEMPT - EFFECTIVELY_CONNECTED_INCOME - EXEMPT_REDUCED_UNDER_IRC - INCOME_NOT_US_SOURCE - EXEMPT_REDUCED_UNDER_TREATY - PORTFOLIO_INTEREST_EXEMPT - QI_ASSUMES_PRIMARY_WITHHOLDING - WP_OR_WT - US_BRANCH_TREATED_AS_US_PERSON - QI_REPRESENTS_INCOME_EXEMPT - QSL_ASSUMES_PRIMARY_WITHHOLDING - PAYEE_SUBJECTED_TO_CHAPTER4_WITHHOLDING - QDD_ASSUMES_PRIMARY_WITHHOLDING - EXEMPT_UNDER_897L - EXEMPT_UNDER_892 x-enumDescriptions: WITHHELD_NOT_EXEMPT: "`00` — an amount was withheld under chapter 3 at a rate greater than zero that is not due to backup withholding." EFFECTIVELY_CONNECTED_INCOME: "`01` — effectively connected income." EXEMPT_REDUCED_UNDER_IRC: "`02` — exempt or reduced withholding under the Internal Revenue Code; use only if no other chapter 3 exemption code applies." INCOME_NOT_US_SOURCE: "`03` — income is not from U.S. sources." EXEMPT_REDUCED_UNDER_TREATY: "`04` — exempt or reduced withholding under a tax treaty; the recipient's country in box 13b must be a treaty country." PORTFOLIO_INTEREST_EXEMPT: "`05` — portfolio interest exempt under the Internal Revenue Code." QI_ASSUMES_PRIMARY_WITHHOLDING: "`06` — QI that assumes primary withholding responsibility; if the QI is acting as a QDD, use `22` instead." WP_OR_WT: "`07` — withholding foreign partnership or withholding foreign trust that has represented such status on its Form W-8IMY." US_BRANCH_TREATED_AS_US_PERSON: "`08` — U.S. branch treated as a U.S. person; used only if the branch or territory FI represented on Form W-8IMY that it agrees to be so treated." QI_REPRESENTS_INCOME_EXEMPT: "`10` — QI that has not assumed primary withholding responsibility represents on its withholding statement that the income is exempt from withholding." QSL_ASSUMES_PRIMARY_WITHHOLDING: "`11` — QSL that assumes primary withholding responsibility for a substitute dividend payment." PAYEE_SUBJECTED_TO_CHAPTER4_WITHHOLDING: "`12` — payee subjected to chapter 4 withholding, so chapter 3 withholding does not apply." QDD_ASSUMES_PRIMARY_WITHHOLDING: "`22` — QDD that assumes primary withholding responsibility for the payment." EXEMPT_UNDER_897L: "`23` — exempt under section 897(l), for QIE distributions to a qualified foreign pension fund." EXEMPT_UNDER_892: "`24` — exempt under section 892, for income paid to a foreign government or international organization." Form1042SChapter3: type: object title: Chapter 3 exemption and rate properties: exemption_code: description: "Box 3a. Why no tax, or a reduced rate of tax, was withheld under chapter 3. Supply it whenever the rate in box 3b is zero. Several codes require the recipient's TIN: `01` with most recipient chapter 3 statuses, `08` outright, and `06`, `07`, `10`, `11` or `22`, where the TIN must begin with `98`. Under `04` the recipient's country must be a treaty country." $ref: "#/components/schemas/Form1042SChapter3ExemptionCode" tax_rate: type: string format: decimal description: "Box 3b, as a decimal fraction rather than the percentage the paper form prints: 30% is `0.3000`, exempt is `0.0000`. Four decimal places, and no rate of 100% or more. Required within the group." pattern: ^0?\.[0-9]{4}$ examples: - "0.1500" required: - tax_rate Form1042SChapter4ExemptionCode: type: string title: Chapter 4 exemption code description: Box 4a, printed as the IRS two-digit code. enum: - WITHHELD_NOT_EXEMPT - GRANDFATHERED_PAYMENT - EFFECTIVELY_CONNECTED_INCOME - PAYEE_NOT_SUBJECT_TO_CHAPTER4_WITHHOLDING - EXCLUDED_NONFINANCIAL_PAYMENT - FOREIGN_ENTITY_ASSUMES_PRIMARY_WITHHOLDING - US_PAYEES_OF_PFFI_OR_RDCFFI - EXEMPT_UNDER_IGA - DORMANT_ACCOUNT - OTHER_PAYMENT_NOT_SUBJECT_CHAPTER4 x-enumDescriptions: WITHHELD_NOT_EXEMPT: "`00` — an amount was withheld under chapter 4 at a rate greater than zero that is not due to backup withholding." GRANDFATHERED_PAYMENT: "`13` — grandfathered payment under a grandfathered obligation; use only if it is the only applicable exemption code." EFFECTIVELY_CONNECTED_INCOME: "`14` — effectively connected income." PAYEE_NOT_SUBJECT_TO_CHAPTER4_WITHHOLDING: "`15` — payee not subject to chapter 4 withholding, including where the 90-day grace period following a change in circumstances is applied." EXCLUDED_NONFINANCIAL_PAYMENT: "`16` — excluded nonfinancial payment described in Regulations section 1.1473-1(a)(4)(iii); use only if it is the only applicable exemption code." FOREIGN_ENTITY_ASSUMES_PRIMARY_WITHHOLDING: "`17` — foreign entity that assumes primary withholding responsibility (a QI, WP or WT)." US_PAYEES_OF_PFFI_OR_RDCFFI: "`18` — U.S. payees of a participating FFI or registered deemed-compliant FFI reporting a chapter 4 withholding rate pool of U.S. payees." EXEMPT_UNDER_IGA: "`19` — exempt from withholding under an IGA; used only to report a U.S. reportable account or nonconsenting U.S. account receiving a payment subject to chapter 3 withholding." DORMANT_ACCOUNT: "`20` — dormant account; used only where the escrow procedure for dormant accounts under Regulations section 1.1471-4(b)(6) is applied." OTHER_PAYMENT_NOT_SUBJECT_CHAPTER4: "`21` — other payment not subject to chapter 4 withholding, where no other chapter 4 exemption code applies, including income code `37`, return of capital." Form1042SChapter4: type: object title: Chapter 4 exemption and rate properties: exemption_code: description: Box 4a. Why no tax was withheld under chapter 4. Where box 3 indicates chapter 4, this is `WITHHELD_NOT_EXEMPT` and the rate in box 4b is `0.3000`. $ref: "#/components/schemas/Form1042SChapter4ExemptionCode" tax_rate: type: string format: decimal description: Box 4b, as a decimal fraction. Chapter 4 knows only two rates, `0.0000` and `0.3000`. pattern: ^0?\.[0-9]{4}$ examples: - "0.3000" required: - exemption_code - tax_rate Form1042SWithholdingAgentStatus: type: object title: Withholding agent status override description: | Boxes 12b and 12c for one form, where they are not the filer's usual pair. The filer's other box 12 entries — its EIN, name, GIIN, country code, FTIN and address — are facts about the entity and are held on the `Filer`. Its two status codes very nearly are too, which is why they live on the `withholding_agent` profile there; but the instructions give two cases where the code is a fact about the *filing* instead, and one filer TIN can then produce a mixed set: * A U.S. financial institution reports chapter 4 status `01`, "except when a foreign branch of a U.S. financial institution issues Form 1042-S (in such a case, indicate the chapter 4 status code as 50)". Which branch issued it is a property of the form. * "A withholding agent that is a partnership and is reporting allocations of QDD items to its partners should use chapter 3 status code 40 (partnership QDD)" — so a partnership uses `40` on the forms that report those allocations and its ordinary status on the rest. Both codes are required on every form, so a form that overrides one still inherits the other from the profile: this object is not all-or-nothing. properties: chapter_3_status: description: Box 12b. Overrides `Filer.withholding_agent.chapter_3_status`. Omit to inherit it. $ref: "#/components/schemas/Chapter3Status" chapter_4_status: description: Box 12c. Overrides `Filer.withholding_agent.chapter_4_status`. Omit to inherit it. $ref: "#/components/schemas/Chapter4Status" Form1042SEntityName: type: object title: Third-party name description: The name of a party that is neither the filer nor the recipient — a primary withholding agent, an intermediary, a payer. Give a person's name or a business name, not both; the paper form has one line for either. properties: person_name: type: string description: A whole name on one line, where the party is an individual. maxLength: 35 pattern: ^([A-Za-z0-9'\-] ?)*[A-Za-z0-9'\-]$ business_name_line1: type: string maxLength: 75 pattern: ^(([A-Za-z0-9#\-()]|&|') ?)*([A-Za-z0-9#\-()]|&|')$ business_name_line2: type: string description: A continuation of the business name. maxLength: 75 pattern: ^(([A-Za-z0-9#/%\-()]|&|') ?)*([A-Za-z0-9#/%\-()]|&|')$ additional_name: type: string description: A second party on the same line, which the paper form runs on after the name. maxLength: 75 pattern: ^(([A-Za-z0-9#\-()]|&|') ?)*([A-Za-z0-9#\-()]|&|')$ Form1042SPrimaryWithholdingAgent: type: object title: Primary withholding agent description: Boxes 14a and 14b. properties: name: description: Box 14a. $ref: "#/components/schemas/Form1042SEntityName" ein: type: string description: "Box 14b, nine digits unpunctuated. Required within the group: the name may be left out, but the EIN is what identifies the agent to the IRS." pattern: ^[0-9]{9}$ required: - ein Form1042SIntermediary: type: object title: Intermediary or flow-through entity description: Boxes 15a–15i. Once the object is present the EIN, both status codes, the country and the address are all required, so an intermediary known only by name cannot be reported. properties: ein: type: string description: Box 15a, nine digits unpunctuated. pattern: ^[0-9]{9}$ chapter_3_status: description: Box 15b, printed as the IRS two-digit code. The same table the filer's box 12b and the recipient's box 13f draw on. $ref: "#/components/schemas/Chapter3Status" chapter_4_status: description: Box 15c, printed as the IRS two-digit code. A separate table from chapter 3, whose digits overlap it — which is why both are named rather than numeric. $ref: "#/components/schemas/Chapter4Status" name: description: Box 15d. $ref: "#/components/schemas/Form1042SEntityName" giin: type: string description: Box 15e, the global intermediary identification number. maxLength: 19 country: description: Box 15f, the intermediary's country of residence for tax purposes. $ref: "#/components/schemas/Country" foreign_tin: type: string description: Box 15g, the tax identification number issued by that country. maxLength: 50 address: description: Boxes 15h and 15i. $ref: "#/components/schemas/Address" required: - ein - chapter_3_status - chapter_4_status - country - address Form1042SPayer: type: object title: Payer description: Boxes 16a–16e. properties: name: description: Box 16a. $ref: "#/components/schemas/Form1042SEntityName" ein: type: string description: Box 16b, nine digits unpunctuated. The paper form calls it the payer's TIN, but the value must be an EIN. Required within the group. pattern: ^[0-9]{9}$ giin: type: string description: Box 16c. maxLength: 19 chapter_3_status: description: Box 16d, printed as the IRS two-digit code. $ref: "#/components/schemas/Chapter3Status" chapter_4_status: description: Box 16e, printed as the IRS two-digit code. $ref: "#/components/schemas/Chapter4Status" required: - ein - chapter_3_status - chapter_4_status Form1042SStateTax: type: object title: State tax withheld description: One state's line of boxes 17a, 17b and 17c. properties: state_tax_withheld: type: string format: decimal description: Box 17a, in whole US dollars. pattern: ^[0-9]+$ maxLength: 15 state_id_number: type: string description: Box 17b, the payer's state tax number. Defaults to the filer's `state_registrations` entry for `state`; set it only to override that. examples: - WA-4471902 state: description: Box 17c. Required — a withheld amount with no state attached cannot be credited to anyone. $ref: "#/components/schemas/StateCode" required: - state Form1042S: type: object title: Form 1042-S description: "One Form 1042-S: one payment of U.S. source income to one foreign person, under one income code, at one withholding rate. A withholding agent that pays a recipient under two income codes files two of these." properties: unique_form_identifier: type: string description: | The ten-digit identifier the withholding agent assigns to this form, printed in the "UNIQUE FORM IDENTIFIER" box at the top of every copy. It is the withholding agent's own number, not the IRS's, and it must be unique among the forms that agent files for the year and must stay the same across every amendment of this form — that is how the IRS ties an amendment to what it amends. Required: the paper form cannot be issued without one. pattern: ^([1-9][0-9]{9}|0[1-9][0-9]{8}|00[1-9][0-9]{7}|000[1-9][0-9]{6}|0000[1-9][0-9]{5}|00000[1-9][0-9]{4}|000000[1-9][0-9]{3}|0000000[1-9][0-9]{2}|000000000[1-9][0-9]|000000000[1-9])$ examples: - "0000000317" income_code: description: "Box 1. Which kind of U.S. source income the payment was. The code governs much of the rest of the form: a withholding allowance in box 5 belongs only to `SCHOLARSHIP_FELLOWSHIP_GRANTS` through `COMPENSATION_DURING_STUDYING_TRAINING` and `ARTIST_ATHLETE_NO_CENTRAL_WITHHOLDING_AGREEMENT`, and a scholarship or fellowship grant exempted under a treaty requires the recipient's TIN. Required." $ref: "#/components/schemas/Form1042SIncomeCode" gross_income: type: string format: decimal description: Box 2, in whole US dollars. The gross amount paid before any withholding or allowance — not the net. A withholding allowance in box 5 must not exceed it. Required. pattern: ^[0-9]+$ maxLength: 15 examples: - "12500" chapter: description: Box 3. Which chapter the amounts reported were withheld or paid under. The two treatments are mutually exclusive, so this is required. Where chapter 3 is indicated, the recipient carries a chapter 3 status; where chapter 4 is indicated, box 4a is `WITHHELD_NOT_EXEMPT` and box 4b is `0.3000`. $ref: "#/components/schemas/Form1042SChapterIndicator" chapter_3: description: "Boxes 3a and 3b. Optional: omit the object for a payment reported wholly under chapter 4." $ref: "#/components/schemas/Form1042SChapter3" chapter_4: description: Boxes 4a and 4b. Required on every form, whichever chapter box 3 indicates, and both members are required within it. $ref: "#/components/schemas/Form1042SChapter4" withholding_allowance: type: string format: decimal description: Box 5, in whole US dollars. Personal exemptions and other allowances subtracted from gross income before withholding. It must not exceed box 2, and it belongs only to income codes `16` through `20` or `42` — scholarships, personal services, teaching, training, or an artist or athlete without a central withholding agreement. pattern: ^[0-9]+$ maxLength: 15 net_income: type: string format: decimal description: Box 6, in whole US dollars. Complete it only where a withholding allowance was entered in box 5; the IRS reads it as gross income less that allowance. pattern: ^[0-9]+$ maxLength: 15 federal_tax_withheld: type: string format: decimal description: "Box 7a, in whole US dollars. What this withholding agent withheld — tax withheld by another agent belongs in box 8. Required, and `0` is a legitimate value on a fully exempt payment: the box 10 withholding credit is computed from it, so its absence and a zero are not the same statement." pattern: ^[0-9]+$ maxLength: 15 examples: - "3750" escrow_procedures_applied: type: boolean default: false description: Box 7b. True where the tax in box 7a was withheld but not deposited with the IRS because the escrow procedure for dormant accounts or for a payment whose character was undetermined was applied. The year the tax is finally deposited, report the same income again under income code `50`. subsequent_year_partnership_withholding: type: boolean default: false description: Box 7c. True where the withholding reported here occurred in a year after the year of the payment, with respect to a partnership interest. qi_wp_wt_revising_reporting: type: boolean default: false description: Box 7d. True where the filer is a qualified intermediary, withholding foreign partnership or withholding foreign trust revising its reporting on Form 1042-S to report to a specific recipient rather than to a withholding rate pool. tax_withheld_by_other_agents: type: string format: decimal description: Box 8, in whole US dollars. Tax withheld on this income by an agent other than the filer. A non-zero amount makes `primary_withholding_agent` required. Omitting it counts as zero in the box 10 withholding credit. pattern: ^[0-9]+$ maxLength: 15 overwithheld_tax_repaid: type: string format: decimal description: Box 9, in whole US dollars. Overwithheld tax repaid to the recipient under the reimbursement or set-off procedures. It should not exceed boxes 7a and 8 combined, since it repays tax reported in those boxes, and it is subtracted when the box 10 withholding credit is computed. pattern: ^[0-9]+$ maxLength: 15 tax_paid_by_withholding_agent: type: string format: decimal description: Box 11, in whole US dollars. Tax the withholding agent paid out of its own funds rather than withholding it from the payment. It is not part of the recipient's box 10 credit. pattern: ^[0-9]+$ maxLength: 15 account_number: type: string description: Box 13k — the withholding agent's own account number for this recipient. A field of the form rather than of the recipient, since one recipient can hold several accounts with the same agent. maxLength: 30 withholding_agent: description: Boxes 12b and 12c, for the filers whose status is not the same on every form. Defaults to the filer's `withholding_agent` profile; set it here only to override that for this form. $ref: "#/components/schemas/Form1042SWithholdingAgentStatus" primary_withholding_agent: description: Boxes 14a and 14b. The primary withholding agent, where the filer is not it. Required whenever `tax_withheld_by_other_agents` is non-zero; otherwise supply it only if applicable. $ref: "#/components/schemas/Form1042SPrimaryWithholdingAgent" pro_rata_basis_reporting: type: boolean default: false description: Box 15. True where the filer is a nonqualified intermediary reporting on a pro-rata basis because it could not determine which account holders received which part of the payment. intermediary: description: Boxes 15a–15i. The intermediary or flow-through entity through which the payment passed. Omit the object where the payment went directly to the recipient. $ref: "#/components/schemas/Form1042SIntermediary" payer: description: Boxes 16a–16e. The payer, where the payer is someone other than the filer — a withholding agent reporting a payment made by an agent, paying agent or partnership on its behalf names that party here. $ref: "#/components/schemas/Form1042SPayer" state_taxes: type: array description: Boxes 17a–17c, one entry per state. The paper form prints a single line, but any number of entries may be supplied. items: $ref: "#/components/schemas/Form1042SStateTax" filer_office_code: type: string description: The reporting office this form belongs to — the filer's own code, not one the IRS assigns. Defaults to the filer's single office; set it only where the filer has more than one and this form is not the default one's. minLength: 4 maxLength: 4 required: - unique_form_identifier - income_code - gross_income - chapter - chapter_4 - federal_tax_withheld Form1042SBody: title: Form 1042-S allOf: - type: object properties: type: type: string const: 1042-S required: - type - $ref: "#/components/schemas/Form1042S" Form1097BTCMonthlyCredits: type: object title: Monthly credits description: | The credit allowed to the recipient in each month of the calendar year, in US dollars. Every month is optional — a bond with quarterly credit allowance dates leaves eight of them absent — but the months that are present should sum to `total_credits`, because the IRS checks box 1 against them. All twelve amounts are non-negative: a credit taken back is corrected on the original form rather than netted here. properties: january: type: string format: decimal description: Box 5a, in US dollars. pattern: ^[0-9]+(\.[0-9]{2})?$ examples: - "104.17" february: type: string format: decimal description: Box 5b, in US dollars. pattern: ^[0-9]+(\.[0-9]{2})?$ march: type: string format: decimal description: Box 5c, in US dollars. pattern: ^[0-9]+(\.[0-9]{2})?$ april: type: string format: decimal description: Box 5d, in US dollars. pattern: ^[0-9]+(\.[0-9]{2})?$ may: type: string format: decimal description: Box 5e, in US dollars. pattern: ^[0-9]+(\.[0-9]{2})?$ june: type: string format: decimal description: Box 5f, in US dollars. pattern: ^[0-9]+(\.[0-9]{2})?$ july: type: string format: decimal description: Box 5g, in US dollars. pattern: ^[0-9]+(\.[0-9]{2})?$ august: type: string format: decimal description: Box 5h, in US dollars. pattern: ^[0-9]+(\.[0-9]{2})?$ september: type: string format: decimal description: Box 5i, in US dollars. pattern: ^[0-9]+(\.[0-9]{2})?$ october: type: string format: decimal description: Box 5j, in US dollars. pattern: ^[0-9]+(\.[0-9]{2})?$ november: type: string format: decimal description: Box 5k, in US dollars. pattern: ^[0-9]+(\.[0-9]{2})?$ december: type: string format: decimal description: Box 5l, in US dollars. pattern: ^[0-9]+(\.[0-9]{2})?$ Form1097BTC: type: object title: Form 1097-BTC description: | Bond tax credit distributed to one recipient for one calendar year. One instance is one paper form. A filer that is the issuer of a clean renewable energy bond files a separate form for that bond type (see `bond_type`), so a recipient holding both a section 54 bond and anything else receives more than one form — set `account_number` on each when that happens, because every form filed against one recipient TIN for a year needs its own account number. properties: issuer_role: type: string title: Issuer role description: "Which of the two checkboxes above box 1 is ticked — the capacity in which this filer is issuing the form. Required, and the two capacities are mutually exclusive: exactly one value applies to a given form." enum: - BOND_ISSUER_OR_AGENT - DISTRIBUTING_ENTITY x-enumDescriptions: BOND_ISSUER_OR_AGENT: '`BondIssuerInd` = 1. "Issuer of bond or its agent filing current year Form 1097-BTC for credit being reported" — the first checkbox.' DISTRIBUTING_ENTITY: '`EntityRcvdBondDistriCreditInd` = 1. "An entity or a person that received or should have received a current year Form 1097-BTC and is distributing part or all of that credit to others" — the second checkbox.' total_credits: type: string format: decimal description: "Box 1. The total credit distributed to this recipient over the calendar year, in US dollars. Required: it is the amount the form exists to report, and the recipient carries it to its own return. It should equal the sum of the twelve amounts in `monthly_credits`; a mismatch is nearly always a monthly amount left out." pattern: ^[0-9]+(\.[0-9]{2})?$ examples: - "1250.00" unique_identifier_type: type: string title: Unique identifier type description: Box 2a. What kind of identifier `unique_identifier` is. Supply it whenever `unique_identifier` is supplied; the IRS reads box 2b against this code. enum: - ACCOUNT_NUMBER - CUSIP_NUMBER - OTHER x-enumDescriptions: ACCOUNT_NUMBER: "`A` — the unique identifier is an account number." CUSIP_NUMBER: "`C` — the unique identifier is a CUSIP number. Enter this when a CUSIP number is assigned to the bond and the filer is the bond issuer or its agent." OTHER: "`O` — the unique identifier is neither an account number nor a CUSIP number, such as a self-provided identification number." unique_identifier: type: string description: Box 2b. The identifier of the bond or of the account the credit was distributed under, as assigned by the filer. Printable ASCII and the accented Latin characters `pattern` admits, single-spaced. maxLength: 39 pattern: ^([!-~£§ÁÉÍÑÓ×ÚÜáéíñóúü] ?)*[!-~£§ÁÉÍÑÓ×ÚÜáéíñóúü]$ examples: - 459200HU8 bond_type: type: string title: Bond type description: "Box 3. Required, and the two values are not interchangeable: credits from section 54 clean renewable energy bonds must be reported on their own form, where credits of every other kind may be combined on one." enum: - CLEAN_RENEWABLE_ENERGY_BOND - OTHER x-enumDescriptions: CLEAN_RENEWABLE_ENERGY_BOND: "`101` — clean renewable energy bonds issued under section 54, which must be reported on a separate Form 1097-BTC." OTHER: "`199` — all other bonds. Multiple bond types other than clean renewable energy bonds may be combined on one Form 1097-BTC." monthly_credits: description: Boxes 5a through 5l — the box 1 total broken down by the month the credit allowance date fell in. $ref: "#/components/schemas/Form1097BTCMonthlyCredits" comments: type: string description: Box 6. Free text about the credit — the instructions suggest identifying the bond or explaining an adjustment. At most 100 characters, which is shorter than the space the paper form prints, so longer notes have to be shortened before they are sent. maxLength: 100 pattern: ^([!-~£§ÁÉÍÑÓ×ÚÜáéíñóúü] ?)*[!-~£§ÁÉÍÑÓ×ÚÜáéíñóúü]$ account_number: type: string description: The filer's account number for this recipient, printed in the "Account number (see instructions)" line. A field of the form rather than of the recipient, who can hold more than one account with this filer. maxLength: 30 pattern: ^([!-~£§ÁÉÍÑÓ×ÚÜáéíñóúü] ?)*[!-~£§ÁÉÍÑÓ×ÚÜáéíñóúü]$ examples: - 4471902-01 filer_office_code: type: string description: The reporting office this form belongs to. Defaults to the filer's single office; set it only for a filer with more than one, and then to the `code` of one of its `offices`. Exactly four characters — a length, not a maximum. minLength: 4 maxLength: 4 pattern: ^([!-~£§ÁÉÍÑÓ×ÚÜáéíñóúü] ?)*[!-~£§ÁÉÍÑÓ×ÚÜáéíñóúü]$ examples: - "0001" required: - issuer_role - total_credits - bond_type Form1097BTCBody: title: Form 1097-BTC allOf: - type: object properties: type: type: string const: 1097-BTC required: - type - $ref: "#/components/schemas/Form1097BTC" Form1098C: type: object title: Form 1098-C description: | Contributions of motor vehicles, boats and airplanes, reported by the donee organization to the donor and to the IRS. One instance is one contributed vehicle. A donee that received two vehicles from one donor files two forms and sets `account_number` on each, distinctly, since an account number is required on the second and subsequent forms filed for one donor. properties: date_of_contribution: type: string format: date description: "Box 1. The date the donee took possession of the vehicle. Required: it is the event the form exists to acknowledge — the donor's deduction falls in the year this date lands in." examples: - "2026-03-14" odometer_mileage: type: integer description: Box 2a. The odometer reading in whole miles at the time of contribution. Must not be negative. minimum: 0 maximum: 999999999999 examples: - 86400 vehicle_year: type: string description: Box 2b. The vehicle's model year, four digits. pattern: ^[1-9][0-9]{3}$ examples: - "2014" vehicle_make: type: string description: Box 2c. The manufacturer, as it appears on the title. maxLength: 20 pattern: ^([!-~£§ÁÉÍÑÓ×ÚÜáéíñóúü] ?)*[!-~£§ÁÉÍÑÓ×ÚÜáéíñóúü]$ examples: - Toyota vehicle_model: type: string description: Box 2d. The model line, as it appears on the title. maxLength: 25 pattern: ^([!-~£§ÁÉÍÑÓ×ÚÜáéíñóúü] ?)*[!-~£§ÁÉÍÑÓ×ÚÜáéíñóúü]$ examples: - Camry LE vehicle_identification_number: type: string description: Box 3. The VIN of a motor vehicle, or the hull identification number of a boat or the aircraft identification number of an airplane. Required. maxLength: 25 pattern: ^([!-~£§ÁÉÍÑÓ×ÚÜáéíñóúü] ?)*[!-~£§ÁÉÍÑÓ×ÚÜáéíñóúü]$ examples: - 1HGCM82633A004352 sold_in_arms_length_transaction: type: boolean default: false description: Box 4a. The donee certifies that the vehicle was sold in an arm's length transaction to an unrelated party, which limits the donor's deduction to the gross proceeds in box 4c. Mutually exclusive with `no_transfer_before_improvements_or_use` and `transfer_to_needy_individual`. Where `gross_proceeds` exceeds $500, set this and supply `date_of_sale`. date_of_sale: type: string format: date description: Box 4b. When the vehicle was sold. Required when `sold_in_arms_length_transaction` is set, and required whenever `gross_proceeds` exceeds $500. examples: - "2026-06-02" gross_proceeds: type: string format: decimal description: Box 4c. Gross proceeds of the sale in US dollars, before deducting the donee's selling costs. This is the ceiling on the donor's deduction where the vehicle was sold rather than improved, used or given away. Must not be negative, and must not exceed 999999999999999.99. Where it exceeds $500, set `sold_in_arms_length_transaction` and supply `date_of_sale`. pattern: ^[0-9]+(\.[0-9]{2})?$ examples: - "2750.00" no_transfer_before_improvements_or_use: type: boolean default: false description: Box 5a. The donee certifies that the vehicle will not be transferred for money, other property or services before the completion of material improvements or significant intervening use by the donee. Where this is checked the donor can deduct fair market value rather than sale proceeds, and box 5c must describe the improvements or the use. Mutually exclusive with `sold_in_arms_length_transaction` and `transfer_to_needy_individual`. transfer_to_needy_individual: type: boolean default: false description: Box 5b. The donee certifies that the vehicle is to be transferred to a needy individual for significantly below fair market value in furtherance of the donee's charitable purpose. Mutually exclusive with `sold_in_arms_length_transaction` and `no_transfer_before_improvements_or_use`. material_improvements_description: type: string description: Box 5c. The donee's detailed description of the material improvements or the significant intervening use, and the duration of that use. Required when `no_transfer_before_improvements_or_use` is set; the instructions leave it blank for a box 5b transfer. maxLength: 1000 pattern: ^([!-~£§ÁÉÍÑÓ×ÚÜáéíñóúü] ?)*[!-~£§ÁÉÍÑÓ×ÚÜáéíñóúü]$ goods_or_services_provided: type: boolean description: Box 6a. Whether the donee provided goods or services in exchange for the vehicle. `true` sets the Yes box, `false` the No box. Where it is `true`, supply both `value_of_goods_and_services` and `goods_and_services_description`. value_of_goods_and_services: type: string format: decimal description: Box 6b. The value in US dollars of the goods and services the donee gave the donor in exchange for the vehicle; the donor subtracts it from the deduction. Must not be negative, and must not exceed 999999999999999.99. Required when `goods_or_services_provided` is `true`. pattern: ^[0-9]+(\.[0-9]{2})?$ examples: - "150.00" goods_and_services_description: type: string description: Box 6c. What the goods and services were. Required when `goods_or_services_provided` is `true`. maxLength: 1000 pattern: ^([!-~£§ÁÉÍÑÓ×ÚÜáéíñóúü] ?)*[!-~£§ÁÉÍÑÓ×ÚÜáéíñóúü]$ intangible_religious_benefits_only: type: boolean default: false description: Box 6c checkbox. The donee certifies that the goods and services it provided consisted solely of intangible religious benefits, which the donor does not subtract from the deduction. deduction_limited_to_500: type: boolean default: false description: Box 7. Checked where, under the law, the donor cannot claim a deduction of more than $500 for this vehicle — for example, a sale for $500 or less with none of the box 5 certifications made. account_number: type: string description: 'The donee''s own account or reference number for this donor, printed as "Account number (see instructions)". It identifies the contribution this form reports rather than the donor. Set it distinctly on each form where one donor contributed more than one vehicle: an account number, unique across the forms filed for that donor, is required on the second and subsequent ones.' maxLength: 30 pattern: ^([!-~£§ÁÉÍÑÓ×ÚÜáéíñóúü] ?)*[!-~£§ÁÉÍÑÓ×ÚÜáéíñóúü]$ examples: - 4471902-01 filer_office_code: type: string description: The donee's reporting office this form belongs to. Exactly four characters, and one of the codes on the filer's `offices`. Defaults to the filer's single office. minLength: 4 maxLength: 4 pattern: ^([!-~£§ÁÉÍÑÓ×ÚÜáéíñóúü] ?)*[!-~£§ÁÉÍÑÓ×ÚÜáéíñóúü]$ examples: - "0001" required: - date_of_contribution - vehicle_identification_number - goods_or_services_provided Form1098CBody: title: Form 1098-C allOf: - type: object properties: type: type: string const: 1098-C required: - type - $ref: "#/components/schemas/Form1098C" Form1098E: type: object title: Form 1098-E description: | Student Loan Interest Statement — filed by a lender that received $600 or more of interest on one or more qualified student loans from one borrower during the year. The borrower is this form's recipient; the lender is the filer. properties: student_loan_interest: type: string format: decimal description: "Box 1, in US dollars. The interest the lender received on qualified student loans from this borrower during the year, including capitalized interest and loan origination fees unless `excludes_origination_fees_and_capitalized_interest` is set. Required: it is the amount the form exists to report. Zero is a valid entry; a negative amount is not. At most fifteen digits before the decimal point." pattern: ^[0-9]+(\.[0-9]{2})?$ examples: - "1450.00" excludes_origination_fees_and_capitalized_interest: type: boolean default: false description: Box 2. True when box 1 excludes loan origination fees and capitalized interest *and* the loan was made before 1 September 2004 — both conditions, not either. Reporting those amounts is optional for pre-September-2004 loans, and this box is how the borrower is told which convention was used, since it changes what they can deduct. Leave it false for any loan made on or after that date, where reporting the fees and capitalized interest is mandatory. account_number: type: string description: The lender's account number for this borrower, printed under "Account number (see instructions)". It names the loan rather than the borrower, who can have more than one. Where a filer issues more than one 1098-E to the same borrower TIN, each form needs a distinct account number. maxLength: 30 pattern: ^(([!-~£§ÁÉÍÑÓ×ÚÜáéíñóúü] ?)*[!-~£§ÁÉÍÑÓ×ÚÜáéíñóúü])$ examples: - 4471902-01 filer_office_code: type: string description: The reporting office this return belongs to. Defaults to the filer's single office; set it only where the filer has more than one and this return belongs to other than the default. Exactly four characters. minLength: 4 maxLength: 4 examples: - "0001" required: - student_loan_interest Form1098EBody: title: Form 1098-E allOf: - type: object properties: type: type: string const: 1098-E required: - type - $ref: "#/components/schemas/Form1098E" Form1098FCode: type: string title: Form 1098-F code description: One of the box 9 codes, which qualify how the amounts in boxes 1 through 4 were arrived at. enum: - MULTIPLE_PAYMENTS - MULTIPLE_PAYERS - MULTIPLE_PAYEES - PROVISION_OF_SERVICES_OR_PROPERTY_REQUIRED - PAYMENT_AMOUNT_NOT_IDENTIFIED x-enumDescriptions: MULTIPLE_PAYMENTS: "`A` — Multiple payments: the payer has made or is obligated to make multiple payments to satisfy the total payment required by the suit, order, or agreement." MULTIPLE_PAYERS: "`B` — Multiple payers: more than one payer has a payment obligation pursuant to the suit, order, or agreement." MULTIPLE_PAYEES: "`C` — Multiple payees: there are multiple payees pursuant to the suit, order, or agreement." PROVISION_OF_SERVICES_OR_PROPERTY_REQUIRED: "`D` — Provision of services or provision of property required: the suit, order, or agreement requires the payer to provide services or property." PAYMENT_AMOUNT_NOT_IDENTIFIED: "`E` — Payment amount not identified: the suit, order, or agreement does not identify some or all of the amount required to be paid for the violation, investigation, or inquiry, or does not identify some or all of the aggregate the payer must pay." Form1098F: type: object title: Form 1098-F description: | Fines, penalties and other amounts a payer is required to pay under a suit, court order or agreement with a government entity, where the aggregate is $50,000 or more. Amounts are in US dollars. An amount must not be negative and must not exceed 999,999,999,999,999.99. An amount that has since been reduced is handled by correcting the form rather than by netting. properties: total_required_to_be_paid: type: string format: decimal description: Box 1. The total the payer must pay pursuant to the suit, order or agreement, in US dollars, including amounts paid to third parties and amounts for restitution, remediation or coming into compliance. Enter `0` where the order or agreement does not identify the total, and set `PAYMENT_AMOUNT_NOT_IDENTIFIED` in `codes`. pattern: ^[0-9]+(\.[0-9]{2})?$ examples: - "75000.00" violation_or_potential_violation: type: string format: decimal description: Box 2. So much of box 1 as is to be paid for the violation or potential violation of a law, in US dollars — the punitive part, which the payer cannot deduct. Leave it out where the amount is not identified in the order or agreement. pattern: ^[0-9]+(\.[0-9]{2})?$ restitution_or_remediation: type: string format: decimal description: Box 3. So much of box 1 as the order or agreement identifies as restitution or as remediation of property, in US dollars. This is one of the two figures the payer looks to under section 162(f)(2), so identifying it wrongly costs the payer a deduction it was entitled to. pattern: ^[0-9]+(\.[0-9]{2})?$ compliance: type: string format: decimal description: Box 4. So much of box 1 as the order or agreement identifies as paid to come into compliance with the law, in US dollars — the other section 162(f)(2) figure. pattern: ^[0-9]+(\.[0-9]{2})?$ order_or_agreement_date: type: string format: date description: Box 5. The date the suit, order or agreement was entered into or became binding — not the date of any payment. The form is filed for the calendar year this date falls in, whenever the money actually moves. Supply as `YYYY-MM-DD`. This field is optional; we recommend supplying it, since it is what fixes the year the form belongs to. pattern: ^[1-9][0-9]{3}-([0][1-9]|[1][0-2])-([0][1-9]|[1-2][0-9]|[3][0-1])$ examples: - "2026-03-14" court_or_entity: type: string description: Box 6. The court, or the government or governmental entity, that entered the order or is party to the agreement. Alphanumerics, single spaces, hash, hyphen, parentheses, ampersand and apostrophe only — no period and no comma, so supply `US Dist Ct ND Cal` rather than `U.S. Dist. Ct., N.D. Cal.`. maxLength: 75 pattern: ^(([A-Za-z0-9#\-()]|&|') ?)*([A-Za-z0-9#\-()]|&|')$ examples: - US Dist Ct ND Cal case_number: type: string description: "Box 7. The docket or case number the court or entity assigned. The character set is wider than box 6's: any printable character may be used." maxLength: 30 pattern: ^([!-~£§ÁÉÍÑÓ×ÚÜáéíñóúü] ?)*[!-~£§ÁÉÍÑÓ×ÚÜáéíñóúü]$ examples: - 3:26-cv-01147 case_name: type: string description: Box 8. The case name, or the names of the parties to the suit, order or agreement. One line of at most 100 characters, which is shorter than most captions run — abbreviate the caption to fit rather than relying on truncation. maxLength: 100 pattern: ^([!-~£§ÁÉÍÑÓ×ÚÜáéíñóúü] ?)*[!-~£§ÁÉÍÑÓ×ÚÜáéíñóúü]$ examples: - United States v Halvorsen Marine Services Inc codes: type: array description: Box 9. The circumstances that qualify the figures on this form. Up to five can apply; order is not significant. `PAYMENT_AMOUNT_NOT_IDENTIFIED` is the one to watch — it is what tells the IRS that a zero in box 1 means "unidentified" rather than "nothing owed". maxItems: 5 uniqueItems: true items: $ref: "#/components/schemas/Form1098FCode" account_number: type: string description: The filer's own account number for this payer, printed as "Account number (see instructions)". A field of the form rather than of the payer, who can have more than one matter with this filer. Required, and distinct from the account number on the payer's other 1098-F forms, where more than one 1098-F is filed against the same TIN. maxLength: 30 pattern: ^([!-~£§ÁÉÍÑÓ×ÚÜáéíñóúü] ?)*[!-~£§ÁÉÍÑÓ×ÚÜáéíñóúü]$ filer_office_code: type: string description: The reporting office this form belongs to. Defaults to the filer's single office; set it only where the filer has more than one. Exactly four characters — a length, not a maximum. minLength: 4 maxLength: 4 examples: - "0001" required: - total_required_to_be_paid Form1098FBody: title: Form 1098-F allOf: - type: object properties: type: type: string const: 1098-F required: - type - $ref: "#/components/schemas/Form1098F" Form1098QMonthlyPremium: type: object title: Form 1098-Q monthly premium description: One month's premium payment, boxes 5a through 5l. properties: month: type: string description: Which of the twelve box 5 rows this entry fills. At most one entry per month. enum: - JANUARY - FEBRUARY - MARCH - APRIL - MAY - JUNE - JULY - AUGUST - SEPTEMBER - OCTOBER - NOVEMBER - DECEMBER x-enumDescriptions: JANUARY: Box 5a. FEBRUARY: Box 5b. MARCH: Box 5c. APRIL: Box 5d. MAY: Box 5e. JUNE: Box 5f. JULY: Box 5g. AUGUST: Box 5h. SEPTEMBER: Box 5i. OCTOBER: Box 5j. NOVEMBER: Box 5k. DECEMBER: Box 5l. amount: type: string format: decimal description: "The premium paid in this month, in US dollars. Required: an entry exists to report an amount, and a month with no premium is left out of the array altogether." pattern: ^[0-9]+(\.[0-9]{2})?$ examples: - "5000.00" day: type: integer description: 'The day of the month the premium was paid, printed in the small "dd" field beside the amount. The highest value allowed depends on the month named: 29 in February, 30 in April, June, September and November, 31 in the rest.' maximum: 31 examples: - 15 required: - month - amount Form1098Q: type: object title: Form 1098-Q description: | Payments from a qualifying longevity annuity contract (QLAC) held under a plan, IRA or eligible governmental plan, reported by the contract's issuer for each year the contract is in force — from the year of purchase until the year the annuitant dies or the whole interest is surrendered. Everything the form reports is about one contract: what it pays, when it starts paying, what has been paid in for it, and what it is worth. properties: account_number: type: string description: The issuer's own account number for this participant, printed as "Account number (see instructions)". It names the contract this form reports rather than the participant, who can hold more than one. A filer that issues more than one 1098-Q for the same participant must give each form a distinct account number. maxLength: 30 examples: - QLAC-4471902 plan_number: type: string description: The number identifying the plan under which the contract is held, printed in the header block as "Plan number". Left empty for a contract held in an IRA, which has no plan number. maxLength: 30 pattern: ^([!-~£§ÁÉÍÑÓ×ÚÜáéíñóúü] ?)*[!-~£§ÁÉÍÑÓ×ÚÜáéíñóúü]$ examples: - "001" plan_name: type: string description: The name of the plan under which the contract is held, printed as "Name of plan". Left empty for a contract held in an IRA. maxLength: 35 pattern: ^([!-~£§ÁÉÍÑÓ×ÚÜáéíñóúü] ?)*[!-~£§ÁÉÍÑÓ×ÚÜáéíñóúü]$ examples: - Nutshell Salaried Employees Plan plan_sponsor_ein: type: string description: The employer identification number of the plan sponsor, printed as "Plan sponsor's EIN". This is the sponsor of the plan the contract is held under — not the issuer filing the form, whose own number is the filer's `tin`. pattern: ^[0-9]{9}$ examples: - "001234567" annuity_amount_on_start_date: type: string format: decimal description: Box 1a. The amount of the annuity payable on the annuity start date reported in box 1b, in US dollars. Where the start date can be accelerated (box 2), report the amount payable on the latest permitted start date, and say so on the statement given to the participant. pattern: ^[0-9]+(\.[0-9]{2})?$ examples: - "12000.00" annuity_start_date: type: string format: date description: Box 1b. The date on which the annuity is scheduled to begin, supplied as `YYYY-MM-DD`. If box 2 is checked this is the latest date on which payments can begin; the contract permits an earlier one. pattern: ^[1-9][0-9]{3}-([0][1-9]|[1][0-2])-([0][1-9]|[1-2][0-9]|[3][0-1])$ examples: - "2045-07-01" start_date_may_be_accelerated: type: boolean default: false description: Box 2, printed on Copy B as "If checked, start date may be accelerated". Whether the contract allows the annuity to begin before the date in box 1b. examples: - true total_premiums: type: string format: decimal description: Box 3. Total premiums paid for the contract as of the end of the calendar year, in US dollars — cumulative over the life of the contract, not the year's premiums alone. Required. This year's premiums are part of the total, so it is at least the sum of the amounts in `monthly_premiums`. pattern: ^[0-9]+(\.[0-9]{2})?$ examples: - "50000.00" qlac_fair_market_value: type: string format: decimal description: Box 4. The fair market value of the contract as of the end of the calendar year, in US dollars. Required. pattern: ^[0-9]+(\.[0-9]{2})?$ examples: - "52300.00" monthly_premiums: type: array description: Box 5. The premiums paid during this calendar year, one entry per month in which a premium was paid. Months with no premium are omitted rather than reported as zero. These amounts must not sum to more than `total_premiums`. maxItems: 12 items: $ref: "#/components/schemas/Form1098QMonthlyPremium" filer_office_code: type: string description: The filer's reporting office this form belongs to, as a `FilerOffice.code`. Defaults to the filer's single office, and need only be given by a filer that reports through more than one. minLength: 4 maxLength: 4 examples: - "0001" required: - total_premiums - qlac_fair_market_value Form1098QBody: title: Form 1098-Q allOf: - type: object properties: type: type: string const: 1098-Q required: - type - $ref: "#/components/schemas/Form1098Q" Form1098T: type: object title: Form 1098-T description: | Tuition Statement: what an eligible educational institution paid-or-billed a student in qualified tuition and related expenses, and what it administered in scholarships or grants, for the calendar year. The student uses it to claim the American opportunity or lifetime learning credit, which is why boxes 7, 8 and 9 matter as much as the money does — they decide which credit, if any, the amounts can support. A separate 1098-T reporting box 10 alone is filed by an insurer that made reimbursements or refunds of qualified tuition; an educational institution never fills box 10. properties: payments_received: type: string format: decimal description: Box 1. Total payments received for qualified tuition and related expenses from all sources during the calendar year, in US dollars, net of any reimbursements or refunds made during the year. Report `0.00` on a form filed only to record prior-year adjustments. This is the figure the student's credit is computed from. pattern: ^[0-9]+(\.[0-9]{2})?$ examples: - "12450.00" prior_year_adjustments: type: string format: decimal description: Box 4. Reductions made during this calendar year to qualified tuition and related expenses reported on a 1098-T for a prior year, in US dollars, entered as a positive amount. A figure here can require the student to recapture a credit claimed for that earlier year. pattern: ^[0-9]+(\.[0-9]{2})?$ scholarships_or_grants: type: string format: decimal description: Box 5. Total of scholarships or grants administered and processed by the institution during the calendar year, in US dollars. It reduces the expenses the student can count towards a credit; it does not include amounts the institution merely knows about but did not administer. pattern: ^[0-9]+(\.[0-9]{2})?$ prior_year_scholarship_adjustments: type: string format: decimal description: Box 6. Reductions made during this calendar year to scholarships or grants reported on a 1098-T for a prior year, in US dollars, entered as a positive amount. As with box 4, it can trigger recapture for the earlier year. pattern: ^[0-9]+(\.[0-9]{2})?$ payments_include_next_year_academic_period: type: boolean default: false description: Box 7. Whether the box 1 amount includes payments for an academic period beginning in January through March of the next calendar year. It tells the student that expenses for a term in the next tax year have already been counted in this year's figure, so the same money is not claimed twice. at_least_half_time_student: type: boolean default: false description: Box 8. Whether the student carried at least half the normal full-time workload for at least one academic period beginning during the calendar year. The American opportunity credit is unavailable to a student for whom this is false. graduate_student: type: boolean default: false description: Box 9. Whether the student was enrolled in a programme leading to a graduate degree, graduate-level certificate or other recognised graduate credential. A graduate student cannot claim the American opportunity credit, and checking this box in error is the usual cause of a disallowed credit. insurance_reimbursement_or_refund: type: string format: decimal description: Box 10. Total reimbursements or refunds of qualified tuition and related expenses made by an insurer under an insurance contract, in US dollars. Completed only by the insurer filing the form; an educational institution leaves it empty. The student must reduce any credit claimed by this amount. pattern: ^[0-9]+(\.[0-9]{2})?$ student_tin_solicited: type: boolean default: false description: Whether the filer solicited the student's taxpayer identification number in the manner the regulations prescribe. It has no box on the printed form. This field is optional; we recommend setting it whenever the student's TIN is missing or doubtful, since it is the institution's basis for penalty relief in that case. account_number: type: string description: The service provider or account number the filer uses for this student — printed on the form as "Service Provider/Acct. No. (see instr.)". A field of the form rather than of the student, who can have more than one account with the institution. A filer issuing more than one 1098-T to the same student must give each form a distinct value. maxLength: 30 pattern: ^([!-~£§ÁÉÍÑÓ×ÚÜáéíñóúü] ?)*[!-~£§ÁÉÍÑÓ×ÚÜáéíñóúü]$ examples: - STU-2026-004471 filer_office_code: type: string description: The filer's reporting office for this form. Defaults to the filer's single office; set it only where a filer with several offices — separate campuses reporting under one EIN — needs this form attributed to one of them. Exactly four characters. minLength: 4 maxLength: 4 pattern: ^([!-~£§ÁÉÍÑÓ×ÚÜáéíñóúü] ?)*[!-~£§ÁÉÍÑÓ×ÚÜáéíñóúü]$ examples: - "0001" required: - payments_received Form1098TBody: title: Form 1098-T allOf: - type: object properties: type: type: string const: 1098-T required: - type - $ref: "#/components/schemas/Form1098T" Form1099A: type: object title: Form 1099-A description: | Acquisition or Abandonment of Secured Property, filed by a lender who acquires an interest in property that secured a debt, or who has reason to know that such property has been abandoned. One instance of this schema is one printed form. properties: acquisition_or_abandonment_date: type: string format: date description: "Box 1: the date the lender acquired the secured property, or the date it first knew or had reason to know the property was abandoned. Required — this is the event the form reports, and the date determines the year in which the borrower recognizes gain or loss. Supply as `YYYY-MM-DD`; the year must be 1000 or later." principal_balance: type: string format: decimal description: "Box 2: the balance of principal outstanding on the debt on the date in box 1, in US dollars. Do not include accrued interest or foreclosure costs. Required — it is the amount the form exists to report. Never negative, and the IRS ceiling is 999999999999999.99." pattern: ^[0-9]+(\.[0-9]{2})?$ examples: - "143500.00" fair_market_value: type: string format: decimal description: "Box 4: the fair market value of the property, in US dollars — for a foreclosure or execution sale, the gross proceeds of that sale. Optional, because the instructions allow it to be left blank where property has been abandoned and the lender has not yet acquired it; we recommend supplying it whenever the property was acquired, since the borrower uses it against box 2 to work out cancellation-of-debt income. Never negative." pattern: ^[0-9]+(\.[0-9]{2})?$ examples: - "128000.00" borrower_personally_liable: type: boolean description: "Box 5: whether the borrower was personally liable for repayment of the debt at the time it was incurred, or — if modified — at the time of the last modification. Required. True means recourse debt, which is what tells the borrower to test box 2 against box 4 for cancellation-of-debt income; false means nonrecourse." property_description: type: string description: "Box 6: what the property is. For real property, give the address, or the section, lot and block where there is no address; for personal property, the type, make and model. Enter `CCC` for property acquired by the Commodity Credit Corporation. This field is optional; we recommend supplying it on every form, since without it nothing on the form identifies the property." maxLength: 100 examples: - 876 Arch Rd Cary NC account_number: type: string description: The lender's own account, loan or other number for this borrower, printed under "Account number (see instructions)". It names the loan rather than the borrower, who can have more than one. A lender issuing more than one 1099-A to the same TIN must give each of those forms a distinct account number. maxLength: 30 examples: - 4471902-01 filer_office_code: type: string description: The lender's reporting office for this form. Defaults to the filer's single office; set it only where a filer with several offices files this form from other than the default one. Exactly four characters. minLength: 4 maxLength: 4 examples: - "0001" required: - acquisition_or_abandonment_date - principal_balance - borrower_personally_liable Form1099ABody: title: Form 1099-A allOf: - type: object properties: type: type: string const: 1099-A required: - type - $ref: "#/components/schemas/Form1099A" Form1099BHoldingPeriod: type: string title: Holding period description: Whether a gain or loss reported in box 2 is short-term or long-term. enum: - SHORT_TERM - LONG_TERM x-enumDescriptions: SHORT_TERM: '`ShortTermGainLossInd` = 1, "Short-term gain or loss". Both short term and long term may not be reported on the same Form 1099-B (`F1099B001`).' LONG_TERM: '`LongTermGainLossInd` = 1, "Long-term gain or loss".' Form1099BProceedsType: type: string title: Proceeds type description: Which figure box 1d carries, as reported to the IRS in box 6. enum: - GROSS_PROCEEDS - NET_PROCEEDS x-enumDescriptions: GROSS_PROCEEDS: "`GrossProceedsInd` = 1 — proceeds were not reduced by option premiums; the first box in box 6 is checked." NET_PROCEEDS: "`NetProceedsInd` = 1 — gross proceeds were reduced by option premiums; the second box in box 6 is checked. Cannot be combined with `GROSS_PROCEEDS` (`F1099B003`)." Form1099BStateLocalTax: type: object title: State and local tax description: One state's withholding on this sale. Boxes 14 to 16 print the state name, the state identification number and the state tax withheld; the remaining values appear on no federal copy and reach the state agencies under the Combined Federal/State Filing Program. properties: state: $ref: "#/components/schemas/StateCode" description: "Box 14. Required: an amount withheld belongs to a state, and neither the paper form nor a CF/SF forward means anything without one." state_id_number: type: string description: Box 15, the filer's withholding registration number in this state. Defaults to the filer's `state_registrations` entry for `state`; set it to override that for this form. maxLength: 25 examples: - WA-4471902 state_tax_withheld: type: string format: decimal description: Box 16, in US dollars. pattern: ^[0-9]+(\.[0-9]{2})?$ state_income: type: string format: decimal description: The portion of the proceeds attributable to this state, in US dollars. No box on this form prints it; supply it only where the state expects it. pattern: ^[0-9]+(\.[0-9]{2})?$ state_distribution: type: string format: decimal description: A state-reported distribution amount, in US dollars. Unused by this form, which reports proceeds rather than distributions. pattern: ^[0-9]+(\.[0-9]{2})?$ local_tax_withheld: type: string format: decimal description: Local income tax withheld on this sale, in US dollars. Not printed on this form. pattern: ^[0-9]+(\.[0-9]{2})?$ local_income: type: string format: decimal description: The portion of the proceeds attributable to the locality, in US dollars. Not printed on this form. pattern: ^[0-9]+(\.[0-9]{2})?$ locality: type: string description: The name of the locality the local amounts belong to. maxLength: 20 locality_code: type: string description: The locality's own abbreviation or code, as that jurisdiction assigns it. maxLength: 10 local_distribution: type: string format: decimal description: A locally reported distribution amount, in US dollars. Unused by this form. pattern: ^[0-9]+(\.[0-9]{2})?$ special_data_entries: type: string description: Free text a state agency has asked the filer to carry on the record. Not printed on any federal copy. maxLength: 60 required: - state Form1099B: type: object title: Form 1099-B description: | Proceeds paid to a customer on a sale of securities, commodities, regulated futures contracts, forward contracts or debt instruments, and property or services received through a barter exchange. The filer is the broker or barter exchange (the paper form's PAYER); the recipient is the customer. Both come from the filer and recipient resources. properties: account_number: type: string description: The filer's account number for this transaction's account, printed as "Account number (see instructions)". It names the account the sale was made in rather than the customer, who can hold several; set it to tell one account from another, or one sale from another, on the same recipient. Required whenever `fatca_filing_requirement` is true. maxLength: 30 examples: - 4471902-01 second_tin_notice: type: boolean description: 'Prints the "2nd TIN not." box: the IRS has twice within three calendar years told this filer that this customer''s TIN is wrong. Defaults to `Recipient.tin.second_notice`.' cusip: type: string description: The CUSIP number of the security sold, printed in the "CUSIP number" box. Leave it empty where the instructions permit — for a sale of a security with no CUSIP, and for the box 8–11 contract report. maxLength: 9 pattern: ^[A-Za-z0-9]*$ examples: - "37833100" fatca_filing_requirement: type: boolean default: false description: 'Checks the "FATCA filing requirement" box: the filer is a US payer satisfying its chapter 4 account reporting obligation by filing this form. When it is true, `account_number` is required.' form_8949_checkbox: type: string description: The box the recipient checks on Form 8949 when transcribing this sale, printed in the "Applicable checkbox on Form 8949" box. It restates boxes 2 and 12 from the recipient's point of view, so it should agree with `holding_period` and `basis_reported_to_irs`. Leave it empty on a box 8–11 contract report. enum: - SHORT_TERM_BASIS_REPORTED - SHORT_TERM_BASIS_NOT_REPORTED - LONG_TERM_BASIS_REPORTED - LONG_TERM_BASIS_NOT_REPORTED - UNDETERMINED_HOLDING_PERIOD x-enumDescriptions: SHORT_TERM_BASIS_REPORTED: "`A` — short-term transaction for which the cost or other basis is being reported to the IRS." SHORT_TERM_BASIS_NOT_REPORTED: "`B` — short-term transaction for which the cost or other basis is not being reported to the IRS." LONG_TERM_BASIS_REPORTED: "`D` — long-term transaction for which the cost or other basis is being reported to the IRS." LONG_TERM_BASIS_NOT_REPORTED: "`E` — long-term transaction for which the cost or other basis is not being reported to the IRS." UNDETERMINED_HOLDING_PERIOD: "`X` — the holding period is undetermined." property_description: type: string description: Box 1a — what was sold, in the instructions' own style ("100 sh. XYZ Co."); the number of shares or units, the classes of stock, the CUSIP-less security, or the contract on a box 8–11 report. Required. maxLength: 100 examples: - 100 sh. XYZ Co. date_acquired: type: string format: date description: Box 1b, the date the security was acquired, as `YYYY-MM-DD`. Left empty where the instructions allow "various" or where the holding period is undetermined, and left empty on a box 8–11 contract report. date_sold_or_disposed: type: string format: date description: Box 1c, the trade date of the sale, exchange or retirement — not the settlement date — as `YYYY-MM-DD`. Left empty on a box 8–11 contract report. proceeds: type: string format: decimal description: "Box 1d, in US dollars: the cash and the fair market value of property or services received, gross or net of option premiums according to `proceeds_reported_to_irs`. Negative on a short sale closed at a loss and on certain option positions, which is why this one admits a sign where box 1e and box 1f do not. Left empty on a box 8–11 contract report." pattern: ^-?[0-9]+(\.[0-9]{2})?$ examples: - "8241.55" cost_or_other_basis: type: string format: decimal description: Box 1e, in US dollars, reported only for a covered security. Left empty on a box 8–11 contract report. pattern: ^[0-9]+(\.[0-9]{2})?$ accrued_market_discount: type: string format: decimal description: "Box 1f, in US dollars: market discount accrued on a covered debt instrument up to the date of sale, which the recipient reports as ordinary interest income. Mutually exclusive with `wash_sale_loss_disallowed` — the instructions leave one of the two blank. Left empty on a box 8–11 contract report." pattern: ^[0-9]+(\.[0-9]{2})?$ wash_sale_loss_disallowed: type: string format: decimal description: "Box 1g, in US dollars: the loss disallowed because substantially identical securities were acquired within the wash-sale window. Reported as a positive amount even though it is a loss. Mutually exclusive with `accrued_market_discount`, and left empty on a box 8–11 contract report." pattern: ^[0-9]+(\.[0-9]{2})?$ holding_period: $ref: "#/components/schemas/Form1099BHoldingPeriod" description: Box 2, which of the first two checkboxes is checked. Omit where the holding period is undetermined (report `UNDETERMINED_HOLDING_PERIOD` in `form_8949_checkbox` instead), and on a box 8–11 contract report, where both checkboxes must be left unchecked. ordinary: type: boolean default: false description: "Box 2's third checkbox: the gain or loss is ordinary rather than capital — a contingent payment debt instrument, or a market discount accrual the customer must treat as interest. Independent of `holding_period`. False on a box 8–11 contract report." collectibles: type: boolean default: false description: "Box 3's first checkbox: the proceeds are from a collectible. Not to be set together with `qualified_opportunity_fund`. False on a box 8–11 contract report." qualified_opportunity_fund: type: boolean default: false description: "Box 3's second checkbox: the proceeds are from a disposition of an interest in a qualified opportunity fund. Not to be set together with `collectibles`. False on a box 8–11 contract report." federal_income_tax_withheld: type: string format: decimal description: "Box 4, in US dollars: backup withholding taken because the customer did not furnish a TIN or was notified of underreporting." pattern: ^[0-9]+(\.[0-9]{2})?$ noncovered_security: type: boolean default: false description: "Box 5: the security is noncovered, so boxes 1b, 1e, 1f, 1g and 2 are being reported voluntarily if at all and the IRS disregards them. False on a box 8–11 contract report." proceeds_reported_to_irs: $ref: "#/components/schemas/Form1099BProceedsType" description: Box 6, which of the two checkboxes is checked — whether the box 1d figure was reduced by option premiums. Omit on a box 8–11 contract report, where both checkboxes must be left unchecked. loss_not_allowed: type: boolean default: false description: "Box 7: the customer cannot take a loss on the box 1d amount, because the form reports a corporate acquisition or change in capital structure and the proceeds are only part of what was received. False on a box 8–11 contract report." closed_contracts_profit_or_loss: type: string format: decimal description: "Box 8, in US dollars: profit or (loss) realized on section 1256 contracts closed during the tax year. Supplying this, or any of boxes 9 to 11, makes the form a contract report: boxes 1a–1g, box 13 and the Form 8949 code are then left empty and the box 2/3/5/6/7 checkboxes unchecked." pattern: ^-?[0-9]+(\.[0-9]{2})?$ prior_year_unrealized_profit_or_loss: type: string format: decimal description: "Box 9, in US dollars: unrealized profit or (loss) on section 1256 contracts open at the end of the prior tax year. Same exclusions as box 8." pattern: ^-?[0-9]+(\.[0-9]{2})?$ current_year_unrealized_profit_or_loss: type: string format: decimal description: "Box 10, in US dollars: unrealized profit or (loss) on section 1256 contracts open at the end of the tax year. Same exclusions as box 8." pattern: ^-?[0-9]+(\.[0-9]{2})?$ aggregate_profit_or_loss: type: string format: decimal description: "Box 11, in US dollars: box 8 minus box 9 plus box 10 — the aggregate the customer carries to Form 6781. Same exclusions as box 8. It is not computed here; a broker that reports boxes 8 to 10 supplies it." pattern: ^-?[0-9]+(\.[0-9]{2})?$ basis_reported_to_irs: type: boolean default: false description: "Box 12: the basis in box 1e is being reported to the IRS, which is so for a covered security. Should agree with `form_8949_checkbox` — a checked box 12 goes with code A or D, an unchecked one with B, E or X." bartering: type: string format: decimal description: "Box 13, in US dollars: the fair market value of property or services the member or client received through a barter exchange. Left empty on a box 8–11 contract report." pattern: ^[0-9]+(\.[0-9]{2})?$ state_and_local_taxes: type: array description: Boxes 14 to 16, one entry per state. The paper form prints two columns; more than two entries may be supplied here. items: $ref: "#/components/schemas/Form1099BStateLocalTax" combined_federal_state_filing_states: type: array description: The states this form is to be forwarded to under the Combined Federal/State Filing Program. Nothing is printed for these. Each must be a state that participates in the program. items: $ref: "#/components/schemas/StateCode" filer_office_code: type: string description: Which of the filer's reporting offices issued this form. Defaults to the filer's single office; supply it only for a filer with more than one. minLength: 4 maxLength: 4 examples: - "0001" required: - property_description Form1099BBody: title: Form 1099-B allOf: - type: object properties: type: type: string const: 1099-B required: - type - $ref: "#/components/schemas/Form1099B" Form1099C: type: object title: Form 1099-C description: | Cancellation of a debt of $600 or more by an applicable entity — a financial institution, credit union, federal agency or other creditor within the meaning of section 6050P. One instance is one form: one creditor, one debtor, one identifiable event. A creditor cancelling two separate debts for the same debtor files two forms and sets `account_number` on each, since two forms for one debtor must carry distinct account numbers. properties: identifiable_event_date: type: string format: date description: Box 1. The date on which the event in `identifiable_event_code` occurred — the date of the discharge, not the date the creditor recorded it. Supply as `YYYY-MM-DD`; the year must be 1000 or later. This field is optional; Nutshell recommends supplying it whenever the creditor can establish a date, since the IRS expects one alongside an event code and the debtor uses it to place the cancellation in the right tax year. debt_discharged: type: string format: decimal description: Box 2, in US dollars. The amount of the discharged debt, including any interest reported in box 3 and any other charges the creditor is discharging. Required; the debtor reports this figure as income except to the extent it is excludable. Two decimal places, not negative, at most 999,999,999,999,999.99. pattern: ^[0-9]+(\.[0-9]{2})?$ examples: - "12450.00" interest: type: string format: decimal description: Box 3, in US dollars. Interest already counted inside `debt_discharged`, stated separately so the debtor can work out how much of the cancellation is excludable. It is a component of box 2, never an addition to it, so it must not exceed it. Leave it out where no interest was included. pattern: ^[0-9]+(\.[0-9]{2})?$ debt_description: type: string description: Box 4. What the debt was for — "student loan", "mortgage", "credit card expenditure", and for a debt secured by business or investment property, a description of that property. Required; the debtor cannot classify the cancellation without it. One line of at most 100 characters, regardless of the space the paper form's write-in area suggests. maxLength: 100 pattern: ^([!-~£§ÁÉÍÑÓ×ÚÜáéíñóúü] ?)*[!-~£§ÁÉÍÑÓ×ÚÜáéíñóúü]$ examples: - Student loan debtor_personally_liable: type: boolean description: Box 5 — printed on Copy B and Copy C as "If checked, the debtor was personally liable for repayment of the debt". True where the debtor bore personal liability for repayment at the time the debt was created, or, if modified, at the time of the last modification. Required. identifiable_event_code: type: string description: Box 6. Which event caused the creditor to report the discharge. Required; the instructions permit no blank. Where more than one event applies, report the earliest. enum: - BANKRUPTCY - OTHER_JUDICIAL_DEBT_RELIEF - STATUTE_OF_LIMITATIONS_EXPIRED - FORECLOSURE_ELECTION - DEBT_RELIEF_FROM_PROBATE - BY_AGREEMENT - DECISION_TO_DISCONTINUE_COLLECTION - OTHER_ACTUAL_DISCHARGE x-enumDescriptions: BANKRUPTCY: A — Bankruptcy. OTHER_JUDICIAL_DEBT_RELIEF: "B — Other judicial debt relief: a receivership, foreclosure or similar federal or state court proceeding other than bankruptcy." STATUTE_OF_LIMITATIONS_EXPIRED: C — Statute of limitations for collection of the debt expired, or the statutory period for filing a claim or beginning a deficiency judgment proceeding expired. FORECLOSURE_ELECTION: D — Foreclosure remedies that statutorily extinguish or bar the creditor's right to pursue collection of the debt. DEBT_RELIEF_FROM_PROBATE: E — Debt relief from probate or a similar proceeding. BY_AGREEMENT: F — By agreement between the creditor and the debtor to discharge the debt at less than full consideration. DECISION_TO_DISCONTINUE_COLLECTION: G — Decision or defined policy of the creditor to discontinue collection activity and discharge the debt. OTHER_ACTUAL_DISCHARGE: H — Other actual discharge before an identifiable event. fair_market_value_of_property: type: string format: decimal description: Box 7, in US dollars. The fair market value of property securing the debt where the cancellation followed a foreclosure or abandonment — for a foreclosure, the gross foreclosure bid price. Complete it whenever such property was involved; a creditor can instead file Form 1099-A, but where both are due only this form is filed and box 7 carries the value. Two decimal places, not negative. pattern: ^[0-9]+(\.[0-9]{2})?$ account_number: type: string description: The creditor's own account, loan or file number for this debtor, printed beneath the debtor's address. It names the debt rather than the debtor, who can have had more than one cancelled; set it to distinguish two debts cancelled for one debtor, which must be told apart. maxLength: 30 pattern: ^([!-~£§ÁÉÍÑÓ×ÚÜáéíñóúü] ?)*[!-~£§ÁÉÍÑÓ×ÚÜáéíñóúü]$ examples: - 4471902-01 filer_office_code: type: string description: The creditor's reporting office this form belongs to. Not printed on the form. Defaults to the filer's single office, and need only be given by a filer with more than one. minLength: 4 maxLength: 4 pattern: ^([!-~£§ÁÉÍÑÓ×ÚÜáéíñóúü] ?)*[!-~£§ÁÉÍÑÓ×ÚÜáéíñóúü]$ examples: - "0001" required: - debt_discharged - debt_description - debtor_personally_liable - identifiable_event_code Form1099CBody: title: Form 1099-C allOf: - type: object properties: type: type: string const: 1099-C required: - type - $ref: "#/components/schemas/Form1099C" Form1099CAP: type: object title: Form 1099-CAP description: | What a corporation reports to a shareholder who received cash, stock or other property in a change of corporate control or a substantial change in capital structure. One instance is one form: one shareholder, one class-of-stock line. A shareholder who exchanged more than one class of stock takes more than one form; in that case set `account_number` on each, distinct from the others filed for that shareholder. properties: sale_or_exchange_date: type: string format: date description: Box 1 — the date the shareholder's shares were sold or exchanged in the transaction being reported. Supply as `YYYY-MM-DD`, with a year of 1000 or later. aggregate_amount_received: type: string format: decimal description: Box 2 — the aggregate amount of cash and the fair market value of any stock or other property received in exchange for the stock held, in US dollars. This is the figure the shareholder reports the gain on. Required, and never negative. pattern: ^[0-9]+(\.[0-9]{2})?$ maxLength: 18 examples: - "48250.00" shares_exchanged: type: integer description: Box 3 — the number of the shareholder's shares exchanged in the transaction. Whole shares only; a fractional value is not accepted. maximum: 9999999999999 examples: - 1200 stock_classes_exchanged: type: string description: "Box 4 — the class or classes of stock exchanged, as free text in ten characters: enough for `Common`, `Preferred` or `Common/Pfd`, and not enough for a sentence." maxLength: 10 pattern: ^([!-~£§ÁÉÍÑÓ×ÚÜáéíñóúü] ?)*[!-~£§ÁÉÍÑÓ×ÚÜáéíñóúü]$ examples: - Common account_number: type: string description: The corporation's own account number for this shareholder, printed above box 1 as "Account number (see instructions)". It names the holding this form reports rather than the shareholder, who can have exchanged more than one class of stock. maxLength: 30 examples: - 4471902-01 filer_office_code: type: string description: The reporting office this form belongs to. Defaults to the filer's single office; set it only for a filer with more than one, and only to a code that filer has declared. Not printed on paper. minLength: 4 maxLength: 4 examples: - "0001" required: - aggregate_amount_received Form1099CAPBody: title: Form 1099-CAP allOf: - type: object properties: type: type: string const: 1099-CAP required: - type - $ref: "#/components/schemas/Form1099CAP" Form1099DAStateLocalTax: type: object title: Form 1099-DA state and local tax description: One state's row of the state block, carrying both the state and the local figures for that state. properties: state: description: Box 14. Required — the amounts below have no meaning without the state they belong to. $ref: "#/components/schemas/StateCode" state_id_number: type: string description: Box 15, the broker's withholding registration number in this state. Defaults to the filer's `state_registrations` entry for `state`; set it here only to override that. maxLength: 25 pattern: ^([!-~£§ÁÉÍÑÓ×ÚÜáéíñóúü] ?)*[!-~£§ÁÉÍÑÓ×ÚÜáéíñóúü]$ examples: - WA-4471902 state_tax_withheld: type: string format: decimal description: Box 16, in US dollars and cents. pattern: ^[0-9]+(\.[0-9]+)?$ state_income: type: string format: decimal description: State-reportable income, in US dollars and cents. No box on this form; supply it only where the state asks for it. pattern: ^[0-9]+(\.[0-9]{2})?$ state_distribution: type: string format: decimal description: State-reportable distribution, in US dollars and cents. No box on this form. pattern: ^[0-9]+(\.[0-9]{2})?$ local_tax_withheld: type: string format: decimal description: Local tax withheld, in US dollars and cents. No box on this form. pattern: ^[0-9]+(\.[0-9]{2})?$ local_income: type: string format: decimal description: Locally reportable income, in US dollars and cents. No box on this form. pattern: ^[0-9]+(\.[0-9]{2})?$ locality: type: string description: The locality's name, spelled out. No box on this form. maxLength: 20 pattern: ^([!-~£§ÁÉÍÑÓ×ÚÜáéíñóúü] ?)*[!-~£§ÁÉÍÑÓ×ÚÜáéíñóúü]$ locality_code: type: string description: The locality's abbreviation as the state publishes it. maxLength: 10 pattern: ^([!-~£§ÁÉÍÑÓ×ÚÜáéíñóúü] ?)*[!-~£§ÁÉÍÑÓ×ÚÜáéíñóúü]$ local_distribution: type: string format: decimal description: Locally reportable distribution, in US dollars and cents. No box on this form. pattern: ^[0-9]+(\.[0-9]{2})?$ special_data_entries: type: string description: Free text a state programme requires on the record. It has no box on this form and no federal meaning. maxLength: 60 pattern: ^([!-~£§ÁÉÍÑÓ×ÚÜáéíñóúü] ?)*[!-~£§ÁÉÍÑÓ×ÚÜáéíñóúü]$ required: - state Form1099DA: type: object title: Form 1099-DA description: | Proceeds from a broker's sale, exchange or other disposition of a digital asset on behalf of a customer. The filer is the broker printed in the upper-left block, and the recipient is the customer; neither is restated here. What the request body carries is the asset, the transaction, the character of the gain and the state withholding. properties: account_number: type: string description: The broker's own account number for this customer, printed above box 1a. It names the account the disposition was made in rather than the customer, who can hold several. This field is optional; Nutshell recommends supplying it, since it is what distinguishes two records filed against one recipient TIN — which matters on this form more than most, as a broker commonly issues one record per disposition. maxLength: 30 pattern: ^([!-~£§ÁÉÍÑÓ×ÚÜáéíñóúü] ?)*[!-~£§ÁÉÍÑÓ×ÚÜáéíñóúü]$ examples: - 4471902-01 cusip_number: type: string description: The CUSIP of the disposed asset, printed to the right of the account number. Most digital assets have none; leave it absent rather than filling it with a placeholder. maxLength: 9 pattern: ^[A-Za-z0-9]*$ form_8949_checkbox: type: string description: Which box the recipient checks on Form 8949, printed unnumbered beneath the CUSIP. It restates in one letter what boxes 2 and 6 say between them; the IRS prints it so the customer need not work it out. enum: - SHORT_TERM_BASIS_REPORTED - SHORT_TERM_BASIS_NOT_REPORTED - LONG_TERM_BASIS_REPORTED - LONG_TERM_BASIS_NOT_REPORTED - HOLDING_PERIOD_UNKNOWN x-enumDescriptions: SHORT_TERM_BASIS_REPORTED: "`G` — a short-term transaction for which the cost or other basis is being reported to the IRS." SHORT_TERM_BASIS_NOT_REPORTED: "`H` — a short-term transaction for which the cost or other basis is not being reported to the IRS." LONG_TERM_BASIS_REPORTED: "`J` — a long-term transaction for which the cost or other basis is being reported to the IRS." LONG_TERM_BASIS_NOT_REPORTED: "`K` — a long-term transaction for which the cost or other basis is not being reported to the IRS." HOLDING_PERIOD_UNKNOWN: "`Y` — the broker cannot determine whether the recipient should check box H or box K on Form 8949 because the holding period is unknown." digital_asset_code: type: string description: "Box 1a. The broker's code for the asset disposed of — the ticker or other short identifier the broker uses for it. Required: the record is meaningless without an asset." maxLength: 9 pattern: ^[A-Za-z0-9]*$ examples: - BTC digital_asset_name: type: string description: Box 1b. The asset's name spelled out, for a customer who does not recognize the code in box 1a. Required. minLength: 1 maxLength: 35 pattern: ^([!-~£§ÁÉÍÑÓ×ÚÜáéíñóúü] ?)*[!-~£§ÁÉÍÑÓ×ÚÜáéíñóúü]$ examples: - Bitcoin units: type: string format: decimal description: Box 1c. Units of the asset disposed of, as an exact decimal — up to 32 digits before the point and 18 after it. Required. Where box 11a elects aggregate reporting, this is the total units across the aggregated transactions. pattern: ^[0-9]{1,32}(\.[0-9]{1,18})?$ examples: - "0.153900000000000000" date_acquired: type: string format: date description: Box 1d. When the units disposed of were acquired. Supply a date on or before the end of the tax year, and no later than `date_sold_or_disposed`. Omit it where acquisition dates vary across the units reported or are unknown — the paper copy then prints nothing here, and box 8 or the `HOLDING_PERIOD_UNKNOWN` checkbox carries the reason. date_sold_or_disposed: type: string format: date description: Box 1e. When the disposition occurred. The date must fall within the tax year being reported. proceeds: type: string format: decimal description: Box 1f, in US dollars and cents. Gross or net of option premiums according to `proceeds_reporting_basis`. This is the one amount on this form that can be negative. Supply either this or `nft_first_sale_proceeds` — one of the two must be present, zero or otherwise. pattern: ^-?[0-9]+(\.[0-9]{2})?$ cost_or_other_basis: type: string format: decimal description: Box 1g, in US dollars and cents. Report it only where `basis_reported_to_irs` is true, or where the broker is furnishing it to the customer as optional information. pattern: ^[0-9]+(\.[0-9]{2})?$ accrued_market_discount: type: string format: decimal description: Box 1h, in US dollars and cents. pattern: ^[0-9]+(\.[0-9]{2})?$ wash_sale_loss_disallowed: type: string format: decimal description: Box 1i, in US dollars and cents — the loss disallowed on a wash sale, entered as a positive amount. pattern: ^[0-9]+(\.[0-9]{2})?$ basis_reported_to_irs: type: boolean default: false description: "Box 2. Whether the amount in `cost_or_other_basis` is being reported to the IRS rather than furnished to the customer only. Leave it false on a record that sets `aggregate_reporting_asset`: basis is not reported on aggregated stablecoin or NFT proceeds." proceeds_reporting_basis: type: string description: Box 3. Whether the amount in `proceeds` was reduced by option premiums. Omit it for a disposition involving no options, which is the case the form prints with neither box checked. enum: - GROSS_PROCEEDS - NET_PROCEEDS x-enumDescriptions: GROSS_PROCEEDS: 'The "Gross proceeds" box: box 1f was not reduced by option premiums.' NET_PROCEEDS: 'The "Net proceeds" box: box 1f was reduced by option premiums.' qualified_opportunity_fund: type: boolean default: false description: "The QOF box in box 3: the proceeds are from a disposition of an interest in a qualified opportunity fund." federal_income_tax_withheld: type: string format: decimal description: Box 4, in US dollars and cents. The only permitted value is zero. Send `"0.00"` or omit the property. pattern: ^[0-9]+(\.[0-9]{2})?$ loss_not_allowed: type: boolean default: false description: Box 5. Whether a loss is not allowed to the customer on the basis of the amount in box 1f — the case where box 1f reports gross proceeds only, so the customer cannot compute an allowable loss from this form. gain_or_loss_holding_period: type: string description: Box 6. Whether the gain or loss on the disposition is short-term or long-term under section 1222. The two boxes are mutually exclusive, so at most one of them is checked. Omit the property where the holding period is unknown — `form_8949_checkbox` then carries `HOLDING_PERIOD_UNKNOWN`. enum: - SHORT_TERM - LONG_TERM x-enumDescriptions: SHORT_TERM: The "Short-term" box in box 6. LONG_TERM: The "Long-term" box in box 6. ordinary: type: boolean default: false description: 'The "Ordinary" box in box 6: the gain or loss is ordinary rather than capital.' proceeds_only_cash: type: boolean default: false description: Box 7. Whether the amount in box 1f consists only of cash — no other property or services were received in the exchange. broker_relied_on_customer_acquisition_information: type: boolean default: false description: Box 8. Whether the acquisition date or basis reported came from the customer rather than from the broker's own records. noncovered_security: type: boolean default: false description: Box 9. Whether the asset is a noncovered security, for which the broker is not required to report basis or holding period. aggregate_reporting_asset: type: string description: Box 11a. Set it where this record aggregates many transactions rather than reporting one, and say which optional aggregate reporting method it uses. When it is set, `transaction_count` must be greater than zero and `basis_reported_to_irs` must be false. enum: - QUALIFYING_STABLECOINS - SPECIFIED_NFTS x-enumDescriptions: QUALIFYING_STABLECOINS: 'The "Qualifying stablecoins" box: the aggregated proceeds are from designated sales of qualifying stablecoins.' SPECIFIED_NFTS: 'The "Specified NFTs" box: the aggregated proceeds are from sales of specified NFTs.' transaction_count: type: integer description: Box 11b. How many transactions the aggregated amounts cover. Required whenever `aggregate_reporting_asset` is set, and meaningless otherwise. minimum: 0 maximum: 999999999999999 nft_first_sale_proceeds: type: string format: decimal description: Box 11c, in US dollars and cents. So much of the aggregate gross proceeds in box 1f as is attributable to first sales of specified NFTs by their creator or minter. Either this or `proceeds` must be present, zero or otherwise. pattern: ^[0-9]+(\.[0-9]{2})?$ units_transferred_in: type: string format: decimal description: Box 12a. Units the customer transferred into the account, as an exact decimal on the same scale as `units`. Reported where the broker did not acquire the units it later disposed of. pattern: ^[0-9]{1,32}(\.[0-9]{1,18})?$ transfer_in_date: type: string format: date description: Box 12b. When the units in `units_transferred_in` arrived. Required whenever that box has a value, and the date must fall on or before the end of the tax year being reported. state_and_local_taxes: type: array description: State reporting, boxes 14 through 16 — the paper form prints two rows, so a broker withholding for two states files one record with two entries here rather than two records. Only `state`, `state_id_number` and `state_tax_withheld` have boxes on this form; the remaining properties of the entry are for state programmes that ask for them and print nowhere. items: $ref: "#/components/schemas/Form1099DAStateLocalTax" filer_office_code: type: string description: The reporting office this record belongs to, as an `offices[].code` on the filer. Defaults to the filer's single office; supply it only for a filer that keeps more than one. minLength: 4 maxLength: 4 pattern: ^([!-~£§ÁÉÍÑÓ×ÚÜáéíñóúü] ?)*[!-~£§ÁÉÍÑÓ×ÚÜáéíñóúü]$ examples: - "0001" required: - digital_asset_code - digital_asset_name - units Form1099DABody: title: Form 1099-DA allOf: - type: object properties: type: type: string const: 1099-DA required: - type - $ref: "#/components/schemas/Form1099DA" Form1099DIVStateLocalTax: type: object title: Form 1099-DIV state and local tax description: One state's withholding on this form. The paper form prints only the state, its identification number and the tax withheld (boxes 14, 15 and 16); the remaining properties do not appear on the printed copy. properties: state: description: Box 14. $ref: "#/components/schemas/StateCode" state_id_number: type: string description: Box 15, the payer's withholding registration number in this state. Defaults to the filer's `state_registrations` entry for `state`; set it here to override that for this form alone. maxLength: 25 examples: - WA-4471902 state_tax_withheld: type: string format: decimal description: Box 16. State income tax withheld from the distributions, in US dollars. pattern: ^[0-9]+(\.[0-9]{2})?$ state_income: type: string format: decimal description: The dividends attributed to this state, in US dollars. No box on the paper 1099-DIV; supply it for states that want the figure alongside the withholding. pattern: ^[0-9]+(\.[0-9]{2})?$ state_distribution: type: string format: decimal description: The distribution attributed to this state, in US dollars. No box on the paper 1099-DIV. pattern: ^[0-9]+(\.[0-9]{2})?$ local_tax_withheld: type: string format: decimal description: Local income tax withheld, in US dollars. No box on the paper 1099-DIV. pattern: ^[0-9]+(\.[0-9]{2})?$ local_income: type: string format: decimal description: The dividends attributed to the locality, in US dollars. No box on the paper 1099-DIV. pattern: ^[0-9]+(\.[0-9]{2})?$ locality: type: string description: The name of the taxing locality. No box on the paper 1099-DIV. maxLength: 20 locality_code: type: string description: The locality's abbreviation as the taxing authority assigns it. No box on the paper 1099-DIV. maxLength: 10 local_distribution: type: string format: decimal description: The distribution attributed to the locality, in US dollars. No box on the paper 1099-DIV. pattern: ^[0-9]+(\.[0-9]{2})?$ special_data_entries: type: string description: A free-text field for the filer's own or a state's purposes; the IRS forwards it without interpreting it. maxLength: 60 required: - state Form1099DIV: type: object title: Form 1099-DIV description: | Dividends and distributions paid to one recipient in one calendar year. Amounts are US dollars as decimal strings; omit a box rather than sending `"0.00"` for it, since a zero is a reported figure and an omitted box is not. properties: total_ordinary_dividends: type: string format: decimal description: Box 1a. Total ordinary dividends, in US dollars. This should be at least the sum of `qualified_dividends`, `section_897_ordinary_dividends`, `investment_expenses` and `section_199a_dividends`, each of which is a component of it. Supply it whenever `qualified_dividends` is supplied. pattern: ^[0-9]+(\.[0-9]{2})?$ examples: - "1450.00" qualified_dividends: type: string format: decimal description: Box 1b. The portion of box 1a that qualifies for the capital gains rates, in US dollars. Included in box 1a rather than additional to it. pattern: ^[0-9]+(\.[0-9]{2})?$ total_capital_gain_distribution: type: string format: decimal description: Box 2a. Total capital gain distributions, in US dollars. When non-zero it should be at least the sum of `unrecaptured_section_1250_gain`, `section_1202_gain`, `collectibles_28_percent_gain` and `section_897_capital_gain`, which are its components. pattern: ^[0-9]+(\.[0-9]{2})?$ unrecaptured_section_1250_gain: type: string format: decimal description: Box 2b. The section 1250 gain from certain depreciable real property included in box 2a, in US dollars. pattern: ^[0-9]+(\.[0-9]{2})?$ section_1202_gain: type: string format: decimal description: Box 2c. Gain from qualified small business stock that can be partly excluded under section 1202, included in box 2a, in US dollars. pattern: ^[0-9]+(\.[0-9]{2})?$ collectibles_28_percent_gain: type: string format: decimal description: Box 2d. The 28% rate gain from sales or exchanges of collectibles included in box 2a, in US dollars. pattern: ^[0-9]+(\.[0-9]{2})?$ section_897_ordinary_dividends: type: string format: decimal description: Box 2e. The part of box 1a attributable to a section 897 gain on United States real property interests, in US dollars. Reported for the benefit of foreign persons; a recipient that is not one can disregard it. pattern: ^[0-9]+(\.[0-9]{2})?$ section_897_capital_gain: type: string format: decimal description: Box 2f. The part of box 2a attributable to a section 897 gain on United States real property interests, in US dollars. pattern: ^[0-9]+(\.[0-9]{2})?$ nondividend_distributions: type: string format: decimal description: Box 3. The part of the distribution that is a return of the recipient's basis rather than a dividend, in US dollars. pattern: ^[0-9]+(\.[0-9]{2})?$ federal_income_tax_withheld: type: string format: decimal description: "Box 4. Backup withholding, in US dollars. This box alone is reason enough to file: a 1099-DIV is due for any amount withheld, regardless of the size of the dividend." pattern: ^[0-9]+(\.[0-9]{2})?$ section_199a_dividends: type: string format: decimal description: Box 5. The part of box 1a that is a REIT or other qualified business income dividend eligible for the section 199A deduction, in US dollars. Included in box 1a. pattern: ^[0-9]+(\.[0-9]{2})?$ investment_expenses: type: string format: decimal description: Box 6. The recipient's share of a non-publicly-offered regulated investment company's expenses, in US dollars. Included in box 1a. pattern: ^[0-9]+(\.[0-9]{2})?$ foreign_tax_paid: type: string format: decimal description: Box 7. Foreign tax paid on the dividends and other distributions, in US dollars — converted by the filer, not reported in the foreign currency. pattern: ^[0-9]+(\.[0-9]{2})?$ foreign_country: description: Box 8. The country or US possession to which `foreign_tax_paid` was paid. Where tax was paid to more than one country the IRS expects the single word "Various", which a country code cannot express; such a form has to be filed on paper. $ref: "#/components/schemas/Country" cash_liquidation_distributions: type: string format: decimal description: Box 9. Cash distributed in a partial or complete liquidation of the payer, in US dollars. pattern: ^[0-9]+(\.[0-9]{2})?$ noncash_liquidation_distributions: type: string format: decimal description: Box 10. The fair market value of non-cash property distributed in a partial or complete liquidation of the payer, in US dollars. pattern: ^[0-9]+(\.[0-9]{2})?$ fatca_filing_requirement: type: boolean default: false description: Box 11. Whether the payer is a US payer satisfying its chapter 4 reporting requirement by filing this form, or a foreign financial institution reporting under an applicable intergovernmental agreement. Checking it makes `account_number` mandatory. exempt_interest_dividends: type: string format: decimal description: Box 12. Tax-exempt interest dividends from a mutual fund or other regulated investment company, in US dollars. This should be at least `private_activity_bond_interest_dividends`, which is a part of it. pattern: ^[0-9]+(\.[0-9]{2})?$ private_activity_bond_interest_dividends: type: string format: decimal description: Box 13. The part of box 12 that is interest on specified private activity bonds and so subject to the alternative minimum tax, in US dollars. pattern: ^[0-9]+(\.[0-9]{2})?$ state_and_local_taxes: type: array description: State and local withholding, boxes 14 through 16. Two entries print on the paper form; any beyond the first two do not appear on the recipient's printed copy. items: $ref: "#/components/schemas/Form1099DIVStateLocalTax" combined_federal_state_filing_states: type: array description: The states this form is to be forwarded to under the Combined Federal/State Filing program, so that the filer need not file with them directly. List only the 33 participating states. Not printed on the form. maxItems: 60 items: $ref: "#/components/schemas/StateCode" account_number: type: string description: The filer's account number for this recipient, printed above box 1a. It names the account the dividends were paid on rather than the recipient, who can hold several. Required when `fatca_filing_requirement` is true, and where the filer issues two 1099-DIVs against one TIN each needs a distinct value. maxLength: 30 examples: - 4471902-01 second_tin_notice: type: boolean description: 'The "2nd TIN not." box, printed to the right of the account number: the IRS has twice within three calendar years told this payer that this recipient''s TIN is wrong. Defaults to `Recipient.tin.second_notice`.' filer_office_code: type: string description: The filer's reporting office this form belongs to. Defaults to the filer's single office, and need not be supplied for a filer that has only one. Not printed on the form. minLength: 4 maxLength: 4 examples: - "0001" Form1099DIVBody: title: Form 1099-DIV allOf: - type: object properties: type: type: string const: 1099-DIV required: - type - $ref: "#/components/schemas/Form1099DIV" Form1099INTStateLocalTax: type: object title: Form 1099-INT state and local tax description: One state's withholding on this return, with any locality detail beneath it. Boxes 15 to 17 on the paper form print the state, its identification number and the tax withheld; the remaining properties have no box on the federal form, and are there for state filing programs that ask for more than it shows. properties: state: description: The state whose withholding this entry reports — box 15. $ref: "#/components/schemas/StateCode" state_id_number: type: string description: Box 16 — the payer's withholding registration number in this state. Defaults to the filer's `state_registrations` entry for `state`; set it here only to override that. maxLength: 25 pattern: ^([!-~£§ÁÉÍÑÓ×ÚÜáéíñóúü] ?)*[!-~£§ÁÉÍÑÓ×ÚÜáéíñóúü]$ examples: - WA-4471902 state_tax_withheld: type: string format: decimal description: Box 17 — state income tax withheld from the interest, in US dollars. pattern: ^[0-9]+(\.[0-9]{2})?$ state_income: type: string format: decimal description: The interest attributable to this state, in US dollars. The paper 1099-INT has no box for it; supply it where a state program participating in Combined Federal/State Filing expects the income as well as the tax. pattern: ^[0-9]+(\.[0-9]{2})?$ state_distribution: type: string format: decimal description: Interest is income rather than a distribution, so a 1099-INT ordinarily leaves this unset. In US dollars where a state asks for it. pattern: ^[0-9]+(\.[0-9]{2})?$ local_tax_withheld: type: string format: decimal description: Local income tax withheld from the interest, in US dollars. No box on the paper form. pattern: ^[0-9]+(\.[0-9]{2})?$ local_income: type: string format: decimal description: The interest attributable to the locality named in `locality`, in US dollars. pattern: ^[0-9]+(\.[0-9]{2})?$ locality: type: string description: The name of the locality withholding the tax, as it is to read. maxLength: 20 pattern: ^([!-~£§ÁÉÍÑÓ×ÚÜáéíñóúü] ?)*[!-~£§ÁÉÍÑÓ×ÚÜáéíñóúü]$ locality_code: type: string description: The locality's own code, where the state assigns one. Not checked against any list. maxLength: 10 pattern: ^([!-~£§ÁÉÍÑÓ×ÚÜáéíñóúü] ?)*[!-~£§ÁÉÍÑÓ×ÚÜáéíñóúü]$ local_distribution: type: string format: decimal description: The locality counterpart of `state_distribution`, and likewise not something a 1099-INT ordinarily reports. pattern: ^[0-9]+(\.[0-9]{2})?$ special_data_entries: type: string description: Free text a state asks for that the federal form has no box for. It reaches the state unaltered; the IRS does nothing with it. maxLength: 60 pattern: ^([!-~£§ÁÉÍÑÓ×ÚÜáéíñóúü] ?)*[!-~£§ÁÉÍÑÓ×ÚÜáéíñóúü]$ required: - state Form1099INT: type: object title: Form 1099-INT description: | Interest income paid to one recipient in one calendar year. `interest_income` is the only required field: it is box 1, the amount the form exists to report. Report a year with no interest as `"0"` rather than by omission. A form that reports only federal withholding, or only tax-exempt interest, is otherwise a complete return. properties: interest_income: type: string format: decimal description: Box 1 — interest of $10 or more paid on the account, in US dollars, excluding interest reported in box 3. Required; see the schema description. pattern: ^[0-9]+(\.[0-9]{2})?$ examples: - "1240.55" early_withdrawal_penalty: type: string format: decimal description: "Box 2 — interest or principal forfeited on early withdrawal of a time deposit, in US dollars. Reported gross: it is not netted against box 1." pattern: ^[0-9]+(\.[0-9]{2})?$ savings_bond_and_treasury_interest: type: string format: decimal description: Box 3 — interest on US Savings Bonds, Treasury bills, notes and bonds, in US dollars. Kept out of box 1 because it is exempt from state and local tax. pattern: ^[0-9]+(\.[0-9]{2})?$ federal_income_tax_withheld: type: string format: decimal description: Box 4 — backup withholding, in US dollars. Withheld at 24% of box 1, box 3, box 8 and box 9 where the recipient failed to furnish a TIN or is subject to backup withholding. pattern: ^[0-9]+(\.[0-9]{2})?$ investment_expenses: type: string format: decimal description: Box 5 — the recipient's share of a single-class REMIC's investment expenses, in US dollars. pattern: ^[0-9]+(\.[0-9]{2})?$ foreign_tax_paid: type: string format: decimal description: Box 6 — foreign tax paid on interest, reported in US dollars whichever currency it was paid in. Supply `foreign_country` alongside it. pattern: ^[0-9]+(\.[0-9]{2})?$ foreign_country: description: Box 7 — the foreign country or US territory to which the box 6 tax was paid. Required whenever `foreign_tax_paid` is present. The paper form prints the country's name, which the server derives from the code supplied. $ref: "#/components/schemas/Country" tax_exempt_interest: type: string format: decimal description: Box 8 — tax-exempt interest, in US dollars, including exempt-interest dividends from a mutual fund. This is the total from which `specified_private_activity_bond_interest` is a subset. pattern: ^[0-9]+(\.[0-9]{2})?$ specified_private_activity_bond_interest: type: string format: decimal description: Box 9 — the part of box 8 that is interest on specified private activity bonds, in US dollars, and so subject to alternative minimum tax. Because it is a subset, it must not exceed `tax_exempt_interest`. pattern: ^[0-9]+(\.[0-9]{2})?$ market_discount: type: string format: decimal description: Box 10 — accrued market discount on a covered security, in US dollars, where the recipient has elected to include it in income currently. pattern: ^[0-9]+(\.[0-9]{2})?$ bond_premium: type: string format: decimal description: Box 11 — amortizable bond premium on a covered taxable security other than a Treasury obligation, in US dollars. Reported as a positive amount even though it reduces the recipient's interest income; boxes 11, 12 and 13 differ only in what kind of bond the premium is on. pattern: ^[0-9]+(\.[0-9]{2})?$ treasury_obligation_bond_premium: type: string format: decimal description: Box 12 — amortizable bond premium on a covered US Treasury obligation, in US dollars, corresponding to the interest in box 3. pattern: ^[0-9]+(\.[0-9]{2})?$ tax_exempt_bond_premium: type: string format: decimal description: Box 13 — amortizable bond premium on a covered tax-exempt bond, in US dollars, corresponding to the interest in box 8. pattern: ^[0-9]+(\.[0-9]{2})?$ tax_exempt_bond_cusip: type: string description: Box 14 — the CUSIP number of the tax-exempt or tax credit bond the box 8 or box 9 interest was paid on. Where the interest is from more than one bond, the instructions have the payer enter `VARIOUS` here in place of a number. maxLength: 9 pattern: ^[A-Za-z0-9]*$ examples: - 912828U40 state_and_local_taxes: type: array description: Boxes 15, 16 and 17 — state, state identification number and state tax withheld. The paper form prints two rows; supply as many entries as the return needs, including the locality amounts for which the paper form has no boxes at all. Amounts here are withholding and income, not distributions. items: $ref: "#/components/schemas/Form1099INTStateLocalTax" fatca_filing_requirement: type: boolean default: false description: The "FATCA filing requirement" box, printed to the right of the recipient's address. True where the payer is a US payer reporting this account to satisfy its chapter 4 account reporting requirement. Setting it makes `account_number` required. account_number: type: string description: The "Account number (see instructions)" box — the filer's own number for the account the interest was paid on, which identifies the account rather than the recipient, who can hold several. Required where `fatca_filing_requirement` is true, and required — and distinct on each form — where this filer files more than one 1099-INT for the same recipient TIN in a year. maxLength: 30 pattern: ^([!-~£§ÁÉÍÑÓ×ÚÜáéíñóúü] ?)*[!-~£§ÁÉÍÑÓ×ÚÜáéíñóúü]$ examples: - 4471902-01 second_tin_notice: type: boolean description: The "2nd TIN not." box. Defaults to `Recipient.tin.second_notice`; set it here only to override that for this one form. filer_office_code: type: string description: The reporting office this return belongs to. Defaults to the filer's single office, and may be omitted where the filer has only one. minLength: 4 maxLength: 4 examples: - "0001" combined_federal_state_filing_states: type: array description: "States to which the IRS forwards this return under the Combined Federal/State Filing program. Nothing is printed for these on paper. Each must be a participating state: the program excludes AK, FL, IL, IA, KY, NH, NV, NY, SD, TN, TX, UT, VT, VA, WA, WV, WY and the territories." items: $ref: "#/components/schemas/StateCode" required: - interest_income Form1099INTBody: title: Form 1099-INT allOf: - type: object properties: type: type: string const: 1099-INT required: - type - $ref: "#/components/schemas/Form1099INT" Form1099KStateLocalTax: type: object title: Form 1099-K state and local tax description: State withholding reported for one state on this form, together with any local withholding a state programme collects alongside it. properties: state: description: Box 6. The state the withholding was remitted to, and the state whose identification number box 7 carries. $ref: "#/components/schemas/StateCode" state_id_number: type: string description: "Box 7: the filer's withholding registration number in `state`. Defaults to the filer's `state_registrations` entry for that state; set it here to override." maxLength: 25 examples: - WA-4471902 state_tax_withheld: type: string format: decimal description: "Box 8, in US dollars: state income tax withheld from the payments reported on this form and remitted to `state`." pattern: ^[0-9]+(\.[0-9]{2})?$ state_income: type: string format: decimal description: The portion of `gross_amount`, in US dollars, attributable to `state`. No box on the 1099-K layout carries it; supply it for state programmes that ask for an apportionment. pattern: ^[0-9]+(\.[0-9]{2})?$ state_distribution: type: string format: decimal description: A state distribution amount, in US dollars. Nothing on a 1099-K is a distribution, so leave it unset unless a state programme has asked for it. pattern: ^[0-9]+(\.[0-9]{2})?$ local_tax_withheld: type: string format: decimal description: Local income tax withheld from these payments, in US dollars, remitted to `locality`. pattern: ^[0-9]+(\.[0-9]{2})?$ local_income: type: string format: decimal description: The portion of `gross_amount`, in US dollars, attributable to `locality`. pattern: ^[0-9]+(\.[0-9]{2})?$ locality: type: string description: The name of the city, county or other locality the local tax was withheld for. maxLength: 20 examples: - Cuyahoga County locality_code: type: string description: The locality's own code, where the state programme identifies localities by code rather than by name. maxLength: 10 local_distribution: type: string format: decimal description: A local distribution amount, in US dollars. As with `state_distribution`, no box on this form uses it. pattern: ^[0-9]+(\.[0-9]{2})?$ special_data_entries: type: string description: Free text passed through to the state in the Combined Federal/State Filing Program. The IRS neither reads nor validates it; its content is defined by the receiving state's specification. maxLength: 60 required: - state Form1099K: type: object title: Form 1099-K description: | Payment card and third party network transactions settled to one payee for one tax year. The reportable figure is the **gross** amount settled — before any adjustment for fees, credits, refunds, chargebacks or discounts — which is why every amount on this form is non-negative and why the monthly breakdown in boxes 5a–5l must add back up to box 1a. properties: transactions_reported: type: string title: Kind of transactions reported description: "Which of box 1's transaction-type checkboxes is marked. Required: the two boxes are mutually exclusive treatments of the same gross amount, and exactly one of them must be marked." enum: - PAYMENT_CARD - THIRD_PARTY_NETWORK x-enumDescriptions: PAYMENT_CARD: "`PaymentCardInd` = `1`. Transactions reported are payment card transactions." THIRD_PARTY_NETWORK: "`ThirdPartyNetworkInd` = `1`. Transactions reported are third party network transactions." gross_amount: type: string format: decimal description: "Box 1a, in US dollars: the gross amount of all reportable payment transactions settled to the payee, before deducting fees, refunds or any other amount. Required — it is what the form exists to report, and both box 1b and the monthly amounts in boxes 5a–5l are measured against it." pattern: ^[0-9]+(\.[0-9]{2})?$ examples: - "48250.00" card_not_present_transactions: type: string format: decimal description: "Box 1b, in US dollars: the portion of `gross_amount` arising from transactions where the card was not present at the time of the transaction or the card number was keyed in. It must not exceed `gross_amount`." pattern: ^[0-9]+(\.[0-9]{2})?$ merchant_category_code: type: string description: "Box 2: the four-digit merchant category code used by the card industry to classify the payee's business, where one applies to these transactions." pattern: ^[0-9]{4}$ examples: - "5812" payment_transactions: type: integer description: "Box 3: the number of payment transactions — not including refunds or other reversals — making up `gross_amount`. This field is optional; we recommend supplying it on every form, since the IRS expects a count on each one." minimum: 0 maximum: 9999999999 examples: - 412 federal_income_tax_withheld: type: string format: decimal description: "Box 4, in US dollars: backup withholding taken from these payments where the payee did not furnish a TIN." pattern: ^[0-9]+(\.[0-9]{2})?$ january: type: string format: decimal description: "Box 5a, in US dollars: gross amount of reportable payment transactions settled in January." pattern: ^[0-9]+(\.[0-9]{2})?$ february: type: string format: decimal description: Box 5b, in US dollars. Gross amount settled in February. pattern: ^[0-9]+(\.[0-9]{2})?$ march: type: string format: decimal description: Box 5c, in US dollars. Gross amount settled in March. pattern: ^[0-9]+(\.[0-9]{2})?$ april: type: string format: decimal description: Box 5d, in US dollars. Gross amount settled in April. pattern: ^[0-9]+(\.[0-9]{2})?$ may: type: string format: decimal description: Box 5e, in US dollars. Gross amount settled in May. pattern: ^[0-9]+(\.[0-9]{2})?$ june: type: string format: decimal description: Box 5f, in US dollars. Gross amount settled in June. pattern: ^[0-9]+(\.[0-9]{2})?$ july: type: string format: decimal description: Box 5g, in US dollars. Gross amount settled in July. pattern: ^[0-9]+(\.[0-9]{2})?$ august: type: string format: decimal description: Box 5h, in US dollars. Gross amount settled in August. pattern: ^[0-9]+(\.[0-9]{2})?$ september: type: string format: decimal description: Box 5i, in US dollars. Gross amount settled in September. pattern: ^[0-9]+(\.[0-9]{2})?$ october: type: string format: decimal description: Box 5j, in US dollars. Gross amount settled in October. pattern: ^[0-9]+(\.[0-9]{2})?$ november: type: string format: decimal description: Box 5k, in US dollars. Gross amount settled in November. pattern: ^[0-9]+(\.[0-9]{2})?$ december: type: string format: decimal description: Box 5l, in US dollars. Gross amount settled in December. The twelve monthly amounts must sum to `gross_amount`, and an omitted month counts as zero. pattern: ^[0-9]+(\.[0-9]{2})?$ state_and_local_taxes: type: array description: "Boxes 6 to 8, one entry per state: the state, the filer's identification number in it, and the state income tax withheld from these payments. The printed layout has room for two entries; any number may be supplied here. The locality fields of the shared block have no printed box on this form — supply them only where a state's own filing programme asks for local withholding." items: $ref: "#/components/schemas/Form1099KStateLocalTax" filer_office_code: type: string description: The filer office whose returns this form belongs to. Defaults to the filer's single office; set it only where the filer reports through more than one, and give a code that appears in the filer's `offices`. minLength: 4 maxLength: 4 examples: - "0001" combined_federal_state_filing_states: type: array description: "The states this form is to be forwarded to under the Combined Federal/State Filing Program. Each must be a participating state: Alaska, Florida, Nevada, New Hampshire, New York, South Dakota, Tennessee, Texas, Utah, Vermont, Virginia, Washington, West Virginia and Wyoming do not take part." items: $ref: "#/components/schemas/StateCode" account_number: type: string description: The filer's account number for this payee, naming the account the payments settled into rather than the payee, who can hold more than one. Where a filer issues two 1099-K forms against one TIN, each must carry a distinct account number. maxLength: 30 examples: - 4471902-01 second_tin_notice: type: boolean description: 'Marks the "2nd TIN not." box: the IRS has twice within three calendar years told this filer that this payee''s TIN is wrong. Defaults to `Recipient.tin.second_notice`.' required: - transactions_reported - gross_amount Form1099KBody: title: Form 1099-K allOf: - type: object properties: type: type: string const: 1099-K required: - type - $ref: "#/components/schemas/Form1099K" Form1099LSIssuerName: type: object title: Form 1099-LS issuer name description: The name of the issuer of the life insurance contract, on one or two lines. properties: line1: type: string maxLength: 75 pattern: ^(([A-Za-z0-9#\-()]|&|') ?)*([A-Za-z0-9#\-()]|&|')$ examples: - Cascade Mutual Life Assurance Co line2: type: string description: A continuation of the name, or a name the issuer does business as. maxLength: 75 pattern: ^(([A-Za-z0-9#/%\-()]|&|') ?)*([A-Za-z0-9#/%\-()]|&|')$ required: - line1 Form1099LSAcquirerContact: type: object title: Form 1099-LS acquirer contact description: The name, address and telephone number of the person a payment recipient contacts about this form, where that is not the acquirer. `name` is required whenever the object is present. properties: name: type: string description: A whole name on one line, rather than the parts of one. Digits and apostrophes are allowed, so a department ("Policy Admin Unit") serves as well as a person. maxLength: 35 pattern: ^([A-Za-z0-9'\-] ?)*[A-Za-z0-9'\-]$ examples: - Alice Brown address: description: Where the contact receives post, if it differs from the acquirer's own address. $ref: "#/components/schemas/Address" phone_number: $ref: "#/components/schemas/PhoneNumber" required: - name Form1099LS: type: object title: Form 1099-LS description: | Reportable Life Insurance Sale — filed by the acquirer of an interest in a life insurance contract in a reportable policy sale, and furnished both to the payment recipient and, on a separate Form 1099-SB obligation, to the issuer. One instance is one contract interest acquired from one payment recipient. Where an acquirer buys interests in more than one policy from the same person, each is its own form, and each must carry its own `account_number` distinguishing it from the others filed against that person. properties: policy_number: type: string description: "The number of the life insurance contract whose interest was acquired, printed above box 1. Required: it is what identifies the contract to the issuer, who must reconcile it against a Form 1099-SB." maxLength: 30 pattern: ^([!-~£§ÁÉÍÑÓ×ÚÜáéíñóúü] ?)*[!-~£§ÁÉÍÑÓ×ÚÜáéíñóúü]$ examples: - POL-88213004 amount_paid: type: string format: decimal description: Box 1. The total amount of all payments the acquirer made to the payment recipient for the interest, in US dollars. Not negative. Required — the consideration paid is what the form exists to state. pattern: ^[0-9]+(\.[0-9]{2})?$ examples: - "125000.00" sale_date: type: string format: date description: Box 2. The date the reportable policy sale closed — the date the interest in the contract was acquired. Supply as `YYYY-MM-DD`; the paper form prints it in the acquirer's usual format. This field is optional; we recommend supplying it, since a sale with no date gives the issuer nothing to date its own reporting from. issuer_name: description: The name of the entity responsible for administering the life insurance contract, printed beneath box 2. A business name only. $ref: "#/components/schemas/Form1099LSIssuerName" acquirer_contact: description: The acquirer's information contact, printed at the foot of the form. Supply it only when the contact differs from the acquirer itself; omit the object entirely and the printed form falls back to the filer's own name, address and telephone number. $ref: "#/components/schemas/Form1099LSAcquirerContact" account_number: type: string description: The acquirer's own account number for this payment recipient, printed in the "Account number" box. It names the contract interest this form reports rather than the person, who can have sold more than one. Where more than one form is filed against the same recipient TIN, each must carry a distinct value. maxLength: 30 pattern: ^([!-~£§ÁÉÍÑÓ×ÚÜáéíñóúü] ?)*[!-~£§ÁÉÍÑÓ×ÚÜáéíñóúü]$ examples: - 4471902-01 filer_office_code: type: string description: The reporting office this form belongs to. Defaults to the filer's single office; set it only where the filer has more than one and this form is not the default office's. Not printed on paper. minLength: 4 maxLength: 4 examples: - "0001" required: - policy_number - amount_paid Form1099LSBody: title: Form 1099-LS allOf: - type: object properties: type: type: string const: 1099-LS required: - type - $ref: "#/components/schemas/Form1099LS" Form1099LTCInsured: type: object title: Insured description: The individual whose illness or death gave rise to the benefits. TIN, name and mailing address are all required; where the insured is the policyholder they simply repeat the recipient's values. properties: taxpayer_id: type: string description: The insured's TIN, nine digits unpunctuated, printed as "INSURED'S TIN". Almost always an SSN. No TIN type accompanies it and the IRS does not name/TIN match it. pattern: ^[0-9]{9}$ examples: - "001234567" name: description: Printed as "INSURED'S name". $ref: "#/components/schemas/PersonPartyName" mailing_address: description: The insured's address. Required, though it does not appear on the paper form, which prints only the insured's TIN and name. $ref: "#/components/schemas/Address" required: - taxpayer_id - name - mailing_address Form1099LTC: type: object title: Form 1099-LTC description: | Long-term care benefits and accelerated death benefits paid under an insurance contract or by a viatical settlement provider during the calendar year. At least one of `gross_benefits_paid` and `accelerated_death_benefits_paid` should be present: a return reporting neither reports nothing. Neither is required outright, because the form is used both by long-term care insurers (box 1) and by payers of accelerated death benefits alone (box 2). properties: gross_benefits_paid: type: string format: decimal description: Box 1. The gross long-term care benefits paid this year under the contract, in US dollars, whether paid on a per diem basis or as reimbursement of actual expenses. Not negative, and not above 999,999,999,999,999.99. pattern: ^[0-9]+(\.[0-9]{2})?$ examples: - "4800.00" accelerated_death_benefits_paid: type: string format: decimal description: Box 2. Accelerated death benefits paid this year, in US dollars, under a life insurance contract on the life of an insured certified as terminally or chronically ill, or paid by a viatical settlement provider. Not negative, and not above 999,999,999,999,999.99. pattern: ^[0-9]+(\.[0-9]{2})?$ examples: - "25000.00" payment_basis: type: string title: Payment basis description: "Box 3. Whether the amount in box 1 was paid on a periodic basis or as reimbursement of expenses actually incurred. Required: the recipient needs it to work out how much of the benefit is taxable, and the per diem limit applies only to the first. The two choices are mutually exclusive, matching the two checkboxes on the paper form." enum: - PER_DIEM - REIMBURSED x-enumDescriptions: PER_DIEM: '`PerDiemInd` = 1, box 3 "Per diem". Payments made on any periodic basis without regard to actual expenses.' REIMBURSED: '`ReimbursedAmountInd` = 1, box 3 "Reimbursed amount". Payments made for actual expenses incurred.' insured: description: The insured individual, whose TIN and name the form prints beneath box 3. The insured and the policyholder can be the same person; required either way, so supply it even where the two coincide. $ref: "#/components/schemas/Form1099LTCInsured" qualified_contract: type: boolean default: false description: Box 4. Whether the benefits reported in box 1 were paid from a contract that is a qualified long-term care insurance contract under section 7702B(b). Printed as optional on the paper form; leaving it unset prints an unchecked box. insured_illness_status: type: array title: Insured illness status description: Box 5. The certifications held for the insured. Give both entries where the insured was certified both chronically and terminally ill; give none where the payer holds no certification, which is the case for benefits paid under a contract that is not a qualified one. uniqueItems: true maxItems: 2 items: type: string enum: - CHRONICALLY_ILL - TERMINALLY_ILL x-enumDescriptions: CHRONICALLY_ILL: '`LTCInsuredChronicallyIllInd` = 1, box 5 "Chronically ill". The insured was certified as chronically ill.' TERMINALLY_ILL: '`LTCInsuredTerminallyIllInd` = 1, box 5 "Terminally ill". The insured was certified as terminally ill.' certification_date: type: string format: date description: Box 5, "Date certified". The latest date on which the insured was certified chronically or terminally ill, as `YYYY-MM-DD`. Supply it whenever `insured_illness_status` is non-empty; it has no meaning otherwise. A certification of chronic illness must have been made within the previous 12 months for the per diem exclusion to apply, which is what makes the date worth printing. pattern: ^[1-9][0-9]{3}-(0[1-9]|1[0-2])-(0[1-9]|[1-2][0-9]|3[0-1])$ examples: - "2026-03-14" account_number: type: string description: The payer's own account, policy or contract number for this policyholder, printed above box 1. It names the policy rather than the policyholder, who can hold more than one. Distinct numbers are needed where more than one 1099-LTC is filed for the same policyholder. maxLength: 30 pattern: ^([!-~£§ÁÉÍÑÓ×ÚÜáéíñóúü] ?)*[!-~£§ÁÉÍÑÓ×ÚÜáéíñóúü]$ examples: - LTC-4471902-01 filer_office_code: type: string description: The reporting office this return belongs to. Defaults to the filer's single office; set it only where the filer has more than one and this return is not the default office's. Exactly four characters — a length, not a maximum. minLength: 4 maxLength: 4 pattern: ^([!-~£§ÁÉÍÑÓ×ÚÜáéíñóúü] ?)*[!-~£§ÁÉÍÑÓ×ÚÜáéíñóúü]$ examples: - "0001" required: - payment_basis - insured Form1099LTCBody: title: Form 1099-LTC allOf: - type: object properties: type: type: string const: 1099-LTC required: - type - $ref: "#/components/schemas/Form1099LTC" Form1099MISCStateLocalTax: type: object title: Form 1099-MISC state and local tax description: One state's withholding and income figures, boxes 16 through 18, together with the local and distribution figures this form carries for state and local filing. properties: state: description: The state the withholding was remitted to — the state half of box 17. $ref: "#/components/schemas/StateCode" state_id_number: type: string description: The payer's state number, box 17. Defaults to the filer's `state_registrations` entry for `state`; supply it here only to override that, or where the filer holds no registration for the state. maxLength: 25 pattern: ^(([!-~£§ÁÉÍÑÓ×ÚÜáéíñóúü] ?)*[!-~£§ÁÉÍÑÓ×ÚÜáéíñóúü])$ examples: - WA-4471902 state_tax_withheld: type: string format: decimal description: Box 16. State income tax withheld from the payments, in US dollars. pattern: ^[0-9]+(\.[0-9]{2})?$ state_income: type: string format: decimal description: "Box 18. The portion of the payments reported above that is taxable by this state, in US dollars. It is income rather than a distribution: this form reports payments made, not amounts drawn from an account." pattern: ^[0-9]+(\.[0-9]{2})?$ state_distribution: type: string format: decimal description: A state distribution amount, in US dollars. The paper form has no box for it; supply it where a state's own reporting asks for a figure distinct from `state_income`. pattern: ^[0-9]+(\.[0-9]{2})?$ local_tax_withheld: type: string format: decimal description: City or other local income tax withheld, in US dollars. No box on the paper form; carried for local filing. pattern: ^[0-9]+(\.[0-9]{2})?$ local_income: type: string format: decimal description: The portion of the payments taxable by the locality, in US dollars. No box on the paper form. pattern: ^[0-9]+(\.[0-9]{2})?$ locality: type: string description: The locality's name, as it reads on a local filing. maxLength: 20 pattern: ^(([!-~£§ÁÉÍÑÓ×ÚÜáéíñóúü] ?)*[!-~£§ÁÉÍÑÓ×ÚÜáéíñóúü])$ examples: - Cuyahoga locality_code: type: string description: The locality's own identifying code, where it issues one. maxLength: 10 pattern: ^(([!-~£§ÁÉÍÑÓ×ÚÜáéíñóúü] ?)*[!-~£§ÁÉÍÑÓ×ÚÜáéíñóúü])$ local_distribution: type: string format: decimal description: A local distribution amount, in US dollars. No box on the paper form; the local counterpart of `state_distribution`. pattern: ^[0-9]+(\.[0-9]{2})?$ special_data_entries: type: string description: Free text the payer passes through to the state or locality — what the paper 1099-R and W-2G print as a "special data entries" area and this form does not print at all. The IRS makes no use of it. maxLength: 60 pattern: ^(([!-~£§ÁÉÍÑÓ×ÚÜáéíñóúü] ?)*[!-~£§ÁÉÍÑÓ×ÚÜáéíñóúü])$ required: - state Form1099MISC: type: object title: Form 1099-MISC description: | Miscellaneous Information: the return a payer files for rents, royalties, prizes, fishing boat proceeds, medical payments, crop insurance, attorney gross proceeds and the other payments that fall outside Form 1099-NEC. The payer is the filer on file and the payee is the recipient on file; neither is restated here. Amounts are US dollars and must not be negative — a payer reversing a prior year's payment files a correction rather than a negative figure. properties: rents: type: string format: decimal description: Box 1. Gross rent — real estate, machine rental, pasture — of $2,000 or more, in US dollars. Rent paid to a real estate agent or property manager is not reported here; the agent reports what it passes on to the owner. pattern: ^[0-9]+(\.[0-9]{2})?$ examples: - "18000.00" royalties: type: string format: decimal description: Box 2. Gross royalties of $10 or more from oil, gas, mineral properties, copyrights and patents, in US dollars, before any reduction for severance or other taxes withheld by the operator. Surface royalties belong in box 1 and timber royalties paid under a pay-as-cut contract belong on Form 1099-S. pattern: ^[0-9]+(\.[0-9]{2})?$ other_income: type: string format: decimal description: Box 3. Prizes, awards and other income of $2,000 or more not reportable in another box, in US dollars — including punitive damages, deceased-employee wages paid to an estate, and Indian gaming profits paid to a tribal member. pattern: ^[0-9]+(\.[0-9]{2})?$ federal_income_tax_withheld: type: string format: decimal description: Box 4. Backup withholding, in US dollars — 24% of a reportable payment to a payee who did not furnish a TIN or who the IRS has told the payer is subject to withholding. pattern: ^[0-9]+(\.[0-9]{2})?$ fishing_boat_proceeds: type: string format: decimal description: Box 5. The individual's share of the proceeds from the sale of a catch, or the fair market value of a distribution in kind, to each crew member of a boat with a normal crew of fewer than ten. Cash payments of up to $100 per trip contingent on a minimum catch are included here. US dollars. pattern: ^[0-9]+(\.[0-9]{2})?$ medical_and_health_care_payments: type: string format: decimal description: Box 6. Payments of $2,000 or more to physicians, suppliers and providers of medical or health care services, in US dollars. Reportable even where the payee is a corporation, which is why a corporate recipient is normal on this form. pattern: ^[0-9]+(\.[0-9]{2})?$ direct_sale_over_threshold: type: boolean default: false description: Box 7. Whether the payer made direct sales of $5,000 or more of consumer products to the recipient for resale, anywhere other than a permanent retail establishment. The amount is not reported — this box is the whole of the report, and a form may carry it with every dollar box empty. substitute_payments: type: string format: decimal description: Box 8. Substitute payments of $10 or more in lieu of dividends or tax-exempt interest received by a broker on a customer's behalf while the customer's securities were on loan, in US dollars. pattern: ^[0-9]+(\.[0-9]{2})?$ crop_insurance_proceeds: type: string format: decimal description: Box 9. Crop insurance proceeds of $2,000 or more paid to a farmer by an insurance company, in US dollars, unless the farmer has told the insurer that expenses have been capitalized. pattern: ^[0-9]+(\.[0-9]{2})?$ gross_proceeds_paid_to_an_attorney: type: string format: decimal description: Box 10. Gross proceeds of $600 or more paid to an attorney in connection with legal services — the whole of a settlement cheque, not the fee portion — in US dollars. An attorney's own fee for services is nonemployee compensation and belongs on Form 1099-NEC instead. pattern: ^[0-9]+(\.[0-9]{2})?$ fish_purchased_for_resale: type: string format: decimal description: Box 11. Cash of $600 or more paid during the year for fish or other aquatic life purchased from anyone engaged in the trade or business of catching fish, in US dollars. Printed at the foot of the right-hand column on the paper form, after box 15. pattern: ^[0-9]+(\.[0-9]{2})?$ section_409a_deferrals: type: string format: decimal description: Box 12. The total amount deferred during the year under a nonqualified deferred compensation plan subject to section 409A, in US dollars. This field is optional, and the amount is not included in box 1 of any Form W-2. pattern: ^[0-9]+(\.[0-9]{2})?$ fatca_filing_requirement: type: boolean default: false description: Box 13. Whether the payer is a US payer reporting on this form to satisfy its chapter 4 account reporting requirement, or a foreign financial institution reporting a US account under an applicable model 1 IGA. When this is true, `account_number` is required. nonqualified_deferred_compensation: type: string format: decimal description: Box 15. Income under a nonqualified deferred compensation plan that fails to satisfy section 409A, in US dollars. This amount is also included in `other_income` (box 3) as income of a nonemployee, or in box 1 of Form W-2 for an employee. pattern: ^[0-9]+(\.[0-9]{2})?$ state_and_local_taxes: type: array description: Boxes 16, 17 and 18 — state tax withheld, the payer's state number, and state income — one entry per state. The paper form prints two entries; a third and beyond reach the IRS but do not fit on the printed copies. The locality fields in each entry have no box on this form and are carried for state and local filing only. items: $ref: "#/components/schemas/Form1099MISCStateLocalTax" combined_federal_state_filing_states: type: array description: The states for which this return is to be forwarded under the Combined Federal/State Filing program, so that the payer need not file with them directly. List only participating states — AL, AZ, AR, CA, CT, CO, DC, DE, GA, HI, ID, IN, KS, LA, MA, MD, ME, MI, MN, MS, MT, NE, NJ, NM, NC, ND, OH, OK, OR, PA, RI, SC and WI. items: $ref: "#/components/schemas/StateCode" account_number: type: string description: The payer's own account number for this recipient, printed beneath the address block. A field of the form rather than of the recipient, who can hold more than one account with the payer. Required when `fatca_filing_requirement` is true, and required where the payer files more than one 1099-MISC against a single recipient TIN, since each of those forms needs a distinct value. maxLength: 30 pattern: ^(([!-~£§ÁÉÍÑÓ×ÚÜáéíñóúü] ?)*[!-~£§ÁÉÍÑÓ×ÚÜáéíñóúü])$ examples: - 4471902-01 second_tin_notice: type: boolean description: The "2nd TIN not." box. Whether the IRS has notified the payer twice within three calendar years that this payee's TIN is wrong. Defaults to `Recipient.tin.second_notice`; set it here to override for this form alone. filer_office_code: type: string description: The reporting office this return belongs to, as one of the filer's `offices[].code`. Defaults to the filer's single office; supply it only for a filer that reports through more than one. minLength: 4 maxLength: 4 examples: - "0001" Form1099MISCBody: title: Form 1099-MISC allOf: - type: object properties: type: type: string const: 1099-MISC required: - type - $ref: "#/components/schemas/Form1099MISC" Form1099NECStateLocalTax: type: object title: Form 1099-NEC state and local tax description: "One state row of boxes 5 through 7, and any locality detail carried alongside it. Amounts here are income and withholding, not distributions: `state_distribution` and `local_distribution` have no box on this form." properties: state: description: "Box 6, the state half. Required: an amount reported against no state cannot be routed to one." $ref: "#/components/schemas/StateCode" state_id_number: type: string description: Box 6, the payer's state number half. Defaults to the filer's `state_registrations` entry for `state`; set it here to override that for this form alone. maxLength: 25 examples: - WA-4471902 state_tax_withheld: type: string format: decimal description: Box 5, in US dollars. Nonnegative. pattern: ^[0-9]+(\.[0-9]{2})?$ state_income: type: string format: decimal description: Box 7, in US dollars — the part of the box 1 compensation attributable to this state. Nonnegative. pattern: ^[0-9]+(\.[0-9]{2})?$ state_distribution: type: string format: decimal description: No box on this form. A 1099-NEC reports compensation rather than distributions, so leave it empty. In US dollars, nonnegative. pattern: ^[0-9]+(\.[0-9]{2})?$ local_tax_withheld: type: string format: decimal description: Local income tax withheld, in US dollars. No box on this form; it is forwarded to the state under Combined Federal/State Filing. Nonnegative. pattern: ^[0-9]+(\.[0-9]{2})?$ local_income: type: string format: decimal description: The part of the box 1 compensation attributable to the locality, in US dollars. No box on this form. Nonnegative. pattern: ^[0-9]+(\.[0-9]{2})?$ locality: type: string description: The name of the locality the local amounts belong to. maxLength: 20 examples: - Cuyahoga County locality_code: type: string description: The locality's own identifying code, where the state assigns one. Not validated against any IRS list. maxLength: 10 local_distribution: type: string format: decimal description: No box on this form, and no meaning on it; see `state_distribution`. In US dollars, nonnegative. pattern: ^[0-9]+(\.[0-9]{2})?$ special_data_entries: type: string description: Free text a state asks for and the IRS does not read. It has no box on the federal form; follow the receiving state's specification for what belongs here. maxLength: 60 required: - state Form1099NEC: type: object title: Form 1099-NEC description: | Nonemployee compensation paid in the course of the filer's trade or business — fees, commissions, prizes and awards for services performed by someone who is not an employee — together with any federal or state tax withheld from it. The recipient's name, TIN and address, and the payer block, come from the recipient and filer on file. The recipient must have both a TIN and a mailing address recorded before this form can be filed; neither is set here. The general reporting threshold is $2,000; later years use the IRS inflation-adjusted threshold. Backup withholding is reportable regardless of the payment amount. These reporting thresholds do not prevent creating a below-threshold record. properties: nonemployee_compensation: type: string format: decimal description: "Box 1, in US dollars. The amount the form exists to report, and required for that reason. Report gross compensation before any withholding shown in box 4. Must not be negative: an overpayment recovered in a later year is not netted here." pattern: ^[0-9]+(\.[0-9]{2})?$ examples: - "4750.00" direct_sale_over_threshold: type: boolean default: false description: Box 2. True where the filer made direct sales totaling $5,000 or more of consumer products to the recipient for resale, anywhere other than a permanent retail establishment. The box is a checkbox and carries no amount; a filer that has nothing else to report for the recipient may file a 1099-NEC with this box checked and box 1 empty, which is the one case in which `nonemployee_compensation` is sensibly zero. excess_golden_parachute_payments: type: string format: decimal description: Box 3, in US dollars. Excess golden parachute payments — the portion of a change-in-control payment over the base amount, which the recipient owes a 20% excise tax on. Nonnegative. pattern: ^[0-9]+(\.[0-9]{2})?$ federal_income_tax_withheld: type: string format: decimal description: Box 4, in US dollars. Backup withholding at 24%, taken because the recipient failed to furnish a TIN or the IRS notified the filer to withhold. Nonnegative. pattern: ^[0-9]+(\.[0-9]{2})?$ state_and_local_taxes: type: array description: Boxes 5, 6 and 7, which the paper form prints as two rows so that one payment can be split between two states. `state_income` is the box 1 compensation attributable to the state, not a separate class of income. Locality amounts may be supplied alongside them; this form prints no boxes for those, and they reach the states through the Combined Federal/State Filing program rather than the recipient's copy. items: $ref: "#/components/schemas/Form1099NECStateLocalTax" combined_federal_state_filing_states: type: array description: The states this form is to be forwarded to under the Combined Federal/State Filing program, so that the filer need not file with them separately. Name only participating states — AL, AZ, AR, CA, CT, CO, DC, DE, GA, HI, ID, IN, KS, LA, MA, MD, ME, MI, MN, MS, MT, NE, NJ, NM, NC, ND, OH, OK, OR, PA, RI, SC and WI. Not itself a box on the paper form. items: $ref: "#/components/schemas/StateCode" account_number: type: string description: The filer's account number for this recipient, printed beneath the recipient block. A field of the form rather than of the recipient, who can hold more than one account with the filer. Where the filer files more than one 1099-NEC against a single recipient TIN, each of those forms needs an account number, and they must differ. maxLength: 30 examples: - 4471902-01 second_tin_notice: type: boolean description: 'The "2nd TIN not." box: the IRS has notified the filer twice within three calendar years that this recipient''s TIN is wrong. Defaults to `Recipient.tin.second_notice`; set it here to override that for this form alone.' filer_office_code: type: string description: The filer's reporting office this form belongs to. Defaults to the filer's single office, and may be omitted by a filer that reports as one office. Must match the `code` of one of the filer's `offices`. minLength: 4 maxLength: 4 examples: - "0001" required: - nonemployee_compensation Form1099NECBody: title: Form 1099-NEC allOf: - type: object properties: type: type: string const: 1099-NEC required: - type - $ref: "#/components/schemas/Form1099NEC" Form1099OIDStateLocalTax: type: object title: Form 1099-OID state and local tax description: One state's withholding on this form, printed in boxes 12–14. The locality properties are also accepted, but Form 1099-OID has no printed boxes for them, so they do not appear on the PDF. properties: state: description: Box 12. The state whose withholding this entry reports. $ref: "#/components/schemas/StateCode" state_id_number: type: string description: Box 13, the filer's withholding registration number in `state`. Defaults to the filer's `state_registrations` entry for that state; set it here to override. maxLength: 25 pattern: ^([!-~£§ÁÉÍÑÓ×ÚÜáéíñóúü] ?)*[!-~£§ÁÉÍÑÓ×ÚÜáéíñóúü]$ examples: - WA-4471902 state_tax_withheld: type: string format: decimal description: Box 14. State income tax withheld from the amounts reported on this form. US dollars. pattern: ^[0-9]+(\.[0-9]{2})?$ state_income: type: string format: decimal description: State-reportable income for `state` — on this form, the OID and interest attributed to it. Reported to the state under the Combined Federal/State Filing program; the paper Form 1099-OID prints no box for it. US dollars. pattern: ^[0-9]+(\.[0-9]{2})?$ state_distribution: type: string format: decimal description: A state-level distribution amount, part of the shared state block for forms that report distributions. Form 1099-OID reports accruals rather than distributions, so this is ordinarily left unset. US dollars. pattern: ^[0-9]+(\.[0-9]{2})?$ local_tax_withheld: type: string format: decimal description: Local income tax withheld for `locality`. No printed box on this form. US dollars. pattern: ^[0-9]+(\.[0-9]{2})?$ local_income: type: string format: decimal description: Locally reportable income for `locality`. No printed box on this form. US dollars. pattern: ^[0-9]+(\.[0-9]{2})?$ locality: type: string description: The name of the city, county or other locality the local amounts belong to. maxLength: 20 pattern: ^([!-~£§ÁÉÍÑÓ×ÚÜáéíñóúü] ?)*[!-~£§ÁÉÍÑÓ×ÚÜáéíñóúü]$ locality_code: type: string description: The locality's own abbreviation or code, as that locality issues it. Not an IRS code list — free text. maxLength: 10 pattern: ^([!-~£§ÁÉÍÑÓ×ÚÜáéíñóúü] ?)*[!-~£§ÁÉÍÑÓ×ÚÜáéíñóúü]$ local_distribution: type: string format: decimal description: A locality-level distribution amount, the local counterpart of `state_distribution` and equally unused on this form. US dollars. pattern: ^[0-9]+(\.[0-9]{2})?$ special_data_entries: type: string description: Free text the filer and the state have agreed on, passed through to the state unchanged. The IRS neither validates nor prints it. maxLength: 60 pattern: ^([!-~£§ÁÉÍÑÓ×ÚÜáéíñóúü] ?)*[!-~£§ÁÉÍÑÓ×ÚÜáéíñóúü]$ required: - state Form1099OID: type: object title: Form 1099-OID description: | Original issue discount for one holder and one debt instrument. Amounts are US dollars. Every amount on this form except box 8 must be zero or positive; box 8 alone can be negative. properties: original_issue_discount: type: string format: decimal description: Box 1. OID on the obligation that accrued to this holder over the part of the year the obligation was held, other than OID on a US Treasury obligation, which goes in box 8 instead. Not reduced by any acquisition premium reported in box 6. US dollars. pattern: ^[0-9]+(\.[0-9]{2})?$ examples: - "1204.55" other_periodic_interest: type: string format: decimal description: Box 2. Interest other than OID paid or credited on the obligation during the year — the stated interest a holder reports separately from box 1. US dollars. pattern: ^[0-9]+(\.[0-9]{2})?$ early_withdrawal_penalty: type: string format: decimal description: Box 3. Interest or principal forfeited on an early withdrawal, which the holder deducts rather than netting against boxes 1 and 2. US dollars. pattern: ^[0-9]+(\.[0-9]{2})?$ federal_income_tax_withheld: type: string format: decimal description: Box 4. Backup withholding — where the holder furnished no TIN or the IRS notified the filer that the one furnished was wrong. US dollars. pattern: ^[0-9]+(\.[0-9]{2})?$ market_discount: type: string format: decimal description: Box 5. Accrued market discount for the year on a covered security, reported only where the holder elected under section 1278(b) to include it in income currently. US dollars. pattern: ^[0-9]+(\.[0-9]{2})?$ acquisition_premium: type: string format: decimal description: Box 6. The part of the acquisition premium amortized for the year, which reduces the amount of OID in box 1 that the holder includes in income. Reported as a positive amount even though it works against box 1. US dollars. pattern: ^[0-9]+(\.[0-9]{2})?$ description: type: string description: "Box 7. The obligation these amounts arose on: its CUSIP number, or — where there is none — a description including the issuer, the type of obligation, the coupon rate and the year of maturity. Required; a holder cannot tie the form to a security without it." maxLength: 100 pattern: ^([!-~£§ÁÉÍÑÓ×ÚÜáéíñóúü] ?)*[!-~£§ÁÉÍÑÓ×ÚÜáéíñóúü]$ examples: - 912828YS3 treasury_obligation_original_issue_discount: type: string format: decimal description: Box 8. OID on a US Treasury obligation for the part of the year the holder owned it. May be negative — a deflation adjustment on an inflation-indexed Treasury obligation reduces the year's OID below zero. US dollars. pattern: ^-?[0-9]+(\.[0-9]{2})?$ investment_expenses: type: string format: decimal description: Box 9. The holder's share of investment expenses of a single-class REMIC. US dollars. pattern: ^[0-9]+(\.[0-9]{2})?$ bond_premium: type: string format: decimal description: Box 10. Bond premium amortization allocable to the interest paid during the year on a covered taxable security acquired at a premium. Reported as a positive amount; it offsets box 2. US dollars. pattern: ^[0-9]+(\.[0-9]{2})?$ tax_exempt_original_issue_discount: type: string format: decimal description: Box 11. OID on a tax-exempt obligation that is a covered security. US dollars. pattern: ^[0-9]+(\.[0-9]{2})?$ state_and_local_taxes: type: array description: Boxes 12, 13 and 14 — the state, the filer's identification number in it, and the state tax withheld — one entry per state the filer withheld for. The paper form has room for two; a PDF with more than two entries continues onto a further copy. items: $ref: "#/components/schemas/Form1099OIDStateLocalTax" fatca_filing_requirement: type: boolean default: false description: The "FATCA filing requirement" checkbox. True where the filer is a US payer reporting this account to satisfy its chapter 4 account reporting requirement, or a foreign financial institution reporting under an election to report as a US payer. When this is true, `account_number` is required. account_number: type: string description: The filer's own account, policy or other identifying number for this holder, printed as "Account number (see instructions)". It names the obligation this form reports rather than the holder, who commonly holds several. Required where `fatca_filing_requirement` is true, and where the filer issues more than one 1099-OID for one recipient TIN, in which case each of those forms needs a distinct value. maxLength: 30 pattern: ^([!-~£§ÁÉÍÑÓ×ÚÜáéíñóúü] ?)*[!-~£§ÁÉÍÑÓ×ÚÜáéíñóúü]$ examples: - 4471902-01 second_tin_notice: type: boolean description: The "2nd TIN not." box. True where the IRS has notified the filer twice within three calendar years that this holder's TIN is wrong, which stops further notices for the same account. Defaults to `Recipient.tin.second_notice`; set it here to override for this form alone. combined_federal_state_filing_states: type: array description: The states this form is to be forwarded to under the Combined Federal/State Filing program, which are not printed on the paper form. Each must be a state that participates in the program for this form type. items: $ref: "#/components/schemas/StateCode" filer_office_code: type: string description: Which of the filer's reporting offices issued this form. Defaults to the filer's single office; required only of a filer that has more than one. minLength: 4 maxLength: 4 examples: - "0001" required: - description Form1099OIDBody: title: Form 1099-OID allOf: - type: object properties: type: type: string const: 1099-OID required: - type - $ref: "#/components/schemas/Form1099OID" Form1099PATRStateLocalTax: type: object title: Form 1099-PATR state and local tax description: "One state's — or one locality within a state's — reporting for a 1099-PATR. The amounts here are the distributions and withholding as that jurisdiction taxes them, which need not equal any federal box: a state can exclude per-unit retains the federal return includes." properties: state: description: The jurisdiction this entry reports to. $ref: "#/components/schemas/StateCode" state_id_number: type: string description: The cooperative's withholding registration number in this state. Defaults to the filer's `state_registrations` entry for `state`; set it here to override. maxLength: 25 pattern: ^([!-~£§ÁÉÍÑÓ×ÚÜáéíñóúü] ?)*[!-~£§ÁÉÍÑÓ×ÚÜáéíñóúü]$ examples: - MN-4471902 state_tax_withheld: type: string format: decimal description: State income tax withheld from the distributions, in US dollars. pattern: ^[0-9]+(\.[0-9]{2})?$ state_income: type: string format: decimal description: The amount of the distributions the state treats as income, in US dollars. pattern: ^[0-9]+(\.[0-9]{2})?$ state_distribution: type: string format: decimal description: The gross distribution reported to the state, in US dollars, where the state asks for the distribution rather than the taxable income. pattern: ^[0-9]+(\.[0-9]{2})?$ local_tax_withheld: type: string format: decimal description: Local income tax withheld from the distributions, in US dollars. pattern: ^[0-9]+(\.[0-9]{2})?$ local_income: type: string format: decimal description: The amount of the distributions the locality treats as income, in US dollars. pattern: ^[0-9]+(\.[0-9]{2})?$ locality: type: string description: The name of the city, county or other locality taxing the distributions. maxLength: 20 pattern: ^([!-~£§ÁÉÍÑÓ×ÚÜáéíñóúü] ?)*[!-~£§ÁÉÍÑÓ×ÚÜáéíñóúü]$ examples: - Duluth locality_code: type: string description: The locality's own identifying code, where it issues one; otherwise omit and give `locality` alone. maxLength: 10 pattern: ^([!-~£§ÁÉÍÑÓ×ÚÜáéíñóúü] ?)*[!-~£§ÁÉÍÑÓ×ÚÜáéíñóúü]$ local_distribution: type: string format: decimal description: The gross distribution reported to the locality, in US dollars. pattern: ^[0-9]+(\.[0-9]{2})?$ special_data_entries: type: string description: Free text a state requires alongside the amounts. The IRS neither validates nor interprets it; it reaches the state named in `state` as given. maxLength: 60 pattern: ^([!-~£§ÁÉÍÑÓ×ÚÜáéíñóúü] ?)*[!-~£§ÁÉÍÑÓ×ÚÜáéíñóúü]$ required: - state Form1099PATR: type: object title: Form 1099-PATR description: | Taxable distributions received from cooperatives: what a cooperative paid a patron during the calendar year, together with the section 199A amounts and pass-through credits the patron needs to compute its own deduction. Filed by the cooperative (the PAYER block) for each patron paid at least $10 in patronage dividends and other distributions, or from whom any federal income tax was withheld under the backup withholding rules regardless of amount. properties: patronage_dividends: type: string format: decimal description: Box 1. Patronage dividends paid in cash, qualified written notices of allocation (at stated dollar value) or other property, in US dollars. pattern: ^[0-9]+(\.[0-9]{2})?$ examples: - "1250.00" nonpatronage_distributions: type: string format: decimal description: Box 2. Nonpatronage distributions, in US dollars. Only a cooperative exempt under section 521 reports here; a non-exempt cooperative leaves it empty. pattern: ^[0-9]+(\.[0-9]{2})?$ per_unit_retain_allocations: type: string format: decimal description: Box 3. Per-unit retain allocations paid in cash, qualified per-unit retain certificates or other property, in US dollars. pattern: ^[0-9]+(\.[0-9]{2})?$ federal_income_tax_withheld: type: string format: decimal description: Box 4. Backup withholding, in US dollars — withheld because the patron gave no TIN or gave one the IRS has said is wrong. Any amount here obliges the cooperative to file the form regardless of the size of the distributions. pattern: ^[0-9]+(\.[0-9]{2})?$ redeemed_nonqualified_notices: type: string format: decimal description: Box 5. Amounts paid in redemption of nonqualified written notices of allocation and nonqualified per-unit retain certificates, in US dollars. pattern: ^[0-9]+(\.[0-9]{2})?$ section_199a_g_deduction: type: string format: decimal description: Box 6. The section 199A(g) deduction passed through to the patron, in US dollars. Only a Specified Cooperative can pass one through, so supply this only where `specified_cooperative` is true. pattern: ^[0-9]+(\.[0-9]{2})?$ section_199a_b_7_qualified_payments: type: string format: decimal description: Box 7. Qualified payments under section 199A(b)(7), in US dollars — the figure by which the patron must reduce its own section 199A(a) deduction. As with box 6, only a Specified Cooperative reports it, so supply it only where `specified_cooperative` is true. pattern: ^[0-9]+(\.[0-9]{2})?$ section_199a_a_qualified_items: type: string format: decimal description: Box 8. Qualified items of income, gain, deduction and loss from a trade or business that is not a specified service trade or business, in US dollars. pattern: ^[0-9]+(\.[0-9]{2})?$ section_199a_a_sstb_items: type: string format: decimal description: Box 9. Qualified items attributable to a specified service trade or business (an SSTB), in US dollars. Kept apart from box 8 because the patron's deduction for SSTB items phases out with taxable income. pattern: ^[0-9]+(\.[0-9]{2})?$ investment_credit: type: string format: decimal description: Box 10. Investment credit passed through to the patron, in US dollars. pattern: ^[0-9]+(\.[0-9]{2})?$ work_opportunity_credit: type: string format: decimal description: Box 11. Work opportunity credit passed through to the patron, in US dollars. pattern: ^[0-9]+(\.[0-9]{2})?$ empowerment_zone_credit: type: string format: decimal description: "Box 12, code A: empowerment zone employment credit (Form 8844) passed through to the patron, in US dollars." pattern: ^[0-9]+(\.[0-9]{2})?$ low_sulfur_diesel_fuel_production_credit: type: string format: decimal description: "Box 12, code B: low sulfur diesel fuel production credit (Form 8896), in US dollars." pattern: ^[0-9]+(\.[0-9]{2})?$ small_employer_health_insurance_premiums_credit: type: string format: decimal description: "Box 12, code C: credit for small employer health insurance premiums (Form 8941), in US dollars." pattern: ^[0-9]+(\.[0-9]{2})?$ employer_differential_wage_payments_credit: type: string format: decimal description: "Box 12, code D: credit for employer differential wage payments (Form 8932), in US dollars." pattern: ^[0-9]+(\.[0-9]{2})?$ epa_sulfur_regulations_deduction: type: string format: decimal description: 'Box 12, code E: the deduction for capital costs a small refiner cooperative incurred in complying with EPA sulfur regulations, in US dollars. This one is a deduction rather than a credit, which is why the box is titled "Other credits and deductions".' pattern: ^[0-9]+(\.[0-9]{2})?$ biodiesel_and_renewable_diesel_fuels_credit: type: string format: decimal description: "Box 12, code F: biodiesel, renewable diesel and sustainable aviation fuels credit (Form 8864), in US dollars." pattern: ^[0-9]+(\.[0-9]{2})?$ specified_cooperative: type: boolean description: Box 13. Whether the cooperative is a Specified Cooperative within the meaning of section 199A(g) — one that manufactures, produces, grows or extracts in whole or significant part any agricultural or horticultural product, or markets such products for its patrons. Required. Must be true where box 6 or box 7 carries an amount. account_number: type: string description: The cooperative's own account number for this patron, printed beneath the recipient block as "Account number (see instructions)". A field of the form rather than of the patron, who can hold more than one account with the cooperative. A cooperative issuing more than one 1099-PATR against the same TIN for the year must give each form a distinct account number. maxLength: 30 examples: - 4471902-01 second_tin_notice: type: boolean description: The "2nd TIN not." box. True where the IRS has twice within three calendar years notified the cooperative that this patron's TIN is wrong, which stops further notices for it. Defaults to `Recipient.tin.second_notice`. state_and_local_taxes: type: array description: "State and local reporting for this form: withholding, the income or distribution the state taxed, and the locality. Nothing here prints on the federal copies — the paper 1099-PATR has no state boxes — but the figures are what a state receives under the Combined Federal/State Filing program. One entry per state, or per locality within a state." items: $ref: "#/components/schemas/Form1099PATRStateLocalTax" combined_federal_state_filing_states: type: array description: "The states this form is to be forwarded to under the Combined Federal/State Filing program. Each must be a participating state: AL, AZ, AR, CA, CT, CO, DC, DE, GA, HI, ID, IN, KS, LA, MA, MD, ME, MI, MN, MS, MT, NE, NJ, NM, NC, ND, OH, OK, OR, PA, RI, SC, WI. A state named here that does not take part in the program receives nothing." items: $ref: "#/components/schemas/StateCode" filer_office_code: type: string description: Which of the cooperative's reporting offices this form belongs to, as a four-character code. Defaults to the filer's single office; set it only where the filer has more than one. minLength: 4 maxLength: 4 pattern: ^([!-~£§ÁÉÍÑÓ×ÚÜáéíñóúü] ?)*[!-~£§ÁÉÍÑÓ×ÚÜáéíñóúü]$ examples: - "0001" required: - specified_cooperative Form1099PATRBody: title: Form 1099-PATR allOf: - type: object properties: type: type: string const: 1099-PATR required: - type - $ref: "#/components/schemas/Form1099PATR" Form1099QDistributionSource: type: string title: Distribution source description: Box 5 — the programme the distribution came from. Exactly one applies. enum: - PRIVATE_QTP - STATE_QTP - COVERDELL_ESA x-enumDescriptions: PRIVATE_QTP: Box 5a — the distribution is from a QTP established by one or more private eligible educational institutions; checked instead of state QTP or Coverdell ESA. STATE_QTP: Box 5b — the distribution is from a QTP established by a state; checked instead of private QTP or Coverdell ESA. COVERDELL_ESA: Box 5c — checked when neither of the QTP boxes applies, meaning the distribution is from a Coverdell education savings account. Form1099QDistributionCode: type: string title: Distribution code description: What kind of distribution or withdrawal this was. Codes 2, 3 and 6 concern Coverdell ESAs only. enum: - DISTRIBUTIONS - EXCESS_CONTRIBUTIONS_CURRENT_YEAR - EXCESS_CONTRIBUTIONS_PRIOR_YEAR - DISABILITY - DEATH - PROHIBITED_TRANSACTION x-enumDescriptions: DISTRIBUTIONS: "`1` — distributions (including transfers) to the recipient and any direct payments to a qualified educational facility; not used for withdrawals of excess contributions." EXCESS_CONTRIBUTIONS_CURRENT_YEAR: "`2` — withdrawals of excess Coverdell ESA contributions and earnings taxable in the current year, unless code 3 applies." EXCESS_CONTRIBUTIONS_PRIOR_YEAR: "`3` — withdrawals of excess Coverdell ESA contributions whose earnings are taxable in the prior year in which the excess contributions were made." DISABILITY: "`4` — distributions made after the recipient became disabled within the meaning of section 72(m)(7)." DEATH: "`5` — payments to a decedent's beneficiary, including an estate." PROHIBITED_TRANSACTION: "`6` — prohibited transactions, under the rules of sections 408(e)(2) and 408(e)(4) as applied to a Coverdell ESA." Form1099Q: type: object title: Form 1099-Q description: | A distribution from a qualified tuition program (section 529) or a Coverdell education savings account (section 530). One of these is issued per distributee per account: where a QTP pays both the beneficiary and the account owner, that is two forms, and `account_number` is what tells the two apart. properties: gross_distribution: type: string format: decimal description: Box 1. The total distribution, including any amount rolled over or transferred, in US dollars. Required, and greater than zero — a form reporting nothing has no reason to exist. It must not exceed 999999999999999.99. pattern: ^[0-9]+(\.[0-9]{2})?$ examples: - "4250.00" earnings: type: string format: decimal description: "Box 2. The earnings part of `gross_distribution`, in US dollars. May be negative: a distribution taken at a loss is reported as a negative figure here. Omit it only where the filer is not required to compute earnings (see the Instructions for Forms 1099-Q); where it is supplied alongside `basis`, the two together must equal `gross_distribution`." pattern: ^-?[0-9]+(\.[0-9]{2})?$ examples: - "312.44" basis: type: string format: decimal description: Box 3. The contributions part of `gross_distribution`, in US dollars. When supplied it must equal `gross_distribution` minus `earnings`. pattern: ^[0-9]+(\.[0-9]{2})?$ examples: - "3937.56" trustee_to_trustee_transfer: type: boolean default: false description: Box 4. Whether the distribution was a trustee-to-trustee transfer, including a direct rollover between programs or a change of designated beneficiary. It must not be true at the same time as `qtp_to_roth_ira_transfer` — a transfer to a Roth IRA is reported by that box alone. qtp_to_roth_ira_transfer: type: boolean default: false description: Box 4's second checkbox. Whether the distribution was a direct trustee-to-trustee transfer from a QTP to the designated beneficiary's Roth IRA under section 529(c)(3)(E). Mutually exclusive with `trustee_to_trustee_transfer`. distribution_source: description: "Box 5. Which kind of programme the distribution came from. Required: exactly one of the three checkboxes applies." $ref: "#/components/schemas/Form1099QDistributionSource" recipient_not_designated_beneficiary: type: boolean default: false description: Box 6. Whether the recipient named on this form is someone other than the designated beneficiary — for instance the account owner, or a qualified educational institution paid directly. Leave false when the recipient is the beneficiary. distribution_code: description: The code describing what kind of distribution or withdrawal this was. Optional, and not printed on the paper form. $ref: "#/components/schemas/Form1099QDistributionCode" account_number: type: string description: The filer's account number for this recipient, printed above box 1. It names the account the distribution came from rather than the recipient. Give it a value whenever more than one 1099-Q is filed for the same recipient, where it must differ from the account number on the other forms. maxLength: 30 pattern: ^(([!-~£§ÁÉÍÑÓ×ÚÜáéíñóúü]) ?)*[!-~£§ÁÉÍÑÓ×ÚÜáéíñóúü]$ examples: - 529-0114872 filer_office_code: type: string description: The reporting office this form belongs to. Defaults to the filer's single office; supply it only for a filer with more than one entry in `Filer.offices`, and give the `code` of one of them. minLength: 4 maxLength: 4 examples: - "0001" required: - gross_distribution - distribution_source Form1099QBody: title: Form 1099-Q allOf: - type: object properties: type: type: string const: 1099-Q required: - type - $ref: "#/components/schemas/Form1099Q" Form1099QA: type: object title: Form 1099-QA description: | A distribution from an ABLE (Achieving a Better Life Experience) account under section 529A, reported by the qualified ABLE program for one calendar year. One instance is one form: one payer, one recipient, one account. A program that makes both an ordinary distribution and a program-to-program transfer for the same beneficiary files two forms, each carrying its own `account_number`. properties: gross_distribution: type: string format: decimal description: "Box 1. The total distributed from the ABLE account during the year, in US dollars, before any reduction for the basis in box 3. Required: it is the amount the form exists to report, and the earnings and basis boxes are meaningless without it. Never negative." pattern: ^[0-9]+(\.[0-9]{2})?$ examples: - "1250.00" earnings: type: string format: decimal description: Box 2. The earnings portion of box 1, in US dollars. This is the only signed amount on the form — an ABLE account can lose value, so a negative value down to -999999999999999.99 belongs here where boxes 1 and 3 never take one. Leave it unset rather than sending `0.00` where the program has not computed it. pattern: ^-?[0-9]+(\.[0-9]{2})?$ examples: - "150.00" basis: type: string format: decimal description: Box 3. The investment in the account allocable to box 1, in US dollars. It equals `gross_distribution` minus `earnings`. Never negative. pattern: ^[0-9]+(\.[0-9]{2})?$ examples: - "1100.00" program_to_program_transfer: type: boolean default: false description: Box 4. Whether the distribution was a trustee-to-trustee transfer to another qualified ABLE program, or to the same beneficiary's new account, rather than a distribution to the recipient. able_account_terminated: type: boolean default: false description: Box 5. Whether the ABLE account was terminated during the calendar year reported, which makes this the final return for the account. The paper box reads "Check if ABLE account terminated in the calendar year reported". recipient_not_designated_beneficiary: type: boolean default: false description: 'Box 6. Whether the recipient of the distribution is someone other than the designated beneficiary — for example the beneficiary''s estate after death. Copy B prints the consequence in full: "If this box is checked, the recipient is not the designated beneficiary."' account_number: type: string description: The payer's account number for this recipient, printed beneath the address block. A field of the form rather than of the recipient, since it names the ABLE account this distribution came from. Required where the payer files more than one 1099-QA against a single recipient TIN, and distinct on each of those forms. maxLength: 30 pattern: ^([!-~£§ÁÉÍÑÓ×ÚÜáéíñóúü] ?)*[!-~£§ÁÉÍÑÓ×ÚÜáéíñóúü]$ examples: - ABLE-88213 filer_office_code: type: string description: The reporting office this form belongs to. Defaults to the filer's single office; set it only for a filer with more than one entry in `offices`. Exactly four characters — a length, not a maximum. minLength: 4 maxLength: 4 pattern: ^([!-~£§ÁÉÍÑÓ×ÚÜáéíñóúü] ?)*[!-~£§ÁÉÍÑÓ×ÚÜáéíñóúü]$ examples: - "0001" required: - gross_distribution Form1099QABody: title: Form 1099-QA allOf: - type: object properties: type: type: string const: 1099-QA required: - type - $ref: "#/components/schemas/Form1099QA" Form1099RStateLocalTax: type: object title: Form 1099-R state and local tax description: One state's row of boxes 14-16, with the locality row of boxes 17-19 that goes with it. properties: state: description: "Box 15, first field. The state whose withholding this entry reports. Required: it is what identifies the row." $ref: "#/components/schemas/StateCode" state_id_number: type: string description: Box 15, second field — the payer's state number, printed as "State/Payer's state no.". Defaults to the filer's `state_registrations` entry for `state`; set it here only to override that. maxLength: 25 examples: - WA-4471902 state_tax_withheld: type: string format: decimal description: Box 14, in US dollars. pattern: ^[0-9]+(\.[0-9]{2})?$ state_income: type: string format: decimal description: State income, in US dollars. The 1099-R has no box for it — report the distribution in `state_distribution` instead. pattern: ^[0-9]+(\.[0-9]{2})?$ state_distribution: type: string format: decimal description: Box 16, in US dollars — the part of `gross_distribution` attributable to this state. pattern: ^[0-9]+(\.[0-9]{2})?$ local_tax_withheld: type: string format: decimal description: Box 17, in US dollars. pattern: ^[0-9]+(\.[0-9]{2})?$ local_income: type: string format: decimal description: Local income, in US dollars. As with `state_income`, the 1099-R prints no such box; use `local_distribution` for box 19. pattern: ^[0-9]+(\.[0-9]{2})?$ locality: type: string description: Box 18 — the name of the locality that withheld, in up to 20 characters. maxLength: 20 examples: - Cuyahoga County locality_code: type: string description: "The locality's abbreviation or code, where the locality uses one. It does not print: box 18 prints `locality`." maxLength: 10 local_distribution: type: string format: decimal description: Box 19, in US dollars — the part of the distribution attributable to this locality. pattern: ^[0-9]+(\.[0-9]{2})?$ special_data_entries: type: string description: Free text the state or locality asks the payer to carry alongside this row. A state that has no use for it ignores it. maxLength: 60 required: - state Form1099R: type: object title: Form 1099-R description: | One distribution reported to one recipient for one tax year. Boxes 1 through 13 are the federal amounts; boxes 14 through 19 are the state and local rows, carried in `state_and_local_taxes`. The taxable amount, the capital gain and the net unrealized appreciation must each be no greater than the gross distribution. properties: account_number: type: string description: 'The payer''s own account, policy or contract number for this recipient, printed as "Account number (see instructions)". It names the account or contract distributed from rather than the recipient, who can hold more than one. It stops being optional in two cases: when `fatca_filing_requirement` is true, and when the filer issues more than one 1099-R to the same recipient TIN, where each form must carry a distinct account number.' maxLength: 30 examples: - 4471902-01 gross_distribution: type: string format: decimal description: Box 1, in US dollars — the total distribution before any withholding, being the amount this form exists to report. Required. Enter `0.00` for a distribution of zero rather than omitting the box. pattern: ^[0-9]+(\.[0-9]{2})?$ examples: - "12500.00" taxable_amount: type: string format: decimal description: Box 2a, in US dollars. When nonzero, it must not exceed `gross_distribution`, and where `taxable_amount_not_determined` is true and `ira_sep_simple` is false it must not exceed zero. Leave it absent, rather than zero, where the payer genuinely has not determined it. pattern: ^[0-9]+(\.[0-9]{2})?$ taxable_amount_not_determined: type: boolean default: false description: "The left checkbox of box 2b: the payer was unable to determine the taxable amount. On a non-IRA distribution, do not set it while also reporting a positive `taxable_amount`." total_distribution: type: boolean default: false description: "The right checkbox of box 2b: this distribution closed out the account, so that the payer expects no further payments for the year." capital_gain: type: string format: decimal description: Box 3, in US dollars — the part of `taxable_amount` attributable to pre-1974 participation. Included in box 2a, not additional to it, and when nonzero it must not exceed `gross_distribution`. pattern: ^[0-9]+(\.[0-9]{2})?$ federal_income_tax_withheld: type: string format: decimal description: Box 4, in US dollars. pattern: ^[0-9]+(\.[0-9]{2})?$ employee_contributions: type: string format: decimal description: "Box 5, in US dollars. One box carries three unrelated values depending on the kind of payment: the employee's own contributions, designated Roth contributions recovered tax free, or insurance premiums." pattern: ^[0-9]+(\.[0-9]{2})?$ net_unrealized_appreciation: type: string format: decimal description: Box 6, in US dollars — net unrealized appreciation in the employer's securities distributed as part of a lump sum. When nonzero it must not exceed `gross_distribution`. pattern: ^[0-9]+(\.[0-9]{2})?$ distribution_code: type: string description: 'Box 7, exactly as printed: one distribution code, or one of the permitted two-code combinations. Required — it is the box that tells the IRS and the recipient how the distribution is taxed, and nothing else on the form supplies it. Send only the combinations enumerated here; see the "Guide to Distribution Codes" in the Instructions for Forms 1099-R and 5498 for the meaning of each code and which pairings are allowed.' enum: - "1" - "18" - 1B - 1D - 1K - 1L - 1M - 1P - "2" - "28" - 2B - 2D - 2K - 2L - 2M - 2P - "3" - 3D - "4" - "48" - 4A - 4B - 4D - 4G - 4H - 4K - 4L - 4M - 4P - "5" - "6" - 6W - "7" - 7A - 7B - 7D - 7K - 7L - 7M - "8" - "81" - "82" - "84" - 8B - 8J - 8K - "9" - A - A4 - A7 - B - B1 - B2 - B4 - B7 - B8 - BG - BL - BM - BP - BU - C - CD - D - D1 - D2 - D3 - D4 - D7 - DC - E - F - G - G4 - GB - GK - H - H4 - J - J8 - JP - JS - K - K1 - K2 - K4 - K7 - K8 - KG - L - L1 - L2 - L4 - L7 - LB - M - M1 - M2 - M4 - M7 - MB - "N" - P - P1 - P2 - P4 - PB - PJ - Q - R - S - SJ - T - U - UB - W - W6 - Y4 - Y7 - YK examples: - "7" ira_sep_simple: type: boolean default: false description: "The IRA/SEP/SIMPLE checkbox beside box 7: the distribution came from a traditional IRA, SEP or SIMPLE IRA rather than from a qualified plan. It changes how a zero taxable amount is read: the ceiling that `taxable_amount_not_determined` puts on `taxable_amount` applies only when this is false." other_distribution: type: string format: decimal description: Box 8, in US dollars — the value of an annuity contract or other property distributed as part of the payment. Not included in box 1 or box 2a. pattern: ^[0-9]+(\.[0-9]{2})?$ other_distribution_percentage: type: string format: decimal description: "The percentage field of box 8, expressed as a fraction between 0 and 1 with up to five decimal places: `0.4` is printed as 40%. The recipient's share of the annuity contract or other property reported in `other_distribution`." pattern: ^(0(\.[0-9]{1,5})?|1(\.0{1,5})?)$ examples: - "0.4" total_distribution_percentage: type: string format: decimal description: "Box 9a, expressed as a fraction between 0 and 1 with up to five decimal places: `0.25` is printed as 25%. The recipient's share where one total distribution is split among more than one person." pattern: ^(0(\.[0-9]{1,5})?|1(\.0{1,5})?)$ examples: - "0.25" total_employee_contributions: type: string format: decimal description: Box 9b, in US dollars — the recipient's total investment in the contract, not just the part recovered this year. Distinct from `employee_contributions`, which is the current year's box 5 figure. pattern: ^[0-9]+(\.[0-9]{2})?$ amount_allocable_to_irr: type: string format: decimal description: Box 10, in US dollars — the part of the distribution allocable to an in-plan Roth rollover made within the preceding five years. pattern: ^[0-9]+(\.[0-9]{2})?$ first_year_of_designated_roth_contribution: type: string description: Box 11 — the first year of the recipient's five-taxable-year period in a designated Roth account, as four digits. Relevant to distributions from such an account, which box 7 marks with code B or H. pattern: ^[1-9][0-9]{3}$ examples: - "2019" fatca_filing_requirement: type: boolean default: false description: "Box 12: the payer is a US payer satisfying its chapter 4 reporting requirement by filing this form. Setting it makes `account_number` mandatory." payment_date: type: string format: date description: Box 13 — the date of payment, supplied as `YYYY-MM-DD`. Used for reportable death benefits under section 6050Y, which box 7 marks with code C or D. state_and_local_taxes: type: array description: State and local withholding for this distribution — boxes 14 through 16 for the state and 17 through 19 for the locality. One entry per state; the paper form has room for two, and the amounts within each entry are distributions and the tax withheld from them, not income. items: $ref: "#/components/schemas/Form1099RStateLocalTax" filer_office_code: type: string description: The filer's reporting office this form belongs to. Defaults to the filer's single office; set it only where the filer has more than one and this form is not the default's. minLength: 4 maxLength: 4 examples: - "0001" combined_federal_state_filing_states: type: array description: "The states this form is forwarded to under the Combined Federal/State Filing Program. Each must be a participating state — AL, AZ, AR, CA, CT, CO, DC, DE, GA, HI, ID, IN, KS, LA, MA, MD, ME, MI, MN, MS, MT, NE, NJ, NM, NC, ND, OH, OK, OR, PA, RI, SC or WI. Electing a state does not itself report the state amounts: those belong in `state_and_local_taxes`." maxItems: 62 items: $ref: "#/components/schemas/StateCode" required: - gross_distribution - distribution_code Form1099RBody: title: Form 1099-R allOf: - type: object properties: type: type: string const: 1099-R required: - type - $ref: "#/components/schemas/Form1099R" Form1099S: type: object title: Form 1099-S description: | Proceeds from a real estate transaction: one closing, reported by the person responsible for closing it to the transferor who received the proceeds. A single form covers a single transferor's share of a single closing. Where a property is sold by more than one transferor, each gets their own form with their own share of the gross proceeds — the transaction is not split across boxes on one form. properties: closing_date: type: string format: date description: Box 1. The date of closing, which is the date title transferred or the economic burdens and benefits of ownership shifted to the transferee, whichever is earlier. Required, and it is the date that fixes which tax year the transaction falls in. Supply as `YYYY-MM-DD`. examples: - "2026-06-30" gross_proceeds: type: string format: decimal description: Box 2, in US dollars. The gross proceeds — the total cash received, plus notes payable to the transferor and any liability assumed or taken subject to — without reduction for the transferor's selling expenses. Non-negative, with a maximum of 999,999,999,999,999.99. Required whenever `property_or_services_received` is false. pattern: ^[0-9]+(\.[0-9]{2})?$ examples: - "425000.00" address_or_legal_description: type: string description: "Box 3. The address of the property transferred, including city, state and ZIP code, or — where the property has no address, as with unimproved land — a legal description such as section, lot and block. Required, as one line of at most 100 characters: a longer description has to be abbreviated to fit." maxLength: 100 pattern: ^(([!-~£§ÁÉÍÑÓ×ÚÜáéíñóúü] ?)*[!-~£§ÁÉÍÑÓ×ÚÜáéíñóúü])$ examples: - 876 Arch Rd Cary NC 27513 property_or_services_received: type: boolean description: Box 4. Whether the transferor received, or will receive, property or services as part of the consideration for the transaction. Required. If it is false, supply `gross_proceeds`. foreign_transferor: type: boolean description: Box 5. Whether the transferor is a foreign person — a nonresident alien, foreign partnership, foreign estate or foreign trust. Required. It is what tells the transferee that FIRPTA withholding under section 1445 can be due on the transaction, so a false value on a foreign transferor's form is a substantive error and not a cosmetic one. buyer_real_estate_tax: type: string format: decimal description: Box 6, in US dollars. The portion of any real estate tax charged to the buyer at settlement that covers the part of the year the seller still owned the property — the amount the seller must treat as a reduction of their own real estate tax deduction. Non-negative, with a maximum of 999,999,999,999,999.99. Report it only for a sale or exchange of a residence. pattern: ^[0-9]+(\.[0-9]{2})?$ examples: - "1842.17" account_number: type: string description: The filer's own account number for this transferor, printed under the address block. It names the closing this form reports rather than the transferor, since one transferor can sell more than one property. A filer issuing more than one Form 1099-S against the same transferor TIN must give each form a distinct account number, which is the usual case for a multi-closing settlement agent. maxLength: 30 pattern: ^(([!-~£§ÁÉÍÑÓ×ÚÜáéíñóúü] ?)*[!-~£§ÁÉÍÑÓ×ÚÜáéíñóúü])$ examples: - 4471902-01 filer_office_code: type: string description: The reporting office this form belongs to, as its four-character office code. Defaults to the filer's single office; supply it only where the filer has more than one and this form belongs to other than the first. minLength: 4 maxLength: 4 pattern: ^(([!-~£§ÁÉÍÑÓ×ÚÜáéíñóúü] ?)*[!-~£§ÁÉÍÑÓ×ÚÜáéíñóúü])$ examples: - "0001" required: - closing_date - address_or_legal_description - property_or_services_received - foreign_transferor Form1099SBody: title: Form 1099-S allOf: - type: object properties: type: type: string const: 1099-S required: - type - $ref: "#/components/schemas/Form1099S" Form1099SADistributionCode: type: string title: Form 1099-SA distribution code enum: - NORMAL - EXCESS_CONTRIBUTIONS - DISABILITY - DEATH_DISTRIBUTION - PROHIBITED_TRANSACTION - DEATH_DISTRIBUTION_TO_NONSPOUSE_BENEFICIARY x-enumDescriptions: NORMAL: 1 — Normal distribution. Used for distributions to the account holder and direct payments to a medical service provider, and whenever no other code applies. EXCESS_CONTRIBUTIONS: 2 — Excess contributions. A distribution of excess HSA or Archer MSA contributions to the account holder. DISABILITY: 3 — Disability. Distributions made after the account holder became disabled within the meaning of section 72(m)(7). DEATH_DISTRIBUTION: 4 — Death distribution other than code 6. Payments to a decedent's estate in or after the year of death; not used together with code 6. PROHIBITED_TRANSACTION: 5 — Prohibited transaction, as described in sections 220(e)(2) and 223(e)(2). DEATH_DISTRIBUTION_TO_NONSPOUSE_BENEFICIARY: 6 — Death distribution after the year of death to a nonspouse beneficiary other than an estate; not used together with code 4. Form1099SAAccountType: type: string title: Form 1099-SA account type description: Which of the three checkboxes beside box 3 is checked. The instructions direct the filer to check exactly one. enum: - HSA - ARCHER_MSA - MA_MSA x-enumDescriptions: HSA: The distribution was from a health savings account. ARCHER_MSA: The distribution was from an Archer MSA. MA_MSA: The distribution was from a Medicare Advantage MSA. Form1099SA: type: object title: Form 1099-SA description: | A distribution from a health savings account, an Archer MSA or a Medicare Advantage MSA, reported by the trustee or custodian of the account. One form covers one account type and one distribution code: a trustee that made distributions of two kinds to one account holder files two forms, and sets `account_number` on each so that the pair can be told apart. properties: gross_distribution: type: string format: decimal description: Box 1. The total amount distributed from the account this year, in US dollars, including any earnings on excess contributions reported in box 2 and any amount paid directly to a medical service provider. Required, and must be non-zero — a form reporting nothing has no reason to exist — and must not be negative. pattern: ^[0-9]+(\.[0-9]{2})?$ examples: - "1450.00" earnings_on_excess_contributions: type: string format: decimal description: Box 2. The earnings on excess contributions withdrawn under section 223(f)(3) or 220(f)(3), in US dollars. Included in `gross_distribution`, and so must not exceed it. The value must not be negative. pattern: ^[0-9]+(\.[0-9]{2})?$ examples: - "37.15" distribution_code: description: "Box 3, the single code identifying the kind of distribution. Required. Codes 4 and 6 are mutually exclusive: use 6 only for a payment made after the year of death to a nonspouse beneficiary who is not an estate, and 4 for every other death distribution. Use 1 whenever no other code applies." $ref: "#/components/schemas/Form1099SADistributionCode" fair_market_value_on_date_of_death: type: string format: decimal description: Box 4. The fair market value of the account on the date the account holder died, in US dollars — reported only where the distribution is a death distribution (code 4 or 6). The value must not be negative. pattern: ^[0-9]+(\.[0-9]{2})?$ examples: - "8200.00" account_type: description: "The checkbox to the right of box 3 saying which kind of account the distribution came from. Required, and exclusive: exactly one of the three applies to any one distribution." $ref: "#/components/schemas/Form1099SAAccountType" account_number: type: string description: The trustee's own account number for this account holder, printed above box 1. It names the account distributed from rather than the holder, who can hold more than one. Where two forms are filed for one account holder, distinct account numbers are what keep them apart. maxLength: 30 pattern: ^(([!-~£§ÁÉÍÑÓ×ÚÜáéíñóúü]) ?)*[!-~£§ÁÉÍÑÓ×ÚÜáéíñóúü]$ examples: - HSA-4471902-01 filer_office_code: type: string description: The reporting office this form belongs to. Defaults to the filer's single office; supply it only where the filer has more than one and this form is not the default's. Exactly four characters. minLength: 4 maxLength: 4 examples: - "0001" required: - gross_distribution - distribution_code - account_type Form1099SABody: title: Form 1099-SA allOf: - type: object properties: type: type: string const: 1099-SA required: - type - $ref: "#/components/schemas/Form1099SA" Form1099SBIssuerContact: type: object title: Form 1099-SB issuer contact description: The name, address and telephone number of the person at the issuer whom the seller contacts for information about this form, where that differs from the issuer block printed at the top of the form. properties: name: type: string description: A whole name on one line, rather than the parts of one. maxLength: 35 pattern: ^([A-Za-z0-9'\-] ?)*[A-Za-z0-9'\-]$ examples: - Alice Brown address: $ref: "#/components/schemas/Address" phone_number: $ref: "#/components/schemas/PhoneNumber" Form1099SB: type: object title: Form 1099-SB description: | Seller's investment in a life insurance contract, reported by the issuer of the contract after it is notified of a reportable policy sale or of a transfer to a foreign person. One instance is one form: one contract, one seller. A filer that reports two policies for the same seller files two of these, and sets `account_number` on each so that the pair can be told apart. properties: policy_number: type: string description: The issuer's number for the life insurance contract sold, printed in the "Policy number" box above box 1. Required — a 1099-SB that does not say which policy it concerns cannot be matched to the 1099-LS the acquirer files for the same sale. maxLength: 30 pattern: ^([!-~£§ÁÉÍÑÓ×ÚÜáéíñóúü] ?)*[!-~£§ÁÉÍÑÓ×ÚÜáéíñóúü]$ examples: - LP-4471902 investment_in_contract: type: string format: decimal description: "Box 1, in US dollars: the seller's investment in the contract, being the aggregate premiums paid less amounts previously recovered tax-free, determined under section 6050Y(b)(1)(B). Non-negative, and no greater than 999999999999999.99. One of the two amounts is required, so supply this unless `surrender_amount` is given." pattern: ^[0-9]+(\.[0-9]{2})?$ examples: - "12500.00" surrender_amount: type: string format: decimal description: "Box 2, in US dollars: the amount the seller would have received had the contract been surrendered, reported where the issuer computed the seller's investment under the surrender-value rule. Non-negative, and no greater than 999999999999999.99. Supplying this alone meets the requirement that one of the two amounts be present; leaving both boxes empty does not." pattern: ^[0-9]+(\.[0-9]{2})?$ examples: - "9800.00" issuer_contact: description: The issuer's information contact, printed in the box below box 2 and required there only "if different from ISSUER". Omit it and the paper form prints the filer's own name, address and telephone number. $ref: "#/components/schemas/Form1099SBIssuerContact" account_number: type: string description: The filer's own account number for this seller — the policy account rather than the person, since one seller can sell interests in more than one contract. Required when the filer files more than one form against the same TIN, and distinct on each of those forms. maxLength: 30 examples: - 4471902-01 filer_office_code: type: string description: Which of the filer's reporting offices issued this form. Defaults to the filer's single office; set it only for a filer that reports through more than one. Exactly four characters, as the IRS receives it. minLength: 4 maxLength: 4 examples: - "0001" required: - policy_number Form1099SBBody: title: Form 1099-SB allOf: - type: object properties: type: type: string const: 1099-SB required: - type - $ref: "#/components/schemas/Form1099SB" Form5498ESA: type: object title: Form 5498-ESA description: | Coverdell education savings account contribution information, reported by the trustee or issuer of the account to its designated beneficiary and to the IRS. Both amounts are optional individually, because a beneficiary can receive only a rollover or only cash contributions in the year — but a form reporting neither reports nothing, and the IRS expects at least one of box 1 and box 2 to carry a figure. Contributions and rollovers are reported separately and never in the same box: an amount rolled over from another Coverdell ESA or from a Qualified Tuition Program belongs in box 2 alone, and including it in box 1 as well overstates the beneficiary's contributions against the annual limit. The recipient of this form is the account's designated beneficiary, not the contributor — the person who put the money in is not reported anywhere on it. properties: coverdell_esa_contributions: type: string format: decimal description: Box 1. Contributions made to this Coverdell ESA between 1 January of the tax year and the following 15 April, in US dollars, excluding anything reported in box 2. Rollovers, trustee-to-trustee transfers and the earnings on returned excess contributions do not belong here. The IRS matches this figure against the $2,000 per-beneficiary annual limit across every Form 5498-ESA filed for the beneficiary, so a rollover misreported here can generate an excess contribution notice to a beneficiary who made none. pattern: ^[0-9]+(\.[0-9]{2})?$ examples: - "2000.00" rollover_contributions: type: string format: decimal description: Box 2. Amounts rolled over into this Coverdell ESA during the tax year, in US dollars — from another Coverdell ESA, or from a Qualified Tuition Program. Rollovers do not count against the annual contribution limit, which is why they are reported apart from box 1. pattern: ^[0-9]+(\.[0-9]{2})?$ examples: - "1500.00" account_number: type: string description: The trustee's or issuer's own number for this account, printed under "Account number (see instructions)". It names the Coverdell ESA rather than the beneficiary, who can hold two at one trustee and then receives two forms. Each Form 5498-ESA issued to the same beneficiary must carry a distinct account number. maxLength: 30 pattern: ^(([!-~£§ÁÉÍÑÓ×ÚÜáéíñóúü] ?)*[!-~£§ÁÉÍÑÓ×ÚÜáéíñóúü])$ examples: - 4471902-01 filer_office_code: type: string description: The filer's reporting office for this form. Defaults to the filer's single office; supply it only for a filer with more than one, to say which of them issued the account. Exactly four characters — a length, not a maximum. Not printed on the paper form. minLength: 4 maxLength: 4 pattern: ^(([!-~£§ÁÉÍÑÓ×ÚÜáéíñóúü] ?)*[!-~£§ÁÉÍÑÓ×ÚÜáéíñóúü])$ examples: - "0001" Form5498ESABody: title: Form 5498-ESA allOf: - type: object properties: type: type: string const: 5498-ESA required: - type - $ref: "#/components/schemas/Form5498ESA" Form5498QA: type: object title: Form 5498-QA description: | ABLE account contribution information for one designated beneficiary, for one ABLE account, for the tax year. Amounts are contributions *received* by the programme during the year, not distributions; distributions from the same account are reported on Form 1099-QA. properties: able_contributions: type: string format: decimal description: Box 1. Contributions, including those from a section 529 programme rollover, made to this ABLE account for the year, in US dollars. Excludes ABLE-to-ABLE rollovers, which go in box 2. Never negative. pattern: ^[0-9]+(\.[0-9]{2})?$ examples: - "17000.00" able_to_able_rollovers: type: string format: decimal description: Box 2. Amounts rolled over from another ABLE account into this one during the year, in US dollars. Reported apart from box 1 because a rollover does not count against the annual contribution limit. Never negative. pattern: ^[0-9]+(\.[0-9]{2})?$ cumulative_contributions: type: string format: decimal description: Box 3. Total contributions made to this ABLE account since it was established, in US dollars — a running figure across all years, not just this one. Never negative. pattern: ^[0-9]+(\.[0-9]{2})?$ fair_market_value: type: string format: decimal description: Box 4. The value of the ABLE account on the last day of the tax year, in US dollars. Never negative. pattern: ^[0-9]+(\.[0-9]{2})?$ account_opened_this_year: type: boolean description: 'Box 5, "Check if account opened in" the tax year — true where the ABLE account was established during the tax year being reported, false where it already existed. Required: `false` is the answer for an account carried over from an earlier year, not a way of leaving the box unanswered.' basis_of_eligibility: type: string description: Box 6. Which route establishes the designated beneficiary's eligibility for an ABLE account under section 529A(e)(1). Required. enum: - SSDI_TITLE_II - SSI_TITLE_XVI - DISABILITY_CERTIFICATION x-enumDescriptions: SSDI_TITLE_II: "`A` — Eligibility established under section 529A(e)(1)(A), SSDI, Title II SSA." SSI_TITLE_XVI: "`B` — Eligibility established under section 529A(e)(1)(A), SSI, Title XVI SSA." DISABILITY_CERTIFICATION: "`C` — The designated beneficiary is the subject of a disability certification filed with the IRS in the current filing year." disability_type: type: string description: Box 7. The category of the beneficiary's condition, from the seven-way table in the instructions for Form 5498-QA. Required. Use `OTHER` where the condition appears in none of the six named groups. enum: - DEVELOPMENTAL_DISORDERS - INTELLECTUAL_DISABILITY - PSYCHIATRIC_DISORDERS - NERVOUS_DISORDERS - CONGENITAL_ANOMALIES - RESPIRATORY_DISORDERS - OTHER x-enumDescriptions: DEVELOPMENTAL_DISORDERS: "`1` — Developmental disorders: autistic spectrum disorder, Asperger's disorder, developmental delays, and learning disabilities." INTELLECTUAL_DISABILITY: "`2` — Intellectual disability, which may be mild, moderate, or severe." PSYCHIATRIC_DISORDERS: "`3` — Psychiatric disorders: schizophrenia, major depressive disorder, PTSD, anorexia nervosa, AD/HD, bipolar disorder." NERVOUS_DISORDERS: "`4` — Nervous disorders: blindness, deafness, cerebral palsy, muscular dystrophy, spina bifida, juvenile-onset Huntington's disease, multiple sclerosis, severe sensorineural hearing loss, congenital cataracts." CONGENITAL_ANOMALIES: "`5` — Congenital anomalies: chromosomal abnormalities including Down syndrome, osteogenesis imperfecta, xeroderma pigmentosum, spinal muscular atrophy, fragile X syndrome, Edwards syndrome." RESPIRATORY_DISORDERS: "`6` — Respiratory disorders, such as cystic fibrosis." OTHER: "`7` — Other conditions, including tetralogy of Fallot, hypoplastic left heart syndrome, and end-stage liver disease." account_number: type: string description: The programme's own account number for this beneficiary, printed above box 1 as "Account number (see instructions)". A field of the form rather than of the beneficiary, since it names the ABLE account. Supply one where the same beneficiary receives more than one Form 5498-QA from this filer, and give each of those forms a different number. maxLength: 30 examples: - 4471902-01 filer_office_code: type: string description: The reporting office this form belongs to, matching one of the filer's `offices`. Defaults to the filer's single office; supply it only where the filer reports through more than one. minLength: 4 maxLength: 4 examples: - "0001" required: - account_opened_this_year - basis_of_eligibility - disability_type Form5498QABody: title: Form 5498-QA allOf: - type: object properties: type: type: string const: 5498-QA required: - type - $ref: "#/components/schemas/Form5498QA" Form5498SA: type: object title: Form 5498-SA description: | Contributions to, and the year-end value of, one health savings account, Archer medical savings account or Medicare Advantage MSA, reported by the trustee or custodian that maintains it. One instance is one form: one participant, one account. A trustee that maintains two accounts of the same kind for one participant files one form per account and sets a distinct `account_number` on each, so that the two forms can be told apart. properties: archer_msa_contributions: type: string format: decimal description: Box 1. Archer MSA contributions the employee or self-employed person made during the tax year and, for the tax year, up to 15 April of the following year, in US dollars. Employer contributions belong in box 2, not here; contributions to an HSA are never reported in this box. pattern: ^[0-9]+(\.[0-9]{2})?$ examples: - "1200.00" total_contributions: type: string format: decimal description: Box 2. Every contribution to this account received during the calendar year of the tax year, in US dollars, regardless of the year it was made for and of who made it — employee, employer, self-employed person or, for an HSA, a third party. A contribution made during the tax year for the prior year is counted here and not in box 3. pattern: ^[0-9]+(\.[0-9]{2})?$ examples: - "4300.00" contributions_made_after_year_end: type: string format: decimal description: Box 3. HSA or Archer MSA contributions received after the end of the tax year and designated for it, in US dollars — the contribution-year window that closes on the return due date. pattern: ^[0-9]+(\.[0-9]{2})?$ examples: - "800.00" rollover_contributions: type: string format: decimal description: Box 4. Amounts rolled over into this account from another Archer MSA or HSA, in US dollars. A rollover is not a contribution for the annual limit and must not also appear in box 2. pattern: ^[0-9]+(\.[0-9]{2})?$ fair_market_value: type: string format: decimal description: "Box 5. The value of the account on 31 December of the tax year, in US dollars. Required: the trustee reports it on every Form 5498-SA, including one filed for an account that received no contributions, in which case send the balance — or `0.00` — rather than omitting the box. The IRS uses it to check the participant's Form 8889 or 8853, so an understated value surfaces there." pattern: ^[0-9]+(\.[0-9]{2})?$ examples: - "10432.55" account_type: type: string description: "Which kind of account this form reports — the HSA, Archer MSA and MA MSA checkboxes at the foot of the form, of which exactly one is checked. Required: it selects between three mutually exclusive treatments, and the boxes the IRS expects to be filled differ by kind (box 1 is Archer-MSA-only; an MA MSA takes neither contributions nor rollovers, only a box 5 value)." enum: - HSA - ARCHER_MSA - MA_MSA x-enumDescriptions: HSA: HSAInd = 1. The account is a health savings account. ARCHER_MSA: ArcherMSAInd = 1. The account is an Archer medical savings account. MA_MSA: MAMSAInd = 1. The account is a Medicare Advantage MSA. account_number: type: string description: The trustee's own number for this account, printed in the "Account number" block. It names the account rather than the participant, who can hold more than one. This field is optional; Nutshell recommends setting it where one participant holds more than one account with the same trustee, so that each form identifies its own account. maxLength: 30 pattern: ^([!-~£§ÁÉÍÑÓ×ÚÜáéíñóúü] ?)*[!-~£§ÁÉÍÑÓ×ÚÜáéíñóúü]$ examples: - HSA-4471902-01 filer_office_code: type: string description: The reporting office this form belongs to. Defaults to the filer's single office; supply it only where the filer has more than one. Exactly four characters. minLength: 4 maxLength: 4 examples: - "0001" required: - fair_market_value - account_type Form5498SABody: title: Form 5498-SA allOf: - type: object properties: type: type: string const: 5498-SA required: - type - $ref: "#/components/schemas/Form5498SA" FormW2GStateLocalTax: type: object title: Form W-2G state and local tax description: One state's winnings and withholding, with the locality within it. All amounts are decimal strings in US dollars and must not be negative. properties: state: description: "The state half of box 13: the state whose withholding is reported." $ref: "#/components/schemas/StateCode" state_id_number: type: string description: "The payer's half of box 13: its withholding registration number in this state. Defaults to the filer's `state_registrations` entry for `state`; set it here only to override that." maxLength: 25 pattern: ^([!-~£§ÁÉÍÑÓ×ÚÜáéíñóúü] ?)*[!-~£§ÁÉÍÑÓ×ÚÜáéíñóúü]$ state_tax_withheld: type: string format: decimal description: Box 15. State income tax withheld from these winnings. pattern: ^[0-9]+(\.[0-9]{2})?$ state_income: type: string format: decimal description: Box 14. The portion of the box 1 winnings reportable to this state. pattern: ^[0-9]+(\.[0-9]{2})?$ state_distribution: type: string format: decimal description: Not used on Form W-2G, which reports winnings rather than distributions. Supply `state_income` for box 14. pattern: ^[0-9]+(\.[0-9]{2})?$ local_tax_withheld: type: string format: decimal description: Box 17. Local income tax withheld from these winnings. pattern: ^[0-9]+(\.[0-9]{2})?$ local_income: type: string format: decimal description: Box 16. The portion of the box 1 winnings reportable to the locality named in `locality`. pattern: ^[0-9]+(\.[0-9]{2})?$ locality: type: string description: Box 18. The name of the locality withholding the box 17 tax. maxLength: 20 pattern: ^([!-~£§ÁÉÍÑÓ×ÚÜáéíñóúü] ?)*[!-~£§ÁÉÍÑÓ×ÚÜáéíñóúü]$ examples: - Yonkers locality_code: type: string description: "The locality's own abbreviation or code, where the jurisdiction issues one. It does not print: box 18 carries only the name." maxLength: 10 pattern: ^([!-~£§ÁÉÍÑÓ×ÚÜáéíñóúü] ?)*[!-~£§ÁÉÍÑÓ×ÚÜáéíñóúü]$ local_distribution: type: string format: decimal description: The local counterpart of `state_distribution`, and likewise not used on Form W-2G. Supply `local_income` for box 16. pattern: ^[0-9]+(\.[0-9]{2})?$ special_data_entries: type: string description: Free text the payer passes through to the state or local authority. Not printed on Copy A. maxLength: 60 pattern: ^([!-~£§ÁÉÍÑÓ×ÚÜáéíñóúü] ?)*[!-~£§ÁÉÍÑÓ×ÚÜáéíñóúü]$ required: - state FormW2G: type: object title: Form W-2G description: | One Form W-2G: one reportable gambling winning paid to one winner. A separate form is filed for each winning transaction, not one per winner per year, so a payer that pays the same person twice files twice. Where more than one form is filed for the same winner's TIN, each one needs an `account_number` distinct from the others. properties: reportable_winnings: type: string format: decimal description: Box 1. Gross winnings from this transaction, before any withholding, in US dollars. For a poker tournament this is the amount won less the amount of the wager or buy-in. Required, and never negative. pattern: ^[0-9]+(\.[0-9]{2})?$ examples: - "4750.00" date_won: type: string format: date description: Box 2, where it prints as MM/DD/YYYY. The date of the winning transaction or event, not the date the payment was made; for a wager that pays out over years, the date of the original win. For a winning from a session of bingo, keno or slot machines, the date of the session. Required, as `YYYY-MM-DD`. examples: - "2026-11-14" type_of_wager: type: string description: Box 3, where the payer writes the kind of gambling in words. Required. The choice governs which of `transaction` and `race` is filled in — see those properties. enum: - HORSE_RACE_TRACK - DOG_RACE_TRACK - JAI_ALAI - STATE_CONDUCTED_LOTTERY - KENO - BINGO - SLOT_MACHINES - POKER_WINNINGS - OTHER x-enumDescriptions: HORSE_RACE_TRACK: 1 — Horse race track. DOG_RACE_TRACK: 2 — Dog race track. JAI_ALAI: 3 — Jai-alai. STATE_CONDUCTED_LOTTERY: 4 — State-conducted lottery. KENO: 5 — Keno. BINGO: 6 — Bingo. SLOT_MACHINES: 7 — Slot machines. POKER_WINNINGS: 8 — Poker winnings. OTHER: 9 — Any other type of gambling winnings. federal_income_tax_withheld: type: string format: decimal description: "Box 4. Federal income tax withheld from these winnings, in US dollars: regular gambling withholding at 24%, or backup withholding at 24% where the winner did not furnish a TIN. Never negative." pattern: ^[0-9]+(\.[0-9]{2})?$ examples: - "1140.00" transaction: type: string description: Box 5. The ticket number, machine serial number or other number identifying the winning transaction. Used for sweepstakes, wagering pools, lotteries, bingo, keno, slot machines and poker tournaments; for a poker tournament, the name of the tournament and its sponsor. Leave empty where `race` applies instead. maxLength: 20 pattern: ^([!-~£§ÁÉÍÑÓ×ÚÜáéíñóúü] ?)*[!-~£§ÁÉÍÑÓ×ÚÜáéíñóúü]$ examples: - Machine 4471-902 race: type: string description: Box 6. The race or game the winning ticket was on. Used for horse racing, dog racing, jai alai and other wagering transactions. Leave empty where `transaction` applies instead. maxLength: 20 pattern: ^([!-~£§ÁÉÍÑÓ×ÚÜáéíñóúü] ?)*[!-~£§ÁÉÍÑÓ×ÚÜáéíñóúü]$ examples: - Race 7 winnings_from_identical_wagers: type: string format: decimal description: Box 7. Additional winnings from identical wagers, in US dollars. Identical wagers are separate bets placed on the same outcome, whose winnings are aggregated to decide whether the reporting and withholding thresholds are met. This box carries the winnings from the other identical wagers, over and above the amount in box 1. Never negative. pattern: ^[0-9]+(\.[0-9]{2})?$ cashier: type: string description: Box 8. The number of the cashier who made the winning payment. maxLength: 20 pattern: ^([!-~£§ÁÉÍÑÓ×ÚÜáéíñóúü] ?)*[!-~£§ÁÉÍÑÓ×ÚÜáéíñóúü]$ window: type: string description: Box 10. The number of the window or booth at which the winning payment was made. maxLength: 20 pattern: ^([!-~£§ÁÉÍÑÓ×ÚÜáéíñóúü] ?)*[!-~£§ÁÉÍÑÓ×ÚÜáéíñóúü]$ first_identification_number: type: string description: Box 11. The number of the identification document the payer inspected to verify the winner's name, address and TIN — such as a driver's licence, passport or social security card, recorded with the kind of document and the state or authority that issued it. Not the winner's TIN, which comes from the recipient. maxLength: 40 pattern: ^([!-~£§ÁÉÍÑÓ×ÚÜáéíñóúü] ?)*[!-~£§ÁÉÍÑÓ×ÚÜáéíñóúü]$ examples: - NC DL 34567890 second_identification_number: type: string description: Box 12. A second identification document, inspected and recorded the same way. maxLength: 40 pattern: ^([!-~£§ÁÉÍÑÓ×ÚÜáéíñóúü] ?)*[!-~£§ÁÉÍÑÓ×ÚÜáéíñóúü]$ state_and_local_taxes: type: array description: Boxes 13 through 18. State and local reporting for these winnings. The paper form has room for two entries; supply as many as apply. items: $ref: "#/components/schemas/FormW2GStateLocalTax" account_number: type: string description: The payer's own account number for this winner. Form W-2G has no account-number box, so it does not print on the winner's copy; it names the transaction this form reports rather than the winner, who can be paid more than once. Required where the payer files more than one W-2G for the same winner's TIN, and then distinct on each form. maxLength: 30 pattern: ^([!-~£§ÁÉÍÑÓ×ÚÜáéíñóúü] ?)*[!-~£§ÁÉÍÑÓ×ÚÜáéíñóúü]$ examples: - 4471902-01 filer_office_code: type: string description: Which of the payer's reporting offices this form belongs to. Defaults to the filer's single office; set it only where the filer has more than one. Exactly four characters. minLength: 4 maxLength: 4 pattern: ^([!-~£§ÁÉÍÑÓ×ÚÜáéíñóúü] ?)*[!-~£§ÁÉÍÑÓ×ÚÜáéíñóúü]$ examples: - "0001" required: - reportable_winnings - date_won - type_of_wager FormW2GBody: title: Form W-2G allOf: - type: object properties: type: type: string const: W-2G required: - type - $ref: "#/components/schemas/FormW2G" FormBody: description: | The boxes of one IRS form: what a client sends in addition to the filer and the recipient already on file. `type` names which of the thirty-five forms the rest of the object is. Form 8809, the application for an extension of time to file, is not among them: it is the filer asking on its own behalf and has no recipient to be issued to. oneOf: - $ref: "#/components/schemas/Form1042SBody" - $ref: "#/components/schemas/Form1097BTCBody" - $ref: "#/components/schemas/Form1098Body" - $ref: "#/components/schemas/Form1098CBody" - $ref: "#/components/schemas/Form1098EBody" - $ref: "#/components/schemas/Form1098FBody" - $ref: "#/components/schemas/Form1098QBody" - $ref: "#/components/schemas/Form1098TBody" - $ref: "#/components/schemas/Form1099ABody" - $ref: "#/components/schemas/Form1099BBody" - $ref: "#/components/schemas/Form1099CBody" - $ref: "#/components/schemas/Form1099CAPBody" - $ref: "#/components/schemas/Form1099DABody" - $ref: "#/components/schemas/Form1099DIVBody" - $ref: "#/components/schemas/Form1099INTBody" - $ref: "#/components/schemas/Form1099KBody" - $ref: "#/components/schemas/Form1099LSBody" - $ref: "#/components/schemas/Form1099LTCBody" - $ref: "#/components/schemas/Form1099MISCBody" - $ref: "#/components/schemas/Form1099NECBody" - $ref: "#/components/schemas/Form1099OIDBody" - $ref: "#/components/schemas/Form1099PATRBody" - $ref: "#/components/schemas/Form1099QBody" - $ref: "#/components/schemas/Form1099QABody" - $ref: "#/components/schemas/Form1099RBody" - $ref: "#/components/schemas/Form1099SBody" - $ref: "#/components/schemas/Form1099SABody" - $ref: "#/components/schemas/Form1099SBBody" - $ref: "#/components/schemas/Form3921Body" - $ref: "#/components/schemas/Form3922Body" - $ref: "#/components/schemas/Form5498Body" - $ref: "#/components/schemas/Form5498ESABody" - $ref: "#/components/schemas/Form5498QABody" - $ref: "#/components/schemas/Form5498SABody" - $ref: "#/components/schemas/FormW2GBody" discriminator: propertyName: type mapping: "1098": "#/components/schemas/Form1098Body" "3921": "#/components/schemas/Form3921Body" "3922": "#/components/schemas/Form3922Body" "5498": "#/components/schemas/Form5498Body" 1042-S: "#/components/schemas/Form1042SBody" 1097-BTC: "#/components/schemas/Form1097BTCBody" 1098-C: "#/components/schemas/Form1098CBody" 1098-E: "#/components/schemas/Form1098EBody" 1098-F: "#/components/schemas/Form1098FBody" 1098-Q: "#/components/schemas/Form1098QBody" 1098-T: "#/components/schemas/Form1098TBody" 1099-A: "#/components/schemas/Form1099ABody" 1099-B: "#/components/schemas/Form1099BBody" 1099-C: "#/components/schemas/Form1099CBody" 1099-CAP: "#/components/schemas/Form1099CAPBody" 1099-DA: "#/components/schemas/Form1099DABody" 1099-DIV: "#/components/schemas/Form1099DIVBody" 1099-INT: "#/components/schemas/Form1099INTBody" 1099-K: "#/components/schemas/Form1099KBody" 1099-LS: "#/components/schemas/Form1099LSBody" 1099-LTC: "#/components/schemas/Form1099LTCBody" 1099-MISC: "#/components/schemas/Form1099MISCBody" 1099-NEC: "#/components/schemas/Form1099NECBody" 1099-OID: "#/components/schemas/Form1099OIDBody" 1099-PATR: "#/components/schemas/Form1099PATRBody" 1099-Q: "#/components/schemas/Form1099QBody" 1099-QA: "#/components/schemas/Form1099QABody" 1099-R: "#/components/schemas/Form1099RBody" 1099-S: "#/components/schemas/Form1099SBody" 1099-SA: "#/components/schemas/Form1099SABody" 1099-SB: "#/components/schemas/Form1099SBBody" 5498-ESA: "#/components/schemas/Form5498ESABody" 5498-QA: "#/components/schemas/Form5498QABody" 5498-SA: "#/components/schemas/Form5498SABody" W-2G: "#/components/schemas/FormW2GBody" FormInput: type: object title: Form (writable fields) description: | One IRS form issued by the filer to the recipient it is nested under. Everything the printed form takes from the two parties — the payer block, the recipient's name, TIN and address — comes from those resources rather than from here. What `data` holds is the rest: the boxes of that particular form, and the account number, which belongs to the account this form reports rather than to the recipient holding it. properties: id: description: | Optional. The client may supply its own identifier for the form at creation — a value from the client's own identifier space, such as the number of the account or invoice the form reports — and every later request then addresses the form by it, with no table on the client's side mapping its identifiers to Nutshell's. Where the client omits it, the server uses the form's server-assigned `entity_id` as its `id`. It must be unique across all of the client's forms — under every filer and recipient, not merely this one's — and one already in use is a `409`. It is fixed at creation: an update that supplies a different one is a `409` as well, and an update that omits it leaves the identifier alone. $ref: "#/components/schemas/ResourceId" examples: - inv-2026-000417 tax_year: type: integer const: 2026 description: The tax year the form reports. 2026 is the only year served and any other value is a `400`. It is settled when the form is created — a return for another year is another return — and support for later years widens this rather than moving it. data: description: The form itself, tagged by `type` with which of the thirty-five forms it is. $ref: "#/components/schemas/FormBody" _client: $ref: "#/components/schemas/ClientAttributes" required: - tax_year - data FilingStatus: type: string title: Filing status readOnly: true description: | Where one filing of the form stands. A form has a federal filing and any number of state filings, and each carries its own status: `prepareSnapshot` and `filings/submit` move all of them, but validation and the authorities' responses arrive per filing, so they need not move together. Every status describes the filing of the input in that resource generation. An update that changes `data` resets the current version to `AWAITING_PREPARATION`; earlier generations keep their own filing statuses in `history`. To correct a filing, update the form, then prepare and submit again. enum: - AWAITING_PREPARATION - PREPARING - AWAITING_FILING - SUBMITTING - FILED - AWAITING_CORRECTION x-enumDescriptions: AWAITING_PREPARATION: No filing has been prepared from the form as it now stands. Every filing starts here, and an update to `data` returns it here. PREPARING: A `prepareSnapshot` operation is building this filing. AWAITING_FILING: A filing prepared from the form as it now stands awaits `filings/submit`. A later `prepareSnapshot` may discard and rebuild it; unchanged input may be a no-op. SUBMITTING: A `filings/submit` operation is sending this filing to the taxing authority. FILED: "The filing has been submitted to the taxing authority. Submission is not acceptance: the authority's response arrives afterwards, and one that names errors writes them to `problems` and moves the filing to `AWAITING_CORRECTION`." AWAITING_CORRECTION: Errors stand against this filing in the form's `problems`, found by preparation or returned by the taxing authority. The client resolves them by updating the form, which returns every filing to `AWAITING_PREPARATION`, and then prepares and submits again. examples: - AWAITING_PREPARATION StateFiling: type: object title: State filing readOnly: true description: One state's filing of the form. The server derives which states a form files to from its `data`, so the entries are not written by the client, and each moves through the same statuses the federal filing does — independently, since one state's validation or response says nothing about another's. properties: state: description: The state this filing goes to. $ref: "#/components/schemas/StateCode" status: description: Where this state's filing stands. $ref: "#/components/schemas/FilingStatus" required: - state - status FormProblem: type: object title: Form problem readOnly: true description: | One warning or error standing against the form, in the vocabulary of [RFC 9457](https://datatracker.ietf.org/doc/html/rfc9457): a `type` code identifying the kind of problem, a `title` naming it, and a `detail` specific to this occurrence. It differs from the `Problem` an error response carries in two ways, both because it is a field of a resource rather than a response: it has no HTTP `status`, and it has a `severity`, which is what the filing lifecycle turns on. Preparation writes problems as it validates, replacing what an earlier run wrote; the taxing authorities write them after submission. An update that changes the form's `data` empties the array. properties: type: type: string description: A code identifying the problem type. examples: - recipient-tin-mismatch title: type: string description: A short summary of the problem type. examples: - Recipient TIN does not match IRS records detail: type: string description: A human-readable explanation specific to this occurrence. examples: - The IRS reports no match for the recipient's TIN and name. severity: type: string description: What the problem does to the filing it stands against. An `ERROR` blocks that filing; a `WARNING` does not. enum: - ERROR - WARNING x-enumDescriptions: ERROR: Blocks the filing it stands against, which sits in `AWAITING_CORRECTION` until the form is updated. WARNING: Blocks nothing. The filing proceeds, and the warning remains readable here until the form is updated. examples: - ERROR jurisdiction: type: string description: "The filing the problem stands against: `FEDERAL`, or the two-letter code of a state in `state_filings`. Absent when the problem stands against the form as a whole, in which case an `ERROR` holds every filing." examples: - FEDERAL pointer: type: string description: An [RFC 6901](https://datatracker.ietf.org/doc/html/rfc6901) JSON Pointer to the field the problem arises from, present when it arises from one field. It is relative to the form resource, so a pointer into the boxes begins with `/data`. examples: - /data/account_number required: - type - title - severity Form: allOf: - $ref: "#/components/schemas/FormInput" - type: object properties: generation: $ref: "#/components/schemas/Generation" entity_id: description: The identifier the server assigns the form at creation. Where the client supplies no `id`, this is the form's `id` as well. $ref: "#/components/schemas/EntityId" filer_id: type: string readOnly: true description: The `id` of the filer that issues this form. examples: - acme-payroll-west recipient_id: type: string readOnly: true description: The `id` of the recipient this form is issued to. examples: - "8827" federal_filing_status: description: Where the federal filing of this form stands. `prepareSnapshot` and `filings/submit` move it, and an update that changes `data` returns it to `AWAITING_PREPARATION`. $ref: "#/components/schemas/FilingStatus" state_filings: type: array readOnly: true description: The form's state filings, one entry per state, each carrying its own status. The server derives the entries from `data` — a form reports to the states its state boxes name — so the array is empty where the form names none, and an update that changes `data` re-derives it, every entry starting again at `AWAITING_PREPARATION`. items: $ref: "#/components/schemas/StateFiling" problems: type: array readOnly: true description: The warnings and errors standing against the form, written by `prepareSnapshot` as it validates and by the taxing authorities after submission; empty when nothing stands against it. An `ERROR` holds the filing it names in `AWAITING_CORRECTION`; a `WARNING` accompanies a filing that proceeds. The client resolves problems by updating the form, which empties this array and returns every filing status to `AWAITING_PREPARATION`. items: $ref: "#/components/schemas/FormProblem" created_at: type: string format: date-time readOnly: true description: When the form was created. updated_at: type: string format: date-time readOnly: true description: "When the form last changed — by an update to `data` or to `_client`, or by a move of the filing lifecycle: a status transition, or a change to `problems`. An update that supplied what was already stored is not a change and does not move this, so a form never updated and never prepared carries its `created_at`." required: - generation - id - entity_id - filer_id - recipient_id - federal_filing_status - state_filings - problems - created_at - updated_at FormWithHistory: title: Form with history allOf: - $ref: "#/components/schemas/Form" - type: object properties: history: type: array readOnly: true description: | Earlier versions, newest generation first. Each entry contains the last input saved in that generation and its processing results. An empty array means the resource is at its first generation. items: $ref: "#/components/schemas/Form" required: - history FormPage: type: object title: Form Page properties: resources: type: array description: The forms in this page, which can be empty. items: $ref: "#/components/schemas/Form" next_page_token: $ref: "#/components/schemas/NextPageToken" required: - resources - next_page_token StatementId: type: string format: uuid title: Statement identifier description: The identifier the API assigns the statement when it builds it. It is unique across every filer, so it addresses one statement whichever of the two collections a client found it in, and the API never reuses it. examples: - 3e7c94a1-5b2d-4c6f-8a1e-d90b4f62c817 StatementKind: type: string title: Statement kind readOnly: true description: | Which kind of statement this is. A consolidated 1099 is a `SUBSTITUTE` statement. Every other statement is a `STANDARD` filled form. See `getStatementDocument` for available representations. enum: - STANDARD - SUBSTITUTE x-enumDescriptions: STANDARD: A filled form, available as a PDF. SUBSTITUTE: A consolidated 1099, available as a PDF, an archive, and JSON. examples: - STANDARD StatementStatus: type: string title: Statement status readOnly: true description: | The stage the statement has reached. There is no `PREPARING`. Preparation settles which forms a statement covers, so nothing is listable until preparation for that recipient completes: a statement appears at the end of its own preparation, in `PREPARED` or in `FAILED`. enum: - PREPARED - PUBLISHED - FAILED x-enumDescriptions: PREPARED: Built and readable, and not yet furnished to the recipient. A later `prepareSnapshot` may replace it when input changes; unchanged input may produce no new output. PUBLISHED: "Furnished to the recipient. Permanent: a later prepare neither rebuilds it nor removes it." FAILED: Preparation could not build the statement, and `problem` says why. A later prepare may replace it as inputs are reassessed. examples: - PREPARED StatementSummary: type: object title: Statement summary description: | A statement as `listStatements` and `listRecipientStatements` return it: every field of the statement except `forms`. A statement covers any number of forms, so `forms` is the one field of the resource without a bound. The list operations omit it to keep the size of a page a function of `page_size` alone; the client retrieves the statement (`getStatement` or `getRecipientStatement`) to see the forms it covers. properties: id: $ref: "#/components/schemas/StatementId" filer_id: type: string readOnly: true description: The `id` of the filer that furnishes this statement. examples: - acme-payroll-west recipient_id: type: string readOnly: true description: The `id` of the recipient this statement goes to. examples: - "8827" tax_year: type: integer readOnly: true description: The tax year of the forms this statement covers. 2026 is the only tax year the API serves. examples: - 2026 kind: $ref: "#/components/schemas/StatementKind" status: $ref: "#/components/schemas/StatementStatus" problem: description: Why preparation could not build the statement. Present only where `status` is `FAILED`, and absent otherwise. $ref: "#/components/schemas/Problem" created_at: type: string format: date-time readOnly: true description: When preparation finished building the statement. A statement first appears already prepared, so this is also when it became readable. updated_at: type: string format: date-time readOnly: true description: "When the statement last changed. Publishing is what moves it: a prepare discards and rebuilds rather than editing, so an unpublished statement carries its `created_at` here." published_at: type: string format: date-time readOnly: true description: When `statements/publish` furnished the statement to the recipient. Absent until it does, which makes its presence the same signal as a `status` of `PUBLISHED`. required: - id - filer_id - recipient_id - tax_year - kind - status - created_at - updated_at StatementPage: type: object title: Statement Page properties: resources: type: array description: The statements in this page, each without its `forms` — see `StatementSummary`. The array can be empty. items: $ref: "#/components/schemas/StatementSummary" next_page_token: $ref: "#/components/schemas/NextPageToken" required: - resources - next_page_token StatementForm: type: object title: Form covered by a statement readOnly: true description: One form the statement covers, named by the identifier that addresses it under its recipient and by which IRS form it is. properties: generation: description: | The generation of the form used for this statement. Use it to find the corresponding input in the form's current version or its history. $ref: "#/components/schemas/Generation" id: type: string description: "The `id` of the form, as `getForm` addresses it under this statement's recipient: the identifier the client supplied at the form's creation, or its `entity_id` where the client supplied none." examples: - 6b3f0c2e-8d4a-4f1b-9e57-a2c81d0f3b64 type: type: string description: Which IRS form it is, spelled as the `type` of that form's `data` — for example, `1099-NEC`. examples: - 1099-NEC required: - generation - id - type PresignedUrl: type: object title: Presigned URL readOnly: true description: One representation of the document, addressed by a URL that requires no credentials. Anyone who holds the URL can download the representation until it expires, so the client should handle it as it handles a credential. properties: url: type: string format: uri description: The URL. A `GET` of it, with no `Authorization` header, returns the same bytes `getStatementDocument` returns for this entry's media type. examples: - https://documents.nutshell.example/3e7c94a1-5b2d-4c6f-8a1e-d90b4f62c817.pdf?expires=1770826500&signature=h7Kk2xw expires_at: type: string format: date-time description: "When the URL stops working: `download_ttl_s` seconds after the read that returned it generated it. Past this instant the URL answers an error rather than the document, and the client retrieves the statement again, with `download_ttl_s`, to obtain a fresh one." examples: - "2026-08-11T17:45:00Z" required: - url - expires_at PresignedUrls: type: object title: Presigned URLs readOnly: true description: | One presigned URL per representation of the statement's document, keyed by the representation's media type. The keys are exactly the media types `getStatementDocument` serves for this statement: `application/pdf` for every statement that has a document, joined by `application/vnd.nutshell.statement+zip` and `application/vnd.nutshell.statement+json` where `kind` is `SUBSTITUTE`. Present only where the request supplied `download_ttl_s` and the statement has a document, and absent otherwise — a read without the parameter omits it, as does any read of a `FAILED` statement. Every URL in the object comes from the read that returned it, so all of them expire together. additionalProperties: $ref: "#/components/schemas/PresignedUrl" Statement: title: Statement description: | One document a filer furnishes to a recipient, covering one or more of the forms the filer issued to that recipient. `prepareSnapshot` creates statements for review; `statements/publish` delivers them to recipients. The single-statement reads return this schema, `forms` included. The list operations return `StatementSummary`, which is the same statement without it. `presigned_urls` appears only where the read was asked for it — see `download_ttl_s` on `getStatement`. allOf: - $ref: "#/components/schemas/StatementSummary" - type: object properties: forms: type: array readOnly: true description: The forms this statement covers. Preparation spreads a recipient's forms across the statements it produces, so what a recipient receives is the `forms` of every statement in its collection rather than of any one of them. The list operations omit this field; only the single-statement reads carry it. items: $ref: "#/components/schemas/StatementForm" presigned_urls: $ref: "#/components/schemas/PresignedUrls" required: - forms StatementPdf: type: string format: binary title: Statement (PDF) description: "The statement as a PDF: the document the recipient receives. Every statement has this representation, whichever `kind` it is." SubstituteStatementArchive: type: string format: binary title: Substitute statement (archive) description: The substitute statement as an archive of the same document the PDF carries. This reference does not define the layout of the archive. A `STANDARD` statement does not have this representation and answers `406` to a request for it. SubstituteStatementData: type: object additionalProperties: true title: Substitute statement (JSON) description: The substitute statement as JSON, carrying the same document the PDF does. This reference does not define the structure of the object. A `STANDARD` statement does not have this representation and answers `406` to a request for it. ActionRequest: type: object title: Action request description: Omit the request body or send an empty JSON object. properties: {} additionalProperties: false OperationId: type: string format: uuid title: Operation identifier description: The identifier the server assigns to the operation when it accepts the action that produced it. The server assigns it once and never reuses it. examples: - 2f4a6758-4c61-4a36-a789-069e915ece9d OperationType: type: string title: Operation type readOnly: true description: Which action produced the operation, named as that action's path beneath `/api/v2/{tax_year}/actions`. enum: - prepareSnapshot - statements/publish - filings/submit x-enumDescriptions: prepareSnapshot: Create a snapshot of your tax-year data and prepare returns and recipient statements for review. statements/publish: Publish all eligible statements from the prepared snapshot. filings/submit: Submit all eligible filings from the prepared snapshot. examples: - prepareSnapshot OperationStatus: type: string title: Operation status readOnly: true description: | How far the operation has progressed. `PENDING` and `PROCESSING` indicate work in progress; `SUCCEEDED`, `FAILED` and `CANCELED` are final. One operation can be pending or processing for your tax year at a time. Requesting another action while it runs returns `409 Conflict`. enum: - PENDING - PROCESSING - SUCCEEDED - FAILED - CANCELED x-enumDescriptions: PENDING: Accepted and waiting to begin. PROCESSING: Running. Resources appear in their own collections as the operation progresses, so the client can read part of the result before the whole of it. SUCCEEDED: Processing finished successfully. Inspect resource statuses and problems for individual results. FAILED: Processing failed. Inspect resource statuses and problems for available results. CANCELED: Stopped before completion. The work the operation completed before it stopped stands. examples: - PROCESSING OperationStatistics: type: object title: Operation statistics readOnly: true description: | Counts of completed outputs and processing errors. One recipient can contribute several outputs and errors. Present from `PROCESSING` onwards, with zeros until processing finishes. properties: affected_count: type: integer format: int64 minimum: 0 description: The sum of `completed_count` and `error_count`. examples: - 128349 completed_count: type: integer format: int64 minimum: 0 description: The number of completed outputs. examples: - 128221 error_count: type: integer format: int64 minimum: 0 description: The number of processing errors. Several errors may concern the same resource. examples: - 128 required: - affected_count - completed_count - error_count PrepareSnapshotDetails: type: object title: Snapshot preparation details readOnly: true description: Processing results of a `prepareSnapshot` operation. properties: statistics: $ref: "#/components/schemas/OperationStatistics" StatementsPublishDetails: type: object title: Statement publication details readOnly: true description: Processing results of a `statements/publish` operation. properties: statistics: $ref: "#/components/schemas/OperationStatistics" FilingsSubmitDetails: type: object title: Filing submission details readOnly: true description: Processing results of a `filings/submit` operation. properties: statistics: $ref: "#/components/schemas/OperationStatistics" Operation: type: object title: Operation description: | The status and results of an action. A successful request to an action endpoint returns `202 Accepted` with this resource in the body and its URL in `Location`. Poll that URL to follow processing. properties: generation: type: integer format: int64 readOnly: true description: | The generation of the snapshot this operation prepares, publishes or submits. examples: - 3 id: $ref: "#/components/schemas/OperationId" type: $ref: "#/components/schemas/OperationType" status: $ref: "#/components/schemas/OperationStatus" details: readOnly: true description: "The type-specific processing results. `type` names which of the following shapes it takes." anyOf: - $ref: "#/components/schemas/PrepareSnapshotDetails" - $ref: "#/components/schemas/StatementsPublishDetails" - $ref: "#/components/schemas/FilingsSubmitDetails" created_at: type: string format: date-time readOnly: true description: When the server accepted the action and created this operation. updated_at: type: string format: date-time readOnly: true description: When the operation last changed. completed_at: type: string format: date-time readOnly: true description: When the operation reached `SUCCEEDED`, `FAILED` or `CANCELED`. Absent until it does, which makes its presence the same signal as a terminal `status`. required: - generation - id - type - status - details - created_at - updated_at OperationPage: type: object title: Operation Page properties: resources: type: array description: The operations in this page, most recent first; the array can be empty. items: $ref: "#/components/schemas/Operation" next_page_token: $ref: "#/components/schemas/NextPageToken" required: - resources - next_page_token responses: BadRequest: description: The request was malformed, or failed validation. content: application/problem+json: schema: $ref: "#/components/schemas/Problem" Unauthorized: description: The bearer token was missing, malformed, or expired. content: application/problem+json: schema: $ref: "#/components/schemas/Problem" Forbidden: description: The credential is valid but not permitted to perform this operation. content: application/problem+json: schema: $ref: "#/components/schemas/Problem" Conflict: description: The request is well formed but conflicts with the state of the resource — an attempt to change something settled at creation, or to remove something that has since been sent elsewhere. content: application/problem+json: schema: $ref: "#/components/schemas/Problem" NotFound: description: No such resource exists, or the credential cannot observe it. content: application/problem+json: schema: $ref: "#/components/schemas/Problem" PreconditionFailed: description: The supplied `If-Generation-Match` does not equal the current resource generation. Nothing changed. Read the resource again and reconcile the update before retrying. content: application/problem+json: schema: $ref: "#/components/schemas/Problem" NotAcceptable: description: No representation of the resource matches the request's `Accept` header. `detail` names the media types the resource is available as. content: application/problem+json: schema: $ref: "#/components/schemas/Problem" StatementDocument: description: The document, in the representation `Accept` selected. headers: Content-Disposition: description: Names the file the server offers the document as. schema: type: string examples: - attachment; filename="statement-2026-3e7c94a1-5b2d-4c6f-8a1e-d90b4f62c817.pdf" content: application/pdf: schema: $ref: "#/components/schemas/StatementPdf" application/vnd.nutshell.statement+zip: schema: $ref: "#/components/schemas/SubstituteStatementArchive" application/vnd.nutshell.statement+json: schema: $ref: "#/components/schemas/SubstituteStatementData" ActionAccepted: description: The action was accepted. Follow the operation at `Location` to check its status and results. headers: Location: description: The URL of the operation the server created for this action. schema: type: string format: uri-reference examples: - /api/v2/2026/operations/2f4a6758-4c61-4a36-a789-069e915ece9d content: application/json: schema: $ref: "#/components/schemas/Operation" ActionConflict: description: | Another action is pending or processing for your tax year, or the requested action requires a successfully prepared snapshot. `detail` identifies the running operation or explains which prerequisite must be completed. content: application/problem+json: schema: $ref: "#/components/schemas/Problem" requestBodies: Action: required: false description: Omit the request body or send an empty JSON object. content: application/json: schema: $ref: "#/components/schemas/ActionRequest"