Skip to content

CardDAV explained with examples

Jump to bottom
Christian Scholten edited this page Apr 24, 2019 · 1 revision

For future use, here is some explanation of the CardDAV protocol, including some example messages.

CardDAV exists of 3 main models: users, addressbooks and contacts. A user (also called principal), has multiple addressbooks, while an addressbook has multiple contacts.

Information is exchanged via props. The WebDAV (CardDAV is an extension on WebDAV) protocol allows to request specific props using the PROPFIND method.

Example requests

Principal

Request for basic information

PROPFIND /webdav/7313/155bb7c7b79f8d219ead4862fc8f0542878c748c86269683613bbafa20cd9a73/contacts

<?xml version="1.0" encoding="utf-8" ?>
<A:propfind xmlns:A="DAV:">
  <A:prop><A:resourcetype/><A:current-user-principal/></A:prop>
</A:propfind>

Response

<?xml version="1.0"?>
<D:multistatus xmlns:D="DAV:" xmlns:C="urn:ietf:params:xml:ns:carddav" xmlns:APPLE1="http://calendarserver.org/ns/">
  <D:response>
    <D:href>/webdav/7313/155bb7c7b79f8d219ead4862fc8f0542878c748c86269683613bbafa20cd9a73/contacts/</D:href>
    <D:propstat>
      <D:prop>
        <D:resourcetype>
          <D:collection/>
          <D:principal/>
        </D:resourcetype>
        <D:current-user-principal>
          <D:href>/webdav/7313/155bb7c7b79f8d219ead4862fc8f0542878c748c86269683613bbafa20cd9a73/contacts</D:href>
        </D:current-user-principal>
      </D:prop>
      <D:status>HTTP/1.0 200 OK</D:status>
    </D:propstat>
  </D:response>
</D:multistatus>

Request for addressbooks

PROPFIND /webdav/7313/155bb7c7b79f8d219ead4862fc8f0542878c748c86269683613bbafa20cd9a73/contacts

<?xml version="1.0" encoding="utf-8" ?>
<A:propfind xmlns:A="DAV:" xmlns:B="urn:ietf:params:xml:ns:carddav">
   <A:prop><B:addressbook-home-set/></A:prop>
</A:propfind>

Response

<?xml version="1.0"?>
<D:multistatus xmlns:D="DAV:" xmlns:C="urn:ietf:params:xml:ns:carddav" xmlns:APPLE1="http://calendarserver.org/ns/">
  <D:response>
    <D:href>/webdav/7322/f193cb4a4a6f729fdcd206c6545a92c16ab41337c2e017648ae829a9983b0f48/contacts/</D:href>
    <D:propstat>
      <D:prop>
        <C:addressbook-home-set>
          <D:href>/webdav/7322/f193cb4a4a6f729fdcd206c6545a92c16ab41337c2e017648ae829a9983b0f48/contacts/books/</D:href>
        </C:addressbook-home-set>
      </D:prop>
      <D:status>HTTP/1.0 200 OK</D:status>
    </D:propstat>
  </D:response>
</D:multistatus>

Addressbook collection Request for basic information PROPFIND /webdav/7619/ad39646b04fe51ac1f81dc7d2ed5f00201b82d49bb8f2cba15e177700cd18eca/contacts/books/ Request

<A:propfind xmlns:A="DAV:"><A:prop><A:resourcetype/><A:displayname/></A:prop></A:propfind>

Response (for an addressbook with 3 contacts)

<?xml version="1.0"?>
<D:multistatus xmlns:D="DAV:" xmlns:C="urn:ietf:params:xml:ns:carddav" xmlns:APPLE1="http://calendarserver.org/ns/">
  <D:response>
    <D:href>/webdav/7619/ad39646b04fe51ac1f81dc7d2ed5f00201b82d49bb8f2cba15e177700cd18eca/contacts/books/</D:href>
    <D:propstat>
      <D:prop>
        <D:resourcetype>
          <D:collection/>
        </D:resourcetype>
        <D:displayname>books</D:displayname>
      </D:prop>
      <D:status>HTTP/1.0 200 OK</D:status>
    </D:propstat>
  </D:response>
  <D:response>
    <D:href>/webdav/7619/ad39646b04fe51ac1f81dc7d2ed5f00201b82d49bb8f2cba15e177700cd18eca/contacts/books/leden/</D:href>
    <D:propstat>
      <D:prop>
        <D:resourcetype>
          <D:collection/>
          <C:addressbook/>
        </D:resourcetype>
        <D:displayname>Leden</D:displayname>
      </D:prop>
      <D:status>HTTP/1.0 200 OK</D:status>
    </D:propstat>
  </D:response>
  <D:response>
    <D:href>/webdav/7619/ad39646b04fe51ac1f81dc7d2ed5f00201b82d49bb8f2cba15e177700cd18eca/contacts/books/leden/7618</D:href>
    <D:propstat>
      <D:prop>
        <D:resourcetype/>
        <D:displayname>7618</D:displayname>
      </D:prop>
      <D:status>HTTP/1.0 200 OK</D:status>
    </D:propstat>
  </D:response>
  <D:response>
    <D:href>/webdav/7619/ad39646b04fe51ac1f81dc7d2ed5f00201b82d49bb8f2cba15e177700cd18eca/contacts/books/leden/7617</D:href>
    <D:propstat>
      <D:prop>
        <D:resourcetype/>
        <D:displayname>7617</D:displayname>
      </D:prop>
      <D:status>HTTP/1.0 200 OK</D:status>
    </D:propstat>
  </D:response>
  <D:response>
    <D:href>/webdav/7619/ad39646b04fe51ac1f81dc7d2ed5f00201b82d49bb8f2cba15e177700cd18eca/contacts/books/leden/7616</D:href>
    <D:propstat>
      <D:prop>
        <D:resourcetype/>
        <D:displayname>7616</D:displayname>
      </D:prop>
      <D:status>HTTP/1.0 200 OK</D:status>
    </D:propstat>
  </D:response>
</D:multistatus>

Addressbook

Request for basic information

PROPFIND /webdav/7603/fb6119fa60613ade51b4cee71fcc5e3076acf86a1bbd8ef94e91f9e56bd1dc8f/contacts/books/leden/

<B:propfind xmlns:A="http://calendarserver.org/ns/" xmlns:B="DAV:">
  <B:prop>
    <B:supported-report-set/>
    <B:displayname/>
    <B:current-user-privilege-set/>
    <A:getctag/>
    <B:sync-token/>
  </B:prop>
</B:propfind>

Response

<?xml version="1.0"?>
<D:multistatus xmlns:D="DAV:" xmlns:C="urn:ietf:params:xml:ns:carddav" xmlns:APPLE1="http://calendarserver.org/ns/">
  <D:response>
    <D:href>/webdav/7603/fb6119fa60613ade51b4cee71fcc5e3076acf86a1bbd8ef94e91f9e56bd1dc8f/contacts/books/leden/</D:href>
    <D:propstat>
      <D:prop>
        <D:supported-report-set>
          <D:report><C:addressbook-multiget/></D:report>
        </D:supported-report-set>
        <D:displayname>Leden</D:displayname>
        <D:current-user-privilege-set>
          <D:privilege><D:read/></D:privilege>
          <D:privilege><D:write/></D:privilege>
          <D:privilege><D:write-properties/></D:privilege>
          <D:privilege><D:write-content/></D:privilege>
          <D:privilege><D:read-acl/></D:privilege>
          <D:privilege><D:read-current-user-privilege-set/></D:privilege>
        </D:current-user-privilege-set>
        <APPLE1:getctag>
          1512844716
        </APPLE1:getctag>
      </D:prop>
      <D:status>HTTP/1.0 200 OK</D:status>
    </D:propstat>
    <D:propstat>
      <D:prop>
        <D:sync-token/>
      </D:prop>
      <D:status>HTTP/1.0 501 Not Implemented</D:status>
    </D:propstat>
  </D:response>
  <D:response>
    <D:href>/webdav/7603/fb6119fa60613ade51b4cee71fcc5e3076acf86a1bbd8ef94e91f9e56bd1dc8f/contacts/books/leden/7602</D:href>
    <D:propstat>
      <D:prop>
        <D:supported-report-set/>
        <APPLE1:getctag/>
        <D:sync-token/>
      </D:prop>
      <D:status>HTTP/1.0 501 Not Implemented</D:status>
    </D:propstat>
    <D:propstat>
      <D:prop>
        <D:displayname>7602</D:displayname>
        <D:current-user-privilege-set>
          <D:privilege><D:read/></D:privilege>
          <D:privilege><D:read-acl/></D:privilege>
          <D:privilege><D:read-current-user-privilege-set/></D:privilege>
        </D:current-user-privilege-set>
      </D:prop>
      <D:status>HTTP/1.0 200 OK</D:status>
    </D:propstat>
  </D:response>
  <D:response>
    <D:href>/webdav/7603/fb6119fa60613ade51b4cee71fcc5e3076acf86a1bbd8ef94e91f9e56bd1dc8f/contacts/books/leden/7601</D:href>
    <D:propstat>
      <D:prop>
        <D:supported-report-set/>
        <APPLE1:getctag/>
        <D:sync-token/>
      </D:prop>
      <D:status>HTTP/1.0 501 Not Implemented</D:status>
    </D:propstat>
    <D:propstat>
      <D:prop>
        <D:displayname>7601</D:displayname>
        <D:current-user-privilege-set>
          <D:privilege><D:read/></D:privilege>
          <D:privilege><D:read-acl/></D:privilege>
          <D:privilege><D:read-current-user-privilege-set/></D:privilege>
        </D:current-user-privilege-set>
      </D:prop>
      <D:status>HTTP/1.0 200 OK</D:status>
    </D:propstat>
  </D:response>
  <D:response>
    <D:href>/webdav/7603/fb6119fa60613ade51b4cee71fcc5e3076acf86a1bbd8ef94e91f9e56bd1dc8f/contacts/books/leden/7600</D:href>
    <D:propstat>
      <D:prop>
        <D:supported-report-set/>
        <APPLE1:getctag/>
        <D:sync-token/>
      </D:prop>
      <D:status>HTTP/1.0 501 Not Implemented</D:status>
    </D:propstat>
    <D:propstat>
      <D:prop>
        <D:displayname>7600</D:displayname>
        <D:current-user-privilege-set>
          <D:privilege><D:read/></D:privilege>
          <D:privilege><D:read-acl/></D:privilege>
          <D:privilege><D:read-current-user-privilege-set/></D:privilege>
        </D:current-user-privilege-set>
      </D:prop>
      <D:status>HTTP/1.0 200 OK</D:status>
    </D:propstat>
  </D:response>
</D:multistatus>

Contact

Requesting address data

PROPFIND /webdav/97/98eb13d0ec475dce088ab827cb1f4aca1138ad9ed1bd3a18c6b5c5c484e7196a/contacts/books/leden/8

<B:propfind xmlns:A="http://calendarserver.org/ns/" xmlns:B="DAV:" xmlns:C="urn:ietf:params:xml:ns:carddav">
  <B:prop>
    <C:address-data/>
    <B:displayname/>
  </B:prop>
</B:propfind>

Response

<?xml version="1.0"?>
<D:multistatus xmlns:D="DAV:" xmlns:C="urn:ietf:params:xml:ns:carddav" xmlns:APPLE1="http://calendarserver.org/ns/">
  <D:response>
    <D:href>/webdav/97/98eb13d0ec475dce088ab827cb1f4aca1138ad9ed1bd3a18c6b5c5c484e7196a/contacts/books/leden/8</D:href>
    <D:propstat>
      <D:prop>
        <C:address-data>                    
          BEGIN:VCARD
          VERSION:3.0
          N:Koster;Anna;de;;
          FN:Anna de Koster
          BDAY:19901226
          ADR;TYPE=home:;;Brinkpark 814;Noord Thijsenmaes;;7547 FY;
          EMAIL:[email protected]
          TEL;TYPE=voice,cell:0656149343
          REV:20171209T201519
          PRODID:C.S.V. Alpha
          END:VCARD
        </C:address-data>
        <D:displayname>8</D:displayname>
      </D:prop>
      <D:status>
        HTTP/1.1 200 OK
      </D:status>
    </D:propstat>
  </D:response>
</D:multistatus>
Clone this wiki locally