# Titanium.Contacts > The top-level Contacts module, used for accessing and modifying the system contacts address book. - Source: https://titaniumsdk.com/docs/sdk/13.1.1/Titanium.Contacts - Titanium SDK version: 13.1.1 - Kind: module - Platforms: Android, iPhone, iPad, macOS - Since: Titanium SDK iPhone 0.8, iPad 0.8, Android 0.8, macOS 9.2.0 - Extends: Titanium.Module - Inheritance: Titanium.Module > Titanium.Proxy See examples for more information. #### iOS Platform Notes On iOS, the contacts database may be modified by an external application, causing any `Person` or `Group` objects you've retrieved to be out of sync with the database. The IDs of these objects are not guaranteed to remain the same, so updating an object when it is out of sync may have unpredictable results. To avoid this, listen for the [reload](https://titaniumsdk.com/docs/sdk/Titanium.Contacts.md#reload) event. When you receive a `reload` event, you should assume that any existing `Person` or `Group` objects are invalid and reload them from the `Contacts` module before modifying them. See the examples for a sample use of the `reload` event. If 'ABAddressBookErrorDomain error 0' occurs, it implies that you are not allowed to add or edit certain fields. Check your default account in the iOS settings under contacts. If it's not 'iCloud', most likely it will not support fields such as alternateBirthday or socialProfile. These APIs are unavailable on macOS if the app is built on a version of Xcode < 12. ## Example: Request access to the address book ``` js var performAddressBookFunction = function(){...}; var addressBookDisallowed = function(){...}; if (Ti.Contacts.hasContactsPermissions()) { performAddressBookFunction(); } else { Ti.Contacts.requestContactsPermissions(function(e) { if (e.success) { performAddressBookFunction(); } else { addressBookDisallowed(); } }); } ``` ## Example: Query Existing System Address Book Records Output to the console all properties of all people. ``` js var singleValue = [ 'recordId', 'firstName', 'middleName', 'lastName', 'fullName', 'prefix', 'suffix', 'nickname', 'firstPhonetic', 'middlePhonetic', 'lastPhonetic', 'organization', 'jobTitle', 'department', 'note', 'birthday', 'created', 'modified', 'kind' ]; var multiValue = [ 'email', 'address', 'phone', 'instantMessage', 'relatedNames', 'date', 'url' ]; var people = Ti.Contacts.getAllPeople(); Ti.API.info('Total contacts: ' + people.length); for (var i=0, ilen=people.length; i object is queried in the same way that it is created (as shown in the previous example.) ``` js Ti.API.info('Saving contact...'); Ti.Contacts.createPerson({ firstName: 'Paul', lastName: 'Dowsett', address:{ work:[ { CountryCode: 'gb', // determines how the address is displayed Street: '200 Brook Drive\nGreen Park', City: 'Reading', County: 'Berkshire', Country: 'England', ZIP: 'RG2 6UB' }, { CountryCode: 'gb', // determines how the address is displayed Street: '1 St Pauls Road\nClerkenwell', City: 'City of London', State: 'London', Country: 'England', ZIP: 'EC1 1AA' } ], home:[ { CountryCode: 'gb', // determines how the address is displayed Street: '2 Boleyn Court', City: 'London', State: 'Greenwich', Country: 'England', ZIP: 'SE10' } ] }, birthday: '2012-01-01T12:00:00.000+0000', instantMessage:{ home:[ { service: 'AIM', username: 'leisureAIM' }, { service: 'MSN', username: 'no_paul_here@msn.com' } ], work:[ { service: 'AIM', username: 'seriousAIM' } ] }, organization: 'Appcelerator', phone:{ mobile: ['07900 000001', '07900 000002'], work: ['+44 (0)118 925 6128', '+44 (0)118 000 0000'] }, url:{ homepage: ['www.google.com'], work: ['www.titaniumsdk.com', 'www.example.com'] } }); Ti.API.info('Contact saved'); Ti.API.info('Saving contact...'); var workAddress1 = { 'CountryCode': 'us', 'Street': '440 N. Bernardo Avenue', 'City': 'Mountain View', 'State': 'California', 'Country': 'United States', 'ZIP': '94043' }; Ti.Contacts.createPerson({ firstName:'Arthur', lastName:'Evans', address:{ 'work':[workAddress1] } }); Ti.API.info('Contact saved'); ``` ## Example: Repopulate contact data if it was modified externally Listen for the `reload` event to repopulate the contact data if it was modified externally, for example, in the iOS Contacts app. ``` js var win = Ti.UI.createWindow(); var table = Ti.UI.createTableView(); // Repopulate contact data function reloadContacts() { var contacts = Ti.Contacts.getAllPeople(); var data = []; for (var i = 0; i < contacts.length; i++) { var title = contacts[i].fullName; if (!title || title.length === 0) { title = "(no name)"; } var row = Ti.UI.createTableViewRow({ title: title }); data.push(row); } table.data = data; } Ti.Contacts.addEventListener('reload', function(e){ alert('Reloading contacts. Your contacts were changed externally!'); reloadContacts(); }); // initial call to populate contact data reloadContacts(); win.add(table); win.open(); ``` ## Properties ### AUTHORIZATION_AUTHORIZED - Type: Number - Platforms: Android, iPhone, iPad, macOS - Since: Titanium SDK Android 2.1.3, iPhone 2.1.3, iPad 2.1.3, macOS 9.2.0 - Permission: read-only A [contactsAuthorization](https://titaniumsdk.com/docs/sdk/Titanium.Contacts.md#contactsAuthorization) value indicating that the application is authorized to use the address book. This value is always returned on Android devices, as well as on iOS versions earlier than 6.0. ### AUTHORIZATION_DENIED - Type: Number - Platforms: Android, iPhone, iPad, macOS - Since: Titanium SDK Android 2.1.3, iPhone 2.1.3, iPad 2.1.3, macOS 9.2.0 - Permission: read-only A [contactsAuthorization](https://titaniumsdk.com/docs/sdk/Titanium.Contacts.md#contactsAuthorization) value indicating that the application is not authorized to use the address book. ### AUTHORIZATION_UNKNOWN - Type: Number - Platforms: Android, iPhone, iPad, macOS - Since: Titanium SDK Android 2.1.3, iPhone 2.1.3, iPad 2.1.3, macOS 9.2.0 - Permission: read-only A [contactsAuthorization](https://titaniumsdk.com/docs/sdk/Titanium.Contacts.md#contactsAuthorization) value indicating that the authorization state is unknown. ### CONTACTS_KIND_ORGANIZATION - Type: Number - Platforms: Android, iPhone, iPad, macOS - Permission: read-only Specifies that a contact is an organization. Used with the [Titanium.Contacts.Person.kind](https://titaniumsdk.com/docs/sdk/Titanium.Contacts.Person.md#kind) property. One of the group of contact "kind" constants [CONTACTS_KIND_ORGANIZATION](https://titaniumsdk.com/docs/sdk/Titanium.Contacts.md#CONTACTS_KIND_ORGANIZATION), and [CONTACTS_KIND_PERSON](https://titaniumsdk.com/docs/sdk/Titanium.Contacts.md#CONTACTS_KIND_PERSON). ### CONTACTS_KIND_PERSON - Type: Number - Platforms: Android, iPhone, iPad, macOS - Permission: read-only Specifies that a contact is a person. Used with the [Titanium.Contacts.Person.kind](https://titaniumsdk.com/docs/sdk/Titanium.Contacts.Person.md#kind) property. One of the group of contact "kind" constants [CONTACTS_KIND_ORGANIZATION](https://titaniumsdk.com/docs/sdk/Titanium.Contacts.md#CONTACTS_KIND_ORGANIZATION), and [CONTACTS_KIND_PERSON](https://titaniumsdk.com/docs/sdk/Titanium.Contacts.md#CONTACTS_KIND_PERSON). ### CONTACTS_SORT_FIRST_NAME - Type: Number - Platforms: Android, iPhone, iPad, macOS - Permission: read-only Specifies that group members will be sorted by first name. Used with the [Titanium.Contacts.Group.sortedMembers](https://titaniumsdk.com/docs/sdk/Titanium.Contacts.Group.md#sortedMembers) method. One of the group of contact group "sort" constants [CONTACTS_SORT_FIRST_NAME](https://titaniumsdk.com/docs/sdk/Titanium.Contacts.md#CONTACTS_SORT_FIRST_NAME), and [CONTACTS_SORT_LAST_NAME](https://titaniumsdk.com/docs/sdk/Titanium.Contacts.md#CONTACTS_SORT_LAST_NAME). ### CONTACTS_SORT_LAST_NAME - Type: Number - Platforms: Android, iPhone, iPad, macOS - Permission: read-only Specifies that group members will be sorted by last name. Used with the [Titanium.Contacts.Group.sortedMembers](https://titaniumsdk.com/docs/sdk/Titanium.Contacts.Group.md#sortedMembers) method. One of the group of contact group "sort" constants [CONTACTS_SORT_FIRST_NAME](https://titaniumsdk.com/docs/sdk/Titanium.Contacts.md#CONTACTS_SORT_FIRST_NAME), and [CONTACTS_SORT_LAST_NAME](https://titaniumsdk.com/docs/sdk/Titanium.Contacts.md#CONTACTS_SORT_LAST_NAME). ### contactsAuthorization - Type: Number - Platforms: Android, iPhone, iPad, macOS - Since: Titanium SDK Android 2.1.3, iPhone 2.1.3, iPad 2.1.3, macOS 9.2.0 - Permission: read-only Returns an authorization constant indicating if the application has access to the address book. Always returns `AUTHORIZATION_AUTHORIZED` on iOS pre-6.0 and Android devices. If `contactsAuthorization` is `AUTHORIZATION_RESTRICTED`, you should not attempt to re-authorize: this will lead to issues. Accepts: `Titanium.Contacts.AUTHORIZATION_AUTHORIZED`, `Titanium.Contacts.AUTHORIZATION_DENIED`, `Titanium.Contacts.AUTHORIZATION_UNKNOWN` ### includeNote - Type: Boolean - Platforms: iPhone, iPad, macOS - Since: Titanium SDK iPhone 8.2.1, iPad 8.2.1, macOS 9.2.0 - Default: `true` A boolean value that indicates whether to fetch the notes stored in contacts or not. This property need to be set before calling contacts APIs. From iOS 13 or later if your app fetch note field from contact, the app must have to set key 'com.apple.developer.contacts.notes' to 'true' in entitlements section of tiapp.xml. ``` xml com.apple.developer.contacts.notes ``` See more details at https://developer.apple.com/documentation/bundleresources/entitlements/com_apple_developer_contacts_notes and https://developer.apple.com/contact/request/contact-note-field. ## Methods ### createGroup - Platforms: iPhone, iPad, macOS - Since: Titanium SDK 9.2.0 Creates and returns an instance of [Titanium.Contacts.Group](https://titaniumsdk.com/docs/sdk/Titanium.Contacts.Group.md). This method must be followed by [Titanium.Contacts.save](https://titaniumsdk.com/docs/sdk/Titanium.Contacts.md#save) to commit its changes. Parameters: - `parameters` (Dictionary, optional): Properties to set on a new object, including any in [Titanium.Contacts.Group](https://titaniumsdk.com/docs/sdk/Titanium.Contacts.Group.md) except those marked as non-creation or read-only. Returns: Titanium.Contacts.Group ### createPerson - Platforms: Android, iPhone, iPad, macOS - Since: Titanium SDK 2.1.0 Creates and returns an instance of [Titanium.Contacts.Person](https://titaniumsdk.com/docs/sdk/Titanium.Contacts.Person.md), and commits all pending changes to the underlying contacts database. Parameters: - `parameters` (Dictionary, optional): Properties to set on a new object, including any in [Titanium.Contacts.Person](https://titaniumsdk.com/docs/sdk/Titanium.Contacts.Person.md) except those marked as non-creation or read-only. Returns: Titanium.Contacts.Person ### getAllGroups - Platforms: iPhone, iPad, macOS Gets all groups. Returns: Array ### getAllPeople - Platforms: Android, iPhone, iPad, macOS Gets all people, unless a limit is specified. Parameters: - `limit` (Number): Maximum number of people. Android only. Returns: Array ### getGroupByIdentifier - Platforms: iPhone, iPad, macOS - Since: Titanium SDK iPhone 5.0.0, iPad 5.0.0, macOS 9.2.0 Gets the group with the specified identifier. Parameters: - `id` (String): Group identifier. Returns: Titanium.Contacts.Group ### getPeopleWithName - Platforms: Android, iPhone, iPad, macOS Gets people with a `firstName`, `middleName` or `lastName` field, or a combination of these fields, that match the specified name. Parameters: - `name` (String): Name to match. Returns: Array ### getPersonByIdentifier - Platforms: Android, iPhone, iPad, macOS - Since: Titanium SDK 5.0.0 Gets the person with the specified identifier. Parameters: - `id` (Number): Contact identifier. Returns: Titanium.Contacts.Person ### hasContactsPermissions - Platforms: Android, iPhone, iPad, macOS - Since: Titanium SDK Android 5.1.0, iPhone 5.1.0, iPad 5.1.0, macOS 9.2.0 Returns `true` if the app has contacts access. Returns: Boolean ### removeGroup - Platforms: iPhone, iPad, macOS Removes a group from the address book. This method must be followed by [Titanium.Contacts.save](https://titaniumsdk.com/docs/sdk/Titanium.Contacts.md#save) to commit its changes. Parameters: - `group` (Titanium.Contacts.Group): Contact group. ### removePerson - Platforms: Android, iPhone, iPad, macOS - Since: Titanium SDK 2.1.0 Removes a contact from the address book. On iOS: This method must be followed by a save action to commit the data to the underlying database, which can be done explicitly using [Titanium.Contacts.save](https://titaniumsdk.com/docs/sdk/Titanium.Contacts.md#save) or implicitly using [Titanium.Contacts.createPerson](https://titaniumsdk.com/docs/sdk/Titanium.Contacts.md#createPerson). Although the [Titanium.Contacts.Person](https://titaniumsdk.com/docs/sdk/Titanium.Contacts.Person.md) object will still exist once committed, it will no longer be valid. Continuing to use it will result in unpredictable behavior, including crashes. On Android: This method will remove the person from the Contacts book automatically. Parameters: - `person` (Titanium.Contacts.Person): Contact. ### requestContactsPermissions - Platforms: Android, iPhone, iPad, macOS - Since: Titanium SDK Android 5.1.0, iPhone 5.1.0, iPad 5.1.0, macOS 9.2.0 Requests for contacts access. On Android, the request view will show if the permission is not accepted by the user, and the user did not check the box "Never ask again" when denying the request. If the user checks the box "Never ask again," the user has to manually enable the permission in device settings. This method requests `Manifest.permission.READ_CONTACTS` and `Manifest.permission.WRITE_CONTACTS` on Android. If you require other permissions, you can also use [Titanium.Android.requestPermissions](https://titaniumsdk.com/docs/sdk/Titanium.Android.md#requestPermissions). In iOS 6, Apple introduced the Info.plist key `NSContactsUsageDescription` that is used to display an own description while authorizing contacts permissions. In iOS 10, this key is mandatory and the application will crash if your app does not include the key. Check the [Apple docs](https://developer.apple.com/library/content/documentation/General/Reference/InfoPlistKeyReference/Articles/CocoaKeys.html) for more information. Parameters: - `callback` (Callback, optional): Function to call upon user decision to grant contacts access. Optional on SDK 10, as this method will return a `Promise`, which may be used to handle the result. Returns: Promise - On SDK 10+, this method will return a `Promise` whose resolved value is equivalent to that passed to the optional callback argument. ### save - Platforms: Android, iPhone, iPad, macOS - Since: Titanium SDK 3.0.0 Commits all pending changes to the underlying contacts database. On Android: Takes an array of [Titanium.Contacts.Person](https://titaniumsdk.com/docs/sdk/Titanium.Contacts.Person.md) objects and saves changes for the specified contacts only. Parameters: - `contacts` (Array): List of contacts to save. Used on Android only. ### showContacts - Platforms: Android, iPhone, iPad, macOS Displays a picker that allows a person to be selected. Parameters: - `params` (showContactsParams): Argument containing parameters for this method. Optional on Android. ## Events ### reload - Platforms: iPhone, iPad, macOS - Since: Titanium SDK iPhone 3.1.0, iPad 3.1.0, macOS 9.2.0 Fired when the database backing the contacts module is modified externally. If you have an existing reference to a `Person` or `Group` object, you should obtain a new reference from the `Contacts` module. Using the existing object may result in unpredictable behavior, such as updating the wrong contact. ## Inherited members 7 members are inherited. Each is documented on the type that declares it. - [Titanium.Proxy](https://titaniumsdk.com/docs/sdk/13.1.1/Titanium.Proxy.md): `addEventListener`, `apiName`, `applyProperties`, `bubbleParent`, `fireEvent`, `lifecycleContainer`, `removeEventListener` --- - This corpus documents Titanium SDK 13.4.1. Anything here that does not name a version describes 13.4.1. - Titanium is maintained by TiDev. The Appcelerator toolchain is retired: there is no `appc` CLI, no Appcelerator Studio and no hosted build service. The supported CLI is `titanium` on npm, invoked as `ti`.