This version of the documentation is outdated! Click here for the latest released version.

Contact

Contains properties that describe a contact, such as a user's personal or business contact.

Properties

id: A globally unique identifier. (DOMString)
displayName: The name of this Contact, suitable for display to end-users. (DOMString)
name: An object containing all components of a persons name. (ContactName)
nickname: A casual name by which to address the contact. (DOMString)
phoneNumbers: An array of all the contact's phone numbers. (ContactField[])
emails: An array of all the contact's email addresses. (ContactField[])
addresses: An array of all the contact's addresses. (ContactAddress[])
ims: An array of all the contact's IM addresses. (ContactField[])
organizations: An array of all the contact's organizations. (ContactOrganization[])
birthday: The birthday of the contact. (Date)
note: A note about the contact. (DOMString)
photos: An array of the contact's photos. (ContactField[])
categories: An array of all the user-defined categories associated with the contact. (ContactField[])
urls: An array of web pages associated with the contact. (ContactField[])

Methods

clone: Returns a new Contact object that is a deep copy of the calling object, with the id property set to null.
remove: Removes the contact from the device contacts database, otherwise executes an error callback with a [ContactError](../ContactError/contactError.html) object.
save: Saves a new contact to the device contacts database, or updates an existing contact if a contact with the same id already exists.

Details

The Contact object represents a user's contact. Contacts can be created, stored, or removed from the device contacts database. Contacts can also be retrieved (individually or in bulk) from the database by invoking the [contacts.find](../contacts.find.html) method.

NOTE: Not all of the contact fields listed above are supported on every device platform. Please check each platform's Quirks section for details.

Supported Platforms

Android
BlackBerry WebWorks (OS 5.0 and higher)
iOS
Windows Phone 7 and 8
Windows 8

Save Quick Example

function onSuccess(contact) {
    alert("Save Success");
};

function onError(contactError) {
    alert("Error = " + contactError.code);
};

// create a new contact object
var contact = navigator.contacts.create();
contact.displayName = "Plumber";
contact.nickname = "Plumber";            // specify both to support all devices

// populate some fields
var name = new ContactName();
name.givenName = "Jane";
name.familyName = "Doe";
contact.name = name;

// save to device
contact.save(onSuccess,onError);

Clone Quick Example

    // clone the contact object
    var clone = contact.clone();
    clone.name.givenName = "John";
    console.log("Original contact name = " + contact.name.givenName);
    console.log("Cloned contact name = " + clone.name.givenName);

Remove Quick Example

function onSuccess() {
    alert("Removal Success");
};

function onError(contactError) {
    alert("Error = " + contactError.code);
};

    // remove the contact from the device
    contact.remove(onSuccess,onError);

Full Example

<!DOCTYPE html>
<html>
  <head>
    <title>Contact Example</title>

    <script type="text/javascript" charset="utf-8" src="cordova.js"></script>
    <script type="text/javascript" charset="utf-8">

    // Wait for device API libraries to load
    //
    document.addEventListener("deviceready", onDeviceReady, false);

    // device APIs are available
    //
    function onDeviceReady() {
        // create
        var contact = navigator.contacts.create();
        contact.displayName = "Plumber";
        contact.nickname = "Plumber";                 // specify both to support all devices
        var name = new ContactName();
        name.givenName = "Jane";
        name.familyName = "Doe";
        contact.name = name;

        // save
        contact.save(onSaveSuccess,onSaveError);

        // clone
        var clone = contact.clone();
        clone.name.givenName = "John";
        console.log("Original contact name = " + contact.name.givenName);
        console.log("Cloned contact name = " + clone.name.givenName);

        // remove
        contact.remove(onRemoveSuccess,onRemoveError);
    }

    // onSaveSuccess: Get a snapshot of the current contacts
    //
    function onSaveSuccess(contact) {
        alert("Save Success");
    }

    // onSaveError: Failed to get the contacts
    //
    function onSaveError(contactError) {
        alert("Error = " + contactError.code);
    }

    // onRemoveSuccess: Get a snapshot of the current contacts
    //
    function onRemoveSuccess(contacts) {
        alert("Removal Success");
    }

    // onRemoveError: Failed to get the contacts
    //
    function onRemoveError(contactError) {
        alert("Error = " + contactError.code);
    }

    </script>
  </head>
  <body>
    <h1>Example</h1>
    <p>Find Contacts</p>
  </body>
</html>

Android 2.X Quirks

categories: Not supported on Android 2.X devices, returning null.

BlackBerry WebWorks (OS 5.0 and higher) Quirks

id: Supported. Assigned by the device when saving the contact.
displayName: Supported. Stored in BlackBerry user1 field.
nickname: Not supported, returning null.
phoneNumbers: Partially supported. Phone numbers are stored in BlackBerry fields homePhone1 and homePhone2 if type is 'home', workPhone1 and workPhone2 if type is 'work', mobilePhone if type is 'mobile', faxPhone if type is 'fax', pagerPhone if type is 'pager', and otherPhone if type is none of the above.
emails: Partially supported. The first three email addresses are stored in the BlackBerry email1, email2, and email3 fields, respectively.
addresses: Partially supported. The first and second addresses are stored in the BlackBerry homeAddress and workAddress fields, respectively.
ims: Not supported, returning null.
organizations: Partially supported. The name and title of the first organization are stored in the BlackBerry company and title fields, respectively.
photos: Partially supported. A single thumbnail-sized photo is supported. To set a contact's photo, pass in a either a base64-encoded image, or a URL pointing to the image. The image is scaled down before saving to the BlackBerry contacts database. The contact photo is returned as a base64-encoded image.
categories: Partially supported. Only Business and Personal categories are supported.
urls: Partially supported. The first URL is stored in BlackBerry webpage field.

iOS Quirks

displayName: Not supported on iOS, returning null unless there is no [ContactName](../ContactName/contactname.html) specified, in which case it returns the composite name, nickname or "", respectively.
birthday: Must be input as a JavaScript Date object, the same way it is returned.
photos: Returns a File URL to the image, which is stored in the application's temporary directory. Contents of the temporary directory are removed when the application exits.
categories: This property is currently not supported, returning null.

Windows Phone 7 and 8 Quirks

displayName: When creating a contact, the value provided for the display name parameter differs from the display name retrieved when finding the contact.
urls: When creating a contact, users can input and save more than one web address, but only one is available is available when searching the contact.
phoneNumbers: The pref option is not supported. The type is not supported in a find operation. Only one phoneNumber is allowed for each type.
emails: The pref option is not supported. Home and personal references same email entry. Only one entry is allowed for each type.
addresses: Supports only work, and home/personal type. The home and personal type reference the same address entry. Only one entry is allowed for each type.
organizations: Only one is allowed, and does not support the pref, type, and department attributes.
note: Not supported, returning null.
ims: Not supported, returning null.
birthdays: Not supported, returning null.
categories: Not supported, returning null.