ATathenahq
Team Management

Bulk Invite to Websites or Groups

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. Website invites with a website-scoped key also require the key's creator to be an Admin of every listed website. Direct invites cannot create new accounts with email domains for Cuba, Iran, North Korea, Russia, Belarus, or regional domains for Crimea (including Sevastopol), Donetsk, or Luhansk. The response remains HTTP 201 with success: false and an error for each target in results. General .ua domains remain allowed. Existing accounts can still be invited.

post/api/v1/invites/bulk

Request

  • Base URL
    https://api.athenahq.ai
  • Auth
    API key in header x-api-key

Request body

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.

emailstring 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_idstring

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_idsstring[]

Array of website IDs to invite the user to (1-50). Mutually exclusive with group_ids.

group_idsstring[]

Array of group IDs to invite the user to (1-50). Mutually exclusive with website_ids. Requires a global API key.

first_namestring

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_namestring

Optional last name of the invited user. Used when creating a new user account for 'direct' invites or populating invite records for 'email' invites.

Example request

{
  "invite_method": "direct",
  "email": "user@example.com",
  "role": "viewer",
  "role_id": "789e0123-e89b-12d3-a456-426614174000",
  "website_ids": [
    "123e4567-e89b-12d3-a456-426614174000",
    "987e6543-e21b-12d3-a456-426614174000"
  ],
  "group_ids": [
    "456e7890-e89b-12d3-a456-426614174000",
    "789e0123-e89b-12d3-a456-426614174000"
  ],
  "first_name": "John",
  "last_name": "Doe"
}

Response

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

successboolean required

Whether the bulk operation was processed (always true if request was valid)

Example response

{
  "success": true,
  "results": [
    {
      "website_id": "123e4567-e89b-12d3-a456-426614174000",
      "group_id": "456e7890-e89b-12d3-a456-426614174000",
      "message": "User added to website",
      "error": "User is already a member of this website"
    }
  ]
}

Changes

No recorded changes to this operation across all 3 revisions of this API.