---
title: "Create Invite"
method: POST
path: "/api/v1/invites"
tags: ["Team Management"]
---

# Create Invite

`POST /api/v1/invites`

Invites a user to your organization, a specific website, or a group. Use `invite_method: "direct"` to add the user immediately without sending any email — if the email has no existing account, a new user account is created automatically. Use `invite_method: "email"` to create a pending invite and send an invitation email that the recipient must accept. Group invites require a global API key.

## Request body

- CreateInviteRequest — Request body for creating an invite
  - `type` 'organization' | 'website' | 'group', required — The type of invite. 'organization' grants org-wide access, 'website' grants access to a single website, 'group' grants access to all websites in a group. Group invites require a global API key.
  - `invite_method` 'direct' | 'email', required — How to invite the user. 'direct' adds the user to the resource immediately without sending any email — if no account exists for the email, a new user account is created automatically (with emailVerified=false) and the membership is added. 'email' creates a pending invite record and sends an invitation email via Postmark; the user must accept the invite to gain access.
  - `email` string, email, required — Email address of the user to invite
  - `role` 'admin' | 'viewer' — The role to assign to the invited user. 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_id` string, uuid — Required when type is 'website'. The ID of the website to grant access to
  - `group_id` string, uuid — Required when type is 'group'. The ID of the group to grant access to. 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 the invite record 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 the invite record for 'email' invites.

## Response `201`

User added or invitation sent successfully

- InviteResponse — Response from creating an invite
  - `success` boolean, required — Whether the operation was successful
  - `invite_id` string, uuid — The ID of the created invite (only present for email invites)
  - `user_id` string, uuid — The ID of the user the invite targets. Present only for direct invites (the user is looked up or created immediately). Never returned for email-method invites to prevent cross-tenant account-existence enumeration.
  - `message` string, required — A message describing the result

## Other responses

- `400` — Bad request - Invalid parameters or email send failure
- `401` — Unauthorized - Invalid or missing API key
- `403` — Forbidden - Group invites require a global API key
- `404` — Resource not found
- `409` — Conflict - User already exists or invite pending
- `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)