---
title: "Queue emailed onboarding links for many IdP users"
method: POST
path: "/organizations/{organizationId}/idp-users/onboarding-links"
tags: ["Organizations"]
---

# Queue emailed onboarding links for many IdP users

`POST /organizations/{organizationId}/idp-users/onboarding-links`

## Request

- Base URL: `https://api.xfa.tech`
- URL: `https://api.xfa.tech/organizations/{organizationId}/idp-users/onboarding-links`
- Auth: HTTP bearer

Classifies each requested user (up to 500) and queues an onboarding-link email for the sendable ones; a worker mints, emails and records each link shortly after, re-checking right before minting that the user has not enrolled meanwhile. Skipped users are reported with their reason: not_provisioned, no_recovery_email, already_enrolled, enrollment_unknown (identity could not be asked; skipped to fail closed), recently_sent (a link went out less than 7 days ago, unless resend_recent) or invalid_email. Returns 202 because queued users have not been emailed yet. Requires an organization administrator.

## Path parameters

- `organizationId` string, required

## Request body

- IdpUsersOnboardingLinksRequest
  - `emails` string[], required
  - `resend_recent` boolean: Also queue users whose link was sent less than 7 days ago. Without it the worker also skips a user whose link went out less than 5 minutes before it runs (a duplicate send).

## Response `202`

Users classified; sendable ones queued

- IdpUsersOnboardingLinksResponse
  - `queued` integer, required: Users queued for an emailed onboarding link
  - `results` object[], required: One entry per distinct normalized email, in request order
    - `email` string, required
    - `status` 'queued' | 'invalid_email' | 'not_provisioned' | 'no_recovery_email' | 'already_enrolled' | 'enrollment_unknown' | 'recently_sent' | 'enqueue_failed', required

## Other responses

- `400`: invalid_json, no_emails or too_many_emails
- `403`: Not authorized
- `404`: organization_not_found
- `409`: idp_connection_required or multiple_idp_connections

---

[API](https://skmtc.dev/xfa/apis/xfa-api.md) · [All operations](https://skmtc.dev/xfa/apis/xfa-api/llms.txt) · [OpenAPI document](https://skmtc.dev/xfa/apis/xfa-api/revisions/1a1be0e8972b?raw)