Skip Navigation
  1. BlackBerry Docs
  2. BlackBerry Enterprise Mobility Server 3.7
  3. Contact Service API
  4. Requesting contact list information
  5. Request contacts

Request contacts

You can retrieve contacts from a user's main contact folder and from subfolders that the user has created. Deleted contacts are not returned. If the FolderId is not provided by the client in the request, contacts are retrieved from the main folder.
In the following sample,
BEMS
 retrieves all the contacts for the user, Jamie01, excluding any deleted contacts, from the specific subfolder. The first response from
BEMS
 includes up to 100 contacts, as specified by MaxNumber. Each contact that is retrieved includes the default Basic properties that are specified in
BEMS
. If more than 100 contacts are available (for example, this mailbox includes a TotalCount of 150 contacts) the response includes a MoreAvailable is true, so the client application sends additional requests using the NextOffset value to retrieve contacts in batches until MoreAvailable is false. In this example, the Basic properties returns the following information for the contacts:
  • Display name
  • Email address
  • Given name
  • Surname
In the following example, the client provides a FolderId and
BEMS
 retrieves the contacts from the specific folder. 
POST https://localhost:8443/api/contact 
HTTP/1.1Content-Type: application/json
X-Good-GD-AuthToken: <
GDAuthToken
>
  {  "Account": "jamie01@ex365.example.com",  
     "MaxNumber": 100,  
     "Offset": 0,  
     "UserShape": ["Basic"],
     "FolderId": "AQMkADk0YzU4MjdkLWU1YjktNGE0OC1iZDczKI0Kuc7BmRwA..."" (optional)
  }
If the request is successful,
BEMS
 returns the first 100 contacts that meet the query criteria.
BEMS
 also returns a TotalCount of contacts and NextPageOffset to retrieve the next batch of contacts. 
{ 
 "LookupInfo": 
  { 
    "MoreAvailable": true,
    "TotalCount": 150, 
    "NextPageOffset": 100,
    "Size": 100, 
    "Offset": 0
  },
 "Contacts": [ 
   {
    "DisplayName": "user1_02", 
    "EmailAddress": "user1_02@example.com", 
    "GivenName": "user1",
    "Surname": "02", 
    "UniqueId" : "AAMkADg2Y2IxMzAwLWJmZmYtAAMkADg2Y..."
   },
   {
    "DisplayName": "user2_03", 
    "EmailAddress": "user2_03@example.com", 
    "GivenName": "user2",
    "Surname": "03", 
    "UniqueId" : "AAMkADg2Y2IxMzAwLWJmZmYtNGJjMi1iN..."
   },
 ...
  ]
}
The client sets the Offset to NextPageOffset from the previous query to receive the next batch. 
POST https://localhost:8443/api/contact HTTP/1.1
Content-Type: application/json
X-Good-GD-AuthToken: <
GDAuthToken
>
  {  "Account": "jamie01@ex365.example.com",  
     "MaxNumber": 100,  
     "Offset": 100,  
     "UserShape": ["Basic"],
     "FolderId": "AQMkADk0YzU4MjdkLWU1YjktNGE0OC1iZDczKI0Kuc7BmRwA..."" (optional)
  }
BEMS
 returns the next 50 contacts for a total of 150 contacts. No additional contacts are available. 
{ 
 "LookupInfo": 
  { 
    "MoreAvailable": false,
    "TotalCount": 150, 
    "NextPageOffset": null,
    "Size": 50, 
    "Offset": 100
  }, 
  "Contacts": [
   {
    "DisplayName": "user55_05", 
    "EmailAddress": "user55@example.com", 
    "GivenName": "user55",
    "Surname": "05", 
    "UniqueId" : "tNGJjMi1iNAAMkADg2Y2IxMzAwLWJmZmY..."
   },
   {
    "DisplayName": "user56_06", 
    "EmailAddress": "user56@example.com", 
    "GivenName": "user56",
    "Surname": "06", 
    "UniqueId" : "AAMkADg2Y2IxMmZmYtNGJjMi1iNzAwLWJ..."
   },
  ...
}