# Creating and managing user invitations

This page explains how to perform some fundamental operations with the
Cloud Identity User Invitation API.

## Before you begin

**Note:** Before you use any of the Cloud Identity APIs, you must set up
Cloud Identity. See [Setting up Cloud Identity](https://docs.cloud.google.com/identity/docs/set-up-cloud-identity-admin)
for instructions.

Perform the following tasks before proceeding with the information on this page:

- Read the [User Invitation API overview](https://docs.cloud.google.com/identity/docs/concepts/overview-user-invitations.md.txt).
- Set up the [User Invitation API](https://docs.cloud.google.com/identity/docs/how-to/setup-user-invitations.md.txt).

## Determining invitation eligibility

As noted in the [overview](https://docs.cloud.google.com/identity/docs/concepts/overview-user-invitations.md.txt),
to be invited a user account must meet multiple criteria. You can use the
[`IsInvitableUser()`](https://docs.cloud.google.com/identity/docs/reference/rest/v1/customers.userinvitations/isInvitableUser.md.txt)
method to find out if a given user account is eligible.

### REST

To check the eligibility of a user account, call
[`customers.userinvitations.isInvitableUser()`](https://docs.cloud.google.com/identity/docs/reference/rest/v1/customers.userinvitations/isInvitableUser.md.txt)
with the customer ID and the account's email address.

**Sample request**

```restructuredtext
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()`](https://docs.cloud.google.com/identity/docs/reference/rest/v1/customers.userinvitations/get.md.txt)
with the customer ID and the account's email address.

**Sample request**

```restructuredtext
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()`](https://docs.cloud.google.com/identity/docs/reference/rest/v1/customers.userinvitations/list.md.txt) with the state in the request, it will return only users whose invitation is in that state.
- If you call [`customers.userinvitations.list()`](https://docs.cloud.google.com/identity/docs/reference/rest/v1/customers.userinvitations/list.md.txt) without the state in the request, it will return all user invitations.

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()`](https://docs.cloud.google.com/identity/docs/reference/rest/v1/customers.userinvitations/list.md.txt)
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**

```restructuredtext
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()`](https://docs.cloud.google.com/identity/docs/reference/rest/v1/customers.userinvitations/send.md.txt) 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()`](https://docs.cloud.google.com/identity/docs/reference/rest/v1/customers.userinvitations/send.md.txt)
with the customer ID and the user account's email address.

**Sample request**

```restructuredtext
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()](https://docs.cloud.google.com/identity/docs/reference/rest/v1/customers.userinvitations/cancel.md.txt)
method to cancel an invitation.

### REST

To cancel a user invitation, call
[customers.userinvitations.cancel()](https://docs.cloud.google.com/identity/docs/reference/rest/v1/customers.userinvitations/cancel.md.txt)
with the customer ID and the user account's email address.

**Sample request**

```restructuredtext
POST https://cloudidentity.googleapis.com/v1/customers/C00000000/userinvitations/writer@altostrat.com:cancel
```