Wingspan concepts

Use this page to identify the Wingspan V3 API objects and understand how they relate to each other.

If you know the V1 API, the biggest change is vocabulary. Payees were called collaborators in V1, the contractor was the "member", and the company paying was the "client". The V1 term mapping at the bottom of this page lists every rename.

The model in one picture

flowchart LR
  subgraph Identity
    P[Person<br/>a human with a login]
    SA[ServiceAccount<br/>a machine identity]
    A[Account<br/>a business or individual<br/>that holds money]
    O[Organization<br/>groups Accounts]
  end

  subgraph "Payer's side"
    PY[Payee<br/>who I pay]
    G[Group]
    E[Engagement<br/>a scope of work]
    PE[PayeeEngagement<br/>a payee's assignment<br/>to an engagement]
    RD[RequirementDefinition]
    PB[Payable]
    PR[PayrollRun]
  end

  subgraph "Payee's side"
    PAY[Payer<br/>who pays me]
    INV[Invoice]
    RQ[PayeeRequirement]
  end

  P -- "Stakeholder<br/>(owner, admin, teammate)" --> A
  SA -- owned by --> A
  O -. contains .-> A
  A -- owns --> PY
  PY -. "optionally linked to<br/>(payeeAccountId)" .-> A2[Payee's own Account]
  A2 -- owns --> PAY
  PY -- member of --> G
  PY --> PE
  E --> PE
  E -- requires --> RD
  RD -- instantiated as --> RQ
  RQ -- gates --> PE
  PE --> PB
  PB -- same obligation as --> INV
  PR -- pays many --> PB

The rest of this page walks through each box.

Identity: who is acting

Person

A Person is a human. Every Person can log in. A Person holds sessions, API keys, and MFA factors, and has a notification inbox. Money, bank accounts, and tax records belong to an Account, not to a Person.

Endpoints live under /v3/platform/persons. The Person lifecycle is Created, Invited, Pending, Active, with Inactive (recoverable) and Disabled (terminal) as exits.

Account

An Account is the business entity that holds money, bank accounts, verifications, and tax records. It can be a company, or an individual contractor working for themselves. Accounts don't log in. A Person or a ServiceAccount acts on an Account.

A contractor who works on their own has one Person (the human) and one Account (their business identity). Wingspan presents the two together, so the contractor sees a single profile. A company has one Account with several Persons attached as owners, admins, or teammates.

Accounts can have a parent. A platform that embeds Wingspan usually has one parent Account and a child Account for each of its customers. Account status is Active, Suspended, or Closed. See Parent and child Accounts.

Stakeholder

A Stakeholder links a Person (or another Account) to an Account. It records ownership (ownershipPercentage), whether the stakeholder has control of the business (isController), and what they can do in Wingspan (roleId). Beneficial owners, officers, and teammates are all Stakeholders with different values. Endpoints live under /v3/platform/accounts/{accountId}/stakeholders.

Organization

An Organization groups the Accounts that belong to one customer or partner and is the boundary for single sign-on. It has no bank accounts and no tax filings of its own. Accounts carry an organizationId.

Important: The V3 API does not provide /v3/platform/organizations endpoints. You can read an Account's organizationId, but you cannot create, list, or update Organizations through the V3 API. Contact support if you need to manage an Organization.

ServiceAccount

A ServiceAccount is a machine identity for a backend job or integration where no human is in the loop. An Account or Organization owns it; a Person never does. Give it a role and scopes, then issue API keys to it. See Environments and authentication.

Relationships: who pays whom

Payee

A Payee is your record of someone you pay: a contractor, a vendor, or another business. Your Account owns it. You create it at POST /v3/payments/payees with an email address and a context: Contractor for a 1099 contractor or vendor, or Employee for a W-2 employee. The context decides which engagement types the relationship can hold. PATCH can't change it; use POST /v3/payments/payees/{payeeId}/change-context.

A Payee does not need a Wingspan Account to exist or receive payment. The Payee id is permanent, and every engagement, payable, and payment you create refers to it. When an invited person accepts and links the Payee to an Account they control, Wingspan adds a payeeAccountId. The Payee's id remains unchanged, so existing resources continue to work.

Two fields describe a Payee's state:

See Payees and Payee account linking.

Payer

A Payer is the mirror image: the payee's record of a company that pays them. It lives in the payee's Account and is what a contractor or business uses when they send an invoice. Endpoints live under /v3/payments/payers.

Link request

A link request (PayerPayeeLinkRequest) is the invitation that ties a Payee or Payer record to an Account. It starts as Pending and ends as Linked or Rejected. When you invite a Payee, Wingspan creates a link request and emails the invitee a one-time link. The invitee signs in, selects or creates the Account through which they want to be paid, and accepts the request.

Work: what the payee is paid for

Engagement

An Engagement is a scope of work you define once and assign many payees to, such as "Property inspections" or "ICU travel nursing". It carries the requirements a payee must complete before they can be paid for that work, and optionally a rate card, work definitions, and a worksite. Its engagementType says what kind of work agreement it is: Contractor (1099), Employee (W-2), EmployeeOfRecord, or AgentOfRecord. Endpoints live under /v3/payments/engagements. Status is Active or Archived.

A Worksite is a physical work location your Account defines once (a name and an address). Engagements and assignments refer to it by worksiteId, and employee pay statements use it to assign state income tax. Endpoints live under /v3/payments/worksites. See Worksites.

PayeeEngagement

A PayeeEngagement is one payee's assignment to one engagement. The Wingspan app calls it an assignment. It has its own lifecycle and determines payment eligibility:

paymentsEligibility (Eligible or NotEligible) tells you whether you can pay the payee through this engagement. It becomes Eligible when the payee has completed the engagement's requirements. When you create a payable with only a payeeId, Wingspan uses your default engagement for that payee, creating it if needed.

Manage a payee's assignments at /v3/payments/payees/{payeeId}/engagements. Read and search assignments across payees at /v3/payments/payee-engagements. See Engagements.

PayerEngagement

A PayerEngagement is the payee's side of the same working relationship. It is a separate resource with its own ID and fields, not a copy of the PayeeEngagement.

Group

A Group is a named set of payees, such as "California contractors" or "Q3 onboarding cohort". Use groups to organize and act on payees in bulk. Endpoints live under /v3/payments/groups. Groups replace V1 collaborator groups for organizing payees. In V1, groups also carried eligibility requirements. In V3, requirements attach to engagements instead. See Groups.

Requirements

A RequirementDefinition is a template for something a payee must provide or complete: a tax verification, a signature, an insurance certificate, a license, a background check, a custom document. You attach definitions to an engagement. See /v3/onboarding/requirement-definitions.

A PayeeRequirement is one payee's instance of a definition. Its status moves through PendingCompletion, PendingPayerReview, and Completed. Inactive is a separate administrative flag for a requirement that you disconnected or cancelled. Expiration is tracked separately from status. See /v3/onboarding/payee-requirements and Requirements and eligibility.

Money: what gets paid

Payable

A Payable is an amount you owe one payee. You create it, open it, approve it, and pay it, either on its own or as part of a payroll run. Line items carry the amounts; the payable's amount is their total.

Approval is a separate field, payerApprovalStatus (Pending, PreApproved, Approved, Declined), that you set independently of status. Only Approved payables are paid by a payroll run.

Paid is Wingspan's internal state. It doesn't mean the money has reached the payee's bank. Deposit confirmation means Wingspan's originating bank or provider reported that it finished processing the payment. It still doesn't mean the recipient's bank received the money, that funds are available, or that the payment can't be returned. See Paid vs DepositConfirmed.

See Payable lifecycle and statuses.

Invoice

An Invoice is the same obligation from the payee's perspective. A contractor creates an invoice to bill a payer, and the payer reviews and pays it. A payable represents "what I owe"; an invoice represents "what I'm owed." Endpoints live under /v3/payments/invoices. See Invoices overview.

Payroll run

A PayrollRun pays many approved payables in one funding movement. A Contractor run pays contractors and vendors: it starts in Draft, and POST .../finalize funds it and moves it to Processing, then Paid when the payouts complete. Endpoints live under /v3/payments/payroll-runs. See Payroll runs.

Deductions and payouts

A Deduction is an amount withheld from what you pay a payee, such as an equipment fee. A Payout is the money Wingspan sends to the payee's payout method. Both live under /v3/payments. See Deductions and credits and Payment and payout methods.

V1 and app terms

Common mistakes

• Using an Account ID where a Payee ID belongs. payeeId on a payable is always the Payee record's id, even after the payee links their Account.
• Waiting for the payee to sign up before creating anything. You can create the Payee, its engagement, and payables right away. The payee needs to complete the engagement's requirements before you can open a payable for them.
• Treating Paid as "the money arrived". It's Wingspan's state, not the recipient bank's.
• Setting status in a PATCH. State changes are POST verbs such as /open, /cancel, and /activate.

Related pages

• Glossary
• Quickstart: invite and pay a contractor
• Acting on behalf of Accounts
• Migrating from V1