Create an Account

Creates a new Account under the given parent. Provisions the container that holds a customer's money, KYB, and tax artifacts before any other resource is attached. Principal and authorized-representative data are added separately through Stakeholder records: the Principal with isPrincipal=true, the authorized representative with isController=true. The creator receives Admin access. No Principal is assigned at creation. A business of one (a sole proprietorship, a single-member LLC, or a single-owner S-corporation) sets its Principal with POST /platform/accounts/{accountId}/transfer-principal, or by creating a Stakeholder for the Person who becomes Principal with isPrincipal=true; a business with more than one owner has no Principal. ServiceAccount API keys and Account sessions minted by ServiceAccounts can create children only: parentAccountId is required, and the ServiceAccount needs live Write authority on that parent that extends to new child Accounts, plus users.account:write permission. API keys must send X-Wingspan-Account. Account sessions must include descendants, and the parent must be the bound Account or one of its descendants; their header is optional and defaults to the bound Account, or may select a descendant. These sessions inherit the minting key's scopes; the mint request cannot narrow them. To mint embedded sessions without child-create permission, use a key without users.account:write. Person callers MUST NOT send X-Wingspan-Account. Account-bound Person sessions, leaf Account sessions, and impersonation-issued sessions cannot create new Accounts. Idempotency-Key replay is partitioned by the effective Account whenever one exists, and by the authenticated Person only for unbound, headerless Person callers. The shared response cache may replay a stored response without executing a new create.

A non-empty externalId is unique within an Account hierarchy: a root Account and every Account beneath it. Accounts carried over from Wingspan's earlier account model each start their own hierarchy for this rule, even when they have a parentAccountId. If another Account in the same hierarchy already uses the supplied externalId, the request returns 409 ResourceConflict; create is not an upsert. The Account holding the value may be one the caller cannot list, such as a Closed Account or one outside the caller's access. When it is visible, filter[externalId][eq] on the list endpoint returns it.

Recent Requests
Log in to see full request history
TimeStatusUser Agent
Retrieving recent requests…
LoadingLoading…
Body Params

Creates the Account container only. Principal and authorized-representative identity and access are modeled through Stakeholder records after Account creation: the Principal with isPrincipal=true, the authorized representative with isController=true. The creator receives Admin access. No Principal is assigned at creation. A business of one (a sole proprietorship, a single-member LLC, or a single-owner S-corporation) sets its Principal with POST /platform/accounts/{accountId}/transfer-principal, or by creating a Stakeholder for the Person who becomes Principal with isPrincipal=true; a business with more than one owner has no Principal. A standalone Account omits both hierarchy fields. To create a child, supply parentAccountId; the caller must have Write authority on that parent and the child inherits its Organization. organizationId may accompany parentAccountId only when it matches the parent's Organization. inheritance is allowed only with a parent. Every omitted kind defaults to Overridable. entitlements is allowed only with a parent, which must hold each listed entitlement in Active state. If an entitlement cannot be granted after the Account is written, the request fails but the child exists; see entitlements.

string
length ≤ 200
profile
object

Presentation-only profile. KYB / identity-of-record lives on ComplianceEntity. The stored profile fields are logoUrl, supportEmail, supportPhone, locale, timezone, brandColor, and company.links. Supplying profile on an Account update replaces the presentation fields; send every presentation field you want to keep. company.links is projected from the legacy Member. Omitting company preserves its links; supplying company replaces its links (an empty company clears them).

string

Must be accompanied by parentAccountId and match the parent Organization.

string
^(?:[A-Za-z0-9_.]{22}|[a-f0-9]{24})$

Existing parent Account on which the caller has Write access. Required for ServiceAccount callers using an API key or a descendant-inclusive Account session minted by a ServiceAccount. For an Account session, it must be the bound Account or one of its descendants.

inheritance
object
entitlements
array of objects
length ≤ 14

Entitlements the parent shares with the new child, as with POST /platform/accounts/{accountId}/entitlements. Requires parentAccountId. Only subscription entitlements can be shared, and the parent must hold each one in Active state; otherwise no Account is created. The refusal carries detailCode users.EntitlementNotShareable (422) or users.ParentEntitlementNotActive (409). If an entitlement cannot be granted after the Account is written, for example when a downstream service fails, the request fails but the child exists. Find it with GET /platform/accounts/{parentAccountId}/children or by its externalId, and finish with POST /platform/accounts/{accountId}/entitlements. Send externalId so that a retry returns 409 instead of creating a second child.

entitlements
metadata
object

Customer metadata. The key __ws_create_account_idempotency_key is reserved for transport use and is rejected when supplied by a client.

Headers
string
^(?:[A-Za-z0-9_.]{22}|[a-f0-9]{24})$

Select the Account for an Account-scoped operation. A direct ServiceAccount API key MUST supply this header, and the target must be within the ServiceAccount owner's or Authorization grant's Account boundary. A Person bearer may select an Account on which it has an active Stakeholder, and an Account session may select its bound Account (or a descendant only when the session explicitly includes descendants).

string
length between 1 and 255
^[\x21-\x7e]{1,255}$

Optional idempotency token for authenticated POST and PATCH requests. Reusing the same key and body returns the cached response for 24 hours, except credential operations that explicitly document a 409 because one-time secret material is never cached; reusing it with a different body returns 409 IdempotencyKeyConflict. Use 1-255 printable ASCII characters.

string
enum
Defaults to application/json

Generated from available response content types

Allowed:
Responses

Language
Credentials
Bearer
JWT
LoadingLoading…
Response
Click Try It! to start a request and see the response here! Or choose an example:
application/json
application/problem+json