Get Users

Retrieve users from a Velt workspace using the v2 REST API with filters by organization ID, document ID, user group IDs, or user IDs.

POST /v2/users/get

Get Users

cURL

curl --request POST \
  --url https://api.velt.dev/v2/users/get \
  --header 'Content-Type: application/json' \
  --header 'x-velt-api-key: <x-velt-api-key>' \
  --header 'x-velt-auth-token: <x-velt-auth-token>' \
  --data '
{
  "data": {
    "organizationId": "<string>",
    "documentId": "<string>",
    "folderId": "<string>",
    "userIds": [
      "<string>"
    ],
    "organizationUserGroupIds": [
      "<string>"
    ],
    "allDocuments": true,
    "groupByDocumentId": true,
    "pageSize": 123,
    "pageToken": "<string>"
  }
}
'

import requests

url = "https://api.velt.dev/v2/users/get"

payload = { "data": {
        "organizationId": "<string>",
        "documentId": "<string>",
        "folderId": "<string>",
        "userIds": ["<string>"],
        "organizationUserGroupIds": ["<string>"],
        "allDocuments": True,
        "groupByDocumentId": True,
        "pageSize": 123,
        "pageToken": "<string>"
    } }
headers = {
    "x-velt-api-key": "<x-velt-api-key>",
    "x-velt-auth-token": "<x-velt-auth-token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {
    'x-velt-api-key': '<x-velt-api-key>',
    'x-velt-auth-token': '<x-velt-auth-token>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    data: {
      organizationId: '<string>',
      documentId: '<string>',
      folderId: '<string>',
      userIds: ['<string>'],
      organizationUserGroupIds: ['<string>'],
      allDocuments: true,
      groupByDocumentId: true,
      pageSize: 123,
      pageToken: '<string>'
    }
  })
};

fetch('https://api.velt.dev/v2/users/get', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.velt.dev/v2/users/get",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'data' => [
        'organizationId' => '<string>',
        'documentId' => '<string>',
        'folderId' => '<string>',
        'userIds' => [
                '<string>'
        ],
        'organizationUserGroupIds' => [
                '<string>'
        ],
        'allDocuments' => true,
        'groupByDocumentId' => true,
        'pageSize' => 123,
        'pageToken' => '<string>'
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "x-velt-api-key: <x-velt-api-key>",
    "x-velt-auth-token: <x-velt-auth-token>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.velt.dev/v2/users/get"

	payload := strings.NewReader("{\n  \"data\": {\n    \"organizationId\": \"<string>\",\n    \"documentId\": \"<string>\",\n    \"folderId\": \"<string>\",\n    \"userIds\": [\n      \"<string>\"\n    ],\n    \"organizationUserGroupIds\": [\n      \"<string>\"\n    ],\n    \"allDocuments\": true,\n    \"groupByDocumentId\": true,\n    \"pageSize\": 123,\n    \"pageToken\": \"<string>\"\n  }\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("x-velt-api-key", "<x-velt-api-key>")
	req.Header.Add("x-velt-auth-token", "<x-velt-auth-token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.velt.dev/v2/users/get")
  .header("x-velt-api-key", "<x-velt-api-key>")
  .header("x-velt-auth-token", "<x-velt-auth-token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"data\": {\n    \"organizationId\": \"<string>\",\n    \"documentId\": \"<string>\",\n    \"folderId\": \"<string>\",\n    \"userIds\": [\n      \"<string>\"\n    ],\n    \"organizationUserGroupIds\": [\n      \"<string>\"\n    ],\n    \"allDocuments\": true,\n    \"groupByDocumentId\": true,\n    \"pageSize\": 123,\n    \"pageToken\": \"<string>\"\n  }\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.velt.dev/v2/users/get")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["x-velt-api-key"] = '<x-velt-api-key>'
request["x-velt-auth-token"] = '<x-velt-auth-token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"data\": {\n    \"organizationId\": \"<string>\",\n    \"documentId\": \"<string>\",\n    \"folderId\": \"<string>\",\n    \"userIds\": [\n      \"<string>\"\n    ],\n    \"organizationUserGroupIds\": [\n      \"<string>\"\n    ],\n    \"allDocuments\": true,\n    \"groupByDocumentId\": true,\n    \"pageSize\": 123,\n    \"pageToken\": \"<string>\"\n  }\n}"

response = http.request(request)
puts response.read_body

{
  "result": {
    "status": "success",
    "message": "User(s) retrieved successfully.",
    "data": [
      {
        "email": "[e-mail]",
        "name": "userName",
        "userId": "yourUserId"
      }
    ],
    "pageToken": "pageToken"
  }
}

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.

Prior to using this API, you must:

• Enable advanced queries option in the console
• Deploy v4 series of the Velt SDK.

Endpoint

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

Headers

x-velt-api-key · string · required

Your API key.

x-velt-auth-token · string · required

Your Auth Token.

Body

Params

data · object · required

Show properties

organizationId · string · required

Organization ID

documentId · string

Document ID

folderId · string

Folder ID. Either provide documentId or folderId.

userIds · string[]

Array of User IDs. Limit: Only 30 items can be passed at a time.

organizationUserGroupIds · string[]

Array of Organization User Group IDs. Only 30 items can be passed at a time.

allDocuments · 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.

groupByDocumentId · boolean

If true, the response will be grouped by document ID. This works when allDocuments is set to true.

pageSize · number

Number of items to be retrieved per page. Default: 1000.

pageToken · string

Page token retrieved from previous API call.

Example Requests

1. Get users by organizationId

{
  "data": {
    "organizationId": "yourOrganizationId",
    "pageSize": 1000,
    "pageToken": "pageToken"
  }
}

2. Get users by documentId within an organization

{
  "data": {
    "organizationId": "yourOrganizationId",
    "documentId": "yourDocumentId"
  }
}

3. Get Users from all documents within an organization.

{
  "data": {
    "organizationId": "yourOrganizationId",
    "allDocuments": true,
    "groupByDocumentId": true
  }
}

4. Get users by specific user IDs in an organization

{
  "data": {
    "organizationId": "yourOrganizationId",
    "userIds": [
      "yourUserId1",
      "yourUserId2"
    ]
  }
}

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

{
  "data": {
    "organizationId": "yourOrganizationId",
    "documentId": "yourDocumentId",
    "userIds": [
      "yourUserId1",
      "yourUserId2"
    ]
  }
}

6. Get users by organization and organization user group IDs

{
  "data": {
    "organizationId": "yourOrganizationId",
    "organizationUserGroupIds": [
      "yourOrganizationUserGroupId"
    ]
  }
}

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

{
  "data": {
    "organizationId": "yourOrganizationId",
    "userIds": [
      "yourUserId1",
      "yourUserId2"
    ],
    "organizationUserGroupIds": [
      "yourOrganizationUserGroupId"
    ]
  }
}

8. Get users by folderId within an organization

{
  "data": {
    "organizationId": "yourOrganizationId",
    "folderId": "yourFolderId"
  }
}

Response

Success Response

{
  "result": {
    "status": "success",
    "message": "User(s) retrieved successfully.",
    "data": [
      {
        "email": "[e-mail]",
        "name": "userName",
        "userId": "yourUserId"
      }
    ],
    "nextPageToken": "pageToken"
  }
}

Success Response with allDocuments and groupByDocumentId

{
  "result": {
    "status": "success",
    "message": "User(s) retrieved successfully.",
    "data": {
      "documentId1": [
        {
          "email": "[e-mail]",
          "name": "userName",
          "userId": "yourUserId"
        }
      ]
    },
    "nextPageToken": "pageToken"
  }
}

Failure Response

{
  "error": {
    "message": "Error retrieving user(s).",
    "status": "ERROR_CODE"
  }
}

{
  "result": {
    "status": "success",
    "message": "User(s) retrieved successfully.",
    "data": [
      {
        "email": "[e-mail]",
        "name": "userName",
        "userId": "yourUserId"
      }
    ],
    "pageToken": "pageToken"
  }
}