Reincubate Relay service

Sessions

A pairing process is used to establish a link between a user of the API and a Reincubate Relay app instance. By default, if unpaired, the Reincubate Relay will display its pairing code. The user must give this to your application in order for it to create a valid session, via the following 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": "rirelay.instance"
  },
  "payload": {
    "code": "<Reincubate Relay pairing code>"
  }
}'

Once the session is created, you will be able to view information on the app instance via the session object's source attribute. This should look something like this:

{
  "id": "<session ID>",
  "resource": "session",
  ...
  "source": {
    "id": "<source ID>",
    "resource": "source",
    "user": "<user ID>",
    "type": "rirelay.instance",
    "identifier": "ee360f13-1b54-4d8c-8876-e5f573f0ba1c",
    "info": null,
    "parent": null,
    "children": {
      "data": [
        {
          "id": "<child source ID>",
          "resource": "source",
          "user": "<user ID>",
          "type": "rirelay.source",
          "identifier": "70a4982e-5893-4a5f-8af6-19db834d378d",
          "info": {
            "is_encrypted": true,
            "apple_model_id": "iPhone10,4",
            "apple_serial": "FFABCZGTJC12",
            "name": "iPhone 8",
            "ios_version": "13.2"
          },
          "children": {
            "data": [],
            "has_more": false,
            "total_count": 0,
            "url": "/sources/<child source ID>/children"
          },
          "state": "active",
          "date_created": "2019-10-08T09:02:15.770532Z"
        }
      ],
      "has_more": false,
      "total_count": 0,
      "url": "/sources/<source ID>/children"
    },
    "state": "active",
    "date_created": "2019-10-08T08:58:33.861941Z"
  },
  ...
}

Subscriptions

Unlike other services, a subscription is required before the API can start retrieving data from a Reincubate Relay source. This is to help the app's user understand exactly what data is being accessed.

Subscriptions can only be created against rirelay.source type sources, which are the children of the Reincubate Relay instance. The session to use when polling the source must also be specified.

curl https://ricloud-api.reincubate.com/subscriptions \
  -X POST \
  -H 'Authorization: Token <your key_token>' \
  -H 'Content-Type: application/json' \
  -d '{
  "session": "<session ID>",
  "source": "<child source ID>",
  "poll_payload": {
    "data_types": ["ios_messages.messages"]
  }
}'

The subscription will remain in a pending state until the user has allowed access to the specific device in the Reincubate Relay app interface. Once it has been allowed, the state will transition to active.

An initial poll is immediately created on subscription activation, then subsequent polls will be created when the Reincubate Relay app notifies the API of new data.

Polls

Polls can also be manually created against sources with active subscriptions. This is helpful when troubleshooting retrieved data or when testing out new data types.

curl https://ricloud-api.reincubate.com/polls \
  -X POST \
  -H 'Authorization: Token <your key_token>' \
  -H 'Content-Type: application/json' \
  -d '{
  "subscription": "<subscription ID>",
  "payload": {
    "data_types": ["ios_phone.calls", "whatsapp.messages"]
  }
}'

Events

To stay informed of asynchronous changes, such as a subscription creating a new poll or a session expiring, your implementation will need to receive event notifications from the API via a webhook endpoint.

For details on how to setup and configure your webhook endpoint, see configuring webhooks.

Info types

The Relay service currently only supports retrieving info from rirelay.instance sources, which includes nested info on any associated rirelay.source sources.

`rirelay.instance.info` attributes

name	type	description
`id`	source ID	ID of the source object corresponding to this Relay instance.
`version`	str	Version of the Reincubate Relay app.
`os`	str	Identifier of the operating system the Reincubate Relay app is running on.
`sources`	list of `rirelay.source.info`	List of sources associated with the instance.
`date_created`	datetime	Datetime when this instance was first seen.
`date_last_seen`	datetime	Datetime when this instance was last seen.

`rirelay.source.info` attributes

name	type	description
`id`	source ID	ID of the source object corresponding to this Relay source.
`uid`	str	The unique iOS device ID of the Relay source.
`info`	nested `rirelay.source.info.info`	Metadata for this Relay source.
`date_created`	datetime	Datetime when this source was first seen.
`date_last_seen`	datetime	Datetime when this source was last seen.

`rirelay.source.info.info` attributes

Note that name, ios_version, apple_model_id, apple_serial, and is_encrypted, are also included in the nested info data on Source objects, and are therefore accessible directly via API endpoints.

For other attributes, such as phone_number, a full poll for rirelay.instance.info is required – as this is personally identifiable information not stored by the API.

name	type	description
`name`	str	Name of the Relay source. Available in `Source.info`.
`ios_version`	str	Version of iOS running on the Relay source, i.e. `13.4`. Available in `Source.info`.
`apple_model_id`	str	Model ID of the Relay source, i.e. `iPhone7,2`. Available in `Source.info`.
`apple_serial`	str	Serial number of the Relay source, i.e. `F4KPWDR7G5DN`. Available in `Source.info`.
`phone_number`	optional, str	Phone number of the Relay source. Will be empty if cellular functionality is not enabled on the device (i.e. no SIM or Wi-Fi only).
`is_encrypted`	bool	Whether the Relay source is set to produce encrypted backups. Available in `Source.info`.

Data types

Reincubate Relay 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.history`	Retrieves Safari browser history data.
`ios_safari.cookies`	Retrieves Safari cookie data.
`whatsapp.messages`	Retrieves WhatsApp messages.
`whatsapp.calls`	Retrieves WhatsApp call history.
`whatsapp_business.messages`	Retrieves WhatsApp for Business messages.
`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.

Reincubate Relay aggregated data types

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

iOS Messages

Messages


Data type ID	`ios_messages.messages`

Data attributes

Extends the message data type.

Sample data

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

iOS Contacts

Contacts


Data type ID	`ios_contacts.contacts`

Data attributes

Extends the contact data type.

Data filters

name	type	description
`exclude`	optional array	Omit the named fields from extracted contacts. The only supported value is `photo`, which omits contact photo data.

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 00:00:00.000000Z"
}

iOS Phone

Calls


Data type ID	`ios_phone.calls`

Data attributes

Extends the call data type.

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

iOS Calendar

Events


Data type ID	`ios_calendar.events`

Data attributes

Extends the event data type.

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
}

iOS Notes

Notes


Data type ID	`ios_notes.notes`

Data attributes

Extends the note data type.

iOS Health

Data associated with the iOS Health app and the HealthKit framework.

Data


Data type ID	`ios_health.data`

ios_health.profile attributes

name	type	description
`info_type`	string, always `ios_health.profile`	Item data type ID.
`gender`	optional string	One of: `Female`, `Male`, `Other`.
`date_of_birth`	optional date	The profile owner's date of birth.
`weight`	optional float	The profile owner's weight measurement, in kilograms.
`height`	optional float	The profile owner's height measurement, in meters.
`blood_type`	optional string	The profile owner's blood type.
`fitzpatrick_skin_type`	optional string	The profile owner's Fitzpatrick Skin Type. One of: `Type I`, `Type II`, `Type II`, `Type IV`, `Type V`.

ios_health.profile sample

{
  "info_type": "ios_health.profile",
  "gender": "Female",
  "date_of_birth": "1988-08-22",
  "weight": 75.2543977,
  "height": 1.9812,
  "blood_type": "O+",
  "fitzpatrick_skin_type": "Type V"
}

ios_health.sample attributes

name	type	description
`id`	string	Item ID.
`data_type`	string	Item data type ID. One of the iOS Health data types.
`type`	string	Sample type. One of: `quantity`, `binary`, `category`.
`value`	one of string, float, integer	Sample value. The type of this field depends on the sample `type` attribute.
`unit`	optional string	Set if a non-default sample unit.
`was_user_entered`	boolean	Whether the user entered this measurement manually.
`start_date`	datetime	When the sampling period begun.
`end_date`	datetime	When the sampling period ended.

iOS Health data types:

ios_health.body_mass_index
ios_health.body_fat_percentage
ios_health.height
ios_health.weight
ios_health.lean_body_mass
ios_health.heart_rate
ios_health.steps
ios_health.walking_running_distance
ios_health.resting_energy
ios_health.active_energy
ios_health.flights_climbed
ios_health.oxygen_saturation
ios_health.blood_glucose
ios_health.systolic_blood_pressure
ios_health.diastolic_blood_pressure
ios_health.blood_alcohol_content
ios_health.peripheral_perfusion_index
ios_health.total_fat
ios_health.polyunsaturated_fat
ios_health.monounsaturated_fat
ios_health.saturated_fat
ios_health.dietary_cholesterol
ios_health.sodium
ios_health.carbohydrates
ios_health.fibre
ios_health.dietary_sugar
ios_health.dietary_energy
ios_health.protein
ios_health.vitamin_a
ios_health.vitamin_b6
ios_health.vitamin_b12
ios_health.vitamin_c
ios_health.vitamin_d
ios_health.vitamin_e
ios_health.vitamin_k
ios_health.calcium
ios_health.iron
ios_health.thiamine
ios_health.riboflavin
ios_health.niacin
ios_health.folate
ios_health.biotin
ios_health.pantothenic_acid
ios_health.phosphorous
ios_health.iodine
ios_health.magnesium
ios_health.zinc
ios_health.selenium
ios_health.copper
ios_health.manganese
ios_health.chromium
ios_health.molybdenum
ios_health.chloride
ios_health.potassium
ios_health.number_of_times_fallen
ios_health.electrodermal_activity
ios_health.inhaler_usage
ios_health.respiratory_rate
ios_health.body_temperature
ios_health.sleep_analysis
ios_health.forced_vital_capacity
ios_health.forced_expiration_volume_1
ios_health.peak_expiratory_flow_rate
ios_health.caffeine
ios_health.workout
ios_health.blood_pressure_correlation
ios_health.cycling_distance
ios_health.water
ios_health.uv_index
ios_health.basal_body_temperature
ios_health.cervical_mucus_quality
ios_health.ovulation_test_results
ios_health.menstruation
ios_health.spotting
ios_health.sexual_activity

Sample data

{
  "id": "a1b2c3d41",
  "data_type": "ios_health.walking_running_distance",
  "type": "quantity",
  "value": 6.08,
  "was_user_entered": false,
  "start_date": "2016-07-04T18:11:54.000000Z",
  "end_date": "2016-07-04T18:12:09.000000Z"
}, {
  "id": "a1b2c3d42",
  "data_type": "ios_health.steps",
  "type": "quantity",
  "value": 8.0,
  "was_user_entered": false,
  "start_date": "2016-07-04T18:11:54.000000Z",
  "end_date": "2016-07-04T18:12:09.000000Z"
}, {
  "id": "a1b2c3d43",
  "data_type": "ios_health.caffeine",
  "type": "quantity",
  "value": 800.0,
  "unit": "mg",
  "was_user_entered": true,
  "start_date": "2016-07-04T18:11:54.000000Z",
  "end_date": "2016-07-04T18:12:09.000000Z"
}

iOS Safari

History


Data type ID	`ios_safari.history`

Data attributes

Extends the visit data type.

Sample data

{
  "data_type": "visit",
  "url": "https://reincubate.com/",
  "title": "Reincubate: the app data company",
  "date_created": "2020-01-01T00:00:00.000000Z"
}

Cookies


Data type ID	`ios_safari.cookies`

Data attributes

Extends the cookie data type.

Sample data

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

WhatsApp & WhatsApp for Business

WhatsApp Messages


Data type ID	`whatsapp.messages`

Attributes

Extends the message data type.

WhatsApp Calls


Data type ID	`whatsapp.calls`

Attributes

Extends the call data type.

WhatsApp for Business Messages


Data type ID	`whatsapp_business.messages`

Attributes

Extends the message data type.

Viber

Calls


`viber.messages`	Retrieves Viber messages.
`viber.calls`	Retrieves Viber call history.
`viber.conversations`	Retrieves Viber conversations.
`viber.contacts`	Retrieves Viber contacts.

Messages


Data type ID	`viber.messages`

Attributes

Extends the message data type.

Calls


Data type ID	`viber.calls`

Attributes

Extends the call data type.

Conversations


Data type ID	`viber.conversations`

Attributes

Extends the conversation data type.

Contacts


Data type ID	`viber.contacts`

Attributes

Extends the contact data type.

Kik

Messages


Data type ID	`kik.messages`

Attributes

Extends the message data type.

Contacts


Data type ID	`kik.contacts`

Attributes

Extends the contact data type.

Hike


`hike.messages`	Retrieves Hike messages.
`hike.posts`	Retrieves Hike posts.

Messages


Data type ID	`hike.messages`

Attributes

Extends the message data type.

Posts


Data type ID	`hike.posts`

Attributes

Extends the message data type.

WeChat

Messages


Data type ID	`wechat.messages`

Attributes

Extends the message data type.

Tinder

Messages


Data type ID	`tinder.messages`

Attributes

Extends the message data type.

Line

Messages


Data type ID	`line.messages`

Attributes

Extends the message data type.

Facebook Messenger

Messages


Data type ID	`facebook.messenger`

Attributes

Extends the message data type.

Snapchat

Messages


Data type ID	`snapchat.messages`

Attributes

Extends the message data type.

Stories


Data type ID	`snapchat.stories`

Attributes

Extends the message data type.

Skype

Messages


Data type ID	`skype.messages`

Attributes

Extends the message data type.

Reincubate Relay service

Related articles

Need help?