Organizations

This page explains what an Organization is in the V3 API, how it relates to the Accounts you pay from and get paid into, and where Organizations show up in requests and events today.

Accounts, Organizations, and hierarchy

V3 separates three ideas that V1 folded into the single "organization user" record.

Concept	What it is	Holds money, KYB, tax filings?
Account	A business entity (or a contractor's own business). It owns payees, payables, invoices, bank accounts, and tax artifacts.	Yes
Organization	A tenant that groups related Accounts. It's the boundary for tenant-wide machine identities, roles, rate limits, and event subscriptions.	No
Account hierarchy	Accounts can have a parent Account (`parentAccountId`). A parent can act on its descendants.	Not applicable

An Organization never moves money. Anything regulated (bank accounts, KYB, 1099 filing) belongs to an Account, so every entity that pays or gets paid needs its own Account, even inside one Organization.

A child Account inherits its parent's Organization when you create it. The Account's organizationId field tells you which Organization it belongs to.

flowchart TD
  O[Organization: Northwind Group] -.groups.- R
  R[Account: Northwind Holdings<br/>root] --> A[Account: Alpha LLC<br/>child]
  R --> B[Account: Beta Inc<br/>child]
  A --> P1[Payees of Alpha]
  B --> P2[Payees of Beta]

When you need more than one Account

A single Account is enough for a company with a flat structure that pays contractors (and sends invoices) from one legal entity. Use child Accounts when parts of your business need different properties:

Multiple legal entities. A holding company with three subsidiaries, each with its own tax ID, branding, and contractor relationships. Create one child Account per subsidiary under the parent. Each subsidiary files its own 1099s under its own tax ID.
Many markets or business units. A platform operating in many cities, each with its own originating company. One child Account per market keeps payments and year-end filing attributed to the right entity.
A platform with end-client accounts. A software platform that runs contractor payments for its own customers. Each customer is a child Account under the platform's root, and the platform acts on each one without re-authenticating. See Embed Wingspan in your app.

The how-to for creating and operating child Accounts is Parent and child Accounts.

Where Organizations appear in the API

You don't create or edit Organizations through the V3 API yet. The Organization endpoints (/v3/platform/organizations) aren't available in the V3 API yet. Contact support if you need a new Organization set up or want to change one.

You do use Organization IDs in these places:

Where	How
`Account.organizationId`	Read-only pointer on every Account in an Organization. Children inherit it from their parent.
List Accounts	`GET /v3/platform/accounts?filter[organizationId][eq]={organizationId}` returns the Accounts you can see in that Organization.
ServiceAccounts	`ownerType: Organization` creates a machine identity that covers every Account in the Organization. See Team access and roles.
Custom roles	`ownerType: Organization` defines a role once for every Account in the Organization.
Webhook subscriptions	`scope: { "type": "Organization", "id": ..., "shouldIncludeAccounts": true }` receives Organization events plus events for Accounts in that Organization.
Rate limits	Every request is charged to the target Account's bucket and to its Organization's bucket (`organization-read` 2000/s, `organization-write` 1000/s by default). See Rate limiting.

List the Accounts in an Organization:

curl -G https://api.wingspan.app/v3/platform/accounts \
  -H "Authorization: Bearer $WINGSPAN_TOKEN" \
  --data-urlencode "filter[organizationId][eq]=Og3hTq8VnK1pXw6cMd4bRs" \
  --data-urlencode "page[size]=50"

// (trimmed)
{
  "data": [
    {
      "id": "Nw7kQ2pLx9RtVb3mHc5dZa",
      "status": "Active",
      "organizationId": "Og3hTq8VnK1pXw6cMd4bRs",
      "parentAccountId": null,
      "externalId": "northwind-holdings"
    },
    {
      "id": "Ap4tYs8KqW2nLm6xRb1cVe",
      "status": "Active",
      "organizationId": "Og3hTq8VnK1pXw6cMd4bRs",
      "parentAccountId": "Nw7kQ2pLx9RtVb3mHc5dZa",
      "externalId": "entity-alpha"
    }
  ],
  "pagination": { "nextPageToken": "" }
}

What changed from V1

V1	V3
"Organization user account" for every node	An Account for every node. An Organization is a separate tenant record that holds no money.
`POST /users/organization/user` then `/associate`	One call: `POST /v3/platform/accounts` with `parentAccountId`. The parent is fixed at creation.
`inheritanceStrategy` (`Parent` or `None`) for customization and account config	Not available in the V3 API yet. Each Account keeps its own settings.
`X-WINGSPAN-USER` header	`X-Wingspan-Account` header. See Acting on behalf of Accounts.
Master token	A ServiceAccount with an API key, or a Person session. See Team access and roles.

Common mistakes

Treating an Organization as a payer. Payees, payables, and bank accounts belong to Accounts. If an entity pays contractors, give it an Account.
Nesting too deep. V3 supports multi-level hierarchies, but deeper trees are harder to reason about. Most integrations need two or three levels.
Expecting to re-parent later. Moving an Account to a new parent isn't available. Plan the tree before you create Accounts.

Accounts, Organizations, and hierarchy

When you need more than one Account

Where Organizations appear in the API

What changed from V1

Common mistakes

Related pages