API : CardDAV

The API server has a built-in CardDAV server (RFC 6352), so an employee can subscribe to the Telecom X phonebook directly from the contacts app on an iPhone, iPad, Mac, Android (DAVx5), Thunderbird or any other CardDAV client. Contacts then appear as ordinary contacts on the device, with caller ID on incoming calls.

It is not a REST/JSON API - it speaks WebDAV over HTTPS and serves vCard 3.0. No employee feature or minimum access level is required: every employee that can log in can sync, and always only within their own customer.

Every employee is served three address books. They are named in the employees own language (da or anything else, which falls back to English).

• personal and shared are the PBX phonebook (Mongo collection PbxPhonebook). A contact belongs to the shared book when it has no employee, and to a personal book when it has one. Deleted contacts (deletedAt) are never served.
• colleagues is assembled on the fly and cannot be edited. It contains every non-deleted employee of the customer that has at least one PBX extension with phonebook enabled, with the extension number, direct number, mobile numbers from the employees MVNO accounts, e-mail, title, department, picture and the work address from the customer.

Shared contacts are marked with CATEGORIES:Shared and a [Shared Contact] note, colleagues with CATEGORIES:Colleague and a [Colleague] note, so they can be told apart on the device.

/carddav/                                          Root, principal discovery
/carddav/principals/{employeeId}/                  Principal resource
/carddav/addressbooks/{employeeId}/                Address book home set
/carddav/addressbooks/{employeeId}/personal/       Personal address book
/carddav/addressbooks/{employeeId}/shared/         Shared address book
/carddav/addressbooks/{employeeId}/colleagues/     Colleagues address book
/carddav/addressbooks/{employeeId}/{book}/{id}.vcf Single contact
/carddav/notify                                    Service-to-service push trigger

{employeeId} is always the id of the authenticated employee - any other id gives 404, so one employee can never read another employees books. {id} is the id of the phonebook contact, or for the colleagues book the id of the colleagues employee record. Both must be 24 hex characters and end in .vcf.

Clients detect changes in two ways, both supported:

• Polling. Each collection exposes a CTag (CS:getctag) and each contact an ETag (DAV:getetag). The ETag is the contacts updatedAt in milliseconds, the CTag is <number of contacts>-<newest updatedAt>. When the CTag changes, the client fetches the ETag list and downloads only what changed.
• Apple push. Apple clients subscribe to a collection and get a silent push whenever a contact, a colleague, an extension or an MVNO number changes, so the change is on the phone within seconds instead of at the next poll.

sync-collection (RFC 6578) is not implemented - clients fall back to CTag polling, which is what iOS does anyway.

• PBX Phonebook - the same contacts over REST/JSON.
• Employee create token - creates the app specific password used by passkey-only employees.