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, XLS, XLSX, TSV, PSV, SV, JSON, XML, or PDF files. 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, tax information, engagement, and/or organization account. Each row corresponds to a single contractor.

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)

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

Engagement (Optional)

You may specify an existing, active engagement name to associate the contractor with it. Engagement names must be unique and active. If the contractor is already associated, a warning is shown, but processing continues.

Organization Account ID (Optional)

You can specify a Wingspan Organization Account ID to place the contractor within that organization. Identifiers must be unique within the organization. You cannot provide both Engagement and Organization Account ID in the same row.

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.

Any provided fields overwrite existing data.
Empty cells set fields to null.
At least one additional field (beyond the identifier) is required for an update.
Email updates are allowed only if the contractor has never logged in and if a Wingspan User ID or External ID is provided.

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

Engagements:
If provided and active, the contractor is associated with that engagement. If archived or non-existent, the row fails.

Organization Accounts:
If provided, the contractor is placed within that organization. Identifiers must be unique within the organization. Engagement and Organization Account ID cannot be combined in the same row.

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. Include the matching identifier(s) and updated fields. Omitted fields remain unchanged unless you explicitly set them to null by leaving them blank.