Contacts JSON


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.


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

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


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.


The strings inside contacts should use UTF-8 encoding.


Keys in main Contact dictionary:

contactId displayName checksum
fname mname lname
fnamePhonetic mnamePhonetic lnamePhonetic
nick namePrefix nameSuffix
company departmentName jobTitle
birthday street city
state zip country
countryCode notes contactEntries

Keys in Contact Entry dictionray:

entryId type uri label

Detailed description of keys

(except for those which are obvious)


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


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


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).


ISO2 country code.


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


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


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


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


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