Update a Stakeholder

patch

https://api.wingspan.app/v3/platform/accounts/{accountId}/stakeholders/{stakeholderId}

Partial update. subjectId and subjectType are immutable from the caller's perspective; subjectId is set by the server when an unresolved natural-human Stakeholder resolves. Principal authority is transferred only through POST /platform/accounts/{accountId}/transfer-principal. Setting roleId, roleIds or scopes on an Account-typed Stakeholder returns 422 ValidationError.
Unresolved email updates, Principal controller defaults, and subject-bearing accountSuppliedComplianceEntityId updates are backed by the users service.

Requires a session with recent MFA step-up for StakeholderChange. If step-up is missing or expired, this operation returns 403 StepUpMfaRequired; create and verify an MFA challenge at /v3/platform/mfa-challenges with requiredFor: "StakeholderChange", then retry.

Recent Requests

Time	Status	User Agent
Retrieving recent requests…

Loading…

Path Params

accountId

string

required

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

Account identifier. Newly created V3 Accounts use a 22-character Wingspan ID; migrated Accounts may retain a 24-character lowercase Mongo ObjectId.

stakeholderId

string

required

Unique identifier of a Stakeholder record.

Body Params

Partial update. subjectType, subjectId, and isPrincipal are caller-immutable. Principal authority is transferred only through POST /platform/accounts/{accountId}/transfer-principal. subjectId is set by the server when an unresolved Person Stakeholder invite resolves or creates the Person. Setting email, roleId, roleIds, scopes, isController=true, or accountSuppliedComplianceEntityId on an Account Stakeholder returns 422 ValidationError. PATCH semantics: omitted fields are left unchanged; explicit null clears nullable fields. identitySource is read-only (server-managed). Principal transfer and revocation run the same PrincipalLockedByActiveEngagement checks used for employee / EOR payroll anchoring.
Implementation status: unresolved email updates and staged subject-bearing ComplianceEntity attachment are backed by the users service.

externalId

string | null

Update or clear the unresolved Principal or Person Stakeholder's invite email. Natural-human only. Clearing is rejected while an outstanding invite is pending unless the invite is cancelled/reissued.

accountSuppliedComplianceEntityId

string | null

Re-point a staged subject-bearing ComplianceEntity. The CE must be Account-owned, current, Individual, and subject-bound to this Stakeholder id. Send explicit null to clear the staged CE and, when a Person member is linked, return identitySource to PersonOwned. Natural-human only.

roleId

string | null

^(role_[a-zA-Z0-9_-]+|[A-Z][a-z0-9]+(?:[A-Z][a-z0-9]+)*)$

Replaces the member's roles with this one Role. Send null to remove every role. Send roleId or roleIds, not both.

roleIds

array of strings | null

Replaces the member's roles with this list. Send [] or null to remove every role. Send roleId or roleIds, not both.

roleIds

roleFilters

object | null

PATCH form of RoleAssignmentFilters. Explicit null clears the assignment filters; an object replaces them.

scopes

array of strings

deprecated

Deprecated. Use AuthorizationCreate for access beyond roleId.

scopes

ownershipPercentage

float

0 to 100

isController

boolean

Natural-human only. isPrincipal=true is always controller / authorized representative; explicit false is rejected for a Principal.

controllerBasis

string | null

enum

Allowed:

controlNatures

array of strings, unique

ownershipBand

string | null

noControllerIdentifiedReason

string | null

metadata

object

Free-form key-value pairs. Max 50 keys; key length at most 40 characters; value length at most 500 characters. Where a list endpoint declares metadata filtering, it uses the QueryQL namespace via filter[metadata.{key}][eq]=value or filter[metadata.{key}][in][]=value. Endpoints that do not declare the dynamic Metadata filter do not support Metadata filtering.

Headers

Idempotency-Key

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.

X-Wingspan-Account

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

enum

Defaults to application/json

Generated from available response content types

Allowed:

Responses

200Stakeholder updated

401Unauthenticated

403Forbidden or step-up MFA required

404Resource not found

422Validation error