Contacts Framework

by dpearson26998d90fd121a26No license1.1K starsListed Oct 8, 2026Updated Oct 8, 2026Repository updated 2 months ago

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.

Instructions onlySoftware Development

AI-generated overview

Guides Swift developers in reading, creating, updating, and picking contacts with the Contacts and ContactsUI frameworks.

What it does: This skill provides reference guidance and code patterns for using CNContactStore, CNSaveRequest, and CNContactPickerViewController in Swift 6.3 / iOS 26+ apps. It covers authorization states, predicate and identifier fetches, key descriptors, creating, updating and deleting contacts, a SwiftUI picker wrapper, change observation, common mistakes, and a review checklist. It produces documentation and example code rather than executable artifacts.
When to use it: Use it when fetching contact data, saving or updating contacts, wrapping CNContactPickerViewController in SwiftUI, handling contact permissions, or working with CNContactStore fetch and save requests.
Requirements: No scripts; instructions and reference documentation only. It assumes Swift 6.3 / iOS 26+ development with the Contacts and ContactsUI frameworks, and mentions Info.plist keys and an Apple-approved entitlement for contact notes.

Contacts Framework

Use CNContactStore, CNSaveRequest, and CNContactPickerViewController to fetch, create, update, or pick contacts in Swift 6.3 / iOS 26+ apps.

Setup
Authorization
Fetching Contacts
Key Descriptors
Creating and Updating Contacts
Contact Picker
Observing Changes
Common Mistakes
Review Checklist
References

Setup

Project Configuration

Add NSContactsUsageDescription to Info.plist explaining why the app accesses contacts. The app crashes if it uses contact data APIs without this key.
No additional capability or entitlement is required for ordinary Contacts access.
Add com.apple.developer.contacts.notes only when reading or writing CNContactNoteKey / CNContact.note; this entitlement requires Apple approval before public distribution.

Imports

swift

@preconcurrency import Contacts  // CNContactStore, CNSaveRequest, CNContactimport ContactsUI                // CNContactPickerViewController

@preconcurrency import Contacts  // CNContactStore, CNSaveRequest, CNContactimport ContactsUI                // CNContactPickerViewController

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.

swift

let store = CNContactStore()
func requestAccess() async throws -> Bool {    return try await store.requestAccess(for: .contacts)}
// Check current status without promptingfunc checkStatus() -> CNAuthorizationStatus {    CNContactStore.authorizationStatus(for: .contacts)}

let store = CNContactStore()
func requestAccess() async throws -> Bool {    return try await store.requestAccess(for: .contacts)}
// Check current status without promptingfunc checkStatus() -> CNAuthorizationStatus {    CNContactStore.authorizationStatus(for: .contacts)}

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

swift

func fetchContacts(named name: String) throws -> [CNContact] {    let predicate = CNContact.predicateForContacts(matchingName: name)    let keys: [CNKeyDescriptor] = [        CNContactGivenNameKey as CNKeyDescriptor,        CNContactFamilyNameKey as CNKeyDescriptor,        CNContactPhoneNumbersKey as CNKeyDescriptor    ]    return try store.unifiedContacts(matching: predicate, keysToFetch: keys)}

func fetchContacts(named name: String) throws -> [CNContact] {    let predicate = CNContact.predicateForContacts(matchingName: name)    let keys: [CNKeyDescriptor] = [        CNContactGivenNameKey as CNKeyDescriptor,        CNContactFamilyNameKey as CNKeyDescriptor,        CNContactPhoneNumbersKey as CNKeyDescriptor    ]    return try store.unifiedContacts(matching: predicate, keysToFetch: keys)}

Fetch by Identifier

swift

func fetchContact(identifier: String) throws -> CNContact {    let keys: [CNKeyDescriptor] = [        CNContactGivenNameKey as CNKeyDescriptor,        CNContactFamilyNameKey as CNKeyDescriptor,        CNContactEmailAddressesKey as CNKeyDescriptor    ]    return try store.unifiedContact(withIdentifier: identifier, keysToFetch: keys)}

func fetchContact(identifier: String) throws -> CNContact {    let keys: [CNKeyDescriptor] = [        CNContactGivenNameKey as CNKeyDescriptor,        CNContactFamilyNameKey as CNKeyDescriptor,        CNContactEmailAddressesKey as CNKeyDescriptor    ]    return try store.unifiedContact(withIdentifier: identifier, keysToFetch: keys)}

Enumerate All Contacts

Perform I/O-heavy enumeration off the main thread.

swift

func fetchAllContacts() throws -> [CNContact] {    let keys: [CNKeyDescriptor] = [        CNContactGivenNameKey as CNKeyDescriptor,        CNContactFamilyNameKey as CNKeyDescriptor    ]    let request = CNContactFetchRequest(keysToFetch: keys)    request.sortOrder = .givenName
    var contacts: [CNContact] = []    try store.enumerateContacts(with: request) { contact, _ in        contacts.append(contact)    }    return contacts}

func fetchAllContacts() throws -> [CNContact] {    let keys: [CNKeyDescriptor] = [        CNContactGivenNameKey as CNKeyDescriptor,        CNContactFamilyNameKey as CNKeyDescriptor    ]    let request = CNContactFetchRequest(keysToFetch: keys)    request.sortOrder = .givenName
    var contacts: [CNContact] = []    try store.enumerateContacts(with: request) { contact, _ in        contacts.append(contact)    }    return contacts}

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.

swift

let nameKeys = CNContactFormatter.descriptorForRequiredKeys(for: .fullName)let keys: [CNKeyDescriptor] = [nameKeys, CNContactPhoneNumbersKey as CNKeyDescriptor]

let nameKeys = CNContactFormatter.descriptorForRequiredKeys(for: .fullName)let keys: [CNKeyDescriptor] = [nameKeys, CNContactPhoneNumbersKey as CNKeyDescriptor]

Creating and Updating Contacts

Use CNMutableContact to build new contacts and CNSaveRequest to persist changes.

Creating a New Contact

swift

func createContact(givenName: String, familyName: String, phone: String) throws {    let contact = CNMutableContact()    contact.givenName = givenName    contact.familyName = familyName    contact.phoneNumbers = [        CNLabeledValue(            label: CNLabelPhoneNumberMobile,            value: CNPhoneNumber(stringValue: phone)        )    ]
    let saveRequest = CNSaveRequest()    saveRequest.add(contact, toContainerWithIdentifier: nil) // nil = default container    try store.execute(saveRequest)}

func createContact(givenName: String, familyName: String, phone: String) throws {    let contact = CNMutableContact()    contact.givenName = givenName    contact.familyName = familyName    contact.phoneNumbers = [        CNLabeledValue(            label: CNLabelPhoneNumberMobile,            value: CNPhoneNumber(stringValue: phone)        )    ]
    let saveRequest = CNSaveRequest()    saveRequest.add(contact, toContainerWithIdentifier: nil) // nil = default container    try store.execute(saveRequest)}

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.

swift

func updateContactEmail(identifier: String, email: String) throws {    let keys: [CNKeyDescriptor] = [        CNContactEmailAddressesKey as CNKeyDescriptor    ]    let contact = try store.unifiedContact(withIdentifier: identifier, keysToFetch: keys)    guard let mutable = contact.mutableCopy() as? CNMutableContact else { return }
    mutable.emailAddresses.append(        CNLabeledValue(label: CNLabelWork, value: email as NSString)    )
    let saveRequest = CNSaveRequest()    saveRequest.update(mutable)    try store.execute(saveRequest)}

func updateContactEmail(identifier: String, email: String) throws {    let keys: [CNKeyDescriptor] = [        CNContactEmailAddressesKey as CNKeyDescriptor    ]    let contact = try store.unifiedContact(withIdentifier: identifier, keysToFetch: keys)    guard let mutable = contact.mutableCopy() as? CNMutableContact else { return }
    mutable.emailAddresses.append(        CNLabeledValue(label: CNLabelWork, value: email as NSString)    )
    let saveRequest = CNSaveRequest()    saveRequest.update(mutable)    try store.execute(saveRequest)}

Deleting a Contact

swift

func deleteContact(identifier: String) throws {    let keys: [CNKeyDescriptor] = [CNContactIdentifierKey as CNKeyDescriptor]    let contact = try store.unifiedContact(withIdentifier: identifier, keysToFetch: keys)    guard let mutable = contact.mutableCopy() as? CNMutableContact else { return }
    let saveRequest = CNSaveRequest()    saveRequest.delete(mutable)    try store.execute(saveRequest)}

func deleteContact(identifier: String) throws {    let keys: [CNKeyDescriptor] = [CNContactIdentifierKey as CNKeyDescriptor]    let contact = try store.unifiedContact(withIdentifier: identifier, keysToFetch: keys)    guard let mutable = contact.mutableCopy() as? CNMutableContact else { return }
    let saveRequest = CNSaveRequest()    saveRequest.delete(mutable)    try store.execute(saveRequest)}

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 [blocked] 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

swift

import SwiftUIimport ContactsUI
struct ContactPicker: UIViewControllerRepresentable {    @Binding var selectedContact: CNContact?
    func makeUIViewController(context: Context) -> CNContactPickerViewController {        let picker = CNContactPickerViewController()        picker.delegate = context.coordinator        return picker    }
    func updateUIViewController(_ uiViewController: CNContactPickerViewController, context: Context) {}
    func makeCoordinator() -> Coordinator {        Coordinator(self)    }
    final class Coordinator: NSObject, CNContactPickerDelegate {        let parent: ContactPicker
        init(_ parent: ContactPicker) {            self.parent = parent        }
        func contactPicker(_ picker: CNContactPickerViewController, didSelect contact: CNContact) {            parent.selectedContact = contact        }
        func contactPickerDidCancel(_ picker: CNContactPickerViewController) {            parent.selectedContact = nil        }    }}

import SwiftUIimport ContactsUI
struct ContactPicker: UIViewControllerRepresentable {    @Binding var selectedContact: CNContact?
    func makeUIViewController(context: Context) -> CNContactPickerViewController {        let picker = CNContactPickerViewController()        picker.delegate = context.coordinator        return picker    }
    func updateUIViewController(_ uiViewController: CNContactPickerViewController, context: Context) {}
    func makeCoordinator() -> Coordinator {        Coordinator(self)    }
    final class Coordinator: NSObject, CNContactPickerDelegate {        let parent: ContactPicker
        init(_ parent: ContactPicker) {            self.parent = parent        }
        func contactPicker(_ picker: CNContactPickerViewController, didSelect contact: CNContact) {            parent.selectedContact = contact        }
        func contactPickerDidCancel(_ picker: CNContactPickerViewController) {            parent.selectedContact = nil        }    }}

Using the Picker

swift

struct ContactSelectionView: View {    @State private var selectedContact: CNContact?    @State private var showPicker = false
    var body: some View {        VStack {            if let contact = selectedContact {                Text("\(contact.givenName) \(contact.familyName)")            }            Button("Select Contact") {                showPicker = true            }        }        .sheet(isPresented: $showPicker) {            ContactPicker(selectedContact: $selectedContact)        }    }}

struct ContactSelectionView: View {    @State private var selectedContact: CNContact?    @State private var showPicker = false
    var body: some View {        VStack {            if let contact = selectedContact {                Text("\(contact.givenName) \(contact.familyName)")            }            Button("Select Contact") {                showPicker = true            }        }        .sheet(isPresented: $showPicker) {            ContactPicker(selectedContact: $selectedContact)        }    }}

Filtering the Picker

Use predicates to control which contacts appear and what the user can select.

swift

let picker = CNContactPickerViewController()// Only show contacts that have an email addresspicker.predicateForEnablingContact = NSPredicate(format: "emailAddresses.@count > 0")// Selecting a contact returns it directly (no detail card)picker.predicateForSelectionOfContact = NSPredicate(value: true)

let picker = CNContactPickerViewController()// Only show contacts that have an email addresspicker.predicateForEnablingContact = NSPredicate(format: "emailAddresses.@count > 0")// Selecting a contact returns it directly (no detail card)picker.predicateForSelectionOfContact = NSPredicate(value: true)

Observing Changes

Listen for external contact database changes to refresh cached data.

swift

func observeContactChanges() {    NotificationCenter.default.addObserver(        forName: .CNContactStoreDidChange,        object: nil,        queue: .main    ) { _ in        // Refetch contacts -- cached CNContact objects are stale        refreshContacts()    }}

func observeContactChanges() {    NotificationCenter.default.addObserver(        forName: .CNContactStoreDidChange,        object: nil,        queue: .main    ) { _ in        // Refetch contacts -- cached CNContact objects are stale        refreshContacts()    }}

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.

swift

// WRONG: Fetches far more than the UI displays, including full-resolution photoslet keys: [CNKeyDescriptor] = [    CNContactFormatter.descriptorForRequiredKeys(for: .fullName),    CNContactImageDataKey as CNKeyDescriptor,    CNContactPhoneNumbersKey as CNKeyDescriptor,    CNContactEmailAddressesKey as CNKeyDescriptor,    CNContactPostalAddressesKey as CNKeyDescriptor,    CNContactBirthdayKey as CNKeyDescriptor]
// CORRECT: Fetch only what you displaylet keys: [CNKeyDescriptor] = [    CNContactGivenNameKey as CNKeyDescriptor,    CNContactFamilyNameKey as CNKeyDescriptor]

// WRONG: Fetches far more than the UI displays, including full-resolution photoslet keys: [CNKeyDescriptor] = [    CNContactFormatter.descriptorForRequiredKeys(for: .fullName),    CNContactImageDataKey as CNKeyDescriptor,    CNContactPhoneNumbersKey as CNKeyDescriptor,    CNContactEmailAddressesKey as CNKeyDescriptor,    CNContactPostalAddressesKey as CNKeyDescriptor,    CNContactBirthdayKey as CNKeyDescriptor]
// CORRECT: Fetch only what you displaylet keys: [CNKeyDescriptor] = [    CNContactGivenNameKey as CNKeyDescriptor,    CNContactFamilyNameKey as CNKeyDescriptor]

DON'T: Access unfetched properties

Accessing a property that was not in keysToFetch throws CNContactPropertyNotFetchedException at runtime.

swift

// WRONG: Only fetched name keys, now accessing phonelet keys: [CNKeyDescriptor] = [CNContactGivenNameKey as CNKeyDescriptor]let contact = try store.unifiedContact(withIdentifier: id, keysToFetch: keys)let phone = contact.phoneNumbers.first // CRASH
// CORRECT: Include the key you needlet keys: [CNKeyDescriptor] = [    CNContactGivenNameKey as CNKeyDescriptor,    CNContactPhoneNumbersKey as CNKeyDescriptor]

// WRONG: Only fetched name keys, now accessing phonelet keys: [CNKeyDescriptor] = [CNContactGivenNameKey as CNKeyDescriptor]let contact = try store.unifiedContact(withIdentifier: id, keysToFetch: keys)let phone = contact.phoneNumbers.first // CRASH
// CORRECT: Include the key you needlet keys: [CNKeyDescriptor] = [    CNContactGivenNameKey as CNKeyDescriptor,    CNContactPhoneNumbersKey as CNKeyDescriptor]

DON'T: Mutate a CNContact directly

CNContact is immutable. You must call mutableCopy() to get a CNMutableContact.

swift

// WRONG: CNContact has no setterlet contact = try store.unifiedContact(withIdentifier: id, keysToFetch: keys)contact.givenName = "New Name" // Compile error
// CORRECT: Create mutable copyguard let mutable = contact.mutableCopy() as? CNMutableContact else { return }mutable.givenName = "New Name"

// WRONG: CNContact has no setterlet contact = try store.unifiedContact(withIdentifier: id, keysToFetch: keys)contact.givenName = "New Name" // Compile error
// CORRECT: Create mutable copyguard let mutable = contact.mutableCopy() as? CNMutableContact else { return }mutable.givenName = "New Name"

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.

swift

// WRONG: Jump straight to fetchlet contacts = try store.unifiedContacts(matching: predicate, keysToFetch: keys)
// CORRECT: Check or request access firstlet granted = try await store.requestAccess(for: .contacts)guard granted else { return }let contacts = try store.unifiedContacts(matching: predicate, keysToFetch: keys)

// WRONG: Jump straight to fetchlet contacts = try store.unifiedContacts(matching: predicate, keysToFetch: keys)
// CORRECT: Check or request access firstlet granted = try await store.requestAccess(for: .contacts)guard granted else { return }let contacts = try store.unifiedContacts(matching: predicate, keysToFetch: keys)

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.

swift

// WRONG: Main thread enumerationfunc loadContacts() {    try store.enumerateContacts(with: request) { contact, _ in ... }}
// CORRECT: Run on a background threadfunc loadContacts() async throws -> [CNContact] {    try await Task.detached {        var results: [CNContact] = []        try store.enumerateContacts(with: request) { contact, _ in            results.append(contact)        }        return results    }.value}

// WRONG: Main thread enumerationfunc loadContacts() {    try store.enumerateContacts(with: request) { contact, _ in ... }}
// CORRECT: Run on a background threadfunc loadContacts() async throws -> [CNContact] {    try await Task.detached {        var results: [CNContact] = []        try store.enumerateContacts(with: request) { contact, _ in            results.append(contact)        }        return results    }.value}

Review Checklist

References

Extended patterns (multi-select picker, vCard export, search optimization): references/contacts-patterns.md [blocked]
Contacts framework
CNContactStore
CNContactFetchRequest
CNSaveRequest
CNMutableContact
CNContactPickerViewController
CNContactPickerDelegate
Accessing the contact store
NSContactsUsageDescription
ContactAccessButton
contactAccessPicker(isPresented:completionHandler:)
Contact Keys

Source and attribution

Source:dpearson2699/swift-ios-skillsinskills/contacts-frameworkat commit8d90fd1

License: No license

Content belongs to its original authors. SourceWeft indexes it from a public repository.

Report or request removal

More from dpearson2699/swift-ios-skills

Widgetkit

dpearson2699

Guides implementing, reviewing, and improving WidgetKit widgets and controls for iOS, iPadOS, watchOS, and CarPlay.

Software Development1.1Kupdated 2 months ago

Weatherkit

dpearson2699

Guides iOS developers in fetching WeatherKit forecasts, alerts, and attribution using WeatherService.

Software Development1.1Kupdated 2 months ago

Vision Framework

dpearson2699

Implement computer vision features including text recognition (OCR), face detection, barcode scanning, image segmentation, object tracking, and document scanning in iOS apps. Covers both the modern Swift-native Vision API (iOS 18+) and legacy VNRequest patterns, VisionKit DataScannerViewController for live camera scanning, and CoreMLRequest/VNCoreMLRequest for custom model inference. Use when adding OCR, barcode scanning, face detection, or custom Core ML model inference with Vision.

Awaiting classification1.1Kupdated 2 months ago

Tipkit

dpearson2699

Implement and review Apple TipKit feature-discovery UI for iOS 17+ apps. Use when adding or auditing in-app tips, contextual help, coach marks, Tip, TipView, popoverTip, rules, events, actions, display frequency, testing overrides, reusable tip identifiers, or iOS 18+ TipGroup and CloudKit tip sync; avoid for generic SwiftUI navigation or layout outside tip presentation.

Awaiting classification1.1Kupdated 2 months ago

Tabletopkit

dpearson2699

Guides building multiplayer spatial board games on visionOS with Apple's TabletopKit and RealityKit.

Software Development1.1Kupdated 2 months ago

Swiftui Webkit

dpearson2699

Guides embedding and controlling web content in SwiftUI apps with WebKit for SwiftUI on iOS 26 and later.

Software Development1.1Kupdated 2 months ago

Contacts Framework

Contacts Framework

Contents

Setup

Project Configuration

Imports

Authorization

Authorization States

Fetching Contacts

Fetch by Name

Fetch by Identifier

Enumerate All Contacts

Key Descriptors

Common Keys

Composite Key Descriptors

Creating and Updating Contacts

Creating a New Contact

Updating an Existing Contact

Deleting a Contact

Save Result and Recovery

Contact Picker

SwiftUI Wrapper

Using the Picker

Filtering the Picker

Observing Changes

Common Mistakes

DON'T: Fetch all keys when you only need a name

DON'T: Access unfetched properties

DON'T: Mutate a CNContact directly

DON'T: Skip authorization and assume access

DON'T: Run heavy fetches on the main thread

Review Checklist

References

Source and attribution

More from dpearson2699/swift-ios-skills

Widgetkit

Weatherkit

Vision Framework

Tipkit

Tabletopkit

Swiftui Webkit

More in Software Development

Playground

M5 Onboard

Cardputer Buddy

Web Design Guidelines

Vercel React Native Skills

Vercel React Best Practices