Create or update multiple forms

This section describes how to create and update 1099 forms using a batch job.

Endpoints:

POST /1099/forms/bulk-upsert - Submit multiple 1099 forms for creation or update
GET /jobs/{id} - Check the status of a submitted bulk job

Use case:

Use this functionality when you need to upload or correct many 1099 forms at once. This is ideal for:

Year-end mass filing
Uploading data from accounting, payroll, or ERP systems
Performing batch corrections before or after IRS submission
Running a dryRun to validate a data set prior to committing it

Supported behavior

All supported form types (1099-NEC, 1099-MISC, 1099-K, and so on).
Accepts forms for multiple Issuers in a single request.
Do not accept mixed form types in a single request. The form type must be set for each request.
Performs creates or updates based on the referenceId + issuerId combination.
Accepts incomplete or draft forms for later editing.
Supports a maximum of 5,000 forms per request.

Form identification rules

If a form with the same referenceId and issuerId already exists, the system will update it.
If no match is found, the form will be created as new.
Changes to forms that were already submitted to the IRS are automatically treated as corrections. No special flags are required.

The dryRun flag

Add "dryRun": true to validate the payload without saving any records. This helps detect:

Structural issues
Field format problems
Required field omissions

If the payload is valid, the system will return a simulated success response. If errors exist, they’ll be returned in the response under the errors array.

No data is stored or processed when dryRun is enabled.