Microsoft Graph Invitations is a Microsoft Graph API feature that lets apps programmatically invite external (B2B) users into a Microsoft Entra ID tenant. By calling POST /invitations, it creates a guest user and can send an email invitation with a redemption link, or you can suppress the email and use the returned inviteRedeemUrl to deliver the link yourself.
openapi: 3.1.0
info:
title: Microsoft Graph Invitations
description: Needs a description.
paths:
/invitations:
description: Provides operations to manage the collection of invitation entities.
get:
tags:
- Invitations.invitation
summary: Microsoft Graph Get entities from invitations
operationId: invitations.invitation.ListInvitation
parameters:
- $ref: '#/components/parameters/top'
- $ref: '#/components/parameters/skip'
- $ref: '#/components/parameters/search'
- $ref: '#/components/parameters/filter'
- $ref: '#/components/parameters/count'
- name: $orderby
in: query
description: Order items by property values
style: form
explode: false
schema:
uniqueItems: true
type: array
items:
type: string
- name: $select
in: query
description: Select properties to be returned
style: form
explode: false
schema:
uniqueItems: true
type: array
items:
type: string
- name: $expand
in: query
description: Expand related entities
style: form
explode: false
schema:
uniqueItems: true
type: array
items:
type: string
responses:
2XX:
$ref: '#/components/responses/microsoft.graph.invitationCollectionResponse'
4XX:
$ref: '#/components/responses/error'
5XX:
$ref: '#/components/responses/error'
x-ms-pageable:
nextLinkName: '@odata.nextLink'
operationName: listMore
x-ms-docs-operation-type: operation
post:
tags:
- Invitations.invitation
summary: Microsoft Graph Create invitation
description: >-
Use this API to create a new invitation or reset the redemption status
for a guest user who already redeemed their invitation. The invitation
adds the external user to the organization as part of B2B collaboration.
B2B collaboration is supported in both Microsoft Entra External ID in
workforce and external tenants. When creating a new invitation, you have
several options available:
externalDocs:
description: Find more info here
url: >-
https://learn.microsoft.com/graph/api/invitation-post?view=graph-rest-1.0
operationId: invitations.invitation.CreateInvitation
requestBody:
description: New entity
content:
application/json:
schema:
$ref: '#/components/schemas/microsoft.graph.invitation'
required: true
responses:
2XX:
description: Created entity
content:
application/json:
schema:
$ref: '#/components/schemas/microsoft.graph.invitation'
4XX:
$ref: '#/components/responses/error'
5XX:
$ref: '#/components/responses/error'
x-ms-docs-operation-type: operation
/invitations/$count:
description: Provides operations to count the resources in the collection.
get:
tags:
- Invitations.invitation
summary: Microsoft Graph Get the number of the resource
operationId: invitations.GetCount-8ff1
parameters:
- $ref: '#/components/parameters/search'
- $ref: '#/components/parameters/filter'
responses:
2XX:
$ref: '#/components/responses/ODataCountResponse'
4XX:
$ref: '#/components/responses/error'
5XX:
$ref: '#/components/responses/error'
/invitations/invitedUser:
description: >-
Provides operations to manage the invitedUser property of the
microsoft.graph.invitation entity.
get:
tags:
- Invitations.user
summary: Microsoft Graph Get invitedUser from invitations
description: >-
The user created as part of the invitation creation. Read-only. The id
property is required in the request body to reset a redemption status.
operationId: invitations.GetInvitedUser
parameters:
- name: $select
in: query
description: Select properties to be returned
style: form
explode: false
schema:
uniqueItems: true
type: array
items:
type: string
- name: $expand
in: query
description: Expand related entities
style: form
explode: false
schema:
uniqueItems: true
type: array
items:
type: string
responses:
2XX:
description: Retrieved navigation property
content:
application/json:
schema:
$ref: '#/components/schemas/microsoft.graph.user'
4XX:
$ref: '#/components/responses/error'
5XX:
$ref: '#/components/responses/error'
x-ms-docs-operation-type: operation
/invitations/invitedUser/mailboxSettings:
get:
tags:
- Invitations.user
summary: Microsoft Graph Get mailboxSettings property value
description: >-
Settings for the primary mailbox of the signed-in user. You can get or
update settings for sending automatic replies to incoming messages,
locale, and time zone. Returned only on $select.
operationId: invitations.invitedUser.GetMailboxSettings
parameters:
- name: $select
in: query
description: Select properties to be returned
style: form
explode: false
schema:
uniqueItems: true
type: array
items:
type: string
- name: $expand
in: query
description: Expand related entities
style: form
explode: false
schema:
uniqueItems: true
type: array
items:
type: string
responses:
2XX:
description: Entity result.
content:
application/json:
schema:
$ref: '#/components/schemas/microsoft.graph.mailboxSettings'
4XX:
$ref: '#/components/responses/error'
5XX:
$ref: '#/components/responses/error'
patch:
tags:
- Invitations.user
summary: Microsoft Graph Update property mailboxSettings value.
operationId: invitations.invitedUser.UpdateMailboxSettings
requestBody:
description: New property values
content:
application/json:
schema:
$ref: '#/components/schemas/microsoft.graph.mailboxSettings'
required: true
responses:
2XX:
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/microsoft.graph.mailboxSettings'
4XX:
$ref: '#/components/responses/error'
5XX:
$ref: '#/components/responses/error'
/invitations/invitedUser/serviceProvisioningErrors:
get:
tags:
- Invitations.user
summary: Microsoft Graph Get serviceProvisioningErrors property value
description: >-
Errors published by a federated service describing a nontransient,
service-specific error regarding the properties or link from a user
object. Supports $filter (eq, not, for isResolved and serviceInstance).
operationId: invitations.invitedUser.ListServiceProvisioningErrors
parameters:
- $ref: '#/components/parameters/top'
- $ref: '#/components/parameters/skip'
- $ref: '#/components/parameters/search'
- $ref: '#/components/parameters/filter'
- $ref: '#/components/parameters/count'
- name: $orderby
in: query
description: Order items by property values
style: form
explode: false
schema:
uniqueItems: true
type: array
items:
type: string
- name: $select
in: query
description: Select properties to be returned
style: form
explode: false
schema:
uniqueItems: true
type: array
items:
type: string
- name: $expand
in: query
description: Expand related entities
style: form
explode: false
schema:
uniqueItems: true
type: array
items:
type: string
responses:
2XX:
$ref: >-
#/components/responses/microsoft.graph.serviceProvisioningErrorCollectionResponse
4XX:
$ref: '#/components/responses/error'
5XX:
$ref: '#/components/responses/error'
x-ms-pageable:
nextLinkName: '@odata.nextLink'
operationName: listMore
/invitations/invitedUser/serviceProvisioningErrors/$count:
description: Provides operations to count the resources in the collection.
get:
tags:
- Invitations.user
summary: Microsoft Graph Get the number of the resource
operationId: invitations.invitedUser.ServiceProvisioningErrors.GetCount-df29
parameters:
- $ref: '#/components/parameters/search'
- $ref: '#/components/parameters/filter'
responses:
2XX:
$ref: '#/components/responses/ODataCountResponse'
4XX:
$ref: '#/components/responses/error'
5XX:
$ref: '#/components/responses/error'
/invitations/invitedUserSponsors:
description: >-
Provides operations to manage the invitedUserSponsors property of the
microsoft.graph.invitation entity.
get:
tags:
- invitations.directoryObject
summary: Microsoft Graph Get invitedUserSponsors from invitations
description: >-
The users or groups who are sponsors of the invited user. Sponsors are
users and groups that are responsible for guest users' privileges in the
tenant and for keeping the guest users' information and access up to
date.
operationId: invitations.ListInvitedUserSponsors
parameters:
- $ref: '#/components/parameters/top'
- $ref: '#/components/parameters/skip'
- $ref: '#/components/parameters/search'
- $ref: '#/components/parameters/filter'
- $ref: '#/components/parameters/count'
- name: $orderby
in: query
description: Order items by property values
style: form
explode: false
schema:
uniqueItems: true
type: array
items:
type: string
- name: $select
in: query
description: Select properties to be returned
style: form
explode: false
schema:
uniqueItems: true
type: array
items:
type: string
- name: $expand
in: query
description: Expand related entities
style: form
explode: false
schema:
uniqueItems: true
type: array
items:
type: string
responses:
2XX:
$ref: >-
#/components/responses/microsoft.graph.directoryObjectCollectionResponse
4XX:
$ref: '#/components/responses/error'
5XX:
$ref: '#/components/responses/error'
x-ms-pageable:
nextLinkName: '@odata.nextLink'
operationName: listMore
x-ms-docs-operation-type: operation
/invitations/invitedUserSponsors/{directoryObject-id}:
description: >-
Provides operations to manage the invitedUserSponsors property of the
microsoft.graph.invitation entity.
get:
tags:
- invitations.directoryObject
summary: Microsoft Graph Get invitedUserSponsors from invitations
description: >-
The users or groups who are sponsors of the invited user. Sponsors are
users and groups that are responsible for guest users' privileges in the
tenant and for keeping the guest users' information and access up to
date.
operationId: invitations.GetInvitedUserSponsors
parameters:
- name: $select
in: query
description: Select properties to be returned
style: form
explode: false
schema:
uniqueItems: true
type: array
items:
type: string
- name: $expand
in: query
description: Expand related entities
style: form
explode: false
schema:
uniqueItems: true
type: array
items:
type: string
responses:
2XX:
description: Retrieved navigation property
content:
application/json:
schema:
$ref: '#/components/schemas/microsoft.graph.directoryObject'
4XX:
$ref: '#/components/responses/error'
5XX:
$ref: '#/components/responses/error'
x-ms-docs-operation-type: operation
parameters:
- name: directoryObject-id
in: path
description: The unique identifier of directoryObject
required: true
schema:
type: string
x-ms-docs-key-type: directoryObject
/invitations/invitedUserSponsors/$count:
description: Provides operations to count the resources in the collection.
get:
tags:
- invitations.directoryObject
summary: Microsoft Graph Get the number of the resource
operationId: invitations.invitedUserSponsors.GetCount-648d
parameters:
- $ref: '#/components/parameters/search'
- $ref: '#/components/parameters/filter'
responses:
2XX:
$ref: '#/components/responses/ODataCountResponse'
4XX:
$ref: '#/components/responses/error'
5XX:
$ref: '#/components/responses/error'
components:
schemas:
microsoft.graph.invitation:
allOf:
- $ref: '#/components/schemas/microsoft.graph.entity'
- title: invitation
required:
- '@odata.type'
type: object
properties:
invitedUserDisplayName:
type: string
description: The display name of the user being invited.
nullable: true
invitedUserEmailAddress:
type: string
description: >-
The email address of the user being invited. Required. The
following special characters aren't permitted in the email
address:Tilde (~)Exclamation point (!)Number sign (#)Dollar sign
($)Percent (%)Circumflex (^)Ampersand (&)Asterisk (*)Parentheses
(( ))Plus sign (+)Equal sign (=)Brackets ([ ])Braces ({
})Backslash (/)Slash mark (/)Pipe (/|)Semicolon (;)Colon
(:)Quotation marks (')Angle brackets (< >)Question mark (?)Comma
(,)However, the following exceptions apply:A period (.) or a
hyphen (-) is permitted anywhere in the user name, except at the
beginning or end of the name.An underscore (_) is permitted
anywhere in the user name, including at the beginning or end of
the name.
invitedUserMessageInfo:
anyOf:
- $ref: '#/components/schemas/microsoft.graph.invitedUserMessageInfo'
- type: object
nullable: true
description: >-
Contains configuration for the message being sent to the invited
user, including customizing message text, language, and cc
recipient list.
invitedUserType:
type: string
description: >-
The userType of the user being invited. By default, this is
Guest. You can invite as Member if you're a company
administrator.
nullable: true
inviteRedeemUrl:
type: string
description: The URL the user can use to redeem their invitation. Read-only.
nullable: true
inviteRedirectUrl:
type: string
description: >-
The URL the user should be redirected to after the invitation is
redeemed. Required.
resetRedemption:
type: boolean
description: >-
Reset the user's redemption status and reinvite a user while
retaining their user identifier, group memberships, and app
assignments. This property allows you to enable a user to
sign-in using a different email address from the one in the
previous invitation. When true, the invitedUser/id relationship
is required. For more information about using this property, see
Reset redemption status for a guest user.
nullable: true
sendInvitationMessage:
type: boolean
description: >-
Indicates whether an email should be sent to the user being
invited. The default is false.
nullable: true
status:
type: string
description: >-
The status of the invitation. The possible values are:
PendingAcceptance, Completed, InProgress, and Error.
nullable: true
invitedUser:
anyOf:
- $ref: '#/components/schemas/microsoft.graph.user'
- type: object
nullable: true
description: >-
The user created as part of the invitation creation. Read-only.
The id property is required in the request body to reset a
redemption status.
x-ms-navigationProperty: true
invitedUserSponsors:
type: array
items:
$ref: '#/components/schemas/microsoft.graph.directoryObject'
description: >-
The users or groups who are sponsors of the invited user.
Sponsors are users and groups that are responsible for guest
users' privileges in the tenant and for keeping the guest users'
information and access up to date.
x-ms-navigationProperty: true
'@odata.type':
type: string
x-ms-discriminator-value: '#microsoft.graph.invitation'
microsoft.graph.user:
allOf:
- $ref: '#/components/schemas/microsoft.graph.directoryObject'
- title: user
required:
- '@odata.type'
type: object
properties:
aboutMe:
type: string
description: >-
A freeform text entry field for the user to describe themselves.
Returned only on $select.
nullable: true
accountEnabled:
type: boolean
description: >-
true if the account is enabled; otherwise, false. This property
is required when a user is created. Returned only on $select.
Supports $filter (eq, ne, not, and in).
nullable: true
ageGroup:
type: string
description: >-
Sets the age group of the user. Allowed values: null, Minor,
NotAdult, and Adult. For more information, see legal age group
property definitions. Returned only on $select. Supports $filter
(eq, ne, not, and in).
nullable: true
assignedLicenses:
type: array
items:
$ref: '#/components/schemas/microsoft.graph.assignedLicense'
description: >-
The licenses that are assigned to the user, including inherited
(group-based) licenses. This property doesn't differentiate
between directly assigned and inherited licenses. Use the
licenseAssignmentStates property to identify the directly
assigned and inherited licenses. Not nullable. Returned only on
$select. Supports $filter (eq, not, /$count eq 0, /$count ne 0).
assignedPlans:
type: array
items:
$ref: '#/components/schemas/microsoft.graph.assignedPlan'
description: >-
The plans that are assigned to the user. Read-only. Not
nullable. Returned only on $select. Supports $filter (eq and
not).
authorizationInfo:
anyOf:
- $ref: '#/components/schemas/microsoft.graph.authorizationInfo'
- type: object
nullable: true
birthday:
pattern: >-
^[0-9]{4,}-(0[1-9]|1[012])-(0[1-9]|[12][0-9]|3[01])T([01][0-9]|2[0-3]):[0-5][0-9]:[0-5][0-9]([.][0-9]{1,12})?(Z|[+-][0-9][0-9]:[0-9][0-9])$
type: string
description: >-
The birthday of the user. The Timestamp type represents date and
time information using ISO 8601 format and is always in UTC. For
example, midnight UTC on Jan 1, 2014, is 2014-01-01T00:00:00Z.
Returned only on $select.
format: date-time
businessPhones:
type: array
items:
type: string
description: >-
The telephone numbers for the user. NOTE: Although it's a string
collection, only one number can be set for this property.
Read-only for users synced from the on-premises directory.
Returned by default. Supports $filter (eq, not, ge, le,
startsWith).
city:
type: string
description: >-
The city where the user is located. Maximum length is 128
characters. Returned only on $select. Supports $filter (eq, ne,
not, ge, le, in, startsWith, and eq on null values).
nullable: true
companyName:
type: string
description: >-
The name of the company that the user is associated with. This
property can be useful for describing the company that a guest
comes from. The maximum length is 64 characters.Returned only on
$select. Supports $filter (eq, ne, not, ge, le, in, startsWith,
and eq on null values).
nullable: true
consentProvidedForMinor:
type: string
description: >-
Sets whether consent was obtained for minors. Allowed values:
null, Granted, Denied, and NotRequired. For more information,
see legal age group property definitions. Returned only on
$select. Supports $filter (eq, ne, not, and in).
nullable: true
country:
type: string
description: >-
The country or region where the user is located; for example, US
or UK. Maximum length is 128 characters. Returned only on
$select. Supports $filter (eq, ne, not, ge, le, in, startsWith,
and eq on null values).
nullable: true
createdDateTime:
pattern: >-
^[0-9]{4,}-(0[1-9]|1[012])-(0[1-9]|[12][0-9]|3[01])T([01][0-9]|2[0-3]):[0-5][0-9]:[0-5][0-9]([.][0-9]{1,12})?(Z|[+-][0-9][0-9]:[0-9][0-9])$
type: string
description: >-
The date and time the user was created, in ISO 8601 format and
UTC. The value can't be modified and is automatically populated
when the entity is created. Nullable. For on-premises users, the
value represents when they were first created in Microsoft Entra
ID. Property is null for some users created before June 2018 and
on-premises users that were synced to Microsoft Entra ID before
June 2018. Read-only. Returned only on $select. Supports $filter
(eq, ne, not , ge, le, in).
format: date-time
nullable: true
creationType:
type: string
description: >-
Indicates whether the user account was created through one of
the following methods: As a regular school or work account
(null). As an external account (Invitation). As a local account
for an Azure Active Directory B2C tenant (LocalAccount). Through
self-service sign-up by an internal user using email
verification (EmailVerified). Through self-service sign-up by a
guest signing up through a link that is part of a user flow
(SelfServiceSignUp). Read-only.Returned only on $select.
Supports $filter (eq, ne, not, in).
nullable: true
customSecurityAttributes:
anyOf:
- $ref: >-
#/components/schemas/microsoft.graph.customSecurityAttributeValue
- type: object
nullable: true
description: >-
An open complex type that holds the value of a custom security
attribute that is assigned to a directory object. Nullable.
Returned only on $select. Supports $filter (eq, ne, not,
startsWith). The filter value is case-sensitive. To read this
property, the calling app must be assigned the
CustomSecAttributeAssignment.Read.All permission. To write this
property, the calling app must be assigned the
CustomSecAttributeAssignment.ReadWrite.All permissions. To read
or write this property in delegated scenarios, the admin must be
assigned the Attribute Assignment Administrator role.
department:
type: string
description: >-
The name of the department in which the user works. Maximum
length is 64 characters. Returned only on $select. Supports
$filter (eq, ne, not , ge, le, in, and eq on null values).
nullable: true
deviceEnrollmentLimit:
maximum: 2147483647
minimum: -2147483648
type: number
description: >-
The limit on the maximum number of devices that the user is
permitted to enroll. Allowed values are 5 or 1000.
format: int32
displayName:
type: string
description: >-
The name displayed in the address book for the user. This value
is usually the combination of the user's first name, middle
initial, and family name. This property is required when a user
is created and it can't be cleared during updates. Maximum
length is 256 characters. Returned by default. Supports $filter
(eq, ne, not , ge, le, in, startsWith, and eq on null values),
$orderby, and $search.
nullable: true
employeeHireDate:
pattern: >-
^[0-9]{4,}-(0[1-9]|1[012])-(0[1-9]|[12][0-9]|3[01])T([01][0-9]|2[0-3]):[0-5][0-9]:[0-5][0-9]([.][0-9]{1,12})?(Z|[+-][0-9][0-9]:[0-9][0-9])$
type: string
description: >-
The date and time when the user was hired or will start work in
a future hire. Returned only on $select. Supports $filter (eq,
ne, not , ge, le, in).
format: date-time
nullable: true
employeeId:
type: string
description: >-
The employee identifier assigned to the user by the
organization. The maximum length is 16 characters. Returned only
on $select. Supports $filter (eq, ne, not , ge, le, in,
startsWith, and eq on null values).
nullable: true
employeeLeaveDateTime:
pattern: >-
^[0-9]{4,}-(0[1-9]|1[012])-(0[1-9]|[12][0-9]|3[01])T([01][0-9]|2[0-3]):[0-5][0-9]:[0-5][0-9]([.][0-9]{1,12})?(Z|[+-][0-9][0-9]:[0-9][0-9])$
type: string
description: >-
The date and time when the user left or will leave the
organization. To read this property, the calling app must be
assigned the User-LifeCycleInfo.Read.All permission. To write
this property, the calling app must be assigned the
User.Read.All and User-LifeCycleInfo.ReadWrite.All permissions.
To read this property in delegated scenarios, the admin needs at
least one of the following Microsoft Entra roles: Lifecycle
Workflows Administrator (least privilege), Global Reader. To
write this property in delegated scenarios, the admin needs the
Global Administrator role. Supports $filter (eq, ne, not , ge,
le, in). For more information, see Configure the
employeeLeaveDateTime property for a user.
format: date-time
nullable: true
employeeOrgData:
anyOf:
- $ref: '#/components/schemas/microsoft.graph.employeeOrgData'
- type: object
nullable: true
description: >-
Represents organization data (for example, division and
costCenter) associated with a user. Returned only on $select.
Supports $filter (eq, ne, not , ge, le, in).
employeeType:
type: string
description: >-
Captures enterprise worker type. For example, Employee,
Contractor, Consultant, or Vendor. Returned only on $select.
Supports $filter (eq, ne, not , ge, le, in, startsWith).
nullable: true
externalUserState:
type: string
description: >-
For a guest invited to the tenant using the invitation API, this
property represents the invited user's invitation status. For
invited users, the state can be PendingAcceptance or Accepted,
or null for all other users. Returned only on $select. Supports
$filter (eq, ne, not , in).
nullable: true
externalUserStateChangeDateTime:
pattern: >-
^[0-9]{4,}-(0[1-9]|1[012])-(0[1-9]|[12][0-9]|3[01])T([01][0-9]|2[0-3]):[0-5][0-9]:[0-5][0-9]([.][0-9]{1,12})?(Z|[+-][0-9][0-9]:[0-9][0-9])$
type: string
description: >-
Shows the timestamp for the latest change to the
externalUserState property. Returned only on $select. Supports
$filter (eq, ne, not , in).
format: date-time
nullable: true
faxNumber:
type: string
description: >-
The fax number of the user. Returned only on $select. Supports
$filter (eq, ne, not , ge, le, in, startsWith, and eq on null
values).
nullable: true
givenName:
type: string
description: >-
The given name (first name) of the user. Maximum length is 64
characters. Returned by default. Supports $filter (eq, ne, not ,
ge, le, in, startsWith, and eq on null values).
nullable: true
hireDate:
pattern: >-
^[0-9]{4,}-(0[1-9]|1[012])-(0[1-9]|[12][0-9]|3[01])T([01][0-9]|2[0-3]):[0-5][0-9]:[0-5][0-9]([.][0-9]{1,12})?(Z|[+-][0-9][0-9]:[0-9][0-9])$
type: string
# --- truncated at 32 KB (82 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/microsoft-graph/refs/heads/main/openapi/invitations-openapi-original.yml