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.

If externalId is supplied and already used by another resource of this type for the owning Account, the request returns 409 ResourceConflict; create is not an upsert. Use filter[externalId][eq] on the list endpoint to retrieve the existing resource.

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.

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
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