Data types

Updated

Results returned for data type polls against the API will return information in one of the formats outlined below.

Result payload

Attributes

The root structure of the data JSON payload has the following attributes.

name type description
data list of data objects The data retrieved from the source.
metadata metadata object Metadata related to data.

Metadata

Attributes

name type description
count int The number of objects in data.

File

The file data type is seen throughout the API, as it is a reference to a file that can be downloaded from the API through a files type poll.

Attributes

name type description
file_id string Identifier used to request the file from the API. The value is only guaranteed to be unique in the scope of the current source.
type string, always file Data type specifier.
name string The name of the file, excluding the extension.
extension string, optional The extension of the file if available.
mime_type string, optional The MIME type of the file if available.
size int, optional The size of the file if available.
checksum string, optional The md5 checksum if available.

Example

{
  "file_id": "abc123",
  "type": "file",
  "name": "IMG_0003",
  "extension": "jpg",
  "mime_type": "image/jpeg",
  "size": 2505426,
}

Image

Extends file.

name type description
file_id string Identifier used to request the file from the API. The value is only guaranteed to be unique in the scope of the current source.
type string Always image.
filename string The original file name of the file. The extension in this filename need to match the extension of the file.
file_path string The path of the file relative to other files within its service. For example, the path within a backup.
width int, optional The width of the file if available.
height int, optional The height of the file if available.

Example

{
  "file_id": "abc123",
  "type": "image",
  "filename": "IMG_0003.JPG",
  "file_path": "Media/DCIM/100APPLE/IMG_0003.JPG",
  "name": "IMG_0003",
  "extension": "jpg",
  "mime_type": "image/jpeg",
  "width": 3000,
  "height": 2002,
  "size": 2505426,
}

Video

Extends file.

name type description
file_id string Identifier used to request the file from the API. The value is only guaranteed to be unique in the scope of the current source.
type string Always video.
filename string The original file name of the file. The extension in this filename need to match the extension of the file.
file_path string The path of the file relative to other files within its service. For example, the path within a backup.
width int, optional The width of the file if available.
height int, optional The height of the file if available.
duration int, optional The length of the video if available.

Example

{
  "file_id": "abc123",
  "type": "video",
  "filename": "IMG_0009.MOV",
  "file_path": "Media/DCIM/100APPLE/IMG_0009.MOV",
  "name": "IMG_0009",
  "extension": "mov",
  "mime_type": "video/quicktime",
  "width": 1920,
  "height": 1080,
  "size": 5421796,
  "duration": 9.135623
}

Video

Extends file.

name type description
file_id string Identifier used to request the file from the API. The value is only guaranteed to be unique in the scope of the current source.
type string Always audio.
filename string The original file name of the file. The extension in this filename need to match the extension of the file.
file_path string The path of the file relative to other files within its service. For example, the path within a backup.
transcription string, optional The text transcription for an audio message, if available.

Example

{
  "id": "abc123",
  "type": "audio",
  "filename": "Audio Message.caf",
  "file_path": "Library/SMS/Attachments/.../Audio Message.caf",
  "transcription": "Test voice message",
}

Audio transcriptions

When available in a backup's data, the transcription of audio messages is returned as part of the audio object. This is available on audio messages made in iOS Messages since iOS 17.

Message

Attributes

name type description
id string A unique identifier for the message. Use this to deduplicate returned data if necessary.
data_type string, always message Data type specifier.
type string, optional Used when a messaging service handles a variety of message types. For example SMS and iMessage in the case of iOS Messages.
handle string The 2nd party of the conversation, often an identifier unique to the messaging app.
handle_name string, optional Where available, a display name for the handle.
contact nested contact, optional An object referencing an iOS contact of the 2nd party of the conversation.
conversation_id string Identifier grouping messages by conversation.
from_me bool Whether the message was sent or received.
user string, optional The user of the messaging app in the case where multiple users/accounts may be using a messaging app from the device.
text string The body of the message.
edits list of edits, optional A list of message content edits, for apps where message editing is supported and the history persisted in backups.
attachments list of files, optional An array of file_id values which can be used with the download_file method. If the message includes no attachment, an empty array is returned.
group string, optional The name of the group at the time the message was sent.
group_id string, optional The unique identifier for the group within the context of that app. This may not be an integer, and if present, only provides information in addition to conversation_id.
group_handles list of strings, optional This value is null for person-to-person messages, and in group conversations is an array of strings representing phone numbers or iMessage email addresses.
group_contacts string, optional An array of objects referencing iOS contacts in the group.
deleted bool, optional A boolean value to indicate whether the message had been deleted.
marked_unread bool, optional Whether the user marked the message as unread, if available.
date datetime When the message was sent or received.
date_read datetime, optional When a message was first read, if available.
date_edited datetime, optional When a message was last edited, if applicable.
date_deleted datetime, optional When a message was deleted, if applicable.

Example

{
  "id": "a1b2c3d4",
  "data_type": "message",
  "type": "SMS",
  "handle": "reincubate",
  "handle_name": "Reincubate",
  "conversation_id": "w6x7y8z9",
  "from_me": false,
  "text": "Hi from London!",
  "edits": [{
    "text": "Hi!",
    "date": "2023-06-27T10:20:00.000000Z"
  }, {
    "text": "Hi from London!",
    "date": "2023-06-27T10:21:00.000000Z"
  }],
  "attachments": [],
  "group_handles": [
    "+441234567890",
    "renate@reincubate.com"
  ],
  "deleted": false,
  "date": "2023-06-27T10:20:00.000000Z",
  "date_edited": "2023-06-27T10:21:00.000000Z"
}

Message handles and conversations

The API's data extractors support a historically broad range of source data, and will attempt to realign data that has become fragmented through app and iOS updates over time. As messaging apps add new features, they are not always careful to ensure the underlying data is migrated perfectly to the new structure. Therefore, the API must infer certain information in order to return consistent data.

One such case is for handles and conversation information returned from messaging apps, and most specifically the ios_messages.messages data module. The API will populate conversation_id with either a numeric identifier, if such information exists or can be inferred, or fallback to use the second-party's handle to set conversation_id. Therefore, using this field to tie together messages from the same chat is recommended.

Edited and deleted messages

Information on edited and deleted messages is available for ios_messages.messages for backups made from devices running iOS 16 and later. For deleted messages, information is only expected to be available while the message is still recoverable at the point the backup was made, which Apple say is 30–40 days after deletion.

For edited messages, the history of edits is returned in the edits attribute. Each edit includes the state of text and the time when the edit was committed. The text attribute of the message itself will always be the same as that of the final edit.

Conversation

A conversation thread.

name type description
id string Item ID.
data_type string, always conversation Item data type ID.
group optional string Name of group.
members list of contact items Participants in the conversation.

Contact

contact attributes

name type description
id string Item ID.
data_type string, always contact Item data type ID.
name optional string The contact's full name.
first_name optional string The contact's first name.
middle_name optional string The contact's middle name.
last_name optional string The contact's last name.
prefix optional string The contact's name prefix.
suffix optional string The contact's name suffix.
nickname optional string The contact's nickname.
records list of contact.record items Contact records associated with the contact.
organisation optional string The contact's organisation name.
department optional string The contact's department within the organisation.
jobtitle optional string The contact's job title within the organisation.
birthday optional date The contact's birthday.

contact.record attribute

There are 5 types of contact record items: Phone, Email, URL, Social, and Address. They correspond to a phone number, email address, website URL, social media account handle, and street address, respectively.

The first 4 have the same attributes:

name type description
type string One of: Phone, Email, URL, Social.
name optional string The label associated with the record.
value string The value of the record.

The Address contact record type has additional address fields:

name type description
type string, always Address A phone number record.
name optional string The label associated with the number.
CountryCode optional string A country code.
Country optional string A country name.
ZIP optional string A zip or postal code.
State optional string A state name or abbreviation.
City optional string A city name.
Municipality optional string A municipality name.
SubLocality optional string A neighbourhood or area name.
Street optional string A street address name.

Sample data

{
  "id": "2cf6a837304d6614",
  "data_type": "contact",
  "first_name": "John",
  "middle_name": "'Gala'",
  "last_name": "Appleseed",
  "prefix": "Mr.",
  "suffix": "Jr.",
  "nickname": "John'o",
  "records": [
    {
      "type": "Phone",
      "name": "MAIN",
      "value": "1-800-MY-APPLE"
    },
    {
      "type": "Phone",
      "name": "UK",
      "value": "0800 039 1010"
    },
    {
      "type": "URL",
      "name": "HOMEPAGE",
      "value": "http://www.apple.com"
    },
    {
      "type": "URL",
      "name": "HOMEPAGE",
      "value": "http://www.apple.com/uk/"
    },
    {
      "City": "Cupertino",
      "State": "CA",
      "ZIP": "95014",
      "name": "WORK",
      "CountryCode": "US",
      "Country": "United States",
      "Street": "1 Infinite Loop",
      "type": "Address",
      "SubLocality": null,
      "Municipality": null
    }
  ],
  "organisation": "Apple Inc.",
  "department": "Marketing",
  "jobtitle": "VP Juicing",
  "birthday": "1976-04-01"
}

Call

Attributes

name type description
id string Item ID.
data_type string, always call Item data type ID.
call_type string One of: Phone, FaceTime Video, FaceTime Audio.
address string The target of the call. Could be a phone number, Apple ID, or other identifier.
duration float The duration of the call.
answered bool Whether the call was answered.
from_me bool Whether the call was outgoing or incoming.
date datetime When the call was made.

Sample data

{
  "id": "24116c5b16b85217",
  "data_type": "call",
  "call_type": "Phone",
  "address": "07123456789",
  "duration": 5.131359,
  "answered": false,
  "from_me": true,
  "date": "2015-07-20 10:23:27.538011"
}

Event

event attributes

name type description
id string Item ID.
data_type string, always event Item data type ID.
unique_identifier optional string Item UID for deduplicating across multiple event data sources.
calendar optional string Calendar name.
calendar_uid optional string Calendar UID.
calendar_store optional string Calendar store type, i.e. iCloud, Default.
summary optional string The event summary or title.
description optional string The event description.
start_date optional datetime When the event begins.
end_date optional datetime When the event finishes.
start_time_zone optional string The timezone of start_date.
end_time_zone optional string The timeone of end_date.
all_day boolean Whether the event lasts an entire day.
travel_time optional duration The event's travel time duration.
recurrence optional nested event.recurrence The event's recurrence settings.
location optional string Where the event is taking place.
start_location optional string Where the event is starting from.
attendees optional list of strings Names of event attendees.
attached_url optional string A URL associated with the event.
creation_date optional datetime When the event was created. Not set if default calendar entry, such as public holidays.

event.recurrence attributes

name type description
interval integer The count of repeat to recurr at, i.e. 1 Yearly (once every 1 year).
repeat string One of: OneTime, Daily, Weekly, Monthly, Yearly.
repeat_end_date optional datetime When to stop recurring.

Sample data

{
  "id": "3",
  "unique_identifier": "f5fcf872-34f6-3f60-ba03-74d5a7a3bbbb",
  "calendar": "Home",
  "calendar_id": "477a2001537fe178d6b77cdceb8bac2e",
  "calendar_store": "Default",
  "summary": "Christmas Day",
  "description": "Bank holiday in the UK",
  "start_date": "2017-12-25T00:00:00.000000",
  "end_date": "2017-12-25T23:59:59.000000",
  "start_time_zone": None,
  "end_time_zone": None,
  "all_day": True,
  "travel_time": None,
  "recurrence": {
    "interval": 1,
    "repeat": "Yearly",
    "repeat_end_date": None,
    "specifier": ""
  },
  "location": None,
  "start_location": None,
  "attendees": ["John Appleseed"],
  "attached_url": None,
  "creation_date": None
}

Note

{
  "title": "Monday meeting:",
  "note": "Monday meeting:\n Discuss X,\n discuss Y.",
  "summary": null,
  "folder": "icloud",
  "sub_folder": "work",
  "attachments": [
    {
      "type": "image",
      "file_id": "8e22cf6e524357b4eb3da775d193072ebba9543f",
      "file_path": "Media/80DDDEAD-B33F-37B2-7219432C0359/Image.jpeg"
    }
  ],
  "creation_date": "2016-06-06 13:23:20.000000",
  "last_modified": "2016-06-07 15:21:25.000000"
}

Visit

A record of a website page visit.

Attributes

name type description
data_type string, always visit Item data type ID.
url string The URL of the page visited.
title string The visited page's title.
date_created datetime When the visit occurred. 
{
  "data_type": "visit",
  "url": "https://reincubate.com/",
  "title": "Reincubate: the app data company",
  "date_created": "2020-01-01T00:00:00.000000Z"
}

Cookie

A HTTP cookie.

Attributes

name type description
data_type string, always cookie Item data type ID.
name string The cookie's name.
value string The cookie's value.
domain string The cookie's domain specifier.
path string The cookie's path specifier.
flags string Any flags set on the cookie.
creation_date datetime When the cookie was created.
expiry_date datetime When the cookie expires. 
{
  "data_type": "cookie",
  "name": "sample_cookies",
  "value": "sample_value",
  "domain": "reincubate.com",
  "path": "/",
  "flags": "",
  "creation_date": "2020-01-01T00:00:00.000000Z",
  "expiry_date": "2020-01-01T00:00:00.000000Z"
}

Location

Data attributes

name type description
data_type string, always location A data type identifier.
latitude float The location's latitude coordinate.
longitude float The location's longitude coordinate.
altitude float The location's altitude coordinate.
horizontal_accuracy float The horizontal accuracy for the measurement.
vertical_accuracy float The vertical accuracy for the measurement.
position_type string Identifier for the measurement method used.
date_created datetime When the measurement was made.

Sample data

{
  "data_type": "location",
  "latitude": 51.507452392689146,
  "longitude": -0.07398372304584414,
  "altitude": 0.0,
  "horizontal_accuracy": 65.0,
  "vertical_accuracy": 0.0,
  "positioning_type": "Wifi",
  "date_created": "2020-01-01T00:00:00.000000Z"
}

How can we help?

Our support team are here to help!

Our office hours are Monday to Friday, 9 AM to 5 PM GMT. The time is currently 4:35 PM GMT.

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

Go to support section Contact the enterprise team
Our awesome support team

© 2008 - 2024 Reincubate Ltd. All rights reserved. Registered in England and Wales #5189175, VAT GB151788978. Reincubate® and Camo® are registered trademarks. Privacy policy & terms.

We use cookies to track usage and improve your experience.

I understand Privacy Policy