# Create invitation

`POST /v1/organizations/{organization}/invitations`, operation `invitations.CreateInvitation`

Invites an email address to an organization, as a member or a guest.

The invitee receives an email and joins by accepting. Granting roles on accepting takes setIamPolicy on each resource in grants.

## Parameters

| Name | In | Required | Type | Description |
| --- | --- | --- | --- | --- |
| `organization` | path | Yes | `string` | The organization's ID. |

## Request body

Content-Type: `application/json` (required)

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `email` | `string (email)` | Yes | The email address to invite. |
| `grants` | `Grant[]` | No | Roles the invitee receives on accepting; at most as many as the identity.invitationGrants quota allows. Granting each takes setIamPolicy on its resource. |
| `kind` | `string` | Yes | How the invitee will belong to the organization. Values: `MEMBER`, `GUEST`. |

## Responses

### 201

Created

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `acceptor` | `string` | Yes | Who accepted the invitation, users/{user_id}; empty until accepted. |
| `createTime` | `string (date-time)` | Yes | When the invitation was created. |
| `email` | `string` | Yes | The invited email address. |
| `expireTime` | `string (date-time)` | Yes | When the invitation expires unless accepted. |
| `grants` | `Grant[]` | Yes | Roles the invitee receives on accepting. |
| `inviter` | `string` | Yes | Who sent the invitation, users/{user_id}. |
| `kind` | `string` | Yes | How the invitee will belong to the organization: a MEMBER sees its directory and is included in grants to all members; a GUEST sees only what they are granted. Values: `MEMBER`, `GUEST`. |
| `name` | `string` | Yes | Resource name, organizations/{organization_id}/invitations/{invitation_id}. |
| `state` | `string` | Yes | Lifecycle state: PENDING, waiting for the invitee; ACCEPTED, the invitee joined; REVOKED before it was accepted; EXPIRED, not accepted in time, as invitations last 7 days. Values: `PENDING`, `ACCEPTED`, `REVOKED`, `EXPIRED`. |
| `updateTime` | `string (date-time)` | Yes | When the invitation last changed. |

### default

Error

Base URL: `https://api.kosem.ai`. See [API conventions](https://docs.kosem.ai/reference/api-conventions.md) for authentication, pagination and errors, and [https://docs.kosem.ai/openapi.yaml](https://docs.kosem.ai/openapi.yaml) for the full OpenAPI document.