Request contacts Skip Navigation

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,
retrieves all the contacts for the user, Jamie01, excluding any deleted contacts, from the specific subfolder. The first response from
includes up to 100 contacts, as specified by MaxNumber. Each contact that is retrieved includes the default Basic properties that are specified in
. 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
retrieves the contacts from the specific folder.
POST https://localhost:8443/api/contact HTTP/1.1Content-Type: application/json X-Good-GD-AuthToken: <
> { "Account": "", "MaxNumber": 100, "Offset": 0, "UserShape": ["Basic"], "FolderId": "AQMkADk0YzU4MjdkLWU1YjktNGE0OC1iZDczKI0Kuc7BmRwA..."" (optional) }
If the request is successful,
returns the first 100 contacts that meet the query criteria.
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": "", "GivenName": "user1", "Surname": "02", "UniqueId" : "AAMkADg2Y2IxMzAwLWJmZmYtAAMkADg2Y..." }, { "DisplayName": "user2_03", "EmailAddress": "", "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: <
> { "Account": "", "MaxNumber": 100, "Offset": 100, "UserShape": ["Basic"], "FolderId": "AQMkADk0YzU4MjdkLWU1YjktNGE0OC1iZDczKI0Kuc7BmRwA..."" (optional) }
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": "", "GivenName": "user55", "Surname": "05", "UniqueId" : "tNGJjMi1iNAAMkADg2Y2IxMzAwLWJmZmY..." }, { "DisplayName": "user56_06", "EmailAddress": "", "GivenName": "user56", "Surname": "06", "UniqueId" : "AAMkADg2Y2IxMmZmYtNGJjMi1iNzAwLWJ..." }, ... }