> ## Documentation Index
> Fetch the complete documentation index at: https://velt.dev/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Add Users

Use this API to add Users to:

1. **Organization:** This will provide them access to all the documents in the organization unless the document has `restricted` access type. It will also show users in the contact list of the organization.
2. **Folder:** This will provide them access to all the documents in the folder. If you pass the `folderId`, then the users will be added to the folder and not the organization.
3. **Document:** This will provide them access to the specified document. It will also show users in the contact list of the document. If you pass the `documentId`, then the users will be added to the document and not the organization or folder.

<Info>
  * If organization does not exist, it will be created.
  * If you provide documentId or folderId, then the users will only be added at that level and not at the organization level. To also add users at the organization level, you will need to call this API again with only the organizationId.
  * If User's `initial` is not provided in the User object, then it will be automatically created using the name field.
</Info>

# Endpoint

`POST https://api.velt.dev/v1/users/add`

# Headers

<ParamField header="x-velt-api-key" type="string" required>
  Your API key.
</ParamField>

<ParamField header="x-velt-auth-token" type="string" required>
  Your [Auth Token](/security/auth-tokens).
</ParamField>

# Body

#### Params

<ParamField body="data" type="object" required>
  <Expandable title="properties">
    <ParamField body="organizationId" type="string" required>
      Organization ID
    </ParamField>

    <ParamField body="documentId" type="string">
      Document ID. Provide this if you want to add users to a specific document.
    </ParamField>

    <ParamField body="folderId" type="string">
      Folder ID. Provide this if you want to add users to a specific folder. Either provide `documentId` or `folderId`.
    </ParamField>

    <ParamField body="users" type="User[]" required>
      Array of [User](/api-reference/sdk/models/data-models#user) objects.
    </ParamField>
  </Expandable>
</ParamField>

## **Example Requests**

#### 1. Add users to a specific organization

```JSON theme={null}
{
  "data": {
    "organizationId": "yourOrganizationId",
    "users": [
      {
        "userId": "yourUserId1",
        "name": "User Name",
        "email": "user@email.com"
      }
    ]
  }
}
```

#### 2. Add users to a specific document within an organization

```JSON theme={null}
{
  "data": {
    "organizationId": "yourOrganizationId",
    "documentId": "yourDocumentId",
    "users": [
      {
        "userId": "yourUserId1",
        "name": "User Name",
        "email": "user@email.com"
      }
    ]
  }
}
```

#### 3. Add users to a specific folder within an organization

```JSON theme={null}
{
  "data": {
    "organizationId": "yourOrganizationId",
    "folderId": "yourFolderId",
    "users": [
      {
        "userId": "yourUserId1",
        "name": "User Name",
        "email": "user@email.com"
      }
    ]
  }
}
```

# Response

#### Success Response

```JSON theme={null}
{
  "result": {
    "status": "success",
    "message": "User(s) processed successfully.",
    "data": {
      "yourUserId1": {
        "success": true,
        "id": "4c250058149d6c9fb8c894c9ef29c790",
        "message": "User added."
      }
    }
  }
}
```

#### Failure Response

```JSON theme={null}
{
  "error": {
    "message": "ERROR_MESSAGE",
    "status": "INVALID_ARGUMENT"
  }
}
```

<ResponseExample>
  ```js theme={null}
  {
    "result": {
      "status": "success",
      "message": "User(s) processed successfully.",
      "data": {
        "yourUserId1": {
          "success": true,
          "id": "4c250058149d6c9fb8c894c9ef29c790",
          "message": "User added."
        }
      }
    }
  }
  ```
</ResponseExample>