---
title: "Email a time-limited setup checklist capability to a delegate"
method: POST
path: "/onboarding/v3/delegate-invites"
tags: ["Onboarding"]
---

# Email a time-limited setup checklist capability to a delegate

`POST /onboarding/v3/delegate-invites`

## Request

- Base URL: `https://api.medianfi.com/api/v1`
- URL: `https://api.medianfi.com/api/v1/onboarding/v3/delegate-invites`
- Auth: HTTP bearer

A newly minted raw 256-bit capability is returned once inside delegateUrl and sent by email; only its SHA-256 digest is stored. Retrying the same identity while its server-owned checklist remains live reuses that invite, sends no second email, and omits delegateUrl. A pending invite is inert until delivery succeeds; failed replacement delivery revokes only that pending invite and preserves the prior active checklist and assignments. QA delivery is SendGrid sandbox-only (or recipient-allowlisted); live delivery requires the separate promotion-time environment flip.

## Headers

- `X-Median-App-Surface` 'qa'

## Request body

- OnboardingV3DelegateInviteCreate
  - `name` string, required
  - `email` string, email, required

## Response `200`

Matching live delegate capability reused without another email

- OnboardingV3DelegateInviteApiResponse
  - `success` true, required
  - `data` union, required: A newly minted capability is returned once with its URL. An identical live retry returns the current public invite without exposing that capability again.
    - OnboardingV3DelegateInviteCreated
      - `id` string, uuid, required
      - `name` string, required
      - `email` string, email, required
      - `taskIds` OnboardingV3DelegatedTaskId[], required
      - `status` 'sent' | 'opened' | 'revoked' | 'done', required
      - `createdAt` string, date-time, required
      - `expiresAt` string, date-time, required
      - `reused` false, required
      - `delegateUrl` string, uri, required: Returned once for a newly minted invite; contains the raw capability.
    - OnboardingV3DelegateInviteReused
      - `id` string, uuid, required
      - `name` string, required
      - `email` string, email, required
      - `taskIds` OnboardingV3DelegatedTaskId[], required
      - `status` 'sent' | 'opened' | 'revoked' | 'done', required
      - `createdAt` string, date-time, required
      - `expiresAt` string, date-time, required
      - `reused` true, required: An identical live invite was reused without sending email.

## Other responses

- `201`: Delegate capability minted and email accepted
- `400`: Onboarding request body is not valid JSON
- `401`: Authentication required
- `403`: Insufficient permissions or not a company member
- `404`: Resource not found
- `409`: Request conflicts with the durable onboarding state
- `413`: Onboarding setup request exceeds the 32768-byte route limit
- `415`: Onboarding request charset or content encoding is unsupported
- `422`: Validation error
- `429`: Retry after the indicated number of seconds
- `503`: Required sandbox provider configuration or service is unavailable

---

[API](https://skmtc.dev/medianfi/apis/median-api.md) · [All operations](https://skmtc.dev/medianfi/apis/median-api/llms.txt) · [OpenAPI document](https://skmtc.dev/medianfi/apis/median-api/revisions/20090ea32b0d?raw)