getUser()

const params = {
  q: `[userid] eq 'john_doe@visualvault.com'`,
  fields: "id, name",
  UserExtendedProperties: true,      
  acctInfo: true
};
 
const res = await vvClient.users.getUser(params)

Overview

getUser() is a method in the VisualVault Node.js vvClient wrapper that retrieves user data—including associated metadata—for one or multiple users across all sites.

Clarification: getUsers() vs getUser()

• getUsers(): This method retrieves up to 200 users within a specific site. It is scoped to the site provided in the query, making it ideal for operations limited to a single site.

• getUser(): This method retrieves user data across all sites, regardless of the specific site context. Use this when you need information about a user globally, not tied to a particular site.

Use Cases

• Find information about a single user: Obtain data for a specific user in a site by including the q parameter.

• Find all users in a site: Retrieves data for up to 200 users in a site.

• Perform operations on user objects: Use the returned user data with the vvClient wrapper library to perform additional operations—such as enabling or disabling multiple users in bulk.

Method Signature

vvClient.users.getUser(params)

Parameters

Params Object Example

const params = {
  q: `[userid] eq 'john_doe@visualvault.com'`,
  fields: "id, name",
  UserExtendedProperties: true,      
  acctInfo: true
};

Response

A typical successful response includes:

Response Examples

Records Found:

{
  "meta": {
    "status": 200,
    "statusMsg": "OK",
    "method": "GET",
    "href": "https://vvdemo.visualvault.com/api/v1/TestEnv/TestUsr/users?q=%5Buserid%5D eq %27john.doe%40visualvault.com%27"
  },
  "data": [
    {
      "href": "~/users/f35916ce-836c-4e9d-9ab3-6282c1677505",
      "dataType": "User",
      "id": "f35916ce-836c-4e9d-9ab3-6282c1677505",
      "name": "john.doe@visualvault.com",
      "userid": "john.doe@visualvault.com",
      "firstName": "John",
      "middleInitial": "",
      "lastName": "Doe",
      "passwordExpires": "9999-12-31T00:00:00Z",
      "userIdExpires": "2025-12-31T00:00:00Z",
      "emailAddress": "john.doe@visualvault.com",
      "siteId": "c90ed034-45ec-4508-bd31-85bc08093b6e",
      "userIdNeverExpires": false,
      "passwordNeverExpires": true,
      "enabled": true,
      "lastIpAddress": "",
      "modifyDate": "2025-01-16T13:11:10.54Z",
      "isVaultAccess": true,
      "isVaultAdmin": false
    }
  ]
}

acctInfo Parameter Set On true:

{
  "meta": {
    "status": 200,
    "statusMsg": "OK",
    "method": "GET",
    "href": "https://vvdemo.visualvault.com/api/v1/TestEnv/TestUsr/users?q=%5Buserid%5D eq %27john.doe%40visualvault.com%27"
  },
  "data": [
    {
      "href": "~/users/f35916ce-836c-4e9d-9ab3-6282c1677505",
      "dataType": "User",
      "id": "f35916ce-836c-4e9d-9ab3-6282c1677505",
      "name": "john.doe@visualvault.com",
      "userid": "john.doe@visualvault.com",
      "firstName": "John",
      "middleInitial": "",
      "lastName": "Doe",
      "passwordExpires": "9999-12-31T00:00:00Z",
      "userIdExpires": "2025-12-31T00:00:00Z",
      "emailAddress": "john.doe@visualvault.com",
      "siteId": "c90ed034-45ec-4508-bd31-85bc08093b6e",
      "userIdNeverExpires": false,
      "passwordNeverExpires": true,
      "enabled": true,
      "lastIpAddress": "",
      "modifyDate": "2025-01-16T13:11:10.54Z",
      "isVaultAccess": true,
      "isVaultAdmin": false
    }
  ],
  "account": {
    "href": "",
    "dataType": "CustomerBillingStatusInformation",
    "name": "Acme",
    "accountStatus": 0,
    "trialStartDate": "0001-01-01T00:00:00Z",
    "trialEndDate": "0001-01-01T00:00:00Z",
    "dateCanceled": "0001-01-01T00:00:00Z",
    "dateSuspended": "0001-01-01T00:00:00Z",
    "dateToExpire": "0001-01-01T00:00:00Z",
    "dateToClose": "0001-01-01T00:00:00Z",
    "dateClosed": "0001-01-01T00:00:00Z",
    "billingStartDate": "0001-01-01T00:00:00Z"
  }
}

No Records Found:

{
  "meta": {
    "status": 200,
    "statusMsg": "OK",
    "method": "GET",
    "href": "..."
  },
  "data": []
}

Invalid Template Name:

{"message": "The request is invalid."}

Invalid Field Name in Query:

{
  meta: {
    status: 400,
    statusMsg: "BadRequest",
    method: "GET",
    href: "https://vv5dev.visualvault.com/api/v1/CityofLincoln/Phase2/formtemplates/5e98a19a-afe9-ed11-b97d-0e849d8fa1ab/forms?q=Fake Name eg \"test\"",
    errors: [
      {
        code: null,
        developerMessage: "Invalid expression, invalid column: 'Fake Name', at loc:1",
        message: "Invalid expression, invalid column: 'Fake Name', at loc:1",
        reason: "Query syntax error",
      },
    ],
  },
}

User Metadata Properties

Regardless of whether you request data for specific fields or all fields, each record object always includes the following metadata:

Account Information Properties

This object includes the following properties (included only if the acctInfo parameter is set to true). All date values are provided in ISO 8601 format.

Limitations

• User Limit In Response: The getUser() method can return a maximum of 200 users per request, regardless of the query parameters provided.

• Site User Limit: Each site has a configured user limit, typically set to 2,000 users. If you’re unsure of the specific limit, consult the site administrator.

Best Practices

• Clean up names and emails: Remove any leading or trailing spaces and escape apostrophes to ensure more accurate query results.

• Retrieve only active users: Unless otherwise required by your logic, filter for enabled users to exclude data for users who are no longer active.

Related Methods

• getUsers()