Frequently Asked Question

CardDav - Pull contacts from a CardDav server and return them in various formats

Last Updated 7 days ago

CardDAV API

Overview

This API allows users to retrieve and format contact information from a CardDAV server. It supports fetching contacts, normalising phone numbers, and outputting the data in either CSV or JSON format.

This API is intended for use with PBX systems, such as FreePBX, PBXact and Asterisk, to pull down contacts from a company directory, or a series of user contact lists stored externally, and then import those into the systems contact lists. This is often to provide CLI -> Name reverse lookups or may be used to do call routing, or provide quick dial from handsets.

Version

1.000

Endpoint

/v2/cardDav.php

Authentication

This API requires authentication using an API key. The key should be passed in the HTTP_X_API_KEY header.

Request Parameters

Parameter	Type	Required	Description
u	string	Yes	Base URL of the CardDAV server
user	string	Yes	Username for CardDAV authentication
pass	string	Yes	Password for CardDAV authentication
f	string	No	Output format (csv or json, default: csv)
o	string	No	Output order (np for Name,Phone or pn for Phone,Name, default: pn)

Response

The API returns either a CSV or JSON response based on the 'f' parameter:

CSV Format

Phone,Name
"07123456789","John Doe"
"07987654321","Jane Smith"

JSON Format


{
  "07123456789": "John Doe",
  "07987654321": "Jane Smith"
}

Error Responses

In case of errors, the API returns a JSON object with an error status:


{
  "status": "error_message"
}

Phone Number Normalisation

Phone numbers are normalised to UK format
+44 is replaced with 0
International numbers are prefixed with 00
Numbers are validated to have between 10 and 14 digits

Limitations

The API is designed for UK phone numbers primarily
Only supports basic authentication for CardDAV servers

Example Usage

curl -X POST 'https://api.endpoint/v2/cardDav.php' \
     -H 'X-API-Key: your_api_key_here' \
     -H 'Content-Type: application/x-www-form-urlencoded' \
     -d 'u=http://cardav.example.com&user=johndoe&pass=secret&f=json&o=pn'

Notes

The API performs both PROPFIND and REPORT requests to the CardDAV server
The CardDav URL is constructed as u/carddav/user/ so if u is set to http://my.dav.com and user is set to FRED, then we will query http://my.dav.com/carddav/FRED/ to retrieve the contacts.

Security Considerations

Ensure HTTPS is used for the API endpoint to protect sensitive information
CardDAV credentials are passed as GET parameters, which may be logged in server logs