API Reference

Invite a Stakeholder

post
https://api.wingspan.app/v3/platform/accounts//stakeholders//invite

Resolve or create the Person for an unresolved natural-human Stakeholder and issue a scoped PersonInvite so the stakeholder can complete their own identity. No payer/payee link request is created. The invite link is emailed to the invitee only (suppress with shouldSendEmail: false); the URL is never returned to the caller — the registration magic link is not shared with the inviter. Resolving the Person activates any staged Role materialization. Account admins and ServiceAccounts with users.authorization:write may invite; a ServiceAccount also needs users.stakeholder-admin:write to invite to a principal row. For an unbound entry whose address belongs to an Active Person, this operation always mails a per-entry acceptance token and returns credentialGrant: false, including when shouldSendEmail: false. The entry stays unbound and grants nothing until the Person accepts it from their own signed-in session, with the mailed token or, when their verified email is the invited address, without it.

Requires a session with recent MFA step-up for HighRiskWriteAction. 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: "HighRiskWriteAction", then retry.

Recent Requests
Log in to see full request history
TimeStatusUser Agent
Retrieving recent requests…
LoadingLoading…
Path Params
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 hexadecimal ID.

string
required

Unique identifier of a Stakeholder record.

Body Params

Issue or re-issue an invite token for a Principal or Person Stakeholder. If email is omitted, the server uses Stakeholder.email, or the resolved Person's email when subjectId is already set. If no email can be resolved, the request returns 422 ValidationError. The invite token is bound to the Stakeholder and Account from the path; the invitee is not asked to link or choose an Account.

string

Invite destination. Also updates Stakeholder.email when supplied. Required when the Stakeholder does not already carry an email and has no resolved Person email.

boolean
Defaults to true

If true, Wingspan emails the invite link to the invitee. If false, no email is sent — the invite is still minted and the invitee can request a link themselves via POST /platform/persons/initialization-links. The invite URL is never included in the response; the registration magic link is not shared with the inviter.

string

ISO 8601 duration. Default P14D. Maximum P30D.

string
length ≤ 4096

Optional message included in the invite email.

uri
string
length ≤ 4096

Internal-only note recorded on the resulting invite.

modules
array of objects

Optional onboarding modules the Stakeholder must complete.

modules
requirementDefinitionNames
array of strings

Optional names of RequirementDefinition records to render as gating modules.

requirementDefinitionNames
Headers
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
^(?:[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

Updated 4 months ago

Did this page help you?
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

Updated 4 months ago

Did this page help you?