Titanium Mobile

# Titanium.Contacts.Person

An object that represents a contact record for a person or organization in the system contacts address book.

Availability
0.8
0.8
9.2.0
Extends
Titanium.Proxy

# Overview

A person object is created using Titanium.Contacts.createPerson.

The following two kinds of properties exist for this object:

  • single value - contains either a string or number type value, an array of string type values, or null if unset.
  • multi-value - contains a dictionary with typical keys of home, work and/or other. Each key contains either a string type value, an array of string type values, or a dictionary containing key/value pairs with string type values.

# Adding and Modifying Properties

Support for adding and modifying properties is currently supported on iOS and Android.

# Keys as Address Book UI Labels

Keys act as labels in the address book user interface.

Although there is limited support for custom, arbitrarily-named, keys when used with multi-value properties, there is no support them with single value properties.

On iOS, creating custom keys is not recommended, and will lead to undefined results.

If a label has been created by the user of the device and used with a multi-value property, it will exist as a key with the same name.

See examples in Titanium.Contacts for more information.

These APIs are unavailable on macOS if the app is built on a version of Xcode < 12.

# Properties

# address

Availability
0.8
0.8
9.2.0
address :Dictionary

Addresses for the person. Multi-value. Read-only on Android.

The format of the dictionary accepted by this property is as follows:

  • Keys: any of home, work, and/or other.
  • Values: arrays of dictionary types with seven keys, CountryCode, Street, City, , State, Country and PostalCode, each with a string type value.

On Android:

'CountryCode' and 'County' are currently not supported.

On iOS:

The CountryCode key value may be one of the recognized two-character ISO 3166-1 country codes, and determines the format in which the contact is presented by the address book user interface. See the wikipedia section ISO 3166-1 alpha-2 for a comprehensive list of codes.

# alternateBirthday

Availability
3.6.0
9.2.0
alternateBirthday :Dictionary

Alternate birthday of the person. Single Dictionary.

The format of the dictionary accepted by this property is as follows:

  • Keys: calendarIdentifier, era, year, month, day and isLeapMonth.
  • Values: Use chinese, hebrew and islamic-civil for calendarIdentifier. Use number type for era, year, month and day. These must be consistent with corresponding calendarIdentifier. Use boolean type for isLeapMonth.

# birthday

Availability
0.8
0.8
9.2.0
birthday :String

Date of birth of the person. Single value.

Date format is "yyyy-MM-ddTHH:mm:ss.SSS+0000"

# created READONLY

Availability
0.8
9.2.0
created :String

Date and time that the person record was created. Single value. Deprecated since iOS 9.

Date format is "yyyy-MM-ddTHH:mm:ss.SSS+0000"

# date

Availability
0.8
0.8
9.2.0
date :Dictionary

Dates associated with the person. Multi-value.

Adding or modifying this property is not currently supported.

The format of the dictionary accepted by this property is as follows:

  • Keys: any of anniversary and/or other.
  • Values: array of string type.

Date format is "yyyy-MM-ddTHH:mm:ss.SSS+0000"

# department

Availability
0.8
0.8
9.2.0
department :String

Department of the person. Single value.

# email

Availability
0.8
0.8
9.2.0
email :Dictionary

Email addresses for the person. Multi-value. Read-only on Android.

The format of the dictionary accepted by this property is as follows:

  • Keys: any of home, work, and/or other.
  • Values: array of string type.

# firstName

Availability
0.8
0.8
9.2.0
firstName :String

First name of the person. Single value.

# firstPhonetic

Availability
0.8
0.8
9.2.0
firstPhonetic :String

Phonetic first name of the person. Single value.

# fullName READONLY

Availability
0.8
0.8
9.2.0
fullName :String

Localized full name of the person. Single value. Read-only on Android.

The full name will be printed in the order of. Prefix,first name, middle name, family name, suffix.

# id READONLY

Availability
0.8
id :Number

Record identifier of the person. Single value.

# identifier READONLY

Availability
5.0.0
9.2.0
identifier :String

Identifier of the person.

Prior to iOS 9, use the recordId property.

# image

Availability
0.8
0.8
9.2.0
image :Titanium.Blob

Image for the person. Single value. Read-only for >= iOS9

Set to null to remove the image.

# instantMessage

Availability
0.8
0.8
9.2.0
instantMessage :Dictionary

Instant messenger information of the person. Multi-value.

The format of the dictionary accepted by this property is as follows:

  • Keys: any of home, work and/or other.
  • Values: arrays of dictionary types with two keys, service and username, each with a string type value.

The service key value may be one of AIM, Facebook, GaduGadu, GoogleTalk, ICQ, Jabber, MSN, QQ, Skype, or Yahoo. These values are key sensitive.

# jobTitle

Availability
0.8
0.8
9.2.0
jobTitle :String

Job title of the person. Single value.

# kind

Availability
0.8
0.8
9.2.0
kind :Number

Determines the type of information the person record contains; either person or organization. Read-only on Android.

This API can be assigned the following constants:

# lastName

Availability
0.8
0.8
9.2.0
lastName :String

Last name of the person. Single value.

# lastPhonetic

Availability
0.8
0.8
9.2.0
lastPhonetic :String

Phonetic last name of the person. Single value.

# middleName

Availability
0.8
0.8
9.2.0
middleName :String

Middle name of the person. Single value.

# middlePhonetic

Availability
0.8
0.8
9.2.0
middlePhonetic :String

Phonetic middle name of the person. Single value.

# modified READONLY

Availability
0.8
9.2.0
modified :String

Date and time that the person record was last modified. Single value. Deprecated since iOS 9.

Date format is "yyyy-MM-ddTHH:mm:ss.SSS+0000"

# nickname

Availability
0.8
0.8
9.2.0
nickname :String

Nickname of the person. Single value.

# note

Availability
0.8
0.8
9.2.0
note :String

Notes for the person. Single value.

# organization

Availability
0.8
0.8
9.2.0
organization :String

Organization to which the person belongs. Single value.

# phone

Availability
0.8
0.8
9.2.0
phone :Dictionary

Phone numbers for the person. Multi-value. Read-only on Android.

The format of the dictionary accepted by this property is as follows:

  • Keys: any of home, work, other, mobile, pager, workFax, homeFax, main, and/or iPhone.
  • Values: array of string type.

# prefix READONLY

Availability
0.8
0.8
9.2.0
prefix :String

Prefix for the person. Single value.

# recordId

Availability
0.8
9.2.0
recordId :Number

Record identifier of the person. Single value. Deprecated since iOS 9.

For iOS 9 and later, use the identifier property. Previously, a contact can be selected without requiring User permission. In such case this property returns -1.

# relatedNames

Availability
0.8
0.8
9.2.0
relatedNames :Dictionary

Names of people to which the person is related. Multi-value.

The format of the dictionary accepted by this property is as follows:

  • Keys: any of mother, father, parent, brother, sister, child, friend, spouse, partner, assistant, manager, and/or other.
  • Values: array of string type.

# socialProfile

Availability
3.6.0
9.2.0
socialProfile :Dictionary

Social profile information of the person. Multi-value.

The format of the dictionary accepted by this property is as follows:

  • Keys: any of home, work and/or other.
  • Values: arrays of dictionary types with two keys, service and username each with a string type value.

The service key value may be one of twitter, sinaweibo, gamecenter, facebook, myspace, linkedin, or flickr. These values are key sensitive.

# suffix READONLY

Availability
0.8
0.8
9.2.0
suffix :String

Suffix for the person. Single value.

# url

Availability
0.8
0.8
9.2.0
url :Dictionary

URLs of webpages associated with the person. Multi-value.

The format of the dictionary accepted by this property is as follows:

  • Keys: any of homepage, home, work, and/or other.
  • Values: array of string type.

Contents