Apple Data Connectors: Live Access, Sandbox Testing, and Native API Map
There is no general developer API for Apple Notes, Photos, iCloud Drive, or Safari. What Apple does provide is a set of native frameworks—PhotoKit, EventKit, the Contacts framework—that run with explicit user permission on a signed-in Mac. Figment's hosted Mac infrastructure builds on that model: an isolated Mac holds an approved connection, and your app receives a scoped access token through Figment's consent flow. Your app never handles the Apple password.
This page maps what is available today as a Figment customer, what is available in the free synthetic sandbox, and what Apple's own frameworks require for each service.
What's available today
iMessage is the live production connector. Authorized apps can list conversations, read and search message history, and send to pre-approved conversations. Reads and searches share the messages:read scope; sending requires the separate messages:send scope and is limited to existing conversations the user has explicitly included in the send grant. The developer pays $29/month per active live connection; sandbox is free.
Contacts, Calendar, and Reminders are available as a synthetic read-only sandbox. The sandbox endpoints return invented data with realistic field shapes—no real contacts or calendar entries are accessed—so you can build and validate your data model before live access is offered. The available scopes are contacts:read, calendar:read, and reminders:read.
Notes, Photos, iCloud Drive, Safari, and Voice Memos have no current public Figment customer endpoint. The connector matrix below shows the native Apple framework each service uses, its sync prerequisites, and the access boundary that any helper would need to respect.
Connector matrix
| Service | Figment status | Scopes | Apple framework | Prerequisites & access boundary |
|---|---|---|---|---|
| iMessage | Live | messages:read · messages:send | Messages (Mac-local DB) | iCloud Messages sync on; iPhone online for new carrier messages |
| Contacts | Synthetic sandbox | contacts:read | Contacts (CNContact) | iCloud Contacts sync; synced contacts only |
| Calendar | Synthetic sandbox | calendar:read | EventKit (EKEvent) | iCloud Calendar sync; shared calendars included |
| Reminders | Synthetic sandbox | reminders:read | EventKit (EKReminder) | iCloud Reminders sync; synced lists only |
| Notes | No endpoint | — | Local SQLite / file | iCloud Notes sync on; locked notes require a separate unlock step |
| Photos | No endpoint | — | PhotoKit (PHAsset) | iCloud Photos sync; explicit Photos authorization required; cloud-only assets fetched on demand |
| iCloud Drive | No endpoint | — | FileManager + NSFileCoordinator | Sync this Mac enabled; Desktop & Documents folder is optional and off by default |
| Safari | No endpoint | — | History DB / Safari API | iCloud Safari sync; excludes cookies and login sessions |
| Voice Memos | No endpoint | — | AVFoundation + local store | iCloud Voice Memos sync; not live microphone access |
Sandbox: Contacts, Calendar, and Reminders
The three sandbox endpoints return invented data with the same response envelope as a live response. Use them to build and test your data model before live access is available.
GET /api/apple-connect/v1/connections/{id}/contacts
GET /api/apple-connect/v1/connections/{id}/calendar?start=ISO&end=ISO
GET /api/apple-connect/v1/connections/{id}/reminders?completed=false
Each response follows {data:[...], mode:"sandbox", hasMore, nextOffset, scope:"synthetic sandbox data"}. Optional limit (1–100, default 20) and offset (0–10000) apply to all three. The calendar endpoint requires both start and end when either is supplied; end must follow start and the range must not exceed 366 days. The reminders endpoint accepts completed=true or completed=false; it defaults to false.
Each data item contains these fields:
| Service | Fields |
|---|---|
| Contacts | id, name, organization, emails (array of strings), phones (array of strings) |
| Calendar | id, calendarId, title, start (ISO), end (ISO), allDay, location |
| Reminders | id, calendarId, title, completed, priority, due (ISO, optional) |
All returned data is invented. These endpoints do not access any real Apple library.
Apple native APIs: framework requirements
For services without a current Figment endpoint, the Apple-framework requirements reveal what any Mac-based helper—your own design or a future Figment connector—would need to handle.
Notes stores its content in a local SQLite-backed library protected by the macOS sandbox. Any process reading Notes needs iCloud Notes sync enabled, appropriate sandbox permissions, and must treat locked notes as a distinct case requiring a separate passphrase or biometric step before access is possible.
Photos uses PhotoKit, Apple's official framework for the shared photo library on Mac. PHAsset objects carry photo, video, and Live Photo metadata. Cloud-only assets must be explicitly requested and downloaded before use. Explicit Photos authorization from the user is required—iCloud sign-in alone is not sufficient. A large library on a freshly connected Mac may take time to populate completely.
iCloud Drive files are accessible through the standard macOS filesystem once sync is active. Desktop and Documents folders only appear in iCloud Drive when the user has explicitly enabled that option in iCloud settings; that option is not on by default. A helper scoped to iCloud Drive cannot reach a device's internal phone storage.
Safari iCloud sync carries browsing history, bookmarks, Reading List items, open tabs, and Tab Groups. It does not include website cookies, iCloud Keychain passwords, or active login sessions.
Connection setup and service state
Connecting an Apple Account involves several distinct gates: account sign-in, trusted-device approval, iCloud sync for each service, Mac system permissions, and app-level consent. A connection reports per-service states—connecting, needs_approval, syncing, ready, offline, reconnect_required, revoked—and each service moves through its own states independently. A connector reaching ready on one service does not make others ready, and reaching ready does not guarantee complete history or confirmed delivery.
Revoking one app's grant stops only that app's access. Disconnecting the Apple Account stops every grant and all queued operations on that connection. Manage active grants at /apple-connect/account.
For the full consent model and what "OAuth for iCloud" means in practice, see OAuth for iCloud: Connect Apple Data to Your App.
Get started
Connect Apple Account opens the hosted setup screen. iMessage production access costs $29/month per active live connection; access starts after setup. Sandbox testing is free—the Contacts, Calendar, and Reminders endpoints are available on sandbox connections that have those services selected and the relevant read scope in your app grant.
