Page Summary
-
After setup, the People API allows you to read directory contacts and profiles within a user's domain.
-
Domain administrators must enable external contact and profile sharing for the API to access domain data.
-
You can retrieve a list of all directory people, or focus on specific people by using the search functionality with prefix queries.
-
The API provides methods for efficiently listing directory people that have changed since the last sync, minimizing data transfer.
-
Detailed documentation and code samples in Java and HTTP are available to guide implementation and usage of the API.
After you've completed the steps in Get Ready to Use the People API , you are ready to read directory contacts and profiles.
The following code samples demonstrate how to send a few simple requests. For a full list of methods, see the reference documentation .
List the directory people
To get a list of contacts and profiles in the user's domain directory , use the following code:
Protocol
GET /v1/people:listDirectoryPeople?sources=DIRECTORY_SOURCE_TYPE_DOMAIN_CONTACT&sources=DIRECTORY_SOURCE_TYPE_DOMAIN_PROFILE&readMask=names,emailAddresses HTTP / 1.1 Host : people.googleapis.com
Java
List<String > sources = new ArrayList < > (); sources . add ( "DIRECTORY_SOURCE_TYPE_DOMAIN_CONTACT" ); sources . add ( "DIRECTORY_SOURCE_TYPE_DOMAIN_PROFILE" ); ListDirectoryPeopleResponse response = peopleService . people (). listDirectoryPeople () . setSources ( sources ) . setReadMask ( "metadata,names,emailAddresses" ) . execute (); List<Person > people = response . getPeople ();
List the directory people that have changed
Java
// Initial request List<String > sources = new ArrayList < > (); sources . add ( "DIRECTORY_SOURCE_TYPE_DOMAIN_CONTACT" ); sources . add ( "DIRECTORY_SOURCE_TYPE_DOMAIN_PROFILE" ); ListDirectoryPeopleResponse fullSyncResponse = peopleService . people (). listDirectoryPeople () . setSources ( sources ) . setReadMask ( "metadata,names,emailAddresses" ) . setRequestSyncToken ( true ) . execute (); // Fetch all the pages while ( fullSyncResponse . getNextPageToken () != null ) { fullSyncResponse = peopleService . people (). listDirectoryPeople () . setSources ( sources ) . setReadMask ( "metadata,names,emailAddresses" ) . setRequestSyncToken ( true ) . setPageToken ( fullSyncResponse . getNextPageToken ()) . execute (); } // Some time passes // Fetch incremental changes using the sync token returned in the last fullSyncResponse. try { ListDirectoryPeopleResponse incrementalSyncResponse = peopleService . people (). listDirectoryPeople () . setSources ( sources ) . setReadMask ( "metadata,names,emailAddresses" ) . setSyncToken ( fullSyncResponse . getNextSyncToken ()) . execute (); for ( Person person : incrementalSyncResponse . getDirectoryPeople ()) { handlePerson ( person ); } // Fetch all the pages while ( incrementalSyncResponse . getNextPageToken () != null ) { incrementalSyncResponse = peopleService . people (). listDirectoryPeople . setSources ( sources ) . setReadMask ( "metadata,names,emailAddresses" ) . setSyncToken ( fullSyncResponse . getNextSyncToken ()) . setPageToken ( incrementalSyncResponse . getNextPageToken ()) . execute (); for ( Person person : incrementalSyncResponse . getDirectoryPeople ()) { handlePerson ( person ); } } } catch ( GoogleJsonResponseException e ) { if ( e . getStatusCode () == 410 ) { // Sync token expired. Make full sync request. } } void handlePerson ( Person person ) { if ( person . getMetadata (). getDeleted ()) { // Handle deleted person } else { // Handle changed person } }
More details about sync behavior at ListDirectory .
Search the directory people
To get a list of contacts and profiles in the user's domain directory matching a prefix query , use the following code:
Protocol
POST /v1/people:searchDirectoryPeople?query=John&sources=DIRECTORY_SOURCE_TYPE_DOMAIN_CONTACT&sources=DIRECTORY_SOURCE_TYPE_DOMAIN_PROFILE&readMask=names,emailAddresses HTTP / 1.1 Host : people.googleapis.com
Java
Listsources = new ArrayList < > (); sources . add ( "DIRECTORY_SOURCE_TYPE_DOMAIN_CONTACT" ); sources . add ( "DIRECTORY_SOURCE_TYPE_DOMAIN_PROFILE" ); SearchDirectoryPeopleResponse response = peopleService . people (). searchDirectoryPeople () . setQuery ( "John" ) . setSources ( sources ) . setReadMask ( "metadata,names,emailAddresses" ) . execute (); List<Person > people = response . getPeople ();
