> ## Documentation Index
> Fetch the complete documentation index at: https://docs.zapnito.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Invitations API

> Send an invitation email to join your Zapnito community through the API, and optionally place the invitee in a specific group.

Trigger an invitation email that lets a person join your community. You can also place the invitee in a specific group when they accept.

Before you start, read the [API overview](/api/v1/overview) for how authentication, headers, pagination and errors work.

## Trigger an invitation

Send an invitation on behalf of an existing user.

<ParamField body="user.name" type="string">
  The full name of the person you're inviting.
</ParamField>

<ParamField body="user.email" type="string">
  The email address of the person you're inviting.
</ParamField>

<ParamField body="user.invited_by_email" type="string">
  The email address of the user sending the invitation. This user must have the abilities needed to send invitations.
</ParamField>

<ParamField body="user.origin_content_url" type="string">
  The URL of the content to send the invitee to after they complete the invitation process.
</ParamField>

<ParamField body="user.group_uuid" type="string">
  The UUID of the group to add the user to when they accept the invitation. You can find the UUID in the group's settings in your community.
</ParamField>

```bash title="Trigger an invitation" theme={null}
curl -X POST "https://your-community.zapnito.com/api/v1/invitations" \
  -H "Authorization: Token token=YOUR_API_TOKEN" \
  -H "Content-Type: application/json; charset=utf-8" \
  -d '{
    "user": {
      "name": "Maya Patel",
      "email": "maya.patel@example.com",
      "invited_by_email": "sam.jones@example.com",
      "group_uuid": "a1ecad96-8849-45ba-821e-20199cde45cd"
    }
  }'
```

`POST https://your-community.zapnito.com/api/v1/invitations`

<ResponseExample>
  ```json 200 OK theme={null}
  {
    "invitation": {
      "name": "Maya Patel",
      "email": "maya.patel@example.com",
      "invited_by_email": "sam.jones@example.com",
      "origin_content_url": "https://your-community.zapnito.com/posts/preparing-for-an-audit",
      "group_uuid": "a1ecad96-8849-45ba-821e-20199cde45cd"
    }
  }
  ```

  ```json 403 Forbidden theme={null}
  {
    "error": "sam.jones@example.com does not have the 'create_invitation_with_group' ability"
  }
  ```

  ```json 404 Not Found theme={null}
  {
    "error": "Group not found for provided UUID 'uuid-that-does-not-exist'"
  }
  ```

  ```json 422 Unprocessable Entity theme={null}
  {
    "errors": {
      "email": ["is invalid"]
    }
  }
  ```
</ResponseExample>

* `200 OK`: the invitation was triggered.
* `401 Unauthorized`: your API token isn't recognised or is badly formatted. See [authentication](/api/v1/overview#authentication).
* `403 Forbidden`: the user in `invited_by_email` doesn't have permission to send the invitation. Without `group_uuid` they need the `create_invitation` ability. With `group_uuid` they need the `create_invitation_with_group` ability.
* `404 Not Found`: no group matches `group_uuid`, or no user matches `invited_by_email`. The messages read `Group not found for provided UUID '...'` and `User account for sender ... not found`.
* `422 Unprocessable Entity`: the invitee's email address isn't a valid format.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.