Automating Contacts

Automating Contacts (JXA-first, AppleScript discovery)

Relationship to Other Skills

• Standalone for Contacts: Use this skill for Contacts-specific operations (querying, CRUD, groups).
• Reuse `automating-mac-apps` for: TCC permissions setup, shell command helpers, UI scripting fallbacks, and ObjC bridge patterns.
• Integration: Load both skills when combining Contacts automation with broader macOS scripting.
• PyXA Installation: To use PyXA examples in this skill, see the installation instructions in automating-mac-apps skill (PyXA Installation section).

Core Framing

• Contacts dictionary is AppleScript-first; discover there, implement in JXA
• Object specifiers: read with methods (name(), emails()), write with assignments
• Multi-value fields (emails, phones, addresses) are elements; use constructor + .push()
• Group membership: add ... to command or .people.push; handle duplicates defensively
• TCC permissions required: running host must have Contacts access

Workflow (default)

1) Inspect the Contacts dictionary in Script Editor (JavaScript view). 2) Prototype minimal AppleScript to validate verbs; port to JXA with specifier reads/writes. 3) Use .whose for coarse filtering; fall back to hybrid (coarse filter + JS refine) when needed. 4) Create records with proxy + make, then assign primitives and push multi-values; Contacts.save() to persist. 5) Verify persistence: check person.id() exists after save; handle TCC permission errors. 6) Manage groups after person creation; guard against duplicate membership with existence checks. 7) For photos or broken bridges, use ObjC/clipboard fallback; for heavy queries, batch read or pre-filter. 8) Test operations: run→check results→fix errors in iterative loop.

Validation Checklist

• [ ] Contacts permissions granted (System Settings > Privacy & Security > Contacts)
• [ ] Dictionary inspected and verbs validated in Script Editor
• [ ] AppleScript prototype runs without errors
• [ ] JXA port handles specifiers correctly
• [ ] Multi-value fields pushed to arrays properly
• [ ] Groups existence checked before creation
• [ ] Operations saved and verified with .id() checks
• [ ] Error handling wraps all operations

Quickstart (upsert + group)

const Contacts = Application("Contacts");
const email = "ada@example.com";
try {
  const existing = Contacts.people.whose({ emails: { value: { _equals: email } } })();
  const person = existing.length ? existing[0] : Contacts.Person().make();
  person.firstName = "Ada";
  person.lastName = "Lovelace";
  
  // Handle multi-value email
  const work = Contacts.Email({ label: "Work", value: email });
  person.emails.push(work);
  Contacts.save();
  
  // Handle groups with error checking
  let grp;
  try { 
    grp = Contacts.groups.byName("VIP"); 
    grp.name(); // Verify exists
  } catch (e) {
    grp = Contacts.Group().make(); 
    grp.name = "VIP";
  }
  Contacts.add(person, { to: grp });
  Contacts.save();
  console.log("Contact upserted successfully");
} catch (error) {
  console.error("Contacts operation failed:", error);
}

Pitfalls

• TCC Permissions: Photos/attachments require TCC + Accessibility; use clipboard fallback if blocked
• Yearless birthdays: Not cleanly scriptable; use full dates
• Advanced triggers: Delegate geofencing to Shortcuts app
• Heavy queries: Batch read or pre-filter to avoid timeouts

When Not to Use

• Non-macOS platforms (use platform-specific APIs)
• Simple AppleScript-only solutions (skip JXA complexity)
• iCloud sync operations (use native Contacts framework)
• User-facing apps (use native Contacts framework)
• Cross-platform contact management (use CardDAV or vCard APIs)

What to load

• JXA basics & specifiers: automating-contacts/references/contacts-basics.md
• Recipes (query, create, multi-values, groups): automating-contacts/references/contacts-recipes.md
• Advanced (hybrid filters, clipboard image, TCC, date pitfalls): automating-contacts/references/contacts-advanced.md
• Dictionary & type map: automating-contacts/references/contacts-dictionary.md
• PyXA API Reference (complete class/method docs): automating-contacts/references/contacts-pyxa-api-reference.md

Contacts JXA Advanced Patterns

Performance & hybrid filtering

• .whose is best for coarse filters; complex OR/NOT can throw -1700.
• Pattern: coarse .whose → resolve → JS .filter for regex/complex logic.
• Batch-read when possible: .name(), .emails.value() on a filtered specifier.

TCC / permissions

• The executing host (Terminal/Script Editor/app bundle) must be granted Contacts access.
• For headless/CI, pre-approve via MDM profile; cannot auto-click the prompt.

Multi-value write discipline

• Treat emails/phones/addresses/dates as elements; create objects and .push.
• Use Contacts.save() after meaningful mutations (or after a batch).

Images via clipboard (ObjC bridge)

Direct person.image = Path("...") often fails. Use NSPasteboard to bridge the file:

ObjC.import('AppKit');
const pb = $.NSPasteboard.generalPasteboard;
pb.clearContents;
pb.writeObjects($.NSArray.arrayWithObject("/path/to/photo.jpg"));

// Now try setting or use UI scripting to paste
const person = Contacts.people.byName("Ada Lovelace");
// Depending on OS version you may still need a UI paste; clipboard is the safest staging.

Yearless birthdays & date pitfalls

• JXA coerces dates; yearless birthdays become full dates (current year/1604). No clean way to set "yearless" via JXA—accept year or manipulate vCard externally.
• Set custom dates at noon (T12:00:00) to avoid timezone rollovers.

Group membership errors

• Duplicate adds can throw; guard with an existence check (group.people.whose({ id: {_equals: person.id()} })).
• Prefer Contacts.add(person, { to: group }) for clarity; .people.push is sugar.

When the dictionary is insufficient

• ObjC Contacts.framework is Swift-heavy and awkward to bridge; fallback is usually:
• Deprecated AddressBook bridge (if still present), or
• A small external Swift/Python helper invoked via doShellScript for rare edge cases.

Contacts JXA Basics (specifiers, reads, writes)

Initialize

const app = Application.currentApplication();
app.includeStandardAdditions = true;
const Contacts = Application('Contacts');
if (!Contacts.running()) Contacts.activate();

Specifier vs data

• Contacts.people → specifier (zero IPC).
• Contacts.people() → fetches every person (high cost).
• Contacts.people.name() → one IPC returning array of names.
• Always call methods to read: person.firstName() not person.firstName.

Read collections efficiently

• Prefer server-side filter: Contacts.people.whose({ emails: { value: { _contains: 'acme.com' }}}).
• Access properties on the filtered specifier: .name() or .emails.value() to batch read.
• If .whose is too complex, coarse-filter server-side then refine in JS.

Create & save

• Create root object with proxy + make:

const p = Contacts.Person().make();
p.firstName = "Ada";
p.lastName = "Lovelace";
Contacts.save();

• Multi-value fields are elements; create and push:

const workEmail = Contacts.Email({ label: "Work", value: "ada@engine.co.uk" });
p.emails.push(workEmail);
Contacts.save();

Groups

• Groups are containers; membership is many-to-many.
• Robust add: Contacts.add(person, { to: group });
• Alternative sugar: group.people.push(person); (watch for duplicates).

Common operators for .whose

• _equals, _contains, _beginsWith, _endsWith, _greaterThan, _lessThan, _not.
• Nested collections: { emails: { value: { _endsWith: 'university.edu' }}}.

Contacts Dictionary & Type Map (JXA view)

Core classes (specifiers)

• Application('Contacts')
• people (element): Person objects
• groups (element): Group objects
• Person properties: firstName, lastName, middleName, name, organization, jobTitle, note, birthday, id
• Person elements (multi-value):
• emails → Email { label, value }
• phones → Phone { label, value }
• addresses → Address { label, street, city, state, zip, country, countryCode }
• dates → CustomDate { label, value (Date) }
• socialProfiles → SocialProfile { service, userName, url }
• instantMessages → InstantMessage { service, userName, handle }
• Group properties: name, id
• Group elements: people (members)

Commands

• make / .make(): create Person or Group.
• add <person> to <group> → JXA: Contacts.add(person, { to: group }) (preferred) or group.people.push(person).
• save → Contacts.save() to persist mutations.

Access patterns

• By name: Contacts.people.byName("Ada Lovelace")
• By ID (stable): Contacts.people.byId("<UUID>") (preferred for long-lived refs)
• Batch read: Contacts.people.whose({ organization: {_contains: "Acme"} }).name()

Operator map for .whose

• _equals, _contains, _beginsWith, _endsWith, _greaterThan, _lessThan, _not
• Nested multi-value: { emails: { value: { _endsWith: "edu" }}}

Localization & labels

• Standard labels ("Home", "Work", "Mobile") are accepted as plain strings; Contacts maps to localized internal constants.
• Custom labels are created automatically when you pass a new string (e.g., "Secure Line").

PyXA Contacts Module API Reference

New in PyXA version 0.0.2 - Control macOS Contacts using JXA-like syntax from Python.

This reference documents all classes, methods, properties, and enums in the PyXA Contacts module. For practical examples and usage patterns, see contacts-recipes.md.

Contents

• Class Hierarchy
• XAContactsApplication
• XAContactsPerson
• XAContactsGroup
• XAContactsEntry
• Contact Information Classes
• XAContactsAddress
• XAContactsEmail
• XAContactsPhone
• XAContactsURL
• XAContactsInstantMessage
• XAContactsSocialProfile
• XAContactsCustomDate
• XAContactsRelatedName
• XAContactsDocument
• List Classes
• Enumerations
• Quick Reference Tables

---

Class Hierarchy

XAObject
├── XAContactsApplication (XASBApplication)
│   ├── XAContactsEntry
│   │   ├── XAContactsPerson
│   │   └── XAContactsGroup
│   ├── XAContactsContactInfo
│   │   ├── XAContactsEmail
│   │   ├── XAContactsPhone
│   │   ├── XAContactsURL
│   │   ├── XAContactsCustomDate
│   │   └── XAContactsRelatedName
│   ├── XAContactsAddress
│   ├── XAContactsInstantMessage
│   ├── XAContactsSocialProfile
│   └── XAContactsDocument

---

XAContactsApplication

Bases: XASBApplication

Main entry point for interacting with Contacts.app.

Properties

Methods

people(filter=None) -> XAContactsPersonList

Returns a list of contacts matching the filter.

Parameters:

• filter (dict | None) - Property-value pairs to filter by

Example:

import PyXA
contacts = PyXA.Application("Contacts")
all_people = contacts.people()
for person in all_people:
    print(person.first_name, person.last_name)

groups(filter=None) -> XAContactsGroupList

Returns a list of groups matching the filter.

Parameters:

• filter (dict | None) - Property-value pairs to filter by

Example:

groups = contacts.groups()
print(groups.name())
# ['Family', 'Work', 'Friends', ...]

documents(filter=None) -> XAContactsDocumentList

Returns a list of address book documents matching the filter.

Parameters:

• filter (dict | None) - Property-value pairs to filter by

make(specifier, properties=None, data=None) -> XAObject

Creates a new element without adding to any list. Use XAList.push() to add.

Parameters:

• specifier (str | ObjectType) - Class name to create (e.g., "person", "group")
• properties (dict) - Properties for the object
• data (Any) - Initialization data

Example:

# Create a new person
new_person = contacts.make("person", {
    "firstName": "Ada",
    "lastName": "Lovelace"
})
contacts.people().push(new_person)
contacts.save()

open(file_path)

Opens and imports contacts from a file (vCard, etc.).

Parameters:

• file_path (str | XAPath) - Path to the contact file

Example:

contacts.open("/path/to/contacts.vcf")

save()

Persists all changes to the address book.

Example:

person = contacts.people()[0]
person.first_name = "Updated"
contacts.save()

---

XAContactsPerson

Bases: XAContactsEntry

Represents an individual contact record in the address book.

Properties

Name Properties

Phonetic Properties

Organization Properties

Other Properties

Methods

addresses(filter=None) -> XAContactsAddressList

Returns physical addresses for this contact.

Example:

person = contacts.people()[0]
for addr in person.addresses():
    print(f"{addr.street}, {addr.city}, {addr.state} {addr.zip}")

emails(filter=None) -> XAContactsEmailList

Returns email addresses for this contact.

Example:

emails = person.emails()
print(emails.value())
# ['john@example.com', 'john.doe@work.com']

phones(filter=None) -> XAContactsPhoneList

Returns phone numbers for this contact.

Example:

phones = person.phones()
for phone in phones:
    print(f"{phone.label}: {phone.value}")

urls(filter=None) -> XAContactsURLList

Returns URLs associated with this contact.

instant_messages(filter=None) -> XAContactsInstantMessageList

Returns instant messaging accounts for this contact.

social_profiles(filter=None) -> XAContactsSocialProfileList

Returns social media profiles for this contact.

custom_dates(filter=None) -> XAContactsCustomDateList

Returns custom date fields for this contact.

related_names(filter=None) -> XAContactsRelatedNameList

Returns related names (spouse, assistant, etc.) for this contact.

groups(filter=None) -> XAContactsGroupList

Returns groups this contact belongs to.

Example:

person_groups = person.groups()
print(person_groups.name())
# ['Family', 'VIP']

show() -> XAContactsPerson

Opens Contacts.app and displays this contact.

Example:

person.show()  # Opens contact card in Contacts.app

---

XAContactsGroup

Bases: XAContactsEntry

Represents a contact group in the address book.

Properties

Methods

people(filter=None) -> XAContactsPersonList

Returns contacts that belong to this group.

Example:

family = contacts.groups().by_name("Family")
members = family.people()
print(members.first_name())
# ['John', 'Jane', 'Bob']

groups(filter=None) -> XAContactsGroupList

Returns subgroups within this group.

---

XAContactsEntry

Bases: XAObject

Base class for all contact entries (persons and groups).

Properties

Methods

add_to(parent) -> XAContactsPerson

Adds this entry to a group.

Parameters:

• parent (XAContactsGroup) - The group to add to

Example:

person = contacts.people()[0]
vip_group = contacts.groups().by_name("VIP")
person.add_to(vip_group)
contacts.save()

remove_from(elem) -> XAContactsPerson

Removes this entry from a group.

Parameters:

• elem (XAContactsGroup) - The group to remove from

delete()

Permanently deletes this entry from the address book.

Example:

person = contacts.people().by_first_name("Test")
person.delete()
contacts.save()

---

Contact Information Classes

XAContactsContactInfo

Bases: XAObject

Base class for contact information items (email, phone, URL, etc.).

Properties

---

XAContactsAddress

Bases: XAObject

Represents a physical/mailing address.

Properties

Example:

person = contacts.people()[0]
home_addr = person.addresses().by_label("Home")
print(home_addr.formatted_address)
# "123 Main St\nSan Francisco, CA 94102\nUnited States"

---

XAContactsEmail

Bases: XAContactsContactInfo

Represents an email address entry.

Properties

Example:

# Get work email
work_email = person.emails().by_label("Work")
print(work_email.value)
# "john.doe@company.com"

---

XAContactsPhone

Bases: XAContactsContactInfo

Represents a phone number entry.

Properties

Example:

# Get mobile phone
mobile = person.phones().by_label("Mobile")
print(mobile.value)
# "+1 (555) 123-4567"

---

XAContactsURL

Bases: XAContactsContactInfo

Represents a URL entry (website, social profile, etc.).

Properties

---

XAContactsInstantMessage

Bases: XAObject

Represents an instant messaging account.

Properties

Example:

im_accounts = person.instant_messages()
for im in im_accounts:
    print(f"{im.service_name}: {im.user_name}")

---

XAContactsSocialProfile

Bases: XAObject

Represents a social media profile.

Properties

Example:

profiles = person.social_profiles()
for profile in profiles:
    print(f"{profile.service_name}: @{profile.user_name}")

---

XAContactsCustomDate

Bases: XAContactsContactInfo

Represents a custom date field (anniversary, etc.).

Properties

---

XAContactsRelatedName

Bases: XAContactsContactInfo

Represents a related person (spouse, assistant, etc.).

Properties

---

XAContactsDocument

Bases: XAObject

Represents an address book document.

Properties

---

List Classes

PyXA provides list wrapper classes with fast enumeration and bulk property access.

XAContactsPersonList

Bulk methods for person lists:

people = contacts.people()
people.first_name()       # -> list[str]
people.last_name()        # -> list[str]
people.company()          # -> list[str]
people.department()       # -> list[str]
people.job_title()        # -> list[str]
people.birth_date()       # -> list[datetime]
people.note()             # -> list[str]
people.home_page()        # -> list[str]
people.image()            # -> list[XAImage]
people.vcard()            # -> list[str]

Filter methods:

people.by_first_name("John")
people.by_last_name("Doe")
people.by_company("Acme Corp")
people.by_department("Engineering")
people.by_job_title("Developer")
people.by_birth_date(date)
people.by_nickname("Johnny")

XAContactsGroupList

Bulk methods for group lists:

groups = contacts.groups()
groups.name()             # -> list[str]
groups.id()               # -> list[str]
groups.creation_date()    # -> list[datetime]
groups.modification_date()  # -> list[datetime]

Filter methods:

groups.by_name("Family")
groups.by_id("group-uuid")

XAContactsAddressList

Bulk methods for address lists:

addresses = person.addresses()
addresses.street()        # -> list[str]
addresses.city()          # -> list[str]
addresses.state()         # -> list[str]
addresses.zip()           # -> list[str]
addresses.country()       # -> list[str]
addresses.country_code()  # -> list[str]
addresses.formatted_address()  # -> list[str]
addresses.label()         # -> list[str]

Filter methods:

addresses.by_label("Home")
addresses.by_city("San Francisco")
addresses.by_state("CA")
addresses.by_zip("94102")
addresses.by_country("United States")
addresses.by_country_code("US")

XAContactsEmailList

emails = person.emails()
emails.label()            # -> list[str]
emails.value()            # -> list[str]
emails.by_label("Work")
emails.by_value("john@example.com")

XAContactsPhoneList

phones = person.phones()
phones.label()            # -> list[str]
phones.value()            # -> list[str]
phones.by_label("Mobile")
phones.by_value("+1555123456")

XAContactsURLList

urls = person.urls()
urls.label()              # -> list[str]
urls.value()              # -> list[str]
urls.by_label("Home Page")
urls.by_value("https://example.com")

XAContactsInstantMessageList

ims = person.instant_messages()
ims.service_type()        # -> list[ServiceType]
ims.service_name()        # -> list[str]
ims.user_name()           # -> list[str]
ims.by_service_type(ServiceType.JABBER)
ims.by_user_name("johndoe")

XAContactsSocialProfileList

profiles = person.social_profiles()
profiles.service_name()   # -> list[str]
profiles.user_name()      # -> list[str]
profiles.user_identifier()  # -> list[str]
profiles.url()            # -> list[str]
profiles.by_service_name("Twitter")
profiles.by_user_name("johndoe")
profiles.by_url("https://twitter.com/johndoe")

XAContactsCustomDateList

dates = person.custom_dates()
dates.label()             # -> list[str]
dates.value()             # -> list[datetime]
dates.by_label("Anniversary")

XAContactsRelatedNameList

related = person.related_names()
related.label()           # -> list[str]
related.value()           # -> list[str]
related.by_label("Spouse")
related.by_value("Jane Doe")

XAContactsDocumentList

docs = contacts.documents()
docs.name()               # -> list[str]
docs.file()               # -> list[str]
docs.modified()           # -> list[bool]
docs.by_name("Address Book")
docs.by_modified(True)

---

Enumerations

Format

Archive format options.

ObjectType

Creatable object types for make().

ServiceType

Instant messaging service types.

---

Quick Reference Tables

Common Operations

Contact Multi-Value Fields

Property Access Patterns

# Single object
person = contacts.people()[0]
print(person.first_name)
print(person.company)

# Bulk access on lists
people = contacts.people()
print(people.first_name())    # Returns list[str]
print(people.company())       # Returns list[str]

# Filtering
work_contacts = people.by_company("Acme Corp")
engineers = people.by_department("Engineering")

# Chained filtering (get first work email)
work_email = person.emails().by_label("Work")[0].value

Creating Contacts with Multi-Value Fields

import PyXA

contacts = PyXA.Application("Contacts")

# Create person
person = contacts.make("person", {
    "firstName": "Ada",
    "lastName": "Lovelace",
    "company": "Analytical Engine Inc.",
    "jobTitle": "Chief Mathematician"
})
contacts.people().push(person)

# Add email
email = contacts.make("email", {
    "label": "Work",
    "value": "ada@analyticalengine.com"
})
person.emails().push(email)

# Add phone
phone = contacts.make("phone", {
    "label": "Mobile",
    "value": "+1 (555) 123-4567"
})
person.phones().push(phone)

# Add address
address = contacts.make("address", {
    "label": "Work",
    "street": "123 Innovation Way",
    "city": "London",
    "country": "United Kingdom"
})
person.addresses().push(address)

# Save all changes
contacts.save()

---

See Also

• PyXA Contacts Documentation - Official PyXA documentation
• contacts-basics.md - JXA fundamentals for Contacts
• contacts-recipes.md - Common automation patterns
• contacts-advanced.md - Advanced techniques and troubleshooting
• contacts-dictionary.md - AppleScript dictionary reference

Contacts JXA Recipes

Query contacts by email domain (coarse filter + refine)

const matches = Contacts.people.whose({
  emails: { value: { _endsWith: "acme.com" } }
})();
// refine in JS if needed
const tagged = matches.filter(p => (p.note() || "").includes("VIP"));

Create a person with multi-value fields

const p = Contacts.Person().make();
p.firstName = "Grace";
p.lastName = "Hopper";
p.organization = "US Navy";

p.emails.push(Contacts.Email({ label: "Work", value: "grace@navy.mil" }));
p.phones.push(Contacts.Phone({ label: "Mobile", value: "+1-555-123-4567" }));
p.addresses.push(Contacts.Address({
  label: "Office",
  street: "1 Programming Way",
  city: "Arlington",
  state: "VA",
  zip: "22202",
  country: "USA",
  countryCode: "us"
}));

// Dates: set to noon to avoid TZ shifts
p.dates.push(Contacts.CustomDate({ label: "Anniversary", value: new Date("2015-08-14T12:00:00") }));
Contacts.save();

Add to group (defensive)

function ensureGroup(name) {
  const g = Contacts.groups.whose({ name: { _equals: name } })();
  if (g.length) return g[0];
  const created = Contacts.Group().make();
  created.name = name;
  Contacts.save();
  return created;
}

const group = ensureGroup("System Architects");
const person = Contacts.people.byName("Grace Hopper");

// Avoid duplicate membership
const already = group.people.whose({ id: { _equals: person.id() } })().length > 0;
if (!already) {
  Contacts.add(person, { to: group }); // or group.people.push(person)
  Contacts.save();
}

Hybrid filter when .whose is fragile

const bayArea = Contacts.people.whose({
  addresses: { city: { _equals: "San Francisco" } }
})();

const projectAlpha = bayArea.filter(p => /Project Alpha/i.test(p.note() || ""));