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..."
   },
  ...
}