Data types

Updated over a week ago

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"
}

Result payload

Metadata

File

Image

Video

Message

Conversation

Contact

Call

Event

Note

Visit

Cookie

Location

How can we help?