Connect Find My Devices to an Assistant
Apple does not publish a public Find My API. Figment's Apple Connect reads the Find My state already synced to a connected Mac through iCloud. There is no currently published Figment Find My scope. This page explains what Find My contains, how freshness works for each device type, and how to design an assistant that handles location staleness correctly.
What Find My shows
Apple organizes Find My data into three categories.
Devices lists the Apple hardware registered to the account: iPhone, iPad, Mac, Apple Watch, AirPods, and compatible accessories. Each device carries its last known location, its online or offline state, and whether Lost Mode is active. A device that has gone offline shows the last position Apple recorded before connectivity was lost.
Items lists AirTag-equipped belongings and certified Find My network accessories. Each item shows its last seen location and the timestamp of that detection—which may be minutes or days old depending on how recently an Apple device passed within Bluetooth range.
People shows contacts actively sharing their location with this Apple account. Availability depends entirely on the contact's sharing setting and their device state. Find My can surface only contacts who have already shared with this account; it cannot query anyone else.
Figment reads data already synced to the connected Mac. It is not a direct subscription to the Find My network, and it cannot force a device update or reveal the precise location of a device that is currently offline.
Owned-device operations and location freshness worksheet
This worksheet maps each device or item type to its realistic operations and what "current location" actually means. Use it to decide how often to poll, how to communicate uncertainty to users, and which operations to surface in your assistant.
| Device / item type | Locate | Play sound | Lost Mode | Location update mechanism | Freshness confidence |
|---|---|---|---|---|---|
| iPhone / iPad | ✓ | ✓ | ✓ | Device when online; crowdsourced Bluetooth when offline | High if online; stale once offline |
| Mac | ✓ | ✓ | ✓ | Device when online | Stale once lid is closed off-network |
| Apple Watch | ✓ | ✓ | ✓ | Paired iPhone or independent cellular | Depends on pairing and cellular plan |
| AirPods | ✓ | ✓ | ✓† | Find My network relay when out of owner's range; direct when nearby | Often minutes to hours old |
| AirTag / Find My accessory | ✓ | ✓ | ✓‡ | Anonymous Bluetooth from any nearby Apple device | Ranges from seconds to days |
| Shared item (loaned AirTag) | ✓ | — | — | Same as AirTag | Same as AirTag |
| People (shared location) | ✓ | — | — | Contact's device; subject to their sharing toggle | Variable; outside your control |
† AirPods Lost Mode is available on AirPods (3rd generation or later), AirPods Pro (all generations), and AirPods Max. AirPods (1st and 2nd generation) do not support Lost Mode. AirPods 4 (ANC), AirPods 5 with Wireless Charging Case, and AirPods Pro (2nd generation or later) also support marking each earbud and the case separately as lost (Apple Support).
‡ AirTag Lost Mode notifies the owner the next time the tag is detected and displays contact information when anyone taps the tag with an NFC-capable device. It does not lock the tag or the item it is attached to (Apple Support).
Always include the last-seen timestamp in every location result your assistant presents. A location without a freshness window misleads the user.
Integration design
Figment Apple Connect uses PKCE-based OAuth to give your app scoped, user-approved access to Apple account data. The connection setup—Apple Account sign-in, iCloud sync, and Mac permissions—happens separately on the hosted Mac. Your app receives a Figment access token and a connection_id; it never receives the Apple password.
A Find My scope is not yet published as a public product. When one is available, the developer flow will follow the same model: register your app at figment.so/apple-connect/developers, direct the user through Figment's hosted consent screen, and exchange the returned authorization code for an access token. The full OAuth and PKCE reference is at OAuth for iCloud: Connect Apple Data to Your App.
Before reading Find My data, your app will need to confirm the connection is in a ready state. The connection status endpoint (GET https://figment.so/api/apple-connect/v1/connections/{connection_id}) returns a connection.services object with per-service state, reason, and observedAt (epoch milliseconds). Non-ready services reject read requests. The states connecting, syncing, needs_approval, offline, reconnect_required, and revoked each require a different response—from waiting and retrying, to prompting the user to return to figment.so/apple-connect/account to reconnect. A ready state does not guarantee that iCloud history is complete.
Practical assistant patterns
Travel bag check. A user asks "is my luggage still at the terminal?" The assistant reads the AirTag's last-seen location and timestamp, compares it to the airport coordinates, and responds: "Last detected at Terminal 2 baggage claim, 8 minutes ago." It never says "currently at" because an AirTag location is a Bluetooth-crowd snapshot, not a live fix. If the timestamp is older than two hours, the assistant flags the gap and suggests opening Find My for a manual refresh.
Device security check. A user suspects they left a MacBook in a conference room. The assistant checks the Mac's last known location against the user's registered addresses. The Mac shows offline with a last position inside the building. The assistant reports when the laptop was last seen at that location before going dark, then offers to initiate Lost Mode so the device locks the moment it reconnects. It does not guess whether the device has moved since going offline.
Shared-item morning routine. A parent shared an AirTag-tagged key set with the family account. Each morning an automation checks whether the keys are at the home address. Because AirTag freshness depends on nearby Apple device density, the assistant qualifies its result: "Keys last seen at home address, 4 minutes ago." If the timestamp is from overnight, it notes the confidence gap rather than asserting the keys are home.
Each pattern uses the same rule: qualify every location result with its freshness before presenting it as "current."
What this integration does not cover
- Not arbitrary person tracking. People shows only contacts who have explicitly shared their location with this Apple account.
- Not a live GPS stream. Locations update when devices contact Apple's servers or pass near another Apple device. Build your polling strategy around inherent staleness, not millisecond freshness.
- Not a guaranteed public API. Apple does not publish a documented Find My API. Figment reads native iCloud data on the connected Mac; availability is subject to Apple platform changes and actual native support.
- Not access to devices outside the account. Only devices and items owned by or explicitly shared with this Apple account are visible.
For workflows that center on shared contacts rather than owned devices, see Use Shared Find My Locations in Approved Workflows. For automating smart home devices through the same connection, see Give an Agent Permission to Run Home Scenes and Review Home Camera Events with an Assistant.
The iMessage REST API is available today through Figment Apple Connect. Connect Apple Account to start building with the available scopes, or review the developer documentation for the full scope list and pricing.
