Contacts JSON

Overview

Acrobits apps can load and display contacts from different sources. The obvious source is phone address book, another option is CardDAV server and it is also possible to download contacts from a URL or web service.

The web service should ideally return contacts in our native JSON format, which the app would simply save without any processing. There may be cases though when the contacts are already available in some other format (typically an XML document). We have support for transformations which can turn the XML format into our internal format.

In both cases, it is important to know the internal format used by the apps. It is described in this document.

Example

Below is an example of one contact entry from address book:

{
   "avatar" : "http://example.com/image.png",
   "largeAvatar" : "http://example.com/largerImage.png",
   "birthday" : "1998-06-14",
   "checksum" : "DFC1490F899CB9FD",
   "contactEntries" : [
      {
         "entryId" : "tel:0",
         "label" : "home",
         "type" : "tel",
         "uri" : "555-610-6679"
      },
      {
         "entryId" : "tel:1",
         "label" : "work",
         "type" : "tel",
         "uri" : "+420 276 285 602"
      }
   ],
   "contactAddresses" : [
      {
         "label": "home",
         "city" : "Tiburon",
         "country" : "USA",
         "countryCode" : "us",
         "state" : "CA",
         "street" : "1747 Steuart Street",
         "zip" : "94920"
      }
   ],
   "contactId" : "E94CD15C-7964-4A9B-8AC4-10D7CFB791FD",
   "displayName" : "David Taylor",
   "fname" : "David",
   "lname" : "Taylor",
   "notes" : "Plays on Cole's Little League Baseball Team"
}

Important

Each contact is a dictionary of key-value pairs, where keys are string identifiers and values are strings, or, in case of contactEntries, an array of dictionaries containing phone numbers, emails, urls of the contact. Additionally, there is contactAddresses, which is an array of dictionaries containing the addresses of the contact.

Note

The strings inside contacts should use UTF-8 encoding.

Keys

Keys in main Contact dictionary:

contactId	displayName	checksum
fname	mname	lname
fnamePhonetic	mnamePhonetic	lnamePhonetic
nick	namePrefix	nameSuffix
company	departmentName	jobTitle
birthday	notes	contactEntries
contactAddresses

Keys in Contact Entry dictionray:

entryId

type

uri

label

Keys in Contact Address dictionray:

street	city	state	zip
country	countryCode	label

Detailed description of keys

(except for those which are obvious)

contactId

Unique contact identifier which should not change. This field is required, contacts without this field will be ignored.

Note

In addition to being required, contactId must be unique for each contact entry. If multiple contacts share the same contactId, web service contacts will not work.

displayName

String which will be shown in GUI when presenting the contact in in-call screen, contact list views etc.

checksum

A string value which should change whenever anything in the contact changes. In case you don’t provide one, we will generate it as SHA1 of all values in contact dictionary.

fname, mname, lname

First, Middle, Last names.

fnamePhonetic, mnamePhonetic, lnamePhonetic

Phonetic names, important for sorting contacts which use eastern alphabets (like Kanji).

countryCode

ISO2 country code.

contactEntries

Contains array of dictionaries with phone numbers, emails or uris for the contact.

contactAddresses

Contains array of dictionaries with addresses for the contact.

entryId

Unique identifier of entry. It only has to be unique within the contact where it belongs.

type

Type of contact entry. One of: tel, email, url .

label

The label of contact entry. For example, home, work, mobile etc.

uri

The value of contact entry. The value depends on type, it is either a phone number, email or URL.