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",
"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"
}
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.
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 |
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)
contactId
Unique contact identifier which should not change. This field is required, contacts without this field will be ignored.
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.
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
,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.