Read, create, update, and pick contacts using the Contacts and ContactsUI frameworks. Use when fetching contact data, saving new contacts, wrapping CNContactPickerViewController in SwiftUI, handling contact permissions, or working with CNContactStore fetch and save requests.

Contacts Framework Use CNContactStore , CNSaveRequest , and CNContactPickerViewController to fetch, create, update, or pick contacts in Swift 6.3 / iOS 26+ apps. Contents [Setup]( setup) [Authorization]( authorization) [Fetching Contacts]( fetching contacts) [Key Descriptors]( key descriptors) [Creating and Updating Contacts]( creating and updating contacts) [Contact Picker]( contact picker) [Observing Changes]( observing changes) [Common Mistakes]( common mistakes) [Review Checklist]( review checklist) [References]( references) Setup Project Configuration 1. Add NSContactsUsageDescription to Info.plist explaining why the app accesses contacts. The app crashes if it uses contact data APIs without this key. 2. No additional capability or entitlement is required for ordinary Contacts access. 3. Add com.apple.developer.contacts.notes only when reading or writing CNContactNoteKey / CNContact.note ; this entitlement requires Apple approval before public distribution. Imports Authorization Request access before fetching or saving contacts. The picker ( CNContactPickerViewController ) does not require authorization the system grants access only to the contacts the user selects. Authorization States Status Meaning .notDetermined User has not been prompted yet .authorized Full read/write access granted .denied User denied access; direct to Settings .restricted Parental controls or MDM restrict access .limited iOS 18+: user granted access to selected contacts only Treat both .authorized and .limited as usable Contacts API states. With .limited , fetch, edit, and delete operations only apply to contacts the user granted or the app created. Use ContactAccessButton or contactAccessPicker(isPresented:completionHandler:) to let users add contacts to the app's limited access set. Fetching Contacts Use unifiedContacts(matching:keysToFetch:) for predicate based queries. Use enumerateContacts(with:usingBlock:) for batch enumeration of all contacts. For large cached address books, first fetch identifiers, then fetch detailed contacts in batches by identifier. Fetch by Name Fetch by Identifier Enumerate All Contacts Perform I/O heavy enumeration off the main thread. Key Descriptors Only fetch the properties you need. Accessing an unfetched property throws CNContactPropertyNotFetchedException . Common Keys Key Property CNContactGivenNameKey First name CNContactFamilyNameKey Last name CNContactPhoneNumbersKey Phone numbers array CNContactEmailAddressesKey Email addresses array CNContactPostalAddressesKey Mailing addresses array CNContactImageDataKey Full resolution contact photo CNContactThumbnailImageDataKey Thumbnail contact photo CNContactBirthdayKey Birthday date components CNContactOrganizationNameKey Company name Composite Key Descriptors Use CNContactFormatter.descriptorForRequiredKeys(for:) to fetch all keys needed for formatting a contact's name. Creating and Updating Contacts Use CNMutableContact to build new contacts and CNSaveRequest to persist changes. Creating a New Contact Updating an Existing Contact You must fetch the contact with the properties you intend to modify, create a mutable copy, change the properties, then save. Deleting a Contact Save Result and Recovery try store.execute(saveRequest) returning without throwing is the save success checkpoint. Update an app side cache or success UI only after that return. If it throws, surface or propagate the error, keep the unsaved intent available to the user, and correct the known cause—such as authorization, a read only container, or invalid input—before building a fresh request. Serialize overlapping saves, do not access a request while execute( :) is using it, and refetch a possibly stale contact before a corrected retry when access permits. Do not blindly repeat the same destructive request or require a universal read back that the current access level may not permit. Load [Extended Contacts Patterns](references/contacts patterns.md) for multi select, vCard, and optimized search workflows. Contact Picker CNContactPickerViewController lets users pick contacts without granting full Contacts access. The app receives only the selected contact data. SwiftUI Wrapper Using the Picker Filtering the Picker Use predicates to control which contacts appear and what the user can select. Observing Changes Listen for external contact database changes to refresh cached data. Common Mistakes DON'T: Fetch all keys when you only need a name Over fetching wastes memory and slows queries, especially for contacts with large photos. DON'T: Access unfetched properties Accessing a property that was not in keysToFetch throws CNContactPropertyNotFetchedException at runtime. DON'T: Mutate a CNContact directly CNContact is immutable. You must call mutableCopy() to get a CNMutableContact . DON'T: Skip authorization and assume access Do not let fetch or save calls be the first place the user sees authorization. If status is .notDetermined , request access; if access was denied, contact operations fail with an authorization error. DON'T: Run heavy fetches on the main thread enumerateContacts performs I/O. Running it on the main thread blocks the UI. When strict concurrency checks complain about CNContact crossing task or actor boundaries, use @preconcurrency import Contacts in that file or map contacts into Sendable view models before returning them. Review Checklist [ ] NSContactsUsageDescription added to Info.plist [ ] requestAccess(for: .contacts) called before fetch or save operations [ ] .limited treated as usable access with selected contact caveats [ ] ContactAccessButton or contactAccessPicker offered when users need to expand limited access [ ] Authorization denial handled gracefully (guide user to Settings) [ ] Only needed CNKeyDescriptor keys included in fetch requests [ ] CNContactFormatter.descriptorForRequiredKeys(for:) used when formatting names [ ] Mutable copy created via mutableCopy() before modifying contacts [ ] Every create/update/delete uses CNSaveRequest ; app state advances only after execute( :) succeeds, and failures are surfaced before a corrected request is constructed [ ] Heavy fetches ( enumerateContacts ) run off the main thread [ ] CNContactStoreDidChange observed to refresh cached contacts [ ] CNContactPickerViewController used when full Contacts access is unnecessary [ ] Picker predicates set before presenting the picker view controller [ ] Single CNContactStore instance reused across the app References Extended patterns (multi select picker, vCard export, search optimization): [references/contacts patterns.md](references/contacts patterns.md) [Contacts framework](https://sosumi.ai/documentation/contacts) [CNContactStore](https://sosumi.ai/documentation/contacts/cncontactstore) [CNContactFetchRequest](https://sosumi.ai/documentation/contacts/cncontactfetchrequest) [CNSaveRequest](https://sosumi.ai/documentation/contacts/cnsaverequest) [CNMutableContact](https://sosumi.ai/documentation/contacts/cnmutablecontact) [CNContactPickerViewController](https://sosumi.ai/documentation/contactsui/cncontactpickerviewcontroller) [CNContactPickerDelegate](https://sosumi.ai/documentation/contactsui/cncontactpickerdelegate) [Accessing the contact store](https://sosumi.ai/documentation/contacts/accessing the contact store) [NSContactsUsageDescription](https://sosumi.ai/documentation/bundleresources/information property list/nscontactsusagedescription) [ContactAccessButton](https://sosumi.ai/documentation/contactsui/contactaccessbutton) [contactAccessPicker(isPresented:completionHandler:)](https://sosumi.ai/documentation/swiftui/view/contactaccesspicker(ispresented:completionhandler:)) [Contact Keys](https://sosumi.ai/documentation/contacts/contact keys)

contacts-framework