Example: Create or update multiple forms

Use the sample request and response below as a reference to upload or correct many 1099-NEC forms at once.

Sample request payload

{
  "dryRun": false,
  "type": "1099-NEC",
  "forms": [
    {
    "type": "1099-NEC",
    "issuerId": "141111361",
    "issuerReferenceId": null,
    "taxYear": 2024,
    "referenceId": "NEC-2024-001",
    "tin": "321-00-0000",
    "recipientName": "John Doe",
    "tinType": "SSN",
    "recipientSecondName": "Doe Enterprises",
    "address": "123 Main Street",
    "address2": "Suite 100",
    "city": "New York",
    "state": "NY",
    "zip": "10001",
    "email": "john.doe@example.com",
    "accountNumber": "ACC123456",
    "officeCode": "NY01",
    "countryCode": "US",
    "nonemployeeCompensation": 15000,
    "directSalesIndicator": true,
    "federalIncomeTaxWithheld": 3000,
    "secondTinNotice": false,
    "federalEfileDate": "2024-09-15",
    "stateEfileDate": "2024-09-20",
    "recipientEdeliveryDate": "2024-09-25",
    "postalMail": false,
    "tinMatch": true,
    "addressVerification": true,
    "stateAndLocalWithholding": {
        "stateTaxWithheld": 500,
        "state": "NY",
        "stateIdNumber": "NY123456",
        "stateIncome": 15000,
        "localTaxWithheld": 250,
        "locality": "New York City",
        "localityIdNumber": "NYC789",
        "localIncome": 15000
        }
    },
    {
    "type": "1099-NEC",
    "issuerId": "141536301",
    "issuerReferenceId": null,
    "taxYear": 2024,
    "referenceId": "NEC-2024-002",
    "tin": "789-00-0000",
    "recipientName": "Jane Smith",
    "tinType": "SSN",
    "recipientSecondName": "Jane Enterprises",
    "address": "456 Main Street",
    "address2": "Suite 200",
    "city": "New York",
    "state": "NY",
    "zip": "10001",
    "email": "jane.smith@example.com",
    "accountNumber": "ACC654321",
    "officeCode": "NY02",
    "countryCode": "US",
    "nonemployeeCompensation": 2000,
    "directSalesIndicator": true,
    "federalIncomeTaxWithheld": null,
    "secondTinNotice": false,
    "federalEfileDate": "2024-09-15",
    "stateEfileDate": "2024-09-20",
    "recipientEdeliveryDate": "2024-09-25",
    "postalMail": false,
    "tinMatch": true,
    "addressVerification": true,
    "stateAndLocalWithholding": {
        "stateTaxWithheld": null,
        "state": null,
        "stateIdNumber": null,
        "stateIncome": 0,
        "localTaxWithheld": 0,
        "locality": null,
        "localityIdNumber": null,
        "localIncome": 0
        }
    }
  ]
}

Success response (200 OK)

{
    "id": "update-473",
    "type": "update_job",
    "status": "Success",
    "errorMessage": null,
    "totalProcessed": 2,
    "totalRows": 2,
    "updatedValid": 0,
    "updatedNoEmail": 0,
    "updatedInvalid": 0,
    "skippedDuplicate": 0,
    "skippedInvalid": 0,
    "skippedMultipleMatches": 0,
    "notFound": 0,
    "createdInvalid": 0,
    "createdNoEmail": 0,
    "createdValid": 2,
    "dryRun": false,
    "upsert": true,
    "link": "/jobs/update-473",
    "processedForms": [
        {
            "nonemployeeCompensation": 2000.0,
            "directSalesIndicator": true,
            "federalIncomeTaxWithheld": null,
            "type": "1099-NEC",
            "id": "237804828",
            "issuerId": "141536301",
            "issuerReferenceId": "ACME-2025-002",
            "issuerTin": "456-00-0000",
            "taxYear": 2024,
            "referenceId": "NEC-2024-002",
            "tin": "789-00-0000",
            "recipientName": "Jane Smith",
            "tinType": "SSN",
            "recipientSecondName": "Jane Enterprises",
            "address": "456 Main Street",
            "address2": "Suite 200",
            "city": "New York",
            "state": "NY",
            "zip": "10001",
            "email": "jane.smith@example.com",
            "accountNumber": "ACC654321",
            "officeCode": "NY02",
            "nonUsProvince": null,
            "countryCode": "US",
            "federalEfileDate": "2024-09-15",
            "postalMail": false,
            "stateEfileDate": null,
            "recipientEdeliveryDate": "2024-09-25",
            "tinMatch": true,
            "noTin": false,
            "addressVerification": true,
            "stateAndLocalWithholding": {
                "stateTaxWithheld": null,
                "state": null,
                "stateIdNumber": null,
                "stateIncome": 0.0,
                "localTaxWithheld": 0.0,
                "locality": null,
                "localityIdNumber": null,
                "localIncome": 0.0
            },
            "secondTinNotice": false,
            "federalEfileStatus": {
                "time": "2025-08-29T00:00:00+00:00",
                "status": "scheduled"
            },
            "stateEfileStatus": [],
            "postalMailStatus": {
                "time": null,
                "status": "unscheduled"
            },
            "tinMatchStatus": {
                "time": null,
                "status": "pending"
            },
            "addressVerificationStatus": {
                "time": "2025-08-29T15:21:23-04:00",
                "status": "pending"
            },
            "eDeliveryStatus": {
                "time": "2024-09-25T00:00:00+00:00",
                "status": "scheduled"
            },
            "validationErrors": [],
            "createdAt": "2025-08-29T19:21:23.117000",
            "updatedAt": "2025-08-29T19:21:23.117000"
        },
        {
            "nonemployeeCompensation": 15000.0,
            "directSalesIndicator": true,
            "federalIncomeTaxWithheld": 3000.0,
            "type": "1099-NEC",
            "id": "407767371",
            "issuerId": "141111361",
            "issuerReferenceId": "ACME-2025-001",
            "issuerTin": "123-00-0000",
            "taxYear": 2024,
            "referenceId": "NEC-2024-001",
            "tin": "321-00-0000",
            "recipientName": "John Doe",
            "tinType": "SSN",
            "recipientSecondName": "Doe Enterprises",
            "address": "123 Main Street",
            "address2": "Suite 100",
            "city": "New York",
            "state": "NY",
            "zip": "10001",
            "email": "john.doe@example.com",
            "accountNumber": "ACC123456",
            "officeCode": "NY01",
            "nonUsProvince": null,
            "countryCode": "US",
            "federalEfileDate": "2024-09-15",
            "postalMail": false,
            "stateEfileDate": null,
            "recipientEdeliveryDate": "2024-09-25",
            "tinMatch": true,
            "noTin": false,
            "addressVerification": true,
            "stateAndLocalWithholding": {
                "stateTaxWithheld": 500.0,
                "state": "NY",
                "stateIdNumber": "NY123456",
                "stateIncome": 15000.0,
                "localTaxWithheld": 250.0,
                "locality": "New York City",
                "localityIdNumber": null,
                "localIncome": 15000.0
            },
            "secondTinNotice": false,
            "federalEfileStatus": {
                "time": "2025-08-29T00:00:00+00:00",
                "status": "scheduled"
            },
            "stateEfileStatus": [],
            "postalMailStatus": {
                "time": null,
                "status": "unscheduled"
            },
            "tinMatchStatus": {
                "time": null,
                "status": "pending"
            },
            "addressVerificationStatus": {
                "time": "2025-08-29T15:21:23-04:00",
                "status": "pending"
            },
            "eDeliveryStatus": {
                "time": "2024-09-25T00:00:00+00:00",
                "status": "scheduled"
            },
            "validationErrors": [],
            "createdAt": "2025-08-29T19:21:23.078000",
            "updatedAt": "2025-08-29T19:21:23.078000"
        }
    ]
}

Action failed response

{
    "id": "update-480",
    "type": "update_job",
    "status": "Success",
    "errorMessage": null,
    "totalProcessed": 2,
    "totalRows": 2,
    "updatedValid": 0,
    "updatedNoEmail": 0,
    "updatedInvalid": 0,
    "skippedDuplicate": 1,
    "skippedInvalid": 1,
    "skippedMultipleMatches": 0,
    "notFound": 0,
    "createdInvalid": 0,
    "createdNoEmail": 0,
    "createdValid": 0,
    "dryRun": false,
    "upsert": true,
    "link": "/jobs/update-480",
    "processedForms": []
}