# Invitations

Invitations let you invite or add users to a group or project.

## Reference

- v4 API:

  - `gitlab.v4.objects.GroupInvitation`

  - `gitlab.v4.objects.GroupInvitationManager`

  - `gitlab.v4.objects.Group.invitations`

  - `gitlab.v4.objects.ProjectInvitation`

  - `gitlab.v4.objects.ProjectInvitationManager`

  - `gitlab.v4.objects.Project.invitations`

- GitLab API: https://docs.gitlab.com/api/invitations

## Examples

Danger

Creating an invitation with `create()` returns a status response, rather than invitation details, because it allows sending multiple invitations at the same time.

Thus when using several emails, you do not create a real invitation object you can manipulate, because python-gitlab cannot know which email to track as the ID.

In that case, use a lazy `get()` method shown below using a specific email address to create an invitation object you can manipulate.

Create an invitation:

    invitation = group_or_project.invitations.create(
        {
            "email": "email@example.com",
            "access_level": gitlab.const.AccessLevel.DEVELOPER,
        }
    )

List invitations for a group or project:

    invitations = group_or_project.invitations.list(get_all=True)

Warning

As mentioned above, GitLab does not provide a real GET endpoint for a single invitation. We can create a lazy object to later manipulate it.

Update an invitation:

    invitation = group_or_project.invitations.get("email@example.com", lazy=True)
    invitation.access_level = gitlab.const.AccessLevel.DEVELOPER
    invitation.save()

    # or
    group_or_project.invitations.update(
        "email@example.com",
        {"access_level": gitlab.const.AccessLevel.DEVELOPER}
    )

Delete an invitation:

    invitation = group_or_project.invitations.get("email@example.com", lazy=True)
    invitation.delete()

    # or
    group_or_project.invitations.delete("email@example.com")