.. _contacts_json:

=============
Contacts JSON
=============

.. contents::
   :local:
   :depth: 3

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:

.. code-block:: json

      {
         "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.