Invitations API

  • Tier: Free, Premium, Ultimate
  • Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated

Use the Invitations API to invite or add users to a group or project, and to list pending invitations.

Valid access levels

To send an invitation, you must have access to the project or group you are sending email for. Valid access levels are defined in the Gitlab::Access module. Currently, these levels are valid:

  • No access (0)
  • Minimal access (5)
  • Guest (10)
  • Planner (15)
  • Reporter (20)
  • Developer (30)
  • Maintainer (40)
  • Owner (50)

Add a member to a group or project

Adds a new member. You can specify a user ID or invite a user by email.

Copy to clipboard
POST /groups/:id/invitations
POST /projects/:id/invitations
AttributeTypeRequiredDescription
idinteger/stringyesThe ID or URL-encoded path of the project or group
emailstringyes (if user_id isn’t provided)The email of the new member or multiple emails separated by commas.
user_idinteger/stringyes (if email isn’t provided)The ID of the new member or multiple IDs separated by commas.
access_levelintegeryesA valid access level
expires_atstringnoA date string in the format YEAR-MONTH-DAY
invite_sourcestringnoThe source of the invitation that starts the member creation process. See this issue.
member_role_idintegernoAssigns the new member to the provided custom role. (Introduced) in GitLab 16.6. Ultimate only.
Copy to clipboard
curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" \
     --data "email=test@example.com&user_id=1&access_level=30" "https://gitlab.example.com/api/v4/groups/:id/invitations"
curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" \
     --data "email=test@example.com&user_id=1&access_level=30" "https://gitlab.example.com/api/v4/projects/:id/invitations"

Example responses:

When all emails were successfully sent:

Copy to clipboard
{  "status":  "success"  }

When there was any error sending the email:

Copy to clipboard
{
  "status": "error",
  "message": {
               "test@example.com": "Invite email has already been taken",
               "test2@example.com": "User already exists in source",
               "test_username": "Access level is not included in the list"
             }
}

If administrator approval for role promotions is turned on, membership requests that promote existing users into a billable role require administrator approval.

To enable Manage non-billable promotions, you must first enable the enable_member_promotion_management application setting.

Example response:

Copy to clipboard
{
  "queued_users": {
    "username_1": "Request queued for administrator approval."
  },
  "status": "success"
}

List all invitations pending for a group or project

Gets a list of invited group or project members viewable by the authenticated user. Returns invitations to direct members only, and not through inherited ancestors’ groups.

This function takes pagination parameters page and per_page to restrict the list of members.

Copy to clipboard
GET /groups/:id/invitations
GET /projects/:id/invitations
AttributeTypeRequiredDescription
idinteger/stringyesThe ID or URL-encoded path of the project or group
pageintegernoPage to retrieve
per_pageintegernoNumber of member invitations to return per page
querystringnoA query string to search for invited members by invite email. Query text must match email address exactly. When empty, returns all invitations.
Copy to clipboard
curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/groups/:id/invitations?query=member@example.org"
curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/:id/invitations?query=member@example.org"

Example response:

Copy to clipboard
 [
   {
     "id": 1,
     "invite_email": "member@example.org",
     "created_at": "2020-10-22T14:13:35Z",
     "access_level": 30,
     "expires_at": "2020-11-22T14:13:35Z",
     "user_name": "Raymond Smith",
     "created_by_name": "Administrator"
   },
]

Update an invitation to a group or project

Updates a pending invitation’s access level or access expiry date.

Copy to clipboard
PUT /groups/:id/invitations/:email
PUT /projects/:id/invitations/:email
AttributeTypeRequiredDescription
idinteger/stringyesThe ID or URL-encoded path of the project or group.
emailstringyesThe email address the invitation was previously sent to.
access_levelintegernoA valid access level (defaults: 30, the Developer role).
expires_atstringnoA date string in ISO 8601 format (YYYY-MM-DDTHH:MM:SSZ).
Copy to clipboard
curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/groups/55/invitations/email@example.org?access_level=40"
curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/55/invitations/email@example.org?access_level=40"

Example response:

Copy to clipboard
{
  "expires_at": "2012-10-22T14:13:35Z",
  "access_level": 40,
}

Delete an invitation to a group or project

Deletes a pending invitation by email address.

Copy to clipboard
DELETE /groups/:id/invitations/:email
DELETE /projects/:id/invitations/:email
AttributeTypeRequiredDescription
idinteger/stringyesThe ID or URL-encoded path of the project or group
emailstringyesThe email address to which the invitation was previously sent
Copy to clipboard
curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/groups/55/invitations/email@example.org"
curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/55/invitations/email@example.org"
  • Returns 204 and no content on success.
  • Returns 403 forbidden if unauthorized to delete the invitation.
  • Returns 404 not found if authorized and no invitation is found for that email address.
  • Returns 409 if the request was valid but the invitation could not be deleted.