Data types

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 |
---|---|---|
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. |
data_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
{ "id": "abc123", "data_type": "file", "name": "IMG_0003", "extension": "jpg", "mime_type": "image/jpeg", "size": 2505426, }
Image
Extends file.
name | type | description |
---|---|---|
filename |
string | The original file name of the file. The extension in this filename need to match the extension of the file. |
filepath |
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
{ "id": "abc123", "data_type": "image", "filename": "IMG_0003.JPG", "filepath": "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 |
---|---|---|
filename |
string | The original file name of the file. The extension in this filename need to match the extension of the file. |
filepath |
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
{ "id": "abc123", "data_type": "video", "filename": "IMG_0009.MOV", "filepath": "Media/DCIM/100APPLE/IMG_0009.MOV", "name": "IMG_0009", "extension": "mov", "mime_type": "video/quicktime", "width": 1920, "height": 1080, "size": 5421796, "duration": 9.135623 }
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. |
conversation_id |
string | Identifier grouping messages by conversation. |
handle |
string | The 2nd party of the conversation. |
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. |
text |
string | The body of the message. |
from_me |
bool | Whether the message was sent or received. |
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_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 |
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_contacts |
string, optional | An array of objects referencing iOS contacts in the group. |
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. |
deleted |
bool, optional | A boolean value to indicate whether the message had been deleted. |
date |
datetime | When the message was sent or received. |
contact |
nested contact, optional | An object referencing an iOS contact of the 2nd party of the conversation. |
Example
{ "id": "a1b2c3d4", "data_type": "message", "conversation_id": "w6x7y8z9", "handle": "vodafone", "type": "SMS", "text": "Hi from Vodafone!", "attachments": [], "group_handles": [ "+441234567890", "renate@reincubate.com" ], "from_me": false, "deleted": false, "date": "2020-01-01T00:00:00.000000Z" }
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" }
'name': self.name, 'creation_date': creation_date, 'expiry_date': expiry_date, 'domain': self.domain, 'flags': self.flags, 'path': self.path, 'value': self.value,
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" }