invitations

Creates, updates, deletes, gets or lists an invitations resource.

Overview

Name	invitations
Type	Resource
Id	github.orgs.invitations

Fields

The following fields are returned by SELECT queries:

list_pending_invitations

Response

Name	Datatype	Description
id	integer (int64)
node_id	string	(example: "MDIyOk9yZ2FuaXphdGlvbkludml0YXRpb24x")
created_at	string
email	string
failed_at	string
failed_reason	string
invitation_source	string	(example: "member")
invitation_teams_url	string	(example: "https://api.github.com/organizations/16/invitations/1/teams")
inviter	object	A GitHub user. (title: Simple User)
login	string
role	string
team_count	integer

Methods

The following methods are available for this resource:

Name	Accessible by	Required Params	Optional Params	Description
list_pending_invitations	select	org	per_page, page, role, invitation_source	The return hash contains a role field which refers to the Organization Invitation role and will be one of the following values: direct_member, admin, billing_manager, or hiring_manager. If the invitee is not a GitHub member, the login field in the return hash will be null.
create_invitation	insert	org		Invite people to an organization by using their GitHub user ID or their email address. In order to create invitations in an organization, the authenticated user must be an organization owner. This endpoint triggers notifications. Creating content too quickly using this endpoint may result in secondary rate limiting. For more information, see "Rate limits for the API" and "Best practices for using the REST API."
cancel_invitation	delete	org, invitation_id		Cancel an organization invitation. In order to cancel an organization invitation, the authenticated user must be an organization owner. This endpoint triggers notifications.

Parameters

Parameters can be passed in the WHERE clause of a query. Check the Methods section to see which parameters are required or optional for each operation.

Name	Datatype	Description
invitation_id	integer	The unique identifier of the invitation.
org	string	The organization name. The name is not case sensitive.
invitation_source	string	Filter invitations by their invitation source.
page	integer	The page number of the results to fetch. For more information, see "Using pagination in the REST API."
per_page	integer	The number of results per page (max 100). For more information, see "Using pagination in the REST API."
role	string	Filter invitations by their member role.

SELECT examples

list_pending_invitations

The return hash contains a role field which refers to the Organization
Invitation role and will be one of the following values: direct_member, admin,
billing_manager, or hiring_manager. If the invitee is not a GitHub
member, the login field in the return hash will be null.

SELECT
id,
node_id,
created_at,
email,
failed_at,
failed_reason,
invitation_source,
invitation_teams_url,
inviter,
login,
role,
team_count
FROM github.orgs.invitations
WHERE org = '{{ org }}' -- required
AND per_page = '{{ per_page }}'
AND page = '{{ page }}'
AND role = '{{ role }}'
AND invitation_source = '{{ invitation_source }}'
;

INSERT examples

create_invitation

Invite people to an organization by using their GitHub user ID or their email address. In order to create invitations in an organization, the authenticated user must be an organization owner.

This endpoint triggers notifications. Creating content too quickly using this endpoint may result in secondary rate limiting. For more information, see "Rate limits for the API"
and "Best practices for using the REST API."

INSERT INTO github.orgs.invitations (
invitee_id,
email,
role,
team_ids,
org
)
SELECT 
{{ invitee_id }},
'{{ email }}',
'{{ role }}',
'{{ team_ids }}',
'{{ org }}'
RETURNING
id,
node_id,
created_at,
email,
failed_at,
failed_reason,
invitation_source,
invitation_teams_url,
inviter,
login,
role,
team_count
;

Manifest

# Description fields are for documentation purposes
- name: invitations
props:
  - name: org
    value: "{{ org }}"
    description: Required parameter for the invitations resource.
  - name: invitee_id
    value: {{ invitee_id }}
    description: |
      **Required unless you provide `email`**. GitHub user ID for the person you are inviting.
  - name: email
    value: "{{ email }}"
    description: |
      **Required unless you provide `invitee_id`**. Email address of the person you are inviting, which can be an existing GitHub user.
  - name: role
    value: "{{ role }}"
    description: |
      The role for the new member.
      * `admin` - Organization owners with full administrative rights to the organization and complete access to all repositories and teams.
      * `direct_member` - Non-owner organization members with ability to see other members and join teams by invitation.
      * `billing_manager` - Non-owner organization members with ability to manage the billing settings of your organization.
      * `reinstate` - The previous role assigned to the invitee before they were removed from your organization. Can be one of the roles listed above. Only works if the invitee was previously part of your organization.
    valid_values: ['admin', 'direct_member', 'billing_manager', 'reinstate']
    default: direct_member
  - name: team_ids
    value:
      - {{ team_ids }}
    description: |
      Specify IDs for the teams you want to invite new members to.

DELETE examples

cancel_invitation

Cancel an organization invitation. In order to cancel an organization invitation, the authenticated user must be an organization owner.

This endpoint triggers notifications.

DELETE FROM github.orgs.invitations
WHERE org = '{{ org }}' --required
AND invitation_id = '{{ invitation_id }}' --required
;