# Create Invitation

Invite someone by email. MindCloud emails them a link to join your company.

`POST https://connect.mindcloud.co/v2/invitations`

Permissions: `member:create`.

## Parameters

### Headers

- `X-Company-Id` (string): Optional. The id of the organization to act in. Leave it out to act in the API key's own organization. A key can also act in its child organizations, and, with "Use this key across all of your organizations" on, in every organization its creator can open in the app. List them with GET /v2/companies. Every response's X-Company-Id header names the organization it acted in. See [Organizations](https://mindcloud.co/docs/api/rest/introduction/organizations).

### Body

- `email` (string, required): Who to invite.
- `roleId` (string): The role they get when they join, from List Roles. Leave it out for the built-in Member role.

## Example request

```bash
curl --request POST \
  --url 'https://connect.mindcloud.co/v2/invitations' \
  --header 'Authorization: Bearer $MINDCLOUD_API_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
  "email": "sam@acme.com",
  "roleId": "Rl5wB9cF3hJp"
}'
```

## Response fields

- `id` (string): The invitation's id: the pending member's userId (List Members), until they sign up.
- `email` (string): Who was invited.
- `roleId` (string): The role they get when they join, from List Roles.
- `roleName` (string): That role's name.
- `status` (string): pending while they have not signed up. Create Invitation answers accepted for someone who already had a MindCloud account and joined at once; they are then a member (List Members).
  Allowed values:
    - `pending`
    - `accepted`
- `createdOn` (date): When they were invited.

## Errors

- 403 Access denied (API_KEY_PERMISSION_DENIED, MEMBER_ACTOR_NOT_RESOLVED, MEMBER_ROLE_EXCEEDS_ACTOR, MEMBER_PERSONAL_COMPANY_INVITES_FORBIDDEN): `FORBIDDEN` / `MEMBER_ROLE_EXCEEDS_ACTOR` "You cannot assign a role that grants permissions you do not hold: role:manage."
- 409 Already a member: `CONFLICT` / `MEMBER_ALREADY_IN_COMPANY` "sam@acme.com is already a member. Use Update Member to change their role."