# Apple Data Connectors: Live Access, Sandbox Testing, and Native API Map

Canonical: https://figment.so/apple-data-connectors

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](/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](/oauth-for-icloud).

## Get started

[**Connect Apple Account**](/apple-connect/developers) 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.