Last modified on August 22, 2023 at 8:09 pm
Overview
Retrieve a list of all users in your organization with a specified email address. The search will be performed using a substring match, allowing you to search for all users whose email contains a particular domain, for example. However, this means that when searching for an exact email address you will need to do your own check on the results to ensure the record is an exact match and not simply a substring of the email address you specified. 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": ""
}
Examples
Substring Search on Domain
This example shows use of the substring match to find all users whose email addresses contain a specific domain name.
Request
GET /dc/api/v5/users?email=@exampleorg.com HTTP/1.1 Host: api.digitalchalk.com Accept: application/json
Response
HTTP/1.1 200 OK
Content-type: application/json
Content-length: 931
{
results: [
{
"id": "3622881a721f0fe399dc6f1086a4510e",
"firstName": "Richard",
"lastName": "Munroe",
"username": "rmunroe",
"email": "support@exampleorg.com",
"tags": [ "nm", "santafe" ],
"locale": "en",
"createdDate": "2009-04-15T00:50:04Z",
"lastLoginDate": "2013-11-05T06:27:02Z"
},
{
"id": "624335ee29ac7d2399dc6f123974ac71",
"firstName": "Wayne",
"lastName": "Szynkowski",
"username": "wszynkowski",
"email": "billingsupport@exampleorg.com",
"locale": "en",
"createdDate": "2011-02-26T00:50:04Z",
"lastLoginDate": "2012-02-01T06:27:02Z"
},
{
"id": "729a9d651237425b071903472390cf22",
"firstName": "Maria",
"lastName": "Szynkowski",
"username": "mszynkowski",
"email": "sales@exampleorg.com",
"locale": "en",
"createdDate": "2011-02-26T00:50:06Z",
"lastLoginDate": "2012-03-01T06:27:02Z"
},
{
"id": "6201889cadff2de399dc6f1239761121",
"firstName": "Marc",
"lastName": "Sanchez",
"username": "msanchez",
"email": "support@exampleorg.com",
"tags": [ "canada" ],
"locale": "en",
"createdDate": "2011-02-26T00:50:05Z",
"lastLoginDate": "2013-02-01T06:27:02Z"
}
]
}
Multiple Users with Matching Email Addresses
This example shows two scenarios where multiple results can be returned when searching on a single email address. In the first, when an organization has a usernames enabled, it is possible for multiple users to share a single email address. In the second, even though you have specified a full email address as a search parameter, it is possible that it will occur as a substring on another email address in the system.
Request
GET /dc/api/v5/users?email=support@exampleorg.com HTTP/1.1 Host: api.digitalchalk.com Accept: application/json
Response
HTTP/1.1 200 OK
Content-type: application/json
Content-length: 931
{
results: [
{
"id": "3622881a721f0fe399dc6f1086a4510e",
"firstName": "Richard",
"lastName": "Munroe",
"username": "rmunroe",
"email": "support@exampleorg.com",
"tags": [ "nm", "santafe" ],
"locale": "en",
"createdDate": "2009-04-15T00:50:04Z",
"lastLoginDate": "2013-11-05T06:27:02Z"
},
{
"id": "624335ee29ac7d2399dc6f123974ac71",
"firstName": "Wayne",
"lastName": "Szynkowski",
"username": "wszynkowski",
"email": "billingsupport@exampleorg.com",
"locale": "en",
"createdDate": "2011-02-26T00:50:04Z",
"lastLoginDate": "2012-02-01T06:27:02Z"
},
{
"id": "6201889cadff2de399dc6f1239761121",
"firstName": "Marc",
"lastName": "Sanchez",
"username": "msanchez",
"email": "support@exampleorg.com",
"tags": [ "canada" ],
"locale": "en",
"createdDate": "2011-02-26T00:50:05Z",
"lastLoginDate": "2013-02-01T06:27:02Z"
}
]
}