> For the complete documentation index, see [llms.txt](https://developer.onehub.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developer.onehub.com/methods/invitations.md).

# Invitations

Invitations are placeholders for [rolemap](/methods/rolemaps.md) objects. You cannot create a rolemap directly because, sometimes, user approval is required. Invitations are sent to users via email and, once accepted, create a rolemap on the object they were invited to with the requested [role](/api/roles.md).

## Create an Invitation

<mark style="color:green;">`POST`</mark> `https://ws-api.onehub.com/:item/:id/invitations`

Create an invitation to the `:item` (Workspace, folder, or file) specified via `:id`.

#### Path Parameters

| Name  | Type    | Description                                                                  |
| ----- | ------- | ---------------------------------------------------------------------------- |
| :item | string  | The type of item. Can be `workspaces`, `folders`, or `files`.                |
| :id   | integer | The unique identifier of the item you would like to create an invitation to. |

#### Request Body

| Name       | Type   | Description                                                                                                                      |
| ---------- | ------ | -------------------------------------------------------------------------------------------------------------------------------- |
| invitation | object | This is the top level object that contains the `emails` and `role_name` keys described below.                                    |
| emails     | string | The email addresses you would like to invite to the item. Multiple email addresses should be comma delimited in a single string. |
| role\_name | string | The effective role granted to the user(s).                                                                                       |

{% tabs %}
{% tab title="201 Returns a share object and a 201 if the call succeeds." %}

```yaml
{
  "share": {
    "emails": "",
    "email_errors": [],
    "join_errors": [],
    "invited_emails": [
      { "first-user@example.com": 5967 },
      { "second-user@example.com": 5977 }
    ],
    "errors": {}
  }
}
```

{% endtab %}

{% tab title="422 Returns a 422 with an error in the message body if an invalid email is provided or if a limit is reached." %}

```yaml
//
```

{% endtab %}
{% endtabs %}

#### Example Request Body

```javascript
{
  "invitation": {
    "emails": "first-user@example.com, second-user@example.com",
    "role_name": "Creator"
  }
}
```

{% hint style="info" %}
If a `role_name` is not provided, or is invalid, the [default role](/api/roles.md#available-roles) will be used.
{% endhint %}