Overview

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