API : CardDAV : Notify

Introduction

Service-to-service endpoint that sends a CardDAV push notification to the devices subscribed to an address book. It exists for services that change contacts without going through the API - the MS365 contact sync is the one that uses it - so that a phone finds out about the change immediately instead of at its next poll.

Unlike the rest of /carddav, this endpoint is plain JSON and is not behind Basic authentication. It authenticates with the shared PBX API key and can be called from any server, as it looks the subscriptions up in MongoDB directly.

Request

URL	https://api.telecomx.dk/carddav/notify
Method	POST
Access level	`x-api-key` header matching the platform PBX token. No employee token.
Body	customer	String	Id of the customer. Required.
	employee	String	Id of the employee whose personal book changed. Optional - leave it out for a change to the shared book.
	book	String	`personal` or `shared`. Optional, and validated if given, but the book is decided by whether `employee` is present.

Request example

POST https://api.telecomx.dk/carddav/notify
x-api-key: <pbx token>
 
{
  "customer": "1234567890ABCDEF12345678",
  "employee": "234567890ABCDEF123456789"
}

Response

JSON object
success	Boolean	True when the notifications have been sent.

Example

{
  "success": true
}

Errors

Error code	Message	Description
400	Missing required field: customer	No `customer` in the body.
400	Invalid customer ObjectId	`customer` is not a 24 character hex string.
400	Invalid employee ObjectId	`employee` was given but is not a 24 character hex string.
400	Invalid book type, must be “personal” or “shared”	`book` was given with another value.
401	Unauthorized	Missing or wrong `x-api-key`.

Notes

With employee: the personal book subscribers of that employee are notified. Without it: the shared book subscribers of the customer.
The colleagues book has no external trigger - it is pushed automatically when an employee, extension or MVNO account changes.
The call succeeds with success: true even when nobody is subscribed, which is the normal case for a customer with no Apple devices.

WIKI

Table of Contents