@capacitor/contacts

Access, search, pick, create, update and remove device contacts.

Install

To use npm

npm install @capacitor/contacts

To use yarn

yarn add @capacitor/contacts

Sync native files

npx cap sync

iOS

Add the NSContactsUsageDescription key to your app's Info.plist and describe why the app accesses the user's contacts; iOS crashes on first contacts access without it:

<key>NSContactsUsageDescription</key>
<string>We need access to contacts to search, save and remove them.</string>

Notes:

• The plugin uses the modern Contacts framework (CNContactStore, never the deprecated AddressBook APIs), so it fully supports iOS 18+ Limited Access: find, save and remove operate on the subset the user shared with the app, and pickContact presents the system picker (which needs no permission and always shows the full contact list).
• The note field is not supported on iOS: reading or writing it requires Apple's restricted com.apple.developer.contacts.notes entitlement. The field is omitted on read and ignored on save.
• Contact ids are opaque CNContact identifiers; ids persisted by the legacy AddressBook-based Cordova plugin do not resolve after migration.

Android

The plugin declares READ_CONTACTS and WRITE_CONTACTS in its own manifest; Gradle manifest merging adds them to your app automatically. Each method requests the runtime permission it needs the first time it runs; read for find/pickContact, read + write for save/remove.

Permission model

This plugin intentionally exposes no checkPermissions() / requestPermissions() methods: permissions are requested implicitly by each method, matching the legacy cordova-plugin-contacts behavior. A call rejects with OS-PLUG-CONT-0020 when the user denies access.

Errors

Every rejection carries a structured code + message:

Code	Meaning
OS-PLUG-CONT-0000	Unknown error
OS-PLUG-CONT-0001	Invalid argument (e.g. unknown id)
OS-PLUG-CONT-0002	Timeout (reserved, currently unused)
OS-PLUG-CONT-0003	Pending operation (e.g. picker already open)
OS-PLUG-CONT-0004	I/O error
OS-PLUG-CONT-0005	Not supported
OS-PLUG-CONT-0006	Operation cancelled (picker closed)
OS-PLUG-CONT-0020	Permission denied

Usage

import { Contacts } from '@capacitor/contacts';

// Search every field for "ada" and return all matches with a phone number
const { contacts } = await Contacts.find({
  fields: ['*'],
  filter: 'ada',
  multiple: true,
  hasPhoneNumber: true,
});

// Create a contact
const saved = await Contacts.save({
  contact: {
    name: { givenName: 'Ada', familyName: 'Lovelace' },
    phoneNumbers: [{ type: 'mobile', value: '+351910000000' }],
    emails: [{ type: 'home', value: '[email protected]' }],
  },
});

// Update it (id present -> update)
await Contacts.save({ contact: { ...saved, nickname: 'Countess' } });

// Pick a contact with the native picker
const picked = await Contacts.pickContact();

// Remove it by id
await Contacts.remove({ id: saved.id! });

API

• find(...)
• save(...)
• remove(...)
• pickContact()
• Interfaces
• Type Aliases

find(...)

find(options: ContactFindOptions) => Promise<ContactFindResult>

Queries the device contacts database and returns the matching contacts.

Requests the READ_CONTACTS (Android) / Contacts (iOS) permission internally the first time it runs; there is no separate permission method.

iOS 18+: under Limited Access the search runs against (and returns only) the subset of contacts the user shared with the app.

Param	Type
options	ContactFindOptions

Returns:

Promise<ContactFindResult>

Since: 1.0.0

---

save(...)

save(options: ContactSaveOptions) => Promise<Contact>

Persists a new contact or updates an existing one (matched by contact.id). Resolves with the full saved contact.

Requests the READ/WRITE_CONTACTS (Android) / Contacts (iOS) permission internally.

iOS 18+: works under Limited Access: new contacts are added to the app's accessible set; updating requires the target contact to be in that set (otherwise the call rejects with OS-PLUG-CONT-0001).

Param	Type
options	ContactSaveOptions

Returns:

Promise<Contact>

Since: 1.0.0

---

remove(...)

remove(options: ContactRemoveOptions) => Promise<void>

Removes the contact with the given id from the device contacts database. Rejects with OS-PLUG-CONT-0001 when no contact has that id (on iOS 18+ Limited Access, also when the contact is outside the accessible set).

Requests the READ/WRITE_CONTACTS (Android) / Contacts (iOS) permission internally.

Param	Type
options	ContactRemoveOptions

Since: 1.0.0

---

pickContact()

pickContact() => Promise<Contact>

Launches the native contact picker UI and resolves with the contact the user selects. Rejects with OS-PLUG-CONT-0006 if the user cancels.

On iOS the system picker requires no permission and always shows the full contact list, even under iOS 18+ Limited Access (the picked contact is returned without joining the app's accessible set). On Android the READ_CONTACTS permission is requested internally to read the picked contact's details.

Returns:

Promise<Contact>

Since: 1.0.0

---

Interfaces

ContactFindResult

Result of a {@link ContactsPlugin.find} call.

Prop	Type	Description	Since
contacts	Contact[]	The contacts matching the search criteria.	1.0.0

Contact

A single device contact.

Prop	Type	Description	Since
id	string	Globally unique, platform-assigned identifier. Absent for contacts not yet saved to the device.	1.0.0
rawId	string	Android raw-contact id backing this aggregated contact. iOS leaves this unset.	1.0.0
displayName	string	Name suitable for display to end users.	1.0.0
name	ContactName	The structured name components.	1.0.0
nickname	string	A casual name by which to address the contact.	1.0.0
phoneNumbers	ContactField[]	The contact's phone numbers.	1.0.0
emails	ContactField[]	The contact's email addresses.	1.0.0
addresses	ContactAddress[]	The contact's postal addresses.	1.0.0
ims	ContactField[]	The contact's instant-messaging handles.	1.0.0
organizations	ContactOrganization[]	The contact's organizations.	1.0.0
birthday	number	The contact's birthday as epoch milliseconds.	1.0.0
note	string	A free-form note about the contact. iOS: not supported by default: reading/writing a contact's note requires Apple's restricted com.apple.developer.contacts.notes entitlement. Without it the field is omitted on read and ignored on save. Android has no such restriction.	1.0.0
photos	ContactField[]	The contact's photos. Reads return type: 'url' with the value holding a reference to the image, never image bytes: on Android the contact's content:// photo URI, on iOS the path of a copy written to the app's temporary directory (cleared by the system). On save, the first entry is applied: pass type: 'base64' with base64 data, or type: 'url' with a local file:///content:// URI to import.	1.0.0
categories	ContactField[]	User-defined categories associated with the contact. Read-only: populated from the contact's group memberships on Android, never returned on iOS (the Contacts framework has no equivalent), and ignored on save.	1.0.0
urls	ContactField[]	Web pages associated with the contact.	1.0.0

ContactName

Structured name of a {@link Contact}.

Prop	Type	Description	Since
formatted	string	The complete formatted name.	1.0.0
familyName	string	Family (last) name.	1.0.0
givenName	string	Given (first) name.	1.0.0
middleName	string	Middle name.	1.0.0
honorificPrefix	string	Honorific prefix (e.g. Mr., Dr.).	1.0.0
honorificSuffix	string	Honorific suffix (e.g. Esq.).	1.0.0

ContactField

A generic, repeatable contact field (phone number, email, IM, photo, URL, category).

Prop	Type	Description	Since
type	string	The kind of field, e.g. home, work, mobile. For photos, url or base64.	1.0.0
value	string	The field value (phone number, email address, URI, etc.).	1.0.0
pref	boolean	true if this is the contact's preferred value for the field.	1.0.0
id	string	Platform-assigned id of this individual field entry.	1.0.0

ContactAddress

A postal address of a {@link Contact}.

Prop	Type	Description	Since
id	string	Platform-assigned id of this address entry.	1.0.0
pref	boolean	true if this is the contact's preferred address.	1.0.0
type	string	The kind of address, e.g. home, work.	1.0.0
formatted	string	The full address formatted for display.	1.0.0
streetAddress	string	The street address.	1.0.0
locality	string	The city or locality.	1.0.0
region	string	The state or region.	1.0.0
postalCode	string	The ZIP or postal code.	1.0.0
country	string	The country name.	1.0.0

ContactOrganization

An organization a {@link Contact} belongs to.

Prop	Type	Description	Since
id	string	Platform-assigned id of this organization entry. Android only; iOS models the organization as flat contact properties without an id.	1.0.0
pref	boolean	true if this is the contact's preferred organization.	1.0.0
type	string	The kind of organization, e.g. work.	1.0.0
name	string	The organization name.	1.0.0
department	string	The department within the organization.	1.0.0
title	string	The contact's title at the organization.	1.0.0

ContactFindOptions

Search options accepted by {@link ContactsPlugin.find}.

Prop	Type	Description	Since
fields	ContactFieldType[]	Fields to search against. Pass ['*'] to match every field. An empty array is invalid and rejects with OS-PLUG-CONT-0001. The id field matches by exact identifier; all other fields match case-insensitive substrings. photos and categories are not searchable.	1.0.0
filter	string	Search string matched (case-insensitively) against the selected fields. An empty/omitted filter returns every contact.	1.0.0
multiple	boolean	When true, returns every match; when false (default), returns at most one contact.	1.0.0
desiredFields	ContactFieldType[]	If set, each returned {@link Contact} only includes these fields (plus the always-present id).	1.0.0
hasPhoneNumber	boolean	OutSystems extension: when true, only contacts that have at least one phone number are returned. Defaults to false.	1.0.0

ContactSaveOptions

Options accepted by {@link ContactsPlugin.save}.

Prop	Type	Description	Since
contact	Contact	The contact to create (no id) or update (existing id). Update semantics: every field present on the contact replaces the stored value entirely (e.g. name replaces the whole structured name, phoneNumbers replaces all phone numbers); omitted fields are left unchanged.	1.0.0

ContactRemoveOptions

Options accepted by {@link ContactsPlugin.remove}.

Prop	Type	Description	Since
id	string	The native id of the contact to remove.	1.0.0

Type Aliases

ContactFieldType

The set of contact fields a {@link ContactsPlugin.find} call can search against or request back. Mirrors the legacy Cordova ContactFieldType string values exactly.

'addresses' | 'birthday' | 'categories' | 'country' | 'department' | 'displayName' | 'emails' | 'familyName' | 'formatted' | 'givenName' | 'honorificPrefix' | 'honorificSuffix' | 'id' | 'ims' | 'locality' | 'middleName' | 'name' | 'nickname' | 'note' | 'organizations' | 'phoneNumbers' | 'photos' | 'postalCode' | 'region' | 'streetAddress' | 'title' | 'urls'