Get shared contacts

You can request shared user contacts in a variety of ways:

  • All shared contacts
  • A set of contacts that match a specified criteria
  • A single shared contact
  • A photo for a contact

By default, the entries in a feed aren't ordered.

Get all shared contacts

  1. To get all shared contacts, send an HTTP GET request to the contacts feed URL:

    GET https://www.google.com/m8/feeds/contacts/DOMAIN/PROJECTION

    Replace the following:

    • DOMAIN: The URL for your domain—for example, example.com.
    • PROJECTION: The projection value that specifies the gd:extendedProperty elements. For a list of supported values, see Projection values.

    The feed returns an HTTP 200 OK status code and a standard Atom 1.0 feed containing the contacts. The following is an example of a contacts feed with only one entry:

    <feed xmlns='http://www.w3.org/2005/Atom'
    xmlns:openSearch='http://a9.com/-/spec/opensearchrss/1.0/'
    xmlns:gd='http://schemas.google.com/g/2005'
    xmlns:gContact='http://schemas.google.com/contact/2008'
    xmlns:batch='http://schemas.google.com/gdata/batch'>
  <id>https://www.google.com/m8/feeds/contacts/example.com/base</id>
  <updated>2008-03-05T12:36:38.836Z</updated>
  <category scheme='http://schemas.google.com/g/2005#kind'
    term='http://schemas.google.com/contact/2008#contact' />
  <title type='text'>example.com's Contacts</title>
  <link rel='http://schemas.google.com/g/2005#feed'
    type='application/atom+xml'
    href='https://www.google.com/m8/feeds/contacts/example.com/full' />
  <link rel='http://schemas.google.com/g/2005#post'
    type='application/atom+xml'
    href='https://www.google.com/m8/feeds/contacts/example.com/full' />
  <link rel='http://schemas.google.com/g/2005#batch'
    type='application/atom+xml'
    href='https://www.google.com/m8/feeds/contacts/example.com/full/batch' />
  <link rel='self' type='application/atom+xml'
    href='https://www.google.com/m8/feeds/contacts/example.com/full?max-results=25' />
  <author>
    <name>example.com</name>
    <email>example.com</email>
  </author>
  <generator version='1.0' uri='https://www.google.com/m8/feeds/contacts'>
    Contacts
  </generator>
  <openSearch:totalResults>1</openSearch:totalResults>
  <openSearch:startIndex>1</openSearch:startIndex>
  <openSearch:itemsPerPage>25</openSearch:itemsPerPage>
  <entry>
    <id>
      https://www.google.com/m8/feeds/contacts/example.com/base/c9012de
    </id>
    <updated>2008-03-05T12:36:38.835Z</updated>
    <category scheme='http://schemas.google.com/g/2005#kind'
      term='http://schemas.google.com/contact/2008#contact' />
    <title type='text'>Fitzgerald</title>
    <gd:name>
      <gd:fullName>Fitzgerald</gd:fullName>
    </gd:name>
    <link rel="http://schemas.google.com/contacts/2008/rel#photo" type="image/*"
      href="http://google.com/m8/feeds/photos/media/example.com/c9012de"/>
    <link rel='self' type='application/atom+xml'
      href='https://www.google.com/m8/feeds/contacts/example.com/full/c9012de' />
    <link rel='edit' type='application/atom+xml'
      href='https://www.google.com/m8/feeds/contacts/example.com/full/c9012de/1204720598835000' />
    <gd:phoneNumber rel='http://schemas.google.com/g/2005#home'
      primary='true'>
      456
    </gd:phoneNumber>
    <gd:extendedProperty name="pet" value="hamster" />
  </entry>
</feed>

  2. The feed doesn't return more than 10MB in a single response. To get the entire contact list, repeatedly follow the returned feed's Next link until you no longer see that link in the return feed.

Get shared contacts by using query parameters

You can request a set of contacts that match a specified criteria, such as requesting contacts updated after a given date. There is no support for full-text queries or locating a contact by email address. For a complete list of supported query parameters, see Domain Shared Contacts API reference guide.

  1. Send an HTTP GET request to the contacts feed URL with a defined parameter:

    GET https://www.google.com/m8/feeds/contacts/DOMAIN/PROJECTION?PARAMETER

    Replace the following:

    • DOMAIN: The URL for your domain—for example, example.com.
    • PROJECTION: The projection value that specifies the gd:extendedProperty elements. For a list of supported values, see Projection values.
    • PARAMETER: One of the supported query parameters. For more information, see Domain Shared Contacts API reference guide.

    For example, to get all the domain shared contact entries updated after March 16, 2022 for example.com, send an HTTP request to the domain shared contact feed URL and add the updated-min parameter to the request URL:

    GET https://www.google.com/m8/feeds/contacts/example.com/full?updated-min=2022-03-16T00:00:00

    When you send that GET request, the server returns an HTTP 200 OK status code and a feed containing any domain shared contacts that were created or updated after the date specified.

  2. The feed doesn't return more than 10MB in a single response. To get the entire contact list with the specified criteria, repeatedly follow the returned feed's Next link until you no longer see that link in the return feed.

Track incremental changes

To track incremental changes to a domain shared contact list, do the following: 1. When you send a request for a feed, keep track of the value of the feed's <updated> element. 1. You can get only the domain shared contacts that have changed since the previous request by setting the query parameter updated-min to that <updated> value, and setting showdeleted to true.

Get a single shared contact

To get a single shared contact, you must use the contact's self link. You can only get the shared contact's self link by locating the contact's entry in the shared contacts feed. If you're not sure what value to use for the self link, see Get all contacts and Get contacts by using query parameters.

  1. To get a specific domain shared contact, send an HTTP GET request to the self link of a contact: 
    GET https://www.google.com/m8/feeds/contacts/DOMAIN/PROJECTION/:SELF_LINK>
    Replace the following:
  • DOMAIN: The URL for your domain—for example, example.com.
  • PROJECTION: The projection value that specifies the gd:extendedProperty elements. For a list of supported values, see Projection values.
  • SELF_LINK: A unique numerical value that represents a single shared contact—for example, 12345.

The server then returns an HTTP 200 OK status code and an entry containing the contact.

For example, to get a domain shared contact with self link set to https://www.google.com/m8/feeds/contacts/example.com/full/12345, send the following HTTP request:

GET https://www.google.com/m8/feeds/contacts/example.com/full/12345

Next steps