# 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 %}


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://developer.onehub.com/methods/invitations.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.