ContactsService Data Types
ContactsService defines and uses several data types.
An object representing a contact.
| Property Name | Type | Description | Example |
|---|---|---|---|
id | String | A stringified number unique to each contact. Generated by the native device at the time of contact creation. | "42" |
name | ContactName | An object representing a contact's name. | {familyName: "Locklear", givenName: "Awanasa"} |
phoneNumbers | ContactLabeledValue | An array of objects containing phone numbers for the contact. | [{mobile: "2065550100"}, {work: "3435550101"}, { home: "6195550102"}] |
emails | ContactLabeledValue | An array of objects containing email addresses for the contact. | [{personal: "awanasa_locklear_736251@hotmail.com"}, {work: "awanasa_locklear_fake_work_email@employer.com"}] |
addresses | ContactAddress | An object representing a contact's address. | {type: "work", streetAddress: "415 Mission St", locality: "San Francisco", postalCode: "94105"} |
ims | ContactLabeledValue | An array of objects containing instant messaging (IM) usernames for the contact. | [{hangouts: "a_locklear"}, {telegram: "awanasa.data"}] |
orgaizations | ContactOrganization | An object representing a contact's organization. | {name: "Main Stage Analytics", department: "Data Engineering", title: "Data Scientist"} |
note | String | A text field for any extra information about the contact. | Mother-in-law's neighbor |
urls | ContactLabeledValue | An array of objects containing URLs for the contact. | [{company_website_1: "www.salesforce.com"}, {company_website_2: "www.tableau.com"}, {company_website_3: "https://slack.com"}] |
An object representing a contact’s name.
| Property Name | Type | Description | Example |
|---|---|---|---|
displayName | String | A string representing the name to be displayed for the contact. Only present on Android devices. | Chan Ming Lewis |
familyName | String | A string representing the contact’s family name (also known as “surname” or “last name”). | Lewis |
givenName | String | A string representing the contact’s given name (also known as “first name”). | Chan |
middleName | String | A string representing the contact’s middle name. | Ming |
namePrefix | String | A string representing the contact’s name prefix. | Mr. |
nameSuffix | String | A string representing the contact’s name suffix. | Jr. |
An object representing a contact’s address.
| Property Name | Type | Description | Example |
|---|---|---|---|
type | String | A string representing the type of address for a contact’s address. | "Work" |
streetAddress | String | A string representing the street address for a contact’s address. | "415 Mission St" |
locality | String | A string representing the locality (also known as the “city”) for a contact’s address. | "San Francisco" |
region | String | A string representing the region (also known as the “state” or “province”) for a contact’s address. | "California" |
postalCode | String | A string representing the postal code for a contact’s address. | "94105" |
country | String | A string representing the country for a contact’s address. | "U.S.A." |
An object representing a contact’s organization.
| Property Name | Type | Description | Example |
|---|---|---|---|
name | String | A string representing the name of a contact’s organization. | "Salesforce" |
department | String | A string representing the department of a contact’s organization. | "Engineering" |
title | String | A 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 Name | Type | Description | Example |
|---|---|---|---|
label | String | The display name that categorizes the data in value. In the following examples, home, homepage, and work are label properties. |
|
value | String | The value of the data specified in label. |
|
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 Name | Type | Description | Example |
|---|---|---|---|
permissionRationaleText | String | Optional 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 Name | Type | Description |
|---|---|---|
code | ContactsServiceFailureCode | A value representing the reason for a contacts error. Possible failure codes include the following:
|
message | String | A 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. |