As noted in the overview,
to be invited a user account must meet multiple criteria. You can use the
IsInvitableUser()
method to find out if a given user account is eligible.
GET https://cloudidentity.googleapis.com/v1/customers/C00000000/userinvitations/writer@altostrat.com:isInvitableUser
Retrieving user invitations
The User Invitation API provides methods for retrieving a single user
invitation and retrieving all of them. When retrieving all user invitations,
you can optionally filter them by state and set the sorting order.
Retrieving a single user invitation
REST
To retrieve a single user invitation, call
customers.userinvitations.get()
with the customer ID and the account's email address.
Sample request
GET https://cloudidentity.googleapis.com/v1/customers/C00000000/userinvitations/writer@altostrat.com
Retrieving a list of user invitations
All unmanaged users appear automatically as invitations in the NOT_YET_SENT
state until otherwise acted upon by either the admin or the end user. Once an
invitation is accepted by the user, the account is no longer considered
unmanaged.
If you call
customers.userinvitations.list()
with the state in the request, it will return only users whose invitation
is in that state.
You can check for multiple states by adding an or operator in the filter:
state=='accepted'||state=='declined'
REST
To retrieve a list of user invitations, call
customers.userinvitations.list()
with the customer ID and any desired query parameters to filter, order, and
paginate the results. The following example returns a list of all unmanaged
users, ordered by the last updated time in descending order.
Sample request
GET https://cloudidentity.googleapis.com/v1/customers/C00000000/userinvitations?filter=state!='accepted'&orderBy='updateTime desc'
Sending user invitations
User invitations are not automatically sent to eligible users. Once you have a
list of the users you want to invite, you can use the
customers.userinvitations.send() method.
This will also create an invitation if it doesn't exist.
REST
To send a user invitation email to a user, call
customers.userinvitations.send()
with the customer ID and the user account's email address.
Sample request
POST https://cloudidentity.googleapis.com/v1/customers/C00000000/userinvitations/writer@altostrat.com:send
Canceling user invitations
User invitations can be canceled until they are either accepted or declined.
Call the
customers.userinvitations.cancel()
method to cancel an invitation.
[[["Easy to understand","easyToUnderstand","thumb-up"],["Solved my problem","solvedMyProblem","thumb-up"],["Other","otherUp","thumb-up"]],[["Hard to understand","hardToUnderstand","thumb-down"],["Incorrect information or sample code","incorrectInformationOrSampleCode","thumb-down"],["Missing the information/samples I need","missingTheInformationSamplesINeed","thumb-down"],["Other","otherDown","thumb-down"]],["Last updated 2025-09-04 UTC."],[[["\u003cp\u003eThis page provides guidance on using the Cloud Identity User Invitation API to manage user invitations, including checking eligibility, retrieving, sending, and canceling them.\u003c/p\u003e\n"],["\u003cp\u003eYou can verify if a user account is eligible for an invitation using the \u003ccode\u003eIsInvitableUser()\u003c/code\u003e method, which requires the customer ID and the user's email address.\u003c/p\u003e\n"],["\u003cp\u003eThe API allows retrieval of single or multiple user invitations, with the option to filter by state and sort the results when retrieving a list of invitations.\u003c/p\u003e\n"],["\u003cp\u003eUser invitations are not automatically sent; you must use the \u003ccode\u003ecustomers.userinvitations.send()\u003c/code\u003e method to send an invitation email to a specific user, which also creates the invitation if one does not already exist.\u003c/p\u003e\n"],["\u003cp\u003eUser invitations can be canceled until they are accepted or declined, by using the \u003ccode\u003ecustomers.userinvitations.cancel()\u003c/code\u003e method.\u003c/p\u003e\n"]]],[],null,["# Creating and managing user invitations\n======================================\n\nThis page explains how to perform some fundamental operations with the\nCloud Identity User Invitation API.\n\nBefore you begin\n----------------\n\n**Note:** Before you use any of the Cloud Identity APIs, you must set up\nCloud Identity. See [Setting up Cloud Identity](/identity/docs/set-up-cloud-identity-admin)\nfor instructions.\n\nPerform the following tasks before proceeding with the information on this page:\n\n- Read the [User Invitation API overview](/identity/docs/concepts/overview-user-invitations).\n- Set up the [User Invitation API](/identity/docs/how-to/setup-user-invitations).\n\nDetermining invitation eligibility\n----------------------------------\n\nAs noted in the [overview](/identity/docs/concepts/overview-user-invitations),\nto be invited a user account must meet multiple criteria. You can use the\n[`IsInvitableUser()`](/identity/docs/reference/rest/v1/customers.userinvitations/isInvitableUser)\nmethod to find out if a given user account is eligible. \n\n### REST\n\nTo check the eligibility of a user account, call\n[`customers.userinvitations.isInvitableUser()`](/identity/docs/reference/rest/v1/customers.userinvitations/isInvitableUser)\nwith the customer ID and the account's email address.\n\n**Sample request** \n\n GET https://cloudidentity.googleapis.com/v1/customers/C00000000/userinvitations/writer@altostrat.com:isInvitableUser\n\nRetrieving user invitations\n---------------------------\n\nThe User Invitation API provides methods for retrieving a single user\ninvitation and retrieving all of them. When retrieving all user invitations,\nyou can optionally filter them by state and set the sorting order.\n\n### Retrieving a single user invitation\n\n### REST\n\nTo retrieve a single user invitation, call\n[`customers.userinvitations.get()`](/identity/docs/reference/rest/v1/customers.userinvitations/get)\nwith the customer ID and the account's email address.\n\n**Sample request** \n\n GET https://cloudidentity.googleapis.com/v1/customers/C00000000/userinvitations/writer@altostrat.com\n\n### Retrieving a list of user invitations\n\nAll unmanaged users appear automatically as invitations in the `NOT_YET_SENT`\nstate until otherwise acted upon by either the admin or the end user. Once an\ninvitation is accepted by the user, the account is no longer considered\nunmanaged.\n\n- If you call [`customers.userinvitations.list()`](/identity/docs/reference/rest/v1/customers.userinvitations/list) with the state in the request, it will return only users whose invitation is in that state.\n- If you call [`customers.userinvitations.list()`](/identity/docs/reference/rest/v1/customers.userinvitations/list) without the state in the request, it will return all user invitations.\n\nYou can check for multiple states by adding an `or` operator in the filter:\n`state=='accepted'||state=='declined'` \n\n### REST\n\nTo retrieve a list of user invitations, call\n[`customers.userinvitations.list()`](/identity/docs/reference/rest/v1/customers.userinvitations/list)\nwith the customer ID and any desired query parameters to filter, order, and\npaginate the results. The following example returns a list of all unmanaged\nusers, ordered by the last updated time in descending order.\n\n**Sample request** \n\n GET https://cloudidentity.googleapis.com/v1/customers/C00000000/userinvitations?filter=state!='accepted'&orderBy='updateTime desc'\n\nSending user invitations\n------------------------\n\nUser invitations are not automatically sent to eligible users. Once you have a\nlist of the users you want to invite, you can use the\n[`customers.userinvitations.send()`](/identity/docs/reference/rest/v1/customers.userinvitations/send) method.\nThis will also create an invitation if it doesn't exist. \n\n### REST\n\nTo send a user invitation email to a user, call\n[`customers.userinvitations.send()`](/identity/docs/reference/rest/v1/customers.userinvitations/send)\nwith the customer ID and the user account's email address.\n\n**Sample request** \n\n POST https://cloudidentity.googleapis.com/v1/customers/C00000000/userinvitations/writer@altostrat.com:send\n\nCanceling user invitations\n--------------------------\n\nUser invitations can be canceled until they are either accepted or declined.\nCall the\n[customers.userinvitations.cancel()](/identity/docs/reference/rest/v1/customers.userinvitations/cancel)\nmethod to cancel an invitation. \n\n### REST\n\nTo cancel a user invitation, call\n[customers.userinvitations.cancel()](/identity/docs/reference/rest/v1/customers.userinvitations/cancel)\nwith the customer ID and the user account's email address.\n\n**Sample request** \n\n POST https://cloudidentity.googleapis.com/v1/customers/C00000000/userinvitations/writer@altostrat.com:cancel"]]
