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 / authorized-representative data is added separately through Stakeholder records (isPrincipal=true). For a root Account, the gateway assigns the authenticated Person as the bootstrap Account principal, which carries implicit Admin authority and selects that Person's onboarding lane. Clients cannot choose or read this compatibility pointer; replace it through POST /platform/accounts/{accountId}/transfer-principal. Child Account principals remain explicit. ServiceAccount API keys and Account sessions minted by ServiceAccounts can create children only: parentAccountId is required and must match the effective Account, with live Write authority and users.account:write permission. API keys must select that parent with X-Wingspan-Account. Account sessions must include 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 / authorized-representative identity and access are modeled through a Stakeholder (isPrincipal=true) after Account creation. For a standalone Account, the authenticated Person becomes its bootstrap Account principal with implicit Admin authority and owns the Person onboarding lane. Clients cannot choose or read that compatibility pointer; the principal-transfer action replaces it. 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. Child principals are never inferred from the creator. organizationId may accompany parentAccountId only when it matches the parent's Organization.

string
length ≤ 200
profile
object

Presentation-only profile. KYB / identity-of-record lives on ComplianceEntity. The persisted profile fields are logoUrl, supportEmail, supportPhone, locale, timezone, and brandColor. Legacy identity fields below are retained for compatibility; update identity through ComplianceEntity. Supplying profile on an Account update replaces the entire profile; send every existing profile field you intend to preserve.

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. Must match the effective Account selected by X-Wingspan-Account, or the session's bound Account when the header is omitted.

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