ContactsService Data Types

ContactsService defines and uses several data types.

An object representing a contact.

Property NameTypeDescriptionExample
idStringA stringified number unique to each contact. Generated by the native device at the time of contact creation."42"
nameContactNameAn object representing a contact's name.{familyName: "Locklear", givenName: "Awanasa"}
phoneNumbersContactLabeledValueAn array of objects containing phone numbers for the contact.[{mobile: "2065550100"}, {work: "3435550101"}, { home: "6195550102"}]
emailsContactLabeledValueAn array of objects containing email addresses for the contact.[{personal: ""}, {work: ""}]
addressesContactAddressAn object representing a contact's address.{type: "work", streetAddress: "415 Mission St", locality: "San Francisco", postalCode: "94105"}
imsContactLabeledValueAn array of objects containing instant messaging (IM) usernames for the contact.[{hangouts: "a_locklear"}, {telegram: ""}]
orgaizationsContactOrganizationAn object representing a contact's organization.{name: "Main Stage Analytics", department: "Data Engineering", title: "Data Scientist"}
noteStringA text field for any extra information about the contact.Mother-in-law's neighbor
urlsContactLabeledValueAn array of objects containing URLs for the contact.[{company_website_1: ""}, {company_website_2: ""}, {company_website_3: ""}]

An object representing a contact’s name.

Property NameTypeDescriptionExample
displayNameStringA string representing the name to be displayed for the contact. Only present on Android devices.Chan Ming Lewis
familyNameStringA string representing the contact’s family name (also known as “surname” or “last name”).Lewis
givenNameStringA string representing the contact’s given name (also known as “first name”).Chan
middleNameStringA string representing the contact’s middle name.Ming
namePrefixStringA string representing the contact’s name prefix.Mr.
nameSuffixStringA string representing the contact’s name suffix.Jr.

An object representing a contact’s address.

Property NameTypeDescriptionExample
typeStringA string representing the type of address for a contact’s address."Work"
streetAddressStringA string representing the street address for a contact’s address."415 Mission St"
localityStringA string representing the locality (also known as the “city”) for a contact’s address."San Francisco"
regionStringA string representing the region (also known as the “state” or “province”) for a contact’s address."California"
postalCodeStringA string representing the postal code for a contact’s address."94105"
countryStringA string representing the country for a contact’s address."U.S.A."

An object representing a contact’s organization.

Property NameTypeDescriptionExample
nameStringA string representing the name of a contact’s organization."Salesforce"
departmentStringA string representing the department of a contact’s organization."Engineering"
titleStringA string representing the title the contact holds in the organization."Senior Program Manager"

An object containing a label and a value for a miscellaneous piece of contact information.

Property NameTypeDescriptionExample
labelStringThe display name that categorizes the data in value. In the following examples, home, homepage, and work are label properties.
  • {home: "6195550102"}
  • {homepage: ""}
  • {work: ""}
valueStringThe value of the data specified in label.
  • {home: "6195550102"}
  • {homepage: ""}
  • {work: ""}

Labels and values are provided by the platform, and aren’t altered by ContactsService. Contacts apps on Android and iOS provide standard labels for fields, such as “home” or “work” for phone numbers and emails, but it’s also possible to enter custom label values. Exercise caution when processing labeled values where you depend on specific label text, or specific formats for values like phone numbers.

An object representing configuration details for a ContactsService session.

Property NameTypeDescriptionExample
permissionRationaleTextStringOptional parameter, used by Android only. This only appears after an initial denial by the user. To use the default permission message, pass in an empty object.The default permission message is “To import Contacts, permission is needed to access Contacts. Tap Allow in the following permissions dialog.”"The app needs to access your contacts to use contacts-related functionality."

An object representing an error that occurred when accessing ContactsService features.

Property NameTypeDescription
codeContactsServiceFailureCodeA value representing the reason for a contacts error. Possible failure codes include the following:
messageStringA string value describing the reason for the failure. This value is suitable for use in user interface messages. The message is provided in English, and isn’t localized.