Reincubate Relay service

Updated
Cover image for: 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.
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.

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

Messages
Data type ID whatsapp.messages

Attributes

Extends the message data type.

Calls
Data type ID whatsapp.calls

Attributes

Extends the call 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.

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 10:48 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

Can we improve this article?

We love hearing from users: why not drop us an email, leave a comment, or tweet @reincubate?

© 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