Forms received
List the tax forms issued to a Person or to an Account with the Wingspan V3 API.
A recipient can list the tax forms issued to them. These calls return summaries. Follow formId to /v3/compliance/forms for the full form, its PDF, and its history.
Prerequisites
- For the Person call: a Person session. It's Person-scoped, so don't send
X-Wingspan-Account. - For the Account call: an Account credential with scope
payments.tax-form-received:read. The Account in the path must be the Account you act as.
Endpoints
| Method and path | Operation |
|---|---|
GET /v3/platform/persons/{personId}/forms-received | listPersonFormsReceived |
GET /v3/platform/accounts/{accountId}/forms-received | listAccountFormsReceived |
Both take page[size] and page[token]. Follow pagination.nextPageToken until it's an empty string.
Person view
GET .../persons/{personId}/forms-received returns forms issued to the Person, across every Account the Person was principal of in the tax year.
| Filter | Notes |
|---|---|
filter[taxYear][eq] | Integer, for example 2025. |
filter[type][eq] | For example 1099Nec, 1099Misc, or T4A. |
Row fields: id, formId, type, taxYear, issuerAccountId, recipientAccountId, accountId, personId, amount, currency, deliveredAt.
curl -g "https://api.wingspan.app/v3/platform/persons/$PERSON_ID/forms-received?filter[taxYear][eq]=2025" \
-H "Authorization: Bearer $WINGSPAN_TOKEN"Errors: 400 for a malformed filter or an X-Wingspan-Account header on this Person call, 404 when the Person isn't visible to the caller.
Account view
GET .../accounts/{accountId}/forms-received returns the forms issued to that Account as the recipient. It doesn't return forms the Account issued to others. A W-9 isn't listed here; list those with GET /v3/compliance/forms filtered by type W9 and recipientAccountId.
Each filter takes exactly one operator, eq or anyOf. Filters combine with AND.
| Filter | Values |
|---|---|
taxYear | Integer, 2021 to 2026. |
type | 1099Nec, 1099Misc, T4A. |
status | Draft, Effective, Voided. |
Sort with sort[createdAt]=asc or desc. The default is newest first.
Row fields:
| Field | Meaning |
|---|---|
id, formId | The projection id and the id of the form in /v3/compliance/forms. |
type, taxYear | Form type and tax year. |
issuerAccountId, recipientAccountId, recipientPersonId | Who issued the form and who received it. recipientPersonId is set when the person named on the form is resolved. |
amount, currency | Amount on the form. amount is null before filing. |
status | Draft, Effective, Superseded, Expired, or Voided. |
submissionStatus | Filing state with the tax authority: Created, Submitted, Accepted, Rejected, or Voided. |
deliveryStatus | NotDelivered, Pending, Delivered, or Failed. Independent of filing. |
deliveredAt | When the form was delivered, if it was. |
hasPendingCorrectionRequest | true while a correction request is open. |
w9Confirmed | Whether a W-9 is confirmed. |
curl -g "https://api.wingspan.app/v3/platform/accounts/$ACCOUNT_ID/forms-received?filter[type][eq]=1099Nec&filter[status][eq]=Effective&sort[createdAt]=desc" \
-H "Authorization: Bearer $WINGSPAN_TOKEN" \
-H "X-Wingspan-Account: $ACCOUNT_ID"Errors: 403 when the path Account isn't the Account you act as, 404 when the Account isn't visible, 422 for an invalid filter or sort, 503 when the service is temporarily unavailable. Retry a 503 after a short delay.
Related pages
Updated 12 minutes ago