Account hierarchy and settings

This page covers the Account calls that sit around create and update: navigating the tree, the link between a child and its parent, product entitlements, settings, eligibility, entity-type changes, and search. To create a child Account and send requests as one, see Parent and child Accounts.

Prerequisites

An Account credential, a Person session, or a ServiceAccount that can access the Account in the path. Every call here is Account-scoped, so use X-Wingspan-Account when you act on a child.
Scopes: users.account:read for reads and users.account:write for writes.

Endpoints

Method and path	Operation
`GET /v3/platform/accounts/{accountId}/children`	`listAccountChildren`
`GET /v3/platform/accounts/{accountId}/ancestors`	`getAccountAncestors`
`GET /v3/platform/accounts/{accountId}/hierarchy`	`getAccountHierarchy`
`GET /v3/platform/accounts/{accountId}/parent-link`	`getAccountParentLink`
`PATCH /v3/platform/accounts/{accountId}/parent-link`	`updateAccountParentLink`
`POST /v3/platform/accounts/{accountId}/associate`	`associateAccount`
`GET /v3/platform/accounts/{accountId}/entitlements`	`listAccountEntitlements`
`GET /v3/platform/accounts/{accountId}/settings`	`getAccountSettings`
`PATCH /v3/platform/accounts/{accountId}/settings`	`updateAccountSettings`
`GET /v3/platform/accounts/{accountId}/eligibility`	`getAccountEligibility`
`POST /v3/platform/accounts/{accountId}/change-entity-type`	`changeAccountEntityType`
`POST /v3/platform/accounts/{accountId}/move`	`moveAccount`
`POST /v3/platform/accounts/{accountId}/transfer-principal`	`transferAccountPrincipal`
`POST /v3/platform/accounts/search`	`searchAccounts`

Navigate the tree

Children. GET .../children returns the accessible direct children, one level down. Closed children are left out. It supports page[size] (1 to 200) and page[token], and filter[externalId][eq].
Ancestors. GET .../ancestors returns the accessible ancestors from the root down to the immediate parent, for breadcrumbs. Closed ancestors are walked for continuity but omitted from the response. The body is { "accountId", "data": [Account] }.
Hierarchy. GET .../hierarchy returns the full tree of descendants. Each node has id, accountId, email, firstName, lastName, companyName, and a nested children array.

Read and update the parent link

The parent link holds the inheritance mode for each kind of setting between a child and its parent. For the meaning of the modes see Parent and child Accounts.

GET .../parent-link returns id, accountId, parentAccountId, inheritance, metadata, events, and actors. A root Account, or a child with no link, returns 404. A link is never created by a first write.

PATCH .../parent-link takes at least one of:

Field	Notes
`inheritance`	Any of `branding`, `payerSettings`, `paymentMethods`, `internalAccounts`, `customFields`, `payeeRequirements`, `rateCards`, `complianceEntity`. Each value is `Overridable`, `Enforced`, or `Disabled`. A mode can't be `null`.
`metadata`	Merges by key. A `null` value removes the key. Up to 50 keys, values up to 500 characters. Keys can't start with `$` or contain a dot.

Omitted keys stay as they are. Parent and Organization ids can't be changed.

curl -X PATCH https://api.wingspan.app/v3/platform/accounts/$CHILD_ID/parent-link \
  -H "Authorization: Bearer $WINGSPAN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "inheritance": { "branding": "Enforced", "rateCards": "Disabled" }, "metadata": { "region": "west" } }'

The call needs Write authority on the parent Account. The child's own admin, Principal, or API key can't change the link without it. Errors: 404 when there's no link, 422 for an invalid value.

Associate an existing Account

POST .../associate takes { "parentAccountId": "..." }. It links an Account that has no parent to that parent. If the Account already has a parent it returns 409; use move instead.

Entitlements

GET .../entitlements returns { "data": [ ... ] }, one entry per recorded product:

Field	Meaning
`productCode`	`ContractorPayments`, `ArInvoicing`, or `SCorpPayroll`.
`provisioningPending`	`true` while the product is still being activated. `state` is absent then.
`state`	`Active` allows new work and reads. `OffBoarding` allows reads and finishing in-flight work. `Removed` allows nothing.
`notAfter`	Access ends at this time, when present.

A product appears after its purchase or grant is recorded, which can lag the purchase.

Settings

GET .../settings returns the Account's settings singleton. PATCH .../settings applies a JSON Merge Patch.

Field	Notes
`enabledServices`	Array of service names.
`payrollConfig`	`defaultPaySchedule` (`Weekly`, `Biweekly`, `SemiMonthly`, `Monthly`) and `approvalDeadlineHours`.
`isTwoFactorEnabled`	Boolean.
`notificationPreferences`	Deprecated. Channel preferences now belong to the Person's notification channel settings.

Eligibility

GET .../eligibility returns the Account's onboarding and verification status: isEligible, a requirements count (total, complete, incomplete, blocking), missingFields[], and verificationStatus for tax, banking, and enhanced, each None, Pending, Verified, or Failed. GET /v3/onboarding/status returns a similar summary for the contractor's own Account. See Identity verification.

Change the entity type

POST .../change-entity-type starts an asynchronous change to the Account's regulated entity type. The Account id stays the same.

Field	Required	Notes
`targetEntityType`	Yes	`SoleProp`, `SCorp`, `CCorp`, `Partnership`, `Trust`, `Other`, `LlcSCorp`, `LlcCCorp`, or `LlcPartnership`.
`effectiveDate`	No	Date. Defaults to when the operation completes.
`bankAccountStrategy`	No	`Transfer` (default) keeps existing financial accounts when supported. `Reissue` opens new ones and closes the old ones.

curl -X POST https://api.wingspan.app/v3/platform/accounts/$ACCOUNT_ID/change-entity-type \
  -H "Authorization: Bearer $WINGSPAN_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{ "targetEntityType": "LlcSCorp", "bankAccountStrategy": "Transfer" }'

The 202 response is an AsyncOperation (id, operationType, status). The Location header is the polling URL and Retry-After is a suggested delay in seconds. Poll GET /v3/platform/operations/{id} until status leaves Processing.

Status	When
`404`	The Account isn't visible to the caller.
`409 ResourceLocked`	Funds movements on the Account aren't terminal yet. Retry after they finish.
`422`	`targetEntityType` is missing or isn't a listed value.

The catalog lists Account.EntityTypeChanged and Account.EntityTypeChangeFailed. Subscribe with POST /v3/platform/webhooks. See Webhooks and events.

Search Accounts

POST /v3/platform/accounts/search takes a JSON body and returns an AccountList page.

Field	Notes
`query`	Free-text string.
`filters`	Structured filter object.
`sort`	Comma-separated fields. Prefix with `-` for descending, for example `-createdAt`.
`limit`	1 to 100, default 25.

Send an Idempotency-Key and, on a child, X-Wingspan-Account. Scope users.account:read. Errors: 401, 403, and 422 for an invalid body.