Stakeholder invitations

When an Account admin invites a teammate, the invite creates a Stakeholder record on the Account. If the invited email belongs to an existing Active Person, the Stakeholder stays unbound and grants nothing until that Person accepts it. This page covers the Person's side: find pending invitations, accept one, and list the Accounts they're a Stakeholder of.

The admin's side (create the Stakeholder, then POST /v3/platform/accounts/{accountId}/stakeholders/{stakeholderId}/invite) is in Team access and roles.

Prerequisites

• A signed-in Person session for the invited Person. API keys and OAuth tokens aren't accepted for acceptance.
• For no-token acceptance: the Person's email must be verified and must be the invited address. See Person invites and sign-in.
• These calls are Person-scoped. Don't send X-Wingspan-Account.

Endpoints

1. List pending invitations

curl https://api.wingspan.app/v3/platform/persons/$PERSON_ID/stakeholder-invitations \
  -H "Authorization: Bearer $WINGSPAN_TOKEN"

// 200 OK
{
  "url": "/v3/platform/persons/Pe6kQ2pLx9RtVb3mHc5dZa/stakeholder-invitations",
  "data": [
    {
      "stakeholderId": "Sk8vTn2LwX5sYb4kMc7dZa",
      "accountId": "Nw7kQ2pLx9RtVb3mHc5dZa",
      "accountDisplayName": "Northwind Staffing"
    }
  ],
  "pagination": { "nextPageToken": "" }
}

The list holds unexpired invitations addressed to the Person's verified email. A Person whose email isn't verified gets an empty list. accountDisplayName is null when the inviting Account has no business name on record. Supports page[size] and page[token]. Passing another Person's id returns 404.

2. Accept an invitation

Pass the stakeholderId from the list.

# No token: the Person's verified email is the invited address.
curl -X POST https://api.wingspan.app/v3/platform/persons/$PERSON_ID/stakeholders/$STAKEHOLDER_ID/accept \
  -H "Authorization: Bearer $WINGSPAN_TOKEN"

With the single-use token from the invitation email, send { "token": "..." } as the body instead. Acceptance binds the Stakeholder to the Person and activates its grants in one step. The 200 response is the Stakeholder.

3. List the Accounts a Person belongs to

GET /v3/platform/persons/{personId}/stakeholders is the Person-side mirror of an Account's Stakeholder list. It returns every Stakeholder record the Person holds across Accounts. It returns only bound rows, and it includes revoked rows unless you filter. Filters: filter[status][eq] (Active or Revoked) and filter[externalId][eq].

Webhooks

The catalog lists Stakeholder.Created and Stakeholder.Invited. Subscribe with POST /v3/platform/webhooks. See Webhooks and events.

Related pages

• Team access and roles
• Person invites and sign-in