---
title: "Bulk Invite to Websites or Groups"
method: POST
path: "/api/v1/invites/bulk"
tags: ["Team Management"]
---

# Bulk Invite to Websites or Groups

`POST /api/v1/invites/bulk`

Invites a user to multiple websites OR multiple groups in a single request. Provide exactly one of `website_ids` or `group_ids` — the two are mutually exclusive. Each target is processed independently, so some may succeed while others fail (e.g., if the user is already a member). In 'email' mode a single consolidated invitation email is sent. Group invites require a global API key.

## Request body

- BulkInviteRequest — Request body for inviting a user to multiple websites or multiple groups. Provide exactly one of `website_ids` or `group_ids` — the two are mutually exclusive. A single consolidated invitation email is sent in 'email' mode.
  - `invite_method` 'direct' | 'email', required — How to invite the user. 'direct' adds the user to each target immediately without sending any email — if no account exists for the email, a new user account is created automatically (with emailVerified=false). 'email' creates pending invite records and sends a single consolidated invitation email.
  - `email` string, email, required — Email address of the user to invite
  - `role` 'admin' | 'viewer' — The role to assign to the invited user on each target. Mutually exclusive with `role_id`.
  - `role_id` string — Assign any role by ID — a system role or one of your organization's custom roles (see `GET /api/v1/roles`). Mutually exclusive with `role`. Returns 404 if the role does not exist or belongs to another organization. Defaults to Viewer when neither `role` nor `role_id` is given. System role IDs are GUID-shaped sentinels (e.g. `00000000-0000-0000-0000-000000000001`), not RFC 4122 UUIDs.
  - `website_ids` string[] — Array of website IDs to invite the user to (1-50). Mutually exclusive with `group_ids`.
  - `group_ids` string[] — Array of group IDs to invite the user to (1-50). Mutually exclusive with `website_ids`. Requires a global API key.
  - `first_name` string — Optional first name of the invited user. Used when creating a new user account for 'direct' invites or populating invite records for 'email' invites.
  - `last_name` string — Optional last name of the invited user. Used when creating a new user account for 'direct' invites or populating invite records for 'email' invites.

## Response `201`

Bulk invite processed. Check individual results for per-target outcomes.

- BulkInviteResponse — Response from a bulk invite request. Each target (website or group) is processed independently.
  - `success` boolean, required — Whether the bulk operation was processed (always true if request was valid)
  - `results` BulkInviteResult[], required — Per-target results (one entry per website or group in the request)
    - `website_id` string, uuid — The website ID this result is for (present only when the request used `website_ids`)
    - `group_id` string, uuid — The group ID this result is for (present only when the request used `group_ids`)
    - `success` boolean, required — Whether the invite was successful for this target
    - `invite_id` string, uuid — The invite ID (only present for successful email invites)
    - `user_id` string, uuid — The ID of the user the invite targets. Present only for successful direct invites. Never returned for email-method invites to prevent cross-tenant account-existence enumeration.
    - `message` string — Success message (present when success is true)
    - `error` string — Error message (present when success is false)

## Other responses

- `400` — Bad request - Invalid parameters
- `401` — Unauthorized - Invalid or missing API key
- `403` — Forbidden - Group invites require a global API key
- `404` — One or more targets not found or do not belong to this organization
- `500` — Internal server error

---

[API](https://skmtc.net/athenahq/apis/athenahq-api.md) · [All operations](https://skmtc.net/athenahq/apis/athenahq-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/athenahq/athenahq-api/versions/6c5d71622cb9/schema)