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

# Get Users

Use this API to retrieve users based on various filters such as organization ID, document ID, organization user group IDs or user IDs. You can use these filters in various combinations to get the desired users. Some examples are shown below.

<Warning>
  Prior to using this API, you must:

  * Enable advanced queries option in [the console](https://console.velt.dev/dashboard/config/appconfig)
  * Deploy v4 series of the Velt SDK.
</Warning>

# Endpoint

`POST https://api.velt.dev/v2/users/get`

# 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
    </ParamField>

    <ParamField body="folderId" type="string">
      Folder ID. Either provide `documentId` or `folderId`.
    </ParamField>

    <ParamField body="userIds" type="string[]">
      Array of User IDs. Limit: Only 30 items can be passed at a time.
    </ParamField>

    <ParamField body="organizationUserGroupIds" type="string[]">
      Array of Organization User Group IDs. Only 30 items can be passed at a time.
    </ParamField>

    <ParamField body="allDocuments" type="boolean">
      If true, all document users within the organization will be retrieved. You need not pass `documentId` in this case. This will not fetch organization-level users.
    </ParamField>

    <ParamField body="groupByDocumentId" type="boolean">
      If true, the response will be grouped by document ID. This works when `allDocuments` is set to true.
    </ParamField>

    <ParamField body="pageSize" type="number">
      Number of items to be retrieved per page. Default: 1000.
    </ParamField>

    <ParamField body="pageToken" type="string">
      Page token retrieved from previous API call.
    </ParamField>
  </Expandable>
</ParamField>

## **Example Requests**

#### 1. Get users by organizationId

```JSON theme={null}
{
  "data": {
    "organizationId": "yourOrganizationId",
    "pageSize": 1000,
    "pageToken": "pageToken"
  }
}
```

#### 2. Get users by documentId within an organization

```JSON theme={null}
{
  "data": {
    "organizationId": "yourOrganizationId",
    "documentId": "yourDocumentId"
  }
}
```

#### 3. Get Users from all documents within an organization.

```JSON theme={null}
{
  "data": {
    "organizationId": "yourOrganizationId",
    "allDocuments": true,
    "groupByDocumentId": true
  }
}
```

#### 4. Get users by specific user IDs in an organization

```JSON theme={null}
{
  "data": {
    "organizationId": "yourOrganizationId",
    "userIds": [
      "yourUserId1",
      "yourUserId2"
    ]
  }
}
```

#### 5. Get users by specific user IDs in the given organization and document

```JSON theme={null}
{
  "data": {
    "organizationId": "yourOrganizationId",
    "documentId": "yourDocumentId",
    "userIds": [
      "yourUserId1",
      "yourUserId2"
    ]
  }
}
```

#### 6. Get users by organization and organization user group IDs

```JSON theme={null}
{
  "data": {
    "organizationId": "yourOrganizationId",
    "organizationUserGroupIds": [
      "yourOrganizationUserGroupId"
    ]
  }
}
```

#### 7. Get users by organization, organization user group IDs and user IDs

```JSON theme={null}
{
  "data": {
    "organizationId": "yourOrganizationId",
    "userIds": [
      "yourUserId1",
      "yourUserId2"
    ],
    "organizationUserGroupIds": [
      "yourOrganizationUserGroupId"
    ]
  }
}
```

#### 8. Get users by folderId within an organization

```JSON theme={null}
{
  "data": {
    "organizationId": "yourOrganizationId",
    "folderId": "yourFolderId"
  }
}
```

# Response

#### Success Response

```JSON theme={null}
{
  "result": {
    "status": "success",
    "message": "User(s) retrieved successfully.",
    "data": [
      {
        "email": "userEmail@domain.com",
        "name": "userName",
        "userId": "yourUserId"
      }
    ],
    "nextPageToken": "pageToken"
  }
}
```

#### Success Response with allDocuments and groupByDocumentId

```JSON theme={null}
{
  "result": {
    "status": "success",
    "message": "User(s) retrieved successfully.",
    "data": {
      "documentId1": [
        {
          "email": "userEmail@domain.com",
          "name": "userName",
          "userId": "yourUserId"
        }
      ]
    },
    "nextPageToken": "pageToken"
  }
}

```

#### Failure Response

```JSON theme={null}
{
  "error": {
    "message": "Error retrieving user(s).",
    "status": "ERROR_CODE"
  }
}
```

<ResponseExample>
  ```js theme={null}
  {
    "result": {
      "status": "success",
      "message": "User(s) retrieved successfully.",
      "data": [
        {
          "email": "userEmail@domain.com",
          "name": "userName",
          "userId": "yourUserId"
        }
      ],
      "pageToken": "pageToken"
    }
  }
  ```
</ResponseExample>