Validation model for creating and updating 1099 forms

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 actually 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-file, state e-file, 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 should expect standard HTTP errors only for request-level problems (for example, authentication, malformed JSON, missing the 2 minimal fieldstype andissuerId, or endpoint/verb misuse). Field-format issues are reported invalidationErrors while still 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

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

Federal e-file (IRS)
You must 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-file
Requires federal e-file data plus state-specific fields where applicable (for example,stateAndLocalWithholding.state,stateIdNumber,stateIncome, and so on).
Recipient eDelivery (email)
Requires a validemail 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 respective action won’t be performed.

How server-side validation behaves

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 avalidationErrors array describing the issue(s).

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, butoffice_code violates the max-length rule.