# PhoneGap Documentation

# Contacts

> The `contacts` object provides access to the device contacts database.

Important privacy note: Collection and use of contact data raises important privacy issues. Your app's privacy policy should discuss how the app uses contact data and whether it is shared with any other parties. Contact information is considered sensitive because it reveals the people with whom a person communicates. Therefore, in addition to your app's privacy policy, you should strongly consider providing a just-in-time notice prior to your app accessing or using contact data (if the device operating system doesn't do so already). That notice should provide the same information noted above, as well as obtaining the user's permission (e.g., by presenting choices for "OK" and "No Thanks"). Note that some app marketplaces may require your app to provide just-in-time notice and obtain permission from the user prior to accessing contact data. A clear and easy to understand user experience surrounding the use of contact data will help avoid user confusion and perceived misuse of contact data. For more information, please see the Privacy Guide.

## Methods

- contacts.create
- contacts.find

## Arguments

- contactFields
- contactSuccess
- contactError
- contactFindOptions

## Objects

- Contact
- ContactName
- ContactField
- ContactAddress
- ContactOrganization
- ContactFindOptions
- ContactError

## Permissions

### Android

#### app/res/xml/config.xml

    <plugin name="Contacts" value="org.apache.cordova.ContactManager" />

#### app/AndroidManifest.xml

    <uses-permission android:name="android.permission.GET_ACCOUNTS" />
    <uses-permission android:name="android.permission.READ_CONTACTS" />
    <uses-permission android:name="android.permission.WRITE_CONTACTS" />

### BlackBerry WebWorks

#### www/plugins.xml

    <plugin name="Contact" value="org.apache.cordova.pim.Contact" />

#### www/config.xml

    <feature id="blackberry.find"        required="true" version="1.0.0.0" />
    <feature id="blackberry.identity"    required="true" version="1.0.0.0" />
    <feature id="blackberry.pim.Address" required="true" version="1.0.0.0" />
    <feature id="blackberry.pim.Contact" required="true" version="1.0.0.0" />

### iOS

#### config.xml

    <plugin name="Contacts" value="CDVContacts" />

### Windows Phone

#### Properties/WPAppManifest.xml

    <Capabilities>
        <Capability Name="ID_CAP_CONTACTS" />
    </Capabilities>

Reference: Application Manifest for Windows Phone

# contacts.create

Returns a new Contact object.

    var contact = navigator.contacts.create(properties);

## Description

The `contacts.create` method is synchronous, and returns a new `Contact` object.

This method does not retain the Contact object in the device contacts database, for which you need to invoke the `Contact.save` method.

## Supported Platforms

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

## Quick Example

    var myContact = navigator.contacts.create({"displayName": "Test User"});

## Full Example

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

        <script type="text/javascript" charset="utf-8" src="cordova-x.x.x.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() {
            var myContact = navigator.contacts.create({"displayName": "Test User"});
            myContact.note = "This contact has a note.";
            console.log("The contact, " + myContact.displayName + ", note: " + myContact.note);
        }

        </script>
      </head>
      <body>
        <h1>Example</h1>
        <p>Create Contact</p>
      </body>
    </html>

# contacts.find

Queries the device contacts database and returns one or more `Contact` objects, each containing the fields specified.

    navigator.contacts.find(contactFields, contactSuccess, contactError, contactFindOptions);

## Description

The `contacts.find` method executes asynchronously, querying the device contacts database and returning an array of `Contact` objects. The resulting objects are passed to the `contactSuccess` callback function specified by the contactSuccess parameter.

The contactFields parameter specifies the fields to be used as a search qualifier, and only those results are passed to the contactSuccess callback function. A zero-length contactFields parameter is invalid and results in `ContactError.INVALID_ARGUMENT_ERROR`. A contactFields value of `"*"` returns all contact fields.

The contactFindOptions.filter string can be used as a search filter when querying the contacts database. If provided, a case-insensitive, partial value match is applied to each field specified in the contactFields parameter. If there's a match for any of the specified fields, the contact is returned.

## Parameters

- contactFields: Contact fields to use as a search qualifier. The resulting `Contact` object only features values for these fields. (DOMString[]) [Required]
- contactSuccess: Success callback function invoked with the contacts returned from the database. [Required]
- contactError: Error callback function, invoked when an error occurs. [Optional]
- contactFindOptions: Search options to filter contacts. [Optional]

## Supported Platforms

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

## Quick Example

    function onSuccess(contacts) {
        alert('Found ' + contacts.length + ' contacts.');
    };

    function onError(contactError) {
        alert('onError!');
    };

    // find all contacts with 'Bob' in any name field
    var options      = new ContactFindOptions();
    options.filter   = "Bob";
    options.multiple = true;
    var fields       = ["displayName", "name"];
    navigator.contacts.find(fields, onSuccess, onError, options);

## Full Example

    <!DOCTYPE html>
    <html>
        <head>
            <title>Contact Example</title>
            <script type="text/javascript" charset="utf-8" src="cordova-x.x.x.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() {
                    // find all contacts with 'Bob' in any name field
                    var options = new ContactFindOptions();
                    options.filter = "Bob";
                    var fields = ["displayName", "name"];
                    navigator.contacts.find(fields, onSuccess, onError, options);
                }

                // onSuccess: Get a snapshot of the current contacts

                function onSuccess(contacts) {
                    for (var i = 0; i < contacts.length; i++) {
                        console.log("Display Name = " + contacts[i].displayName);
                    }
                }

                // onError: Failed to get the contacts

                function onError(contactError) {
                    alert('onError!');
                }
            </script>
        </head>

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

# 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` 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` 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-x.x.x.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` 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`.

# ContactAddress

Contains address properties for a `Contact` object.

## Properties

- pref: Set to `true` if this `ContactAddress` contains the user's preferred value. (boolean)
- type: A string indicating what type of field this is, home for example. (DOMString)
- formatted: The full address formatted for display. (DOMString)
- streetAddress: The full street address. (DOMString)
- locality: The city or locality. (DOMString)
- region: The state or region. (DOMString)
- postalCode: The zip code or postal code. (DOMString)
- country: The country name. (DOMString)

## Details

The `ContactAddress` object stores the properties of a single address of a contact. A `Contact` object may include more than one address in a `ContactAddress[]` array.

## Supported Platforms

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

## Quick Example

    // display the address information for all contacts

    function onSuccess(contacts) {
        for (var i = 0; i < contacts.length; i++) {
            for (var j = 0; j < contacts[i].addresses.length; j++) {
                alert("Pref: "         + contacts[i].addresses[j].pref          + "\n" +
                    "Type: "           + contacts[i].addresses[j].type          + "\n" +
                    "Formatted: "      + contacts[i].addresses[j].formatted     + "\n" +
                    "Street Address: " + contacts[i].addresses[j].streetAddress + "\n" +
                    "Locality: "       + contacts[i].addresses[j].locality      + "\n" +
                    "Region: "         + contacts[i].addresses[j].region        + "\n" +
                    "Postal Code: "    + contacts[i].addresses[j].postalCode    + "\n" +
                    "Country: "        + contacts[i].addresses[j].country);
            }
        }
    };

    function onError(contactError) {
        alert('onError!');
    };

    // find all contacts
    var options = new ContactFindOptions();
    options.filter = "";
    var filter = ["displayName", "addresses"];
    navigator.contacts.find(filter, onSuccess, onError, options);

## Full Example

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

        <script type="text/javascript" charset="utf-8" src="cordova-x.x.x.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() {
            // find all contacts
            var options = new ContactFindOptions();
            options.filter = "";
            var filter = ["displayName", "addresses"];
            navigator.contacts.find(filter, onSuccess, onError, options);
        }

        // onSuccess: Get a snapshot of the current contacts
        //
        function onSuccess(contacts) {
            // display the address information for all contacts
            for (var i = 0; i < contacts.length; i++) {
                for (var j = 0; j < contacts[i].addresses.length; j++) {
                    alert("Pref: "           + contacts[i].addresses[j].pref          + "\n" +
                          "Type: "           + contacts[i].addresses[j].type          + "\n" +
                          "Formatted: "      + contacts[i].addresses[j].formatted     + "\n" +
                          "Street Address: " + contacts[i].addresses[j].streetAddress + "\n" +
                          "Locality: "       + contacts[i].addresses[j].locality      + "\n" +
                          "Region: "         + contacts[i].addresses[j].region        + "\n" +
                          "Postal Code: "    + contacts[i].addresses[j].postalCode    + "\n" +
                          "Country: "        + contacts[i].addresses[j].country);
                }
            }
        };

        // onError: Failed to get the contacts
        //
        function onError(contactError) {
            alert('onError!');
        }

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

## Android 2.X Quirks

- pref: Not supported, returning `false` on Android 2.X devices.

## BlackBerry WebWorks (OS 5.0 and higher) Quirks

- pref: Not supported on Blackberry devices, returning `false`.
- type: Partially supported. Only one each of Work and Home type addresses can be stored per contact.
- formatted: Partially supported. Returns a concatenation of all BlackBerry address fields.
- streetAddress: Supported. Returns a concatenation of BlackBerry address1 and address2 address fields.
- locality: Supported. Stored in BlackBerry city address field.
- region: Supported. Stored in BlackBerry stateProvince address field.
- postalCode: Supported. Stored in BlackBerry zipPostal address field.
- country: Supported.

## iOS Quirks

- pref: Not supported on iOS devices, returning `false`.
- formatted: Currently not supported.

# ContactField

Supports generic fields in a `Contact` object. Some properties stored as `ContactField` objects include email addresses, phone numbers, and URLs.

## Properties

- type: A string that indicates what type of field this is, home for example. (DOMString)
- value: The value of the field, such as a phone number or email address. (DOMString)
- pref: Set to `true` if this `ContactField` contains the user's preferred value. (boolean)

## Details

The `ContactField` object is a reusable component that represents contact fields generically. Each `ContactField` object contains a `value`, `type`, and `pref` property. A `Contact` object stores several properties in `ContactField[]` arrays, such as phone numbers and email addresses.

In most instances, there are no pre-determined values for a `ContactField` object's type attribute. For example, a phone number can specify type values of home, work, mobile, iPhone, or any other value that is supported by a particular device platform's contact database. However, for the `Contact` photos field, the type field indicates the format of the returned image: url when the value attribute contains a URL to the photo image, or base64 when the value contains a base64-encoded image string.

## Supported Platforms

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

## Quick Example

        // create a new contact
        var contact = navigator.contacts.create();

        // store contact phone numbers in ContactField[]
        var phoneNumbers = [];
        phoneNumbers[0] = new ContactField('work', '212-555-1234', false);
        phoneNumbers[1] = new ContactField('mobile', '917-555-5432', true); // preferred number
        phoneNumbers[2] = new ContactField('home', '203-555-7890', false);
        contact.phoneNumbers = phoneNumbers;

        // save the contact
        contact.save();

## Full Example

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

        <script type="text/javascript" charset="utf-8" src="cordova-x.x.x.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 a new contact
            var contact = navigator.contacts.create();

            // store contact phone numbers in ContactField[]
            var phoneNumbers = [];
            phoneNumbers[0] = new ContactField('work', '212-555-1234', false);
            phoneNumbers[1] = new ContactField('mobile', '917-555-5432', true); // preferred number
            phoneNumbers[2] = new ContactField('home', '203-555-7890', false);
            contact.phoneNumbers = phoneNumbers;

            // save the contact
            contact.save();

            // search contacts, returning display name and phone numbers
            var options = new ContactFindOptions();
            options.filter = "";
            filter = ["displayName", "phoneNumbers"];
            navigator.contacts.find(filter, onSuccess, onError, options);
        }

        // onSuccess: Get a snapshot of the current contacts
        //
        function onSuccess(contacts) {
            for (var i = 0; i < contacts.length; i++) {
                // display phone numbers
                for (var j = 0; j < contacts[i].phoneNumbers.length; j++) {
                    alert("Type: "      + contacts[i].phoneNumbers[j].type  + "\n" +
                          "Value: "     + contacts[i].phoneNumbers[j].value + "\n" +
                          "Preferred: " + contacts[i].phoneNumbers[j].pref);
                }
            }
        };

        // onError: Failed to get the contacts
        //
        function onError(contactError) {
            alert('onError!');
        }

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

## Android Quirks

- pref: Not supported, returning `false`.

## BlackBerry WebWorks (OS 5.0 and higher) Quirks

- type: Partially supported. Used for phone numbers.
- value: Supported.
- pref: Not supported, returning `false`.

## iOS Quirks

- pref: Not supported, returning `false`.

# ContactFindOptions

Contains properties that can be used to filter the results of a `contacts.find` operation.

## Properties

- filter: The search string used to find contacts. (DOMString) (Default: `""`)
- multiple: Determines if the find operation returns multiple contacts. (Boolean) (Default: false)

## Supported Platforms

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

## Quick Example

    // success callback
    function onSuccess(contacts) {
        for (var i=0; i<contacts.length; i++) {
            alert(contacts[i].displayName);
        }
    };

    // error callback
    function onError(contactError) {
        alert('onError!');
    };

    // specify contact search criteria
    var options = new ContactFindOptions();
        options.filter="";        // empty search string returns all contacts
        options.multiple=true;    // return multiple results
        filter = ["displayName"]; // return contact.displayName field

        // find contacts
    navigator.contacts.find(filter, onSuccess, onError, options);

## Full Example

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

        <script type="text/javascript" charset="utf-8" src="cordova-x.x.x.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() {
            // specify contact search criteria
            var options = new ContactFindOptions();
            options.filter = "";      // empty search string returns all contacts
            options.multiple = true;  // return multiple results
            filter = ["displayName"]; // return contact.displayName field

            // find contacts
            navigator.contacts.find(filter, onSuccess, onError, options);
        }

        // onSuccess: Get a snapshot of the current contacts
        //
        function onSuccess(contacts) {
            for (var i=0; i<contacts.length; i++) {
                alert(contacts[i].displayName);
            }
        };

        // onError: Failed to get the contacts
        //
        function onError(contactError) {
            alert('onError!');
        }

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

# ContactName

Contains different kinds of information about a `Contact` object's name.

## Properties

- formatted: The complete name of the contact. (DOMString)
- familyName: The contact's family name. (DOMString)
- givenName: The contact's given name. (DOMString)
- middleName: The contact's middle name. (DOMString)
- honorificPrefix: The contact's prefix (example Mr. or Dr.) (DOMString)
- honorificSuffix: The contact's suffix (example Esq.). (DOMString)

## Details

The `ContactName` object stores a contact's name properties.

## Supported Platforms

- Android 2.X
- BlackBerry WebWorks (OS 5.0 and higher)
- iOS
- Windows Phone 7 and 8
- Windows 8

## Quick Example

    function onSuccess(contacts) {
        for (var i = 0; i < contacts.length; i++) {
            alert("Formatted: "  + contacts[i].name.formatted       + "\n" +
                "Family Name: "  + contacts[i].name.familyName      + "\n" +
                "Given Name: "   + contacts[i].name.givenName       + "\n" +
                "Middle Name: "  + contacts[i].name.middleName      + "\n" +
                "Suffix: "       + contacts[i].name.honorificSuffix + "\n" +
                "Prefix: "       + contacts[i].name.honorificSuffix);
        }
    };

    function onError(contactError) {
        alert('onError!');
    };

    var options = new ContactFindOptions();
    options.filter = "";
    filter = ["displayName", "name"];
    navigator.contacts.find(filter, onSuccess, onError, options);

## Full Example

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

        <script type="text/javascript" charset="utf-8" src="cordova-x.x.x.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() {
            var options = new ContactFindOptions();
            options.filter="";
            filter = ["displayName","name"];
            navigator.contacts.find(filter, onSuccess, onError, options);
        }

        // onSuccess: Get a snapshot of the current contacts
        //
        function onSuccess(contacts) {
            for (var i = 0; i < contacts.length; i ++) {
                alert("Formatted: " + contacts[i].name.formatted       + "\n" +
                    "Family Name: " + contacts[i].name.familyName      + "\n" +
                    "Given Name: "  + contacts[i].name.givenName       + "\n" +
                    "Middle Name: " + contacts[i].name.middleName      + "\n" +
                    "Suffix: "      + contacts[i].name.honorificSuffix + "\n" +
                    "Prefix: "      + contacts[i].name.honorificPrefix);
            }
        };

        // onError: Failed to get the contacts
        //
        function onError(contactError) {
            alert('onError!');
        }

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

## Android Quirks

- formatted: Partially supported, and read-only. Returns a concatenation of `honorificPrefix`, `givenName`, `middleName`, `familyName`, and `honorificSuffix`.

## BlackBerry WebWorks (OS 5.0 and higher) Quirks

- formatted: Partially supported. Returns a concatenation of BlackBerry firstName and lastName fields.
- familyName: Supported. Stored in BlackBerry lastName field.
- givenName: Supported. Stored in BlackBerry firstName field.
- middleName: Not supported, returning `null`.
- honorificPrefix: Not supported, returning `null`.
- honorificSuffix: Not supported, returning `null`.

## iOS Quirks

- formatted: Partially supported. Returns iOS Composite Name, but is read-only.

# ContactOrganization

Contains a `Contact` object's organization properties.

## Properties

- pref: Set to `true` if this `ContactOrganization` contains the user's preferred value. (boolean)
- type: A string that indicates what type of field this is, home for example. _(DOMString)
- name: The name of the organization. (DOMString)
- department: The department the contract works for. (DOMString)
- title: The contact's title at the organization. (DOMString)

## Details

The `ContactOrganization` object stores a contact's organization properties. A `Contact` object stores one or more `ContactOrganization` objects in an array.

## Supported Platforms

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

## Quick Example

    function onSuccess(contacts) {
        for (var i = 0; i < contacts.length; i++) {
            for (var j = 0; j < contacts[i].organizations.length; j++) {
                alert("Pref: "      + contacts[i].organizations[j].pref       + "\n" +
                    "Type: "        + contacts[i].organizations[j].type       + "\n" +
                    "Name: "        + contacts[i].organizations[j].name       + "\n" +
                    "Department: "  + contacts[i].organizations[j].department + "\n" +
                    "Title: "       + contacts[i].organizations[j].title);
            }
        }
    };

    function onError(contactError) {
        alert('onError!');
    };

    var options = new ContactFindOptions();
    options.filter = "";
    filter = ["displayName", "organizations"];
    navigator.contacts.find(filter, onSuccess, onError, options);

## Full Example

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

        <script type="text/javascript" charset="utf-8" src="cordova-x.x.x.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() {
            var options = new ContactFindOptions();
            options.filter="";
            filter = ["displayName","organizations"];
            navigator.contacts.find(filter, onSuccess, onError, options);
        }

        // onSuccess: Get a snapshot of the current contacts
        //
        function onSuccess(contacts) {
            for (var i = 0; i < contacts.length; i++) {
                for (var j = 0; j < contacts[i].organizations.length; j++) {
                    alert("Pref: "     + contacts[i].organizations[j].pref       + "\n" +
                        "Type: "       + contacts[i].organizations[j].type       + "\n" +
                        "Name: "       + contacts[i].organizations[j].name       + "\n" +
                        "Department: " + contacts[i].organizations[j].department + "\n" +
                        "Title: "      + contacts[i].organizations[j].title);
                }
            }
        };

        // onError: Failed to get the contacts
        //
        function onError(contactError) {
            alert('onError!');
        }

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

## Android 2.X Quirks

- pref: Not supported by Android 2.X devices, returning `false`.

## BlackBerry WebWorks (OS 5.0 and higher) Quirks

- pref: Not supported by Blackberry devices, returning `false`.
- type: Not supported by Blackberry devices, returning `null`.
- name: Partially supported. The first organization name is stored in the BlackBerry company field.
- department: Not supported, returning `null`.
- title: Partially supported. The first organization title is stored in the BlackBerry jobTitle field.

## iOS Quirks

- pref: Not supported on iOS devices, returning `false`.
- type: Not supported on iOS devices, returning `null`.
- name: Partially supported. The first organization name is stored in the iOS kABPersonOrganizationProperty field.
- department: Partially supported. The first department name is stored in the iOS kABPersonDepartmentProperty field.
- title: Partially supported. The first title is stored in the iOS kABPersonJobTitleProperty field.

# ContactError

A `ContactError` object is passed to the `contactError` callback when an error occurs.

## Properties

- code: One of the predefined error codes listed below.

## Constants

- `ContactError.UNKNOWN_ERROR`
- `ContactError.INVALID_ARGUMENT_ERROR`
- `ContactError.TIMEOUT_ERROR`
- `ContactError.PENDING_OPERATION_ERROR`
- `ContactError.IO_ERROR`
- `ContactError.NOT_SUPPORTED_ERROR`
- `ContactError.PERMISSION_DENIED_ERROR`

## Description

The `ContactError` object is returned to the user through the `contactError` callback function when an error occurs.

# contactSuccess

Success callback function that provides the `Contact` array resulting from a `contacts.find` operation.

    function(contacts) {
        // Do something
    }

## Parameters

- contacts: The contact array resulting from a find operation. (Contact)

## Example

    function contactSuccess(contacts) {
        for (var i=0; i<contacts.length; i++) {
            console.log("Display Name = " + contacts[i].displayName);
        }
    }

# contactError

Error callback function for contact functions.

    function(error) {
        // Handle the error
    }

# contactFields

Required parameter for the `contacts.find` method, used to specify which fields should be included in the `Contact` objects resulting from a find operation.

    ["name", "phoneNumbers", "emails"]

# contactFindOptions

Optional parameter of the `contacts.find` method, used to filter the contacts returned from the contacts database.

    {
      filter: "",
      multiple: true,
    };

## Options

- filter: The search string used to filter contacts. (DOMString) (Default: `""`)
- multiple: Determines if the find operation returns multiple contacts. (Boolean) (Default: `false`)