Retrieve All Users – DigitalChalk Developer

Last modified on August 22, 2023 at 9:02 pm

Retrieve a list of all users defined in your organization. This request follows standard practices for paging and filter restriction conventions. The result of this GET request will be JSON-encoded representation of an array of user objects. The object definition is provided below.

JSON Object Definition

The following lists properties on the JSON object representing users you may encounter when retrieving a list of users. Fields with no value set are omitted from the JSON object. For a complete list of user properties and further details, see the User Object Reference.

{
  "id": "",
  "firstName": "",
  "lastName": "",
  "username": "",
  "email": "",
  "tags": [ "", ... ],
  "locale": "",
  "createdDate": "",
  "lastLoginDate": ""
}

Filtering

Filtering the result list can be accomplished by specifying value restrictions for many of the properties on the object. To filter on a specific property, pass a parameter on the GET request with the same name as the property you wish to filter on, specifying the target value as your parameter value. Unless otherwise noted, string-type properties are matched using case-insensitive substring searching.

You may filter the result list based on the following properties:

Parameter name	Details
createdDate	String representation of a date. This can be a precise timestamp, an imprecise date implying a range, or a range of dates. See the Date Filtering documenttation for more detail.
lastLoginDate	String representation of a date. This can be a precise timestamp, an imprecise date implying a range, or a range of dates. See the Date Filtering documenttation for more detail.
firstName	Filter based on the user’s first name.
lastName	Filter based on the user’s last name.
username	Filter based on the username field (if your organization has usernames turned on).
email	Filter based on the user’s email address.

Examples

Standard User List

This example shows a user listing from an organization with two users with usernames turned on (if usernames are disabled for your organization, the username properties will be omitted).

Request

GET /dc/api/v5/users HTTP/1.1
Host: org.digitalchalk.com
Accept: application/json

Response

HTTP/1.1 200 OK
Content-type: application/json
Content-length: 931

{
	results: [
		{
		  "id": "3622881a721f0fe399dc6f1086a4510e",
		  "firstName": "Marc",
		  "lastName": "Sanchez",
		  "username": "msanchez",
		  "email": "msanchez@exampleorg.com",
		  "tags": [ "nm", "santafe" ],
		  "locale": "en",
		  "createdDate": "2009-04-15T00:50:04Z",
		  "lastLoginDate": "2013-11-05T06:27:02Z"
		},
		{
		  "id": "48714967ae7c2de399dc6f1239741099",
		  "firstName": "Wayne",
		  "lastName": "Szynkowski",
		  "username": "wszynkowski",
		  "email": "wszynkowski@exampleorg.com",
		  "tags": [ "canada" ],
		  "locale": "en",
		  "createdDate": "2011-02-26T00:50:04Z",
		  "lastLoginDate": "2012-02-01T06:27:02Z"
		}
	]
}

User List Filtered by First Name

This example shows a user listing from the same organization, but in this case we provide specify a filter on the firstName property. Note that while the filter value is specified in all lower case, the actual value on the user object contains a capital letter. This is a result of the system performing a case-insensitive match.

Request

GET /dc/api/v5/users?firstName=marc HTTP/1.1
Host: org.digitalchalk.com
Accept: application/json

Response

HTTP/1.1 200 OK
Content-type: application/json
Content-length: 931

{
	results: [
		{
		  "id": "3622881a721f0fe399dc6f1086a4510e",
		  "firstName": "Marc",
		  "lastName": "Sanchez",
		  "username": "msanchez",
		  "email": "msanchez@exampleorg.com",
		  "tags": [ "nm", "santafe" ],
		  "locale": "en",
		  "createdDate": "2009-04-15T00:50:04Z",
		  "lastLoginDate": "2013-11-05T06:27:02Z"
		}
	]
}

Reference

User Object Reference