Onboard invited users into an organisation through the API

Accept an organisation invitation through the API, run the invitee onboarding workflow, poll typed deployment status without SSE, and retry a failed onboarding from a clean slate.

Use the invitation onboarding API to bring an invited user into an existing organisation. It runs the invitee provisioning workflow, then reports progress the same way the organisation deployment API does, so a client that already polls or streams organisation deployment reuses the same handling here.

The organisation-creation path lives in the Organisation deployment API. For the invited-user experience in the Console, see Invite users.

When to use each endpoint

The request surface is intentionally minimal. The caller supplies only an invitation identifier; the platform derives the organisation, the invitee address, and whether to create a wallet from the invitation record and an on-chain wallet probe. A client cannot force those inputs.

Job	Method and path	Use it for
Start onboarding	`POST /api/v2/invitations`	Accept an invitation for a new user and start the onboarding workflow.
Accept for existing user	`POST /api/v2/invitation-acceptances`	Accept an invitation for a user who already has a wallet. Wallet creation is skipped automatically.
Read deployment status	`GET /api/v2/invitations/deployments/{deploymentId}`	Poll structured status without an event stream.
Stream deployment progress	`GET /api/v2/invitations/deployments/{deploymentId}/stream`	Track progress over server-sent events.
Prepare a retry	`POST /api/v2/invitation-retries`	Clear a failed onboarding so the next start runs from a clean slate.

Both start endpoints take the same body and return the same shape. Use POST /api/v2/invitations for an invitee who has no wallet yet, and POST /api/v2/invitation-acceptances for an invitee who already has one. If you call the new-user endpoint for a user who already has a wallet, the platform still completes onboarding correctly; it probes for the wallet on-chain rather than trusting the request.

Start onboarding

Send the invitation identifier in the request body. The platform validates the invitation server-side, rejecting a not-found, expired, revoked, or email-mismatched invitation before it starts any provisioning.

curl -X POST "$DALP_API_URL/api/v2/invitations" \
  -H "Content-Type: application/json" \
  -H "Prefer: respond-async" \
  -b "$DALP_SESSION_COOKIE" \
  -c /tmp/dalp-invite.cookies \
  -d '{ "invitationId": "Xk7pQm2rT9wYbN4vL1aC0sE6dF3hJ8gZ" }'

invitationId is the invitation record identifier, a required string. It accepts letters, digits, and the _ and - characters. The Prefer: respond-async header asks the platform to start the workflow and return immediately; see Synchronous and asynchronous responses for the wait and backpressure options.

A successful start returns a deploymentId and the initial progress tree:

{
  "deploymentId": "invitation_Xk7pQm2rT9wYbN4vL1aC0sE6dF3hJ8gZ_1752604800000",
  "tree": [
    { "id": "token", "label": "Validating Invitation", "type": "other", "status": "pending" },
    { "id": "wallet", "label": "Creating Your Wallet", "type": "wallet", "status": "pending" },
    { "id": "identity", "label": "Attaching Identity", "type": "identity", "status": "pending" },
    { "id": "membership", "label": "Granting Membership", "type": "role", "status": "pending" },
    { "id": "smart-wallet", "label": "Provisioning Smart Wallet", "type": "wallet", "status": "pending" }
  ]
}

Each node carries an id, a label, a semantic type, and a status of pending, in-progress, awaiting-approval, completed, or failed. Display text can change, so key your integration off id, type, and status rather than the label. The deployment tree and event protocol match organisation deployment; see Monitor deployment progress for the node and event reference.

Synchronous and asynchronous responses

Onboarding runs asynchronously by default. The platform accepts the request, starts the workflow, and returns a response that points at the status read so you can poll until the workflow reaches a terminal state.

To wait inline instead, send a Prefer: wait=N header, where N is the number of seconds you are willing to wait. The platform attaches to the running workflow and returns the terminal result if the workflow finishes within that budget. When the budget elapses first, the response degrades back to the asynchronous shape that points at the status read. The response reports which preference the platform honoured.

When the chain indexer is catching up, the platform normally lets the workflow wait the reindex out. Send the Prefer: dalp-fail-on-indexer-reindexing directive to opt into backpressure instead: while the indexer is reindexing, the platform rejects the start request and returns a retry hint rather than queuing the workflow. Only the onboarding endpoints honour this directive.

Read deployment status

Poll the status read when you onboard without an event stream, or when a client reconnects and needs server truth after a reload.

curl "$DALP_API_URL/api/v2/invitations/deployments/invitation_Xk7pQm2rT9wYbN4vL1aC0sE6dF3hJ8gZ_1752604800000" \
  -b /tmp/dalp-invite.cookies

For an authorised caller, the read returns a status field with one of four values. Branch on that field rather than on transport signals:

`status`	Meaning	Client handling
`in-progress`	The onboarding workflow is running.	Keep polling.
`completed`	Onboarding finished successfully.	Stop polling and continue the invitee into the organisation.
`failed`	Onboarding failed for good.	Stop polling and surface the failed steps to the user.
`absent`	No workflow exists for this deployment identifier.	Stop polling and restart onboarding or recover the session.

{
  "data": {
    "deploymentId": "invitation_Xk7pQm2rT9wYbN4vL1aC0sE6dF3hJ8gZ_1752604800000",
    "status": "in-progress",
    "tree": [
      { "id": "token", "label": "Validating Invitation", "type": "other", "status": "completed" },
      { "id": "wallet", "label": "Creating Your Wallet", "type": "wallet", "status": "completed" },
      { "id": "identity", "label": "Attaching Identity", "type": "identity", "status": "in-progress" },
      { "id": "membership", "label": "Granting Membership", "type": "role", "status": "pending" },
      { "id": "smart-wallet", "label": "Provisioning Smart Wallet", "type": "wallet", "status": "completed" }
    ]
  },
  "links": {
    "self": "/api/v2/invitations/deployments/invitation_Xk7pQm2rT9wYbN4vL1aC0sE6dF3hJ8gZ_1752604800000"
  }
}

The tree, success, and failedSteps fields appear when the workflow has produced them; treat them as optional. A terminal failure reports status: failed with success: false and, when available, the steps that failed:

{
  "data": {
    "deploymentId": "invitation_Xk7pQm2rT9wYbN4vL1aC0sE6dF3hJ8gZ_1752604800000",
    "status": "failed",
    "success": false
  },
  "links": {
    "self": "/api/v2/invitations/deployments/invitation_Xk7pQm2rT9wYbN4vL1aC0sE6dF3hJ8gZ_1752604800000"
  }
}

The status read enforces the same access rule as the stream. The platform re-validates the invitation against the caller's session, then requires the supplied deploymentId to match the key it derives from that record. The outcome depends on why a lookup fails, so handle two distinct cases:

When the identifier encodes an invitation that belongs to a different signed-in user, the platform returns an email-mismatch error, not a not-found response. Treat this as an access denial rather than a missing deployment.
When the identifier is malformed, points at an invitation that no longer exists, or carries a stale key from a superseded invitation (re-issuing an invitation mints a fresh key), the platform reports the deployment as not found.

The stream applies the same rule, so a client subscribing on behalf of the wrong user receives the email-mismatch error before the connection opens.

Stream deployment progress

Open the event stream when you want push updates instead of polling. Reuse the cookie jar from the start request so the platform keeps the active-organisation context for the connection.

curl -N "$DALP_API_URL/api/v2/invitations/deployments/invitation_Xk7pQm2rT9wYbN4vL1aC0sE6dF3hJ8gZ_1752604800000/stream" \
  -H "Accept: text/event-stream" \
  -b /tmp/dalp-invite.cookies

The stream emits the same event types as organisation deployment.

Event type	Payload fields	Client handling
`tree`	`nodes`	Replace the local deployment tree with the received tree.
`update`	`nodeId`, `status`, optional `error`	Patch the matching node in the local tree.
`complete`	`success`, optional `failedSteps`	Stop listening. If `success` is false, show the failed step details.
`error`	`message`, `error`	Stop listening and inspect the public Platform API error payload.

A complete event is terminal for that stream. Reconnect only when the terminal error is retryable or when the operator restarts the deployment. See Monitor deployment progress for additional client handling guidance.

Retry a failed onboarding

When onboarding fails, prepare a retry before you start again. The retry endpoint clears the prior failed run so the next start begins from a clean slate.

curl -X POST "$DALP_API_URL/api/v2/invitation-retries" \
  -H "Content-Type: application/json" \
  -b /tmp/dalp-invite.cookies \
  -d '{ "invitationId": "Xk7pQm2rT9wYbN4vL1aC0sE6dF3hJ8gZ" }'

{ "ready": true }

The retry response confirms readiness only. It does not return a deploymentId or a tree. After it returns ready, re-submit the same start endpoint you used before to begin a fresh onboarding run, then read its new deploymentId from that response.

Follow this sequence for a resilient client:

Start onboarding once and store the returned deploymentId with the invitee session.
Poll the status read, or subscribe to the stream, until the status is completed or failed.
On failed, call the retry endpoint, then start onboarding again and store the new deploymentId.
On absent after a reload, restart onboarding rather than waiting on a deployment that no longer exists.

Fields

Field	Location	Type	Notes
`invitationId`	Body	string	Invitation record identifier. Accepts letters, digits, `_`, and `-`. Required.
`deploymentId`	Path	string	Deployment key returned by the start endpoint. Used by the status read and stream.
`status`	Response	enum	`in-progress`, `completed`, `failed`, or `absent` on the status read.
`tree`	Response	deployment node[]	Progress tree. Present once the workflow has produced one.
`success`	Response	boolean	Terminal success flag. Present on terminal responses.
`failedSteps`	Response	failed step[]	Failing steps on a failed onboarding. Present when the platform can report them.
`ready`	Response	`true`	Confirms a prepared retry. Returned by the retry endpoint only.

Organisation deployment API documents the deployment tree, the SSE event protocol, and the organisation-creation path this API mirrors.
Invite users covers the invitation experience in the Console.
Request headers explains the Prefer directives and the participant and executor headers for later calls.
Platform API error reference lists the error responses you can receive from these endpoints.

Invitation onboarding API