Retrieving contact list information properties Skip Navigation

Retrieving contact list information properties

The following table describes the request body properties that you can include in the JSON formatted request when you retrieve contact list information from a user's folder in the mailbox.
Parameter
Type
Description
Account
String
This parameter specifies the user's email account that is used to request contact information (for example, jamie01@ex365.example.com).
ByName
String
This parameter specifies to search the user's local contacts based on a specific name.
The search results include all contacts with a set of specified characters. For example, "ByName": "Jane" will return all users that have Jane as their first name, last name, or a part of their name.
When you use this parameter, you can also include the UserShape properties "Basic" or "Detail" to retrieve additional information for the returned contacts. See the UserShape parameter below for more information.  
ByEmail
String
This parameter specifies to search the user's local contact list with a specific email address.
When you use this parameter, you can also include the UserShape parameter properties "Basic" or "Detail" to retrieve additional information for the returned contacts. See the UserShape parameter below for more information.  
FolderId
String
This parameter retrieves contacts from the specified FolderId. This is optional. If the FolderId is not specified,
BEMS
retrieves the contacts from the user's contact folder.
MaxNumber
Integer
This parameter specifies the maximum number of contacts or objects to return in the search query. By default, BEMS can only return up to 512 items at a time. The client must make multiple calls to retrieve more than 512 items by setting the "Offset" parameter. The "MoreAvailable" value tells the client if more items are available. See the API response table below for more information.
Offset
Integer
This parameter specifies the starting point of a batch response. By default, the Offset is 0 (zero).
SinceTs
Integer (long)
This parameter specifies the new or modified contacts in the user's personal contact list since a specified time. SinceTs is specified in epoch time format. If you want to retrieve the new and modified contacts, you must specify the SinceTs to begin searching for contacts.
If the SinceTs is not specified,
BEMS
retrieves all of the contacts from the user's contact folder.
When you use this parameter, you can also include the UserShape parameter properties "Basic" or "Detail" to retrieve additional information for the returned contacts. See the UserShape parameter below for more information.  
UserShape
String array
This parameter specifies the list of attributes to return in the search results (for example, Basic, MobilePhone, JobTitle, Photo).
UserShape supports a preset list of common properties list: Basic and Detail. The Basic and Detail property name lists can be configured in
BEMS
.
  • Basic: By default, this property returns the following list of properties: LastName, DisplayName, EmailAddress, and PhoneNumbers.
  • Detail: By default, this property returns the following list of properties in addition to the Basic properties: PhyicalAddresses, CompanyName, JobTitle, Department, and Photo.
For instructions on how administrators can view or configure the UserShape properties, see Appendix: Configure the UserShape properties.

API response

The following table describes the response properties that might appear in the JSON formatted API response when you retrieve contacts from the user's local contact list.
Property
Type
Description
MoreAvailable
Boolean
This parameter indicates that more contacts are available than the response returned.
If MoreAvailable is true, then the client continues to call the API changing the "Offset" value to the value received in the previous response. The client performs this call until the MoreAvailable value is false, which indicates that there are no more contacts to be returned.
TotalCount
Integer 
This parameter specifies the total number of contacts that match the fetch query.
NextPageOffset
Integer or null
This parameter specifies the starting point of the second batch of contacts that are returned.
Size
Integer
This parameter specifies the number of contacts returned in the response, up to the MaxNumber size specified.
Offset
Integer
This parameter specifies the starting point of a batch response.
Collection
List of MAP
This parameter specifies a list of contacts returned in the request.