Recipient information logic

Use this page to understand which contractor information ends up on a 1099, and how to predict it before you file.

Before filing: three sources, in priority order

Until a form is Submitted, Rejected, or Accepted, it's in the pre-filing stage. During this stage the contractor details on the form come from one of three sources. The first one that exists wins:

Payer overwrites: You or a teammate edit the name, TIN, address, status, or amount directly on the form. The edit applies only to the form, and the form stops syncing with the contractor profile. For example, you notice a wrong address and correct it on the form before filing.
Contractor-provided W-9 information: The contractor enters or confirms their own W-9 details in Wingspan. Changes sync to the form in real time. For example, a contractor updates their address before you file, and the 1099 shows the new address.
Payer-provided W-9 information: You provide the contractor's W-9 details on their behalf, individually or by bulk upload. Changes sync to the form in real time.

Any change to the contractor profile during the pre-filing stage shows up on the form according to this priority. After a form is filed, changes go through corrections.

Which name, TIN, and address

Contractor's situation	Name on the form	TIN	Address
Has an EIN and prefers to use it	Legal business name	EIN	Registered business address, or personal address if none
SSN only, sole proprietor or single-member LLC	Legal business name together with first and last name, if both exist; otherwise "FirstName LastName"	SSN	Personal address
SSN only, any other eligible structure	First and last name	SSN	Personal address

In the API

You can't read or edit a 1099 form through the V3 API yet. You can control and inspect the inputs this logic uses.

Choose whose W-9 data a Payee uses

Every Payee has a w9SourcePolicy:

Value	Whose W-9 data is used
`PayeeSuppliedFallbackToPayer`	The contractor's shared tax information. Falls back to your complete payer-supplied W-9 when the contractor hasn't shared, or their data is incomplete. The default for new Payees.
`PayeeSupplied`	Only the contractor's shared tax information.
`PayerSupplied`	Only the tax information you supplied.

The default matches the web app's priority above: contractor-provided information ahead of payer-provided information.

To change it, update the payee:

curl -X PATCH https://api.wingspan.app/v3/payments/payees/kY9pF34Qy6nB3Wwd25rq4f \
  -H "Authorization: Bearer $WINGSPAN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "w9SourcePolicy": "PayeeSupplied" }'

See where a Payee's tax identity comes from

Get the payee and read:

identitySource: PayerProvided when you attached a payer-supplied ComplianceEntity (payerSuppliedComplianceEntityId), PayeeOwned when the Payee is linked to its own Account and you supplied none. It's a pointer to the source, not a verification result.
payerSuppliedComplianceEntityId: the payer-supplied tax identity, if any.

Read the W-9 on file

When a contractor shares their tax information with you and it's verified, a W-9 appears in your forms. List them with GET /v3/compliance/forms:

curl -G https://api.wingspan.app/v3/compliance/forms \
  -H "Authorization: Bearer $WINGSPAN_TOKEN" \
  --data-urlencode "filter[type][eq]=W9" \
  --data-urlencode "filter[recipientAccountId][eq]=b9eGe0vRBbgi09qynDAkY8"

// 200 OK (trimmed)
{
  "data": [
    {
      "id": "aspzhU8QrTzhJqmHUoZe95",
      "type": "W9",
      "status": "Effective",
      "payeeId": "kY9pF34Qy6nB3Wwd25rq4f",
      "recipient": { "name": "Priya Shah", "tinType": "Ssn", "hasTin": true },
      "source": { "type": "ComplianceEntity" },
      "isManaged": true
    }
  ],
  "pagination": { "nextPageToken": "" }
}

The TIN itself is never returned: hasTin only tells you one is on file. A W-9 whose source tax information is no longer verified, or whose share was revoked, shows status: Expired. Today this list returns W-9s only. See Tax information.