Bulk Uploading Contractors into Wingspan

Upload new or update existing contractors in bulk so they can receive invitations to join Wingspan, confirm their tax information, and ensure accurate 1099 filing. This process is especially helpful if you need to consolidate contractor records mid-year, handle contractors paid outside of Wingspan, or use Wingspan primarily for filing 1099 forms.

When to Use Bulk Uploading Contractors

Consider bulk uploading if:

You migrated to Wingspan mid-year and need to consolidate historical records.

You paid contractors through platforms other than Wingspan.

You are using Wingspan primarily for 1099 form filing.

Bulk imports can be executed multiple times until the January 25th filing deadline.

Note: New contractors added through bulk uploading will receive an invitation to join Wingspan and confirm their tax details.

Permissions: Only users with admin permissions can perform bulk imports.

Step-by-Step Guide to Bulk Uploading Contractors

1. Access the Bulk Upload Page

From the Contractors list, navigate to Actions (3-dots) > Bulk upload contractors. You can also access this feature from the 1099 Filing Dashboard and on the two bulk upload pages.

Follow the instructions to prepare and upload your spreadsheet.

2. Prepare Your Spreadsheet

You can upload CSV or Excel (XLS, XLSX) files only. The file must be UTF-8 encoded. There are no limits on file size or row count.

Your spreadsheet should contain columns for identifying the contractor and optional fields for their basic information, custom fields, and/or tax information. Each row corresponds to a single contractor.

Note on Engagement:
Engagement is not a column in the upload. Instead, you select an Engagement before the upload begins, and that selection applies to all rows. You cannot specify a different engagement per row.

Identifiers (At Least One Required)

Wingspan User ID (highest priority, only applies when updating existing contractors; ignored if creating a new one)
External ID (unique ID that you provide, linking the contractor in Wingspan to your internal records)
Email Address (unique, valid, and accessible; recommended the contractor’s personal email)

If multiple identifiers are provided, the system uses them in the following order of priority to identify the contractor:

Wingspan User ID
External ID
Email Address

Basic Information (Optional)

First Name
Last Name
Business Name (Legal Name)

If First Name and Last Name are omitted, the contractor’s email address appears on their profile until they complete onboarding.

Custom Fields (Optional)

If you have set up custom contractor fields, include columns for them. Data must match the defined data types. Validation errors occur if data types are incorrect.

U.S. Tax Information (Optional)

You may provide W-9 data as a backup for 1099 filings if the contractor never confirms their details.

Required if providing W-9 data:

SSN or EIN (one required, not both)
W-9 Legal Business Name (must match IRS records, specific allowed characters only)
Address fields: Address Line 1 (no P.O. boxes), City, State, Postal Code, Country (defaults to “US” if not provided)
Federal Tax Classification. Allowed values:
- Sole proprietorship
- S-corp
- C-corp
- Partnership
- LLC (single member)
- LLC (Taxed as S-corp)
- LLC (Taxed as C-corp)
- LLC (Taxed as Partnership)

Company structure must match allowed values based on TIN type (SSN or EIN).

Data Validation and Formatting

Allowed characters for names and business names: A-Z, 0-9, hyphens (-), and ampersands (&).
SSNs/EINs can be with or without hyphens.
Country must follow ISO standards.
State must be a two-letter code (for U.S.) or equivalent for other countries.
Postal codes vary by country.

3. Create vs. Update Mode

Create Mode:
Occurs when provided identifiers do not match any existing contractor.

At least one identifier (External ID or Email) is required.
Identifiers must not belong to any existing contractor.
If a Wingspan User ID is provided, it is ignored with a warning since it only applies to existing contractors.

Update Mode:
Occurs when at least one provided identifier matches an existing contractor.

Only custom fields, external IDs, payer-provided W-9 info, and payer-provided name (or company name) can be updated.
Empty cells set these fields to null.
At least one additional field (beyond the identifier) is required for an update.
All other fields (including email) are ignored during Update Mode if the contractor has already logged in.

4. Identifying Existing Contractors

Priority:

Wingspan User ID
External ID
Email Address

Conflicts:

If External ID and Email don’t match the same existing contractor, the row fails.
If Wingspan User ID conflicts with External ID or Email, the row fails.

Immutable Organization Account:
If a contractor already has an Organization Account, it cannot be changed via bulk upload.

Correcting Mismatches:
To fix a mismatch:

Remove the External ID from the incorrect contractor profile.
Re-upload the correct pairing in a subsequent bulk upload.

5. Engagements and Organization Accounts

Because Engagement is selected before you upload—and not within the spreadsheet—it applies to all rows in that upload.

If you also need to specify an Organization Account ID, you can do so in the spreadsheet. However, note that if a contractor already has an Organization Account, it cannot be changed via bulk upload.

6. Upload the Spreadsheet

Upload the prepared spreadsheet from the Bulk Upload page. The system processes each row and provides immediate feedback on errors or warnings.

7. Handling Errors and Validation

Per-Row Validation:
Errors are displayed per row. Cells causing validation errors are highlighted. If any validation fails in a row, that entire row is rejected.

Downloading Error Reports:
If errors occur, a CSV file outlining them is available. Correct the issues and re-upload. Rows that were already successful do not need re-uploading.

Tax Detail Confirmation:
If a contractor never confirms their tax details, Wingspan uses any W-9 information you provided. If no W-9 details were provided by either party, the 1099 cannot be filed.

8. Special Cases

Archived Contractors:
Updating an archived contractor automatically reactivates them. No additional email is sent.

TIN Uniqueness:
Each unique email can only be linked to one TIN (SSN or EIN).

Multiple Bulk Uploads:
Perform multiple imports as needed until the filing deadline.

Frequently Asked Questions (FAQ)

What if a contractor never confirms their tax details?

If W-9 details were provided, that information is used for filing.
If no details are available, the 1099 cannot be filed.

Are there size limitations?
No. There are no limitations on the number of rows or file size.

Can I update contractor details after the initial upload?
Yes, so long as you’re adhering to the Update Mode limitations (i.e., only custom fields, external IDs, payer-provided W-9 info, and payer-provided name/company name). Omitted fields remain unchanged unless you explicitly set them to null by leaving them blank.