# Validation model for creating and updating 1099 forms

Source: https://developer.avalara.com/products/avalara-1099-and-w9/integration-guides/1099-and-w-9/ecb3356632790661/

Guide: 1099 & W-9

# Validation model for creating and updating 1099 forms

Understand the validation model for creating and updating 1099 forms using Avalara APIs.

The Avalara 1099 APIs intentionally separate record creation from filing readiness:

-   Minimum to create or update a form

    The API requires only 2 fields to accept (create or update) a form record:

    -   `type` (for example, `1099-NEC`, `1099-MISC`, and so on)

    -   `issuerId` (the Avalara-issued identifier for the payer/issuer)

-   What’s required to file, deliver, or schedule actions

    The set of fields required to file with the IRS or states or to deliver a recipient copy varies by:

    -   The form type (NEC, MISC, K, R, and so on)
    -   The action that you want to perform (federal e-filing, state e-filing, eDelivery to recipient, print & mail, and so on)

This design lets you create incomplete forms now and add missing details later. For example, while you’re still collecting payee contact data.

When you’ll get a hard error (4xx)

You can expect standard HTTP errors only for request-level problems (for example, authentication, malformed JSON, missing the 2 minimal fields `type` and `issuerId`, or endpoint/verb misuse). Field-format issues are reported in `validationErrors` while persisting the record.

## Sample error response (400 Bad Request)

```
{
    "title": "One or more validation errors occurred.",
    "errors": [
        {
            "type": "issuerId",
            "detail": "Invalid"
        }
    ]
}
```

## Action-specific readiness examples

Examples of readiness checks required for specific actions, such as federal e-filing, state e-filing, recipient eDelivery, and print & mail.

Below are typical readiness checks. These are examples, not an exhaustive list.

-   **Federal e-filing (IRS)**

    Supply all IRS-required boxes for that form type (for example, `nonemployeeCompensation` for 1099-NEC when applicable) plus recipient TIN, recipient name, address fields (or eDelivery if you aren’t mailing), and any other form-specific boxes mandated by the IRS schema.

-   **State e-filing**

    Requires federal e-filing data plus state-specific fields where applicable (for example, `stateAndLocalWithholding.state`, `stateIdNumber`, `stateIncome`, and so on).

-   **Recipient eDelivery (email)**

    Requires a valid `email` for the recipient and any consent requirements that your process enforces.

-   **Print & mail**

    Requires complete postal address fields (for example, `address`, `city`, `state`, `zip`, `countryCode`) and any fields needed to render the recipient’s copy.

If a readiness requirement isn't met, then the system won't perform the respective action.

## How server-side validation behaves

Understand how server-side validation handles field-level issues and provides feedback.

### Accepts the record even with field-level issues

If a property is present but formatted incorrectly (for example, length too long, invalid enumeration, wrong pattern), the API still creates/updates the form and returns a `validationErrors` array describing the issues.

-   Each error identifies the field using a JSON Pointer (for example, `#/office_code`) and includes one or more human-readable messages (for example, “is too long (maximum is 4 characters)”).
-   You can store the record immediately and fix the flagged fields later.

### Sample request (excerpt)

```
{
  "type": "1099-NEC",
  "issuerId": "141111361",
  ...
  "officeCode": "NYC01",
  "countryCode": "US",
  "nonemployeeCompensation": 15000,
  ...
}
```

### Sample response (excerpt)

```
{
  "type": "1099-NEC",
  "id": "181877101",
  "issuerId": "141111361",
  ...
  "validationErrors": [
    {
      "field": "#/office_code",
      "errors": ["is too long (maximum is 4 characters)"]
    }
  ],
  "createdAt": "2025-08-29T14:34:19.207000",
  "updatedAt": "2025-08-29T14:34:19.207000"
}
```

In this example, the form was created successfully, but `office_code` exceeds the maximum length.