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

rirelay.source.info attributes

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.

Data types

Reincubate Relay app data types

Reincubate Relay aggregated data types

Recordings

The .recordings data type lists Voice Memos recordings. Each item has file_id, file_path, filename and last_modified.

With include: ["transcript"], recordings made on iOS 18 and later also carry a transcript attribute with the recording's transcript as plain text. The attribute is omitted when a recording has no transcript. Transcripts are stored inside the audio files, so this filter has the device upload the audio of every recording in the date range, even when files aren't otherwise being retrieved.

{
  "data_types": [{
    "data_type": ".recordings",
    "filters": {
      "include": ["transcript"]
    }
  }]
}

{
  "file_id": "9c1d2e3f4a5b6c7d8e9f0a1b2c3d4e5f6a7b8c9d",
  "file_path": "Recordings/20250312 101500.m4a",
  "filename": "20250312 101500.m4a",
  "last_modified": "2025-03-12 10:15:00.000000",
  "transcript": "Remember to water the plants on Friday."
}

iOS Messages

Messages

Data attributes

Extends the message data type. Messages from iOS 11.3 and later include the line they went over, and on dual-SIM devices its line_id. Messages that couldn't be linked to a conversation carry orphaned and conversation_id_source, as described in message handles and conversations.

The following filters apply to this data type, in addition to the common filters:

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,
  "line": "+447700900123",
  "line_id": "40111C9B-1E34-42D1-943B-93DEDAABA008",
  "line_label": "Work",
  "date": "2020-01-01T00:00:00.000000Z"
}

iOS Contacts

Contacts

Data attributes

Extends the contact data type.

Data filters

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 attributes

Extends the call data type. Calls from iOS 14 and later include the line_id of the line they went over, and its line number where the device has it.

The following filters apply to this data type, in addition to the common filters:

Sample data

{
  "id": "24116c5b16b85217",
  "data_type": "call",
  "call_type": "Phone",
  "address": "07123456789",
  "duration": 5.131359,
  "answered": false,
  "from_me": true,
  "line_id": "40111C9B-1E34-42D1-943B-93DEDAABA008",
  "line": "+447700900123",
  "date": "2015-07-20 10:23:27.538011"
}

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 attributes

Extends the note data type.

iOS Health

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

Data

ios_health.profile attributes

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

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

iOS Files

Files

Lists the documents in the Files app, from these locations:

Documents from third-party storage providers that appear in the Files app are not included.

iCloud Drive documents are listed even if their content was never downloaded to the device. Their content isn't in the backup, so they have content_available set to false and a file_id of null, but still carry their name, path, size and dates.

Attributes

Every item has all of these attributes, set to null where they don't apply.

The following filters apply to this data type, in addition to since and until:

Path patterns ignore case and can match anywhere in file_path, not only at its start. * matches any run of characters, including /. For example, Invoices matches any file with Invoices anywhere in its path, and CloudDocs/*.pdf matches PDFs anywhere in iCloud Drive's own folder. As the Files app hides extensions, match on the name without its extension to find a file whatever its type.

{
  "data_types": [{
    "data_type": "ios_files.files",
    "filters": {
      "paths": ["Invoices/*.pdf"],
      "exclude_paths": ["Archive"]
    }
  }]
}

Sample data

A document stored On My iPhone:

{
  "type": "file",
  "file_id": "4ff0327d0148e7fa175a12f5a25ed7148a29de6d",
  "filename": "Itinerary.docx",
  "name": "Itinerary",
  "extension": "docx",
  "mime_type": "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
  "kind": "document",
  "size": 48213,
  "checksum": null,
  "file_path": "File Provider Storage/Trip/Itinerary.docx",
  "file_domain": "AppDomainGroup-group.com.apple.FileProvider.LocalStorage",
  "source": "on_device",
  "folder": "Trip",
  "content_available": true,
  "last_modified": "2024-07-03 09:46:40.000000",
  "created": null,
  "last_opened": null,
  "item_id": null,
  "content_hash": null,
  "bundle_id": null
}

An iCloud Drive document that wasn't downloaded to the device:

{
  "type": "file",
  "file_id": null,
  "filename": "Profile.mobileconfig",
  "name": "Profile",
  "extension": "mobileconfig",
  "mime_type": null,
  "kind": "other",
  "size": 7508,
  "checksum": null,
  "file_path": "Library/Mobile Documents/com~apple~CloudDocs/Profile.mobileconfig",
  "file_domain": "HomeDomain",
  "source": "icloud_drive",
  "folder": "",
  "content_available": false,
  "last_modified": "2024-06-12 15:02:11.000000",
  "created": "2024-06-12 15:02:11.000000",
  "last_opened": "2024-06-14 08:20:45.000000",
  "item_id": "A0000000-0000-4000-8000-00000000000C",
  "content_hash": "01c4e1f2a6b0d3e5f7a9c8b2d4e6f8a0b1c3d5e7f9",
  "bundle_id": null
}

WhatsApp & WhatsApp for Business

WhatsApp Messages

Attributes

Extends the message data type. Group management events, such as members being added, are returned as messages with message_type: "group_event", described in WhatsApp group event types.

Sample data

A member being added to a group by one of its admins:

{
  "id": 1016,
  "data_type": "message",
  "conversation_id": 3,
  "handle": "40743660246@s.whatsapp.net",
  "handle_name": "Iphone 6",
  "contact": {
    "name": "Iphone 6",
    "phone": "+40743660246"
  },
  "text": "40743660246@s.whatsapp.net",
  "message_type": "group_event",
  "group_event_type": "participant_added",
  "group_event_participants": [
    "40726367814@s.whatsapp.net"
  ],
  "group_event_description": "Iphone 6 (40743660246@s.whatsapp.net) added Luci (40726367814@s.whatsapp.net)",
  "group": "Test group",
  "group_handles": [
    "40743660246@s.whatsapp.net",
    "40726367814@s.whatsapp.net",
    "40758668906@s.whatsapp.net"
  ],
  "attachments": [],
  "from_me": false,
  "date": "2019-09-17T11:43:24.000000Z"
}

WhatsApp Calls

Attributes

Extends the call data type.

WhatsApp for Business Messages

Attributes

Extends the message data type.

Viber

Calls

Messages

Attributes

Extends the message data type.

Calls

Attributes

Extends the call data type.

Conversations

Attributes

Extends the conversation data type.

Contacts

Attributes

Extends the contact data type.

Kik

Messages

Attributes

Extends the message data type.

Contacts

Attributes

Extends the contact data type.

Hike

Messages

Attributes

Extends the message data type.

Posts

Attributes

Extends the message data type.

WeChat

Messages

Attributes

Extends the message data type with the following attributes. Each is omitted when it isn't known.

The following filters apply to this data type, in addition to the common filters. Phone number and email address filters don't apply to it.

Sample data

{
  "id": "e5f6a7b8",
  "data_type": "message",
  "conversation_id": "Chat_5e1c0f7b2d9a4c3e8f6b1a0d9c2e7f4a",
  "handle": "carol",
  "text": "See you there",
  "group": "Weekend plans",
  "from_me": false,
  "wechat_id": "wxid_carol003",
  "wechat_alias": "carol_w",
  "group_wechat_ids": ["wxid_alice001", "wxid_carol003", "wxid_dave004"],
  "group_wechat_aliases": ["alice_w", "carol_w"],
  "date": "2024-05-01T09:30:00.000000Z"
}

Tinder

Messages

Attributes

Extends the message data type.

Line

Messages

Attributes

Extends the message data type.

Facebook Messenger

Messages

Attributes

Extends the message data type.

Snapchat

Messages

Attributes

Extends the message data type.

Stories

Attributes

Extends the message data type.

Skype

Messages

Attributes

Extends the message data type.