Apple iCloud service

Updated

The API supports retrieval of a variety of data and files from Apple's iCloud services. This includes access to device iCloud backup data, Find My iPhone data, and a number of near-realtime CloudKit data sources.

Sessions

Setting up a session for the iCloud services on the API is as straightforward as a login into an iCloud account. The process can require multiple attempts at creating the session if the account has enabled multi-factor authentication, like 2FA or 2SV.

The first call to create a session looks as below.

curl https://ricloud-api.reincubate.com/sessions \
  -X POST \
  -H 'Authorization: Token <your key_token>' \
  -H 'Content-Type: application/json' \
  -d '{
  "source": {
    "user": "1",
    "type": "icloud.account",
    "identifier": "<iCloud account username>"
  },
  "payload": {
    "password": "<iCloud account password>"
  }
}'

For non-2FA/non-2SV enabled accounts, this will be sufficient to establish an active session provided the credentials supplied are valid.

However, an account with 2FA enabled will receive a code-required error response, and the 2FA process will be triggered on devices linked to the account which will send them a 2FA code. This code needs to be provided to the API in the next session creation call.

curl https://ricloud-api.reincubate.com/sessions \
  -X POST \
  -H 'Authorization: Token <your key_token>' \
  -H 'Content-Type: application/json' \
  -d '{
  "source": {
    "user": "1",
    "type": "icloud.account",
    "identifier": "<iCloud account username>"
  },
  "payload": {
    "password": "<iCloud account password>",
    "code": "<fresh 2FA code>"
  }
}'

Finally, an account with 2SV enabled will receive a choice-required error response, along with a list of possible devices linked to the account that can be triggered to complete the 2SV process.

curl https://ricloud-api.reincubate.com/sessions \
  -X POST \
  -H 'Authorization: Token <your key_token>' \
  -H 'Content-Type: application/json' \
  -d '{
  "source": {
    "user": "1",
    "type": "icloud.account",
    "identifier": "<iCloud account username>"
  },
  "payload": {
    "password": "<iCloud account password>",
    "choice": "<choice identifier from choices fields of `choice-required` error>"
  }
}'

This call will trigger a code to be sent to the chosen device, which can then be used as in the payload to complete the session initialisation process.

The parameters accepted by the session creation payload are summarised in the table below.

name type description
password string The iCloud account's password.
code optional, string If the iCloud account has multi-factor (like 2FA) enabled, this parameter will be required.
choice optional, string If the iCloud account has 2SV enabled, this parameter will be required during the session creation process.

Source types

identifier description
icloud.account primary source Corresponds to an iCloud account.
icloud.backup The iCloud backup of an iOS device.

Info types

This poll type retrieves information on the targeted source. The results are published in JSON format.

For example, an info poll targetted at an icloud.account source will return account details, the list of iCloud backups (icloud.backup child sources), and other meta information.

Payload attributes

name type description
info_types list of strings A list of the requested info type identifiers.

Using cURL

curl https://ricloud-api.reincubate.com/polls \
  -X POST \
  -H 'Authorization: Token <your key_token>' \
  -H 'Content-Type: application/json' \
  -d '{
    "session": "2504da05-d2e0-4913-ae17-daa65a933413",
  "payload": {
    "info_types": []
  }
}'

Using ricloud-py

import ricloud

# The ID of a session we made earlier.
session_id = '2504da05-d2e0-4913-ae17-daa65a933413'

poll_payload = {
    'info_types': []
}

poll = ricloud.Poll.create(
  session=session_id,
  payload=poll_payload,
)

Data types

Payload attributes

name type description
data_types list of strings A list of the requested data type identifiers.

Using cURL

curl https://ricloud-api.reincubate.com/polls \
  -X POST \
  -H 'Authorization: Token <your key_token>' \
  -H 'Content-Type: application/json' \
  -d '{
    "session": "2504da05-d2e0-4913-ae17-daa65a933413",
    "payload": {
        "data_types": ["icpl.photos"]
    }
}'

Using ricloud-py

import ricloud

# The ID of a session we made earlier.
session_id = '2504da05-d2e0-4913-ae17-daa65a933413'

poll_payload = {
    'data_types': ['icpl.photos']
}

poll = ricloud.Poll.create(
  session=session_id,
  payload=poll_payload,
)

iCloud data types

identifier description
icpl.photos Retrieves iCloud Photo Library files.
mme_contacts.contacts Retrieves iCloud stored iOS Contacts data.
mme_calendar.events Retrieves iCloud stored iOS Calendar data.
mme_notes.notes Retrieves iCloud stored iOS Notes data.
callkit.calls Retrieves CallKit synced iOS Phone data.
cloudkit_safari.browser_history Retrieve iCloud stored Safari browser history data.
fmip.locations Retrieve Find My iPhone locations data.

iCloud backup app data types

identifier description
ios_messages.messages Retrieves iOS Messages data including iMessage and SMS.
ios_contacts.contacts Retrieves iOS Contacts data.
ios_phone.calls Retrieves iOS Phone data.
ios_calendar.events Retrieves iOS Calendar data.
ios_notes.notes Retrieves iOS Notes data.
ios_health.data Retrieves iOS Health data.
ios_safari.browser_history Retrieves Safari browser history data.
ios_safari.cookies Retrieves Safari cookie data.
whatsapp.messages Retrieves WhatsApp messages.
whatsapp.calls Retrieves WhatsApp call history.
viber.messages Retrieves Viber messages.
viber.calls Retrieves Viber call history.
viber.conversations Retrieves Viber conversations.
viber.contacts Retrieves Viber contacts.
kik.messages Retrieves Kik messages.
kik.contacts Retrieves Kik contacts.
hike.messages Retrieves Hike messages.
hike.posts Retrieves Hike posts.
wechat.messages Retrieves WeChat messages.
tinder.messages Retrieves Tinder messages.
line.messages Retrieves Line messages.
facebook.messages Retrieves Facebook messages.
snapchat.messages Retrieves Snapchat messages.
snapchat.stories Retrieves Snapchat stories.
skype.messages Retrieves Skype messages.

iCloud backup aggregated data types

identifier description
.photos Scans an iCloud backup for image files.
.videos Scans an iCloud backup for video files.
.recordings Scans an iCloud backup for recording files.
.voicemails Scans an iCloud backup for voicemail files.
.app_usage Scans an iCloud backup for app usage information.
.installed_apps Scans an iCloud backup for installed app information.
.locations Scans an iCloud backup for locations.
.linked_watches Scans an iCloud backup for linked Apple Watch information.

iCloud Photo Library

Photos icpl.photos

Retrieves photos stored in the iCloud Photo Library service.

attribute description
Source icloud.account
Setting Settings > [username] > iCloud > Photos > iCloud Photo Library

CallKit

Calls from CallKit callkit.calls

Retrieves call logs synced with the CallKit service.

Errors

callkit-uninitialised

Indicates that the CallKit service has not been setup for this account. The iCloud account owner can resolve this error using an iOS device associated with the iCloud account via the following steps: - Make sure the device is connected to Wi-Fi. - Navigate to Settings > [username] > iCloud. - Turn off iCloud Drive, waiting for 30 to 60 seconds for the change to take effect. - Turn on iCloud Drive once the previous change has completed. This should trigger initialisation.

If the error persists after performing this process, please contact support.

callkit-sync-disabled

In this case, the CallKit service has been initialised but the conditions necessary for devices to start syncing call history to the iCloud have not been met. The API will remotely resolve this via the iCloud, but device associated with the iCloud account may not re-evaluate their sync state as this is cached.

The iCloud account owner can trigger a device to re-check call history sync conditions via the following steps: - Navigate to Settings > [username] > iCloud. - Turn off iCloud Drive, waiting for 30 to 60 seconds for the change to take effect. - Turn on iCloud Drive once the previous change has completed. This should trigger initialisation.

Troubleshooting

  • Recent call history is not getting returned in poll results.

This is typically caused by the device not having synced its latest call history records with the iCloud. The CallKit service is an internal iOS service and cannot be turned on or off in the settings or triggered to sync manually. This can make it difficult to debug missing data as it unclear what the device has or has not synced to the iCloud.

This issue is more common for accounts which do not have much data to sync (less than ~3 calls), which can often be the case for testing accounts.

Recommendations: - Make sure the device has more than a handful of call history records to sync. Our testing has shown that a device with only a couple of call history records will not trigger the iCloud syncing process. - Wait for the device to perform a periodic sync. This can take up to 12 hours depending on how the device is being used, its connectivity state and its charge state. - Plug the device into power. The device is more likely to trigger a sync when in this state.

  • Old call history is not getting returned in poll results.

The CallKit service is designed for syncing call history records between devices and not for storing these records indefinitely. Typically, call history records will be retrievable from CallKit for about 3 months, but this may vary between accounts depending on internal cleanup processes in the iCloud.

CloudKit

Browser history from iCloud cloudkit_safari.browser_history

Retrieve Safari browser history data stored in the iCloud sync service.

MobileMe

Contacts from iCloud mme_contacts.contacts

Retrieves iCloud stored iOS Contacts data.

Calendar from iCloud mme_calendar.events

Retrieves iCloud stored iOS Calendar data.

Notes from iCloud mme_notes.notes

Retrieves iCloud stored iOS Notes data.

Find My iPhone

Locations fmip.locations

Retrieve Find My iPhone location data.

iOS Apps

Messages ios_messages.messages

Retrieves iOS Messages data including iMessage and SMS.

Contacts ios_contacts.contacts

Retrieves iOS Contacts data.

Phone ios_phone.calls

Retrieves iOS Phone data.

Calendar ios_calendar.events

Retrieves iOS Calendar data.

Notes ios_notes.notes

Retrieves iOS Notes data.

Health ios_health.data

Retrieves iOS Health data. Often referred to as HealthKit data.

Safari

Browser history from backups safari.browser_history

Retrieves Safari browser history data from an iCloud backup.

Cookies safari.cookies

Retrieves Safari cookie data from an iCloud backup.

WhatsApp

Messages whatsapp.messages

Retrieves WhatsApp messages.

Calls whatsapp.calls

Retrieves WhatsApp call history.

Viber

Messages viber.messages

Retrieves Viber messages.

Calls viber.calls

Retrieves Viber call history.

Conversations viber.conversations

Retrieves Viber conversations.

Contacts viber.contacts

Retrieves Viber contacts.

Kik

Messages kik.messages

Retrieves Kik messages.

Contacts kik.contacts

Retrieves Kik contacts.

Hike

Messages hike.messages

Retrieves Hike messages.

Posts hike.posts

Retrieves Hike posts.

WeChat

Messages wechat.messages

Retrieves WeChat messages.

Tinder

Messages tinder.messages

Retrieves Tinder messages.

Line

Messages line.messages

Retrieves Line messages.

Facebook

Messages facebook.messages

Retrieves Facebook messages.

Snapchat

There are some caveats around use of this data type; please contact the enterprise team to learn more.

Messages snapchat.messages

Retrieves Snapchat messages.

Stories snapchat.stories

Retrieves Snapchat stories.

Skype

There are some caveats around use of this data type; please contact the enterprise team to learn more.

Messages skype.messages

Retrieves Skype messages.

Aggregators

Photos .photos

Aggregates image files from an iCloud backup.

Videos .videos

Aggregates video files from an iCloud backup.

Recordings .recordings

Aggregates recording files from an iCloud backup.

Voicemails .voicemails

Aggregates voicemail files from an iCloud backup.

App usage .app_usage

Aggregates app usage information from an iCloud backup.

Installed apps .installed_apps

Aggregates installed app information from an iCloud backup.

Locations .locations

Aggregates locations data from an iCloud backup.

Linked watches .linked_watches

Aggregates linked Apple Watch information from an iCloud backup.

File types

Payload attributes

name type description
files list of file object or file IDs A list of the files being requested.

Using cURL

curl https://ricloud-api.reincubate.com/polls \
  -X POST \
  -H 'Authorization: Token <your key_token>' \
  -H 'Content-Type: application/json' \
  -d '{
    "session": "2504da05-d2e0-4913-ae17-daa65a933413",
    "payload": {
        "files": [
            "icpl://01a26621ad6c1a74056891b9c7ed9016b0c319ec0d01e7d658896f59c305768f71961fef92091cfed21f",
            "icpl://0167ba732e5f53e20efd7b0a1d8593b0dd97e698af01afc3ab2f1d65880f713dce0bfb89142ee770fac5"
        ]
    }
}'

Using ricloud-py

import ricloud

# The ID of a session we made earlier.
session_id = '2504da05-d2e0-4913-ae17-daa65a933413'

poll_payload = {
    'files': [
        'icpl://01a26621ad6c1a74056891b9c7ed9016b0c319ec0d01e7d658896f59c305768f71961fef92091cfed21f',
        'icpl://0167ba732e5f53e20efd7b0a1d8593b0dd97e698af01afc3ab2f1d65880f713dce0bfb89142ee770fac5',
    ]
}

poll = ricloud.Poll.create(
  session=session_id,
  payload=poll_payload,
)
identifier description
backup_file or no protocol A file from an iCloud backup.
icpl_file A file from iCloud Photo Library.

Legacy data type maps

iCloud data types

legacy name new name
live_photos icpl.photos
mobileme_contacts icloud_contacts.contacts
mobileme_calendar icloud_calendar.events
mobileme_notes icloud_notes.notes
live_call_history callkit.calls
web_browser_history icloud_safari.browser_history
location fmip.locations

Backup data types

legacy name new name
photos backup.photos
videos backup.videos
recordings backup.recordings
voicemail backup.voicemails
app_usage backup.app_usage
installed_apps backup.installed_apps
locations backup.locations
linked_watches backup.linked_watches
sms ios_messages.messages
contacts ios_contacts.contacts
call_history ios_phone.calls
calendar_appointments ios_calendar.events
notes ios_notes.notes
healthkit ios_health.data
browser_history safari.browser_history
safari_cookies safari.cookies
whatsapp_messages whatsapp.messages
whatsapp_call_history whatsapp.calls
viber_messages viber.messages
viber_call_history viber.calls
viber_conversations viber.conversations
viber_contacts viber.contacts
kik_messages kik.messages
kik_contacts kik.contacts
hike_messages hike.messages
hike_posts hike.posts
wechat_messages wechat.messages
tinder_messages tinder.messages
line_messages line.messages
facebook_messages facebook.messages
snapchat_messages snapchat.messages
snapchat_stories snapchat.stories
skype_messages skype.messages

How can we help?

Our support team are here to help!

Our office hours are Monday to Friday, 9am to 5pm GMT.

We aim to reply to all messages within one working day.

Get in touch › Our awesome support team

© 2008 - 2019 Reincubate Ltd. All rights reserved. Registered in England and Wales #5189175, VAT GB151788978. Reincubate® is a registered trademark. Privacy & terms. We recommend 2FA. Built with in London.