Transfer a principal and move an Account

Two Account calls change who owns an Account or where it sits in the tree. One makes a different Person the Account's Principal. The other re-parents the Account.

Prerequisites

An Account credential. Use X-Wingspan-Account when you act on a child Account.
Scope users.account-ownership:write to transfer a Principal. Scope users.account:write to move an Account.
Send an Idempotency-Key on both calls.

Endpoints

Method and path	Operation
`POST /v3/platform/accounts/{accountId}/transfer-principal`	`transferAccountPrincipal`
`POST /v3/platform/accounts/{accountId}/move`	`moveAccount`

Transfer the Principal

The body is { "personId": "..." }, and personId is required. The named Person becomes the Account's Principal. Wingspan creates that Person's Stakeholder row, or promotes it if it exists. Any Account Admin can call it.

This call needs an elevated session from the signed-in Person (step-up), because it's a stakeholder change. A generic Stakeholder PATCH can't promote or demote the Principal. See Team access and roles and Stakeholder invitations.

curl -X POST https://api.wingspan.app/v3/platform/accounts/$ACCOUNT_ID/transfer-principal \
  -H "Authorization: Bearer $WINGSPAN_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{ "personId": "Zk4rT9wQmL2xNb7vHc3PdS" }'

The 200 response is the Account with the new Principal. The id in the example is illustrative.

Status	When
`403`	The caller isn't an Account Admin, or the session isn't elevated.
`404`	The Account or Person isn't visible to the caller.
`409`	The transfer conflicts with the Account's current state.
`422`	The Account is not a business.

Move an Account

The body is { "newParentAccountId": "..." }, and newParentAccountId is required. The call re-parents the Account within the hierarchy and returns the moved Account with 200. It costs two units of rate limit.

curl -X POST https://api.wingspan.app/v3/platform/accounts/$ACCOUNT_ID/move \
  -H "Authorization: Bearer $WINGSPAN_TOKEN" \
  -H "X-Wingspan-Account: $ACCOUNT_ID" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{ "newParentAccountId": "Nw7kQ2pLx9RtVb3mHc5dZa" }'

Status	When
`403`	The caller lacks write authority on the Account.
`404`	The Account or the new parent isn't visible to the caller.
`409`	The move would create a cycle, or cross an organization boundary.
`422`	`newParentAccountId` is missing or invalid.

After a move, read the new position with GET .../ancestors or GET .../parent-link. See Account hierarchy and settings.

Prerequisites

Endpoints

Transfer the Principal

Move an Account

Related pages