# Invite users

You can send an invitation to a user to obtain the information you need to create the user, in the invitation payload. You can then use that information to create the user intent using the method described in [Create a user](/products/custody/v1.15/api/environment/user/create#create-a-user).

The standard way of creating users is the method described in [Create users](/products/custody/v1.15/api/environment/user/create). In addition, you cannot invite bot users. For bot user creation, go straight to [Create a user](/products/custody/v1.15/api/environment/user/create#create-a-user).

## Create and share an invitation

1. Call the [Create a user invitation](/products/custody/v1.15/api/reference/openapi/user-invitations/paths/~1v1~1domains~1{domainid}~1users~1invitations/post) operation, with a request body similar to the following:

```json
{
 "numberSecondsOfValidity": 634302,
 "user": {
 	"id": "4dddcc15-b6b8-4ed7-83cd-d3950c6b2063",
 	"alias": "invited_user@email.com",
 	"roles": [
 		"operator",
 		"risk"
 	],
 	"customProperties": {},
 	"lock": "Unlocked"
 }
}
```
The body includes the following:
  - An `alias`: A user-friendly identifier, for example, the email address.
  - `roles`: One or more required `roles` for the user. For more information, see [User roles](/products/custody/v1.15/api/environment/user#user-roles).
  - The `numberSecondsOfValidity`: Validity period of the invitation, in seconds.
2. From the response body, share the `id` or `code` of the invitation with the new user, who can use it to respond to the invitation.


## Get a response to the user invitation

To get a response to the user invitation:

1. Share the invitation `id` or `code` with the user.
2. Ask the user to call the [Fill a user invitation](/products/custody/v1.15/api/reference/openapi/user-invitations/paths/~1v1~1users~1invitations~1{idorcode}/post) operation, including the following:
  - In the operation URL: The `id` or `code` from the invitation that the user administrator shared with you.
  - In the request body: The public key the user generated in [Generate a key pair and share the public key](/products/custody/v1.15/api/get-started/register#generate-a-key-pair-and-share-the-public-key).

```json
{
   "publicKey": "string"
}
```


This action does not require any authentication, as the user does not exist yet.
The operation does not return a response body other than a `200` code.

## Finalize the registration

When a user invitation exists in the system, you can choose between the following three options:

1. If the new user responded, complete the registration of the new user.
2. If the invitation has expired, renew the invitation.
3. Cancel the invitation.


All three operations have the same request body, which is made up of the invitation ID and the domain ID, as in this example:


```sh
{
  "id": "f1d73f89-8ab7-4758-9919-e479670e45a5",
  "domainId": "5cd224fe-193e-8bce-c94c-c6c05245e2d1",
}
```

### Complete the registration

To complete the registration, call the [Complete a user invitation](/products/custody/v1.15/api/reference/openapi/user-invitations/paths/~1v1~1domains~1{domainid}~1users~1invitations~1{id}~1complete/post) operation, with the invitation request body shown above.

The response you receive contains the user's ID, alias, and public key. You can use this information to create the user. For more information, see [Create a user](/products/custody/v1.15/api/environment/user/create#create-a-user).

### Renew the invitation

To renew an expired invitation, call the [Renew invitation](/products/custody/v1.15/api/reference/openapi/user-invitations/paths/~1v1~1domains~1{domainid}~1users~1invitations~1{id}~1renew/post) operation, with the invitation request body shown above.

### Cancel an invitation

To cancel an invitation, call the [Cancel a user invitation](/products/custody/v1.15/api/reference/openapi/user-invitations/paths/~1v1~1domains~1{domainid}~1users~1invitations~1{id}~1cancel/post) operation, with the invitation request body shown above.