Manage contacts with the CardDAV protocol

You can view and manage your contacts using Google's CardDAV protocol.

Contacts are stored in the user's Google Account; most Google services have access to the contact list. Your client application can use the CardDAV API to create new contacts, edit or delete existing contacts, and query for contacts that match particular criteria.

Specifications

The full specification is not implemented, but many clients such as Apple iOS™ Contacts and macOS should interoperate correctly.

For each relevant specification, Google's CardDAV support is as follows:

• rfc2518: HTTP Extensions for Distributed Authoring (WebDAV)
  • Supports the HTTP methods GET, PUT, DELETE, OPTIONS, and PROPFIND.
  • Does not support the HTTP methods LOCK, UNLOCK, COPY, MOVE, or MKCOL.
  • Does not support arbitrary (user-defined) WebDAV properties.
  • Does not support WebDAV Access Control (rfc3744).
• rfc5995: Using POST to Add Members to WebDAV Collections
  • Supports creating new contacts without specifying an ID.
• rfc6352: CardDAV: vCard Extensions to Web Distributed Authoring and Versioning (WebDAV)
  • Supports the HTTP method REPORT, but not all defined reports are implemented.
  • Supports providing a principal collection and a contacts collection.
• rfc6578: Collection Synchronization for WebDAV
  • Client applications must switch to this mode of operation after the initial sync.
• rfc6749: The OAuth 2.0 Authorization Framework and rfc6750: The OAuth 2.0 Authorization Framework: Bearer Token Usage
  • Supports authenticating CardDAV client programs using OAuth 2.0 HTTP Authentication. Google does not support any other authentication method. For security of contact data, we require CardDAV connections to use HTTPS.
• rfc6764: Locating Services for Calendaring Extensions to WebDAV (CalDAV) and vCard Extensions to WebDAV (CardDAV)
  • Bootstrapping of CardDAV URLs must take place according to section 6 of rfc6764.
• Supports caldav-ctag-02: Calendar Collection Entity Tag (CTag) in CalDAV, which is shared between the CardDAV and CalDAV specifications. The contacts ctag is like a resource ETag; it changes when anything in the contact address book has changed. This allows the client program to quickly determine that it does not need to synchronize any changed contacts.
• Google uses VCard 3.0 as the contact encoding format. See: rfc6350: VCard 3.0.

Google’s CardDAV requires OAuth 2.0

Google’s CardDAV interface requires OAuth 2.0. Refer to the linked documentation below for information on using OAuth 2.0 to access Google APIs:

• Using OAuth 2.0 to Access Google APIs
• Using OAuth 2.0 for Installed Applications

Connecting to Google's CardDAV server

The CardDAV protocol allows discovery of the address book and contact resources URIs. You must not hardcode any URI as they could change at any time.

Client applications must use HTTPS, and OAuth 2.0 authentication must be provided for the user's Google account. The CardDAV server will not authenticate a request unless it arrives over HTTPS with OAuth 2.0 authentication of a Google account, and your application is registered on DevConsole. Any attempt to connect over HTTP with Basic authentication or with an email/password that doesn't match a Google account results in an HTTP 401 Unauthorized response code.

To use CardDAV, your client program must initially connect to the canonical discovery path by performing an HTTP PROPFIND on:

https://www.googleapis.com/.well-known/carddav

Once redirected (HTTP 301) to an Address Book Resource, your client program can then perform a PROPFIND on it to discover the DAV:current-user-principal, DAV:principal-URL, and addressbook-home-set properties. Your client program can then discover the principal address book by performing a PROPFIND on the addressbook-home-set and looking for the addressbook and collection resources. A full description of this process is beyond the scope of this document. See rfc6352 for more details.

The redirect path returned in the HTTP 301 response through a PROPFIND on the well-known URI must not be permanently cached (as per rfc6764). Devices should retry well-known URI discovery periodically to verify if the cached path is still up to date and resync if the path ever changes. Google recommends a rate of every 2-4 weeks.

Resources

CardDAV uses REST concepts. Client applications act on resources that are designated by their URIs. The current URI structure is specified here to help developers understand the concepts in the following section. The structure may change and must not be hardcoded. Rather, the resources should be discovered according to the RFC.

1. Principal
   • https://www.googleapis.com/carddav/v1/principals/userEmail
2. Home Set
   • https://www.googleapis.com/carddav/v1/principals/userEmail/lists
3. Address Book
   • https://www.googleapis.com/carddav/v1/principals/userEmail/lists/default
4. Contact
   • https://www.googleapis.com/carddav/v1/principals/userEmail/lists/default/contactId

Synchronizing Contacts

The following is a general description of the operations supported. Developers should look for the details in the relevant RFC. Requests and responses are mostly encoded in XML. These are the main operations used by client applications for synchronization:

• Using CTag
  • Client programs use the getctag PROPFIND request on the Address Book resource to determine if any contact has changed on the server and therefore whether a synchronization is needed. The value of this property is guaranteed to change if any contact changes. Client applications should store this value and use it only on the initial sync and as a fallback when a sync-token is invalidated. Periodically polling for the getctag property will result in throttling.
• Using sync-token
  • Client programs use the sync-token PROPFIND request on the Address Book to obtain the sync-token representing its current state. Client applications must store this value and issue periodic sync-collection REPORT requests to determine changes since the last issued sync-token. Issued tokens are valid for 29 days, and the REPORT response will contain a new sync-token.
• Using ETags
  • Client applications issue a getetag PROPFIND request on the Address Book resource (with DEPTH header equal to DEPTH_1). By maintaining the ETag value of each contact, a client program can request the value of contacts that had their ETag changed.
• Retrieving contacts
  • Client applications retrieve contacts by issuing an addressbook-multiget REPORT request. Given a list of contact URIs, the report returns all the requested contacts as VCard 3.0 values. Each entry includes an ETag for the contact.
• Inserting a contact
  • Client applications issue a POST request with the new contact in VCard 3.0 format. The response will contain the ID of the new contact.
• Updating a contact
  • Client applications issue a PUT request with the updated contact in VCard 3.0 format. The contact is updated if the contact already exists in the address book.
  • Client applications should include an If-Match header with the contact's currently known ETag. The server will then reject the PUT request (with HTTP 412) if the current ETag on the server is different from the ETag sent by the client program. This allows for optimistic serialization of updates.
• Deleting a contact
  • Client applications delete a contact by issuing a DELETE request against the contact URI.