Polls

A poll resource contains information on a specific request for data. Once a poll is created, it will trigger the creation of one or more tasks in order to complete the request.

Attributes

Tasks

The most important role of the poll resource is to reflect the progress of its associated tasks and allow the end-user to start fetching results from these as soon as they become available. Therefore, the poll resource exposes task related attributes wherein associated tasks are categorised by their state.

Results

Any results published by tasks running within the poll are surfaced in the poll's results attribute. This allows for consumption of results before the poll has completed.

Errors

Any errors raised by tasks running within the poll will appear in the poll's errors attribute.

States

The state of a poll reflects only whether the poll is awaiting initialisation (pending), is in progress (processing), or all tasks have finished execution (completed).

A poll does not reflect any error states other than through its associated tasks.

Payload

The poll payload indicates which types of information, data types, and files it should work to retrieve. The poll payload attribute schema is described below.

For example, the poll payload to retrieve all types of information on an iCloud account source would be:

{
  "info_types": ["*"]
}

To retrieved a variety of messaging data from an iCloud backup or Reincubate Relay source, but only from a certain date:

{
  "data_types": ["ios_messages.messages", "whatsapp.messages", "viber.messages"],
  "filters": {
    "since": "2019-09-15T22:04:12Z",
    "until": "2021-06-02T12:00:00Z"
  }
}

To retrieve file data for images referenced in an iCloud Photo Library result:

{
  "files": ["icpl://xyz123", "icpl://abc321"]
}

The different attributes can also be used simultaneously:

{
  "info_types": ["*"],
  "data_types": ["ios_phone.calls"]
}

Filters

Filters allow the client to reduce the amount of data returned to only that which is likely to be of interest. For example, you might filter a poll for SMS data to only the last month of data.

The identifiers, lines, paths, exclude and include filters, and their exclusion counterparts, are applied to Reincubate Relay sources only.

Filters in subscription poll payloads

When using subscriptions to generate regular polls, any filters set in the poll payload will only be used on the initial poll of the subscription. Thereafter, the API will do the following:

• Any value for until is ignored as to avoid simply re-polling the same interval repeatedly
• If until was set, the next poll will fetch data from that point in time forward
• If until was not set, the next poll will fetch data from the time of the initial poll forward (i.e. the API will poll progressively as normal)

Data-level filters

Data-level filters, such as phone_numbers and email_addresses, are helpful to reduce processed data to just the items that are relevant to you. These are include filters that drop any data items that don't match or relate to another item that matches one of the values in the filter's list. Take the payload below, for example:

{
  "data_types": ["ios_messages.messages"],
  "filters": {
    "phone_numbers": ["0123456789"],
    "email_addresses": ["test@example.com"]
  }
}

This would return any messages from iOS Messages that relate to a conversation involving either the phone number or email address specified, including any group conversations. It can be helpful to specify multiple values to filter on, as many contacts will have a mix of phone numbers and email-identified accounts, such as Messages' iCloud accounts.

Exclusion-based filters, like exclude_phone_numbers and exclude_email_addresses, do the opposite: removing any data that relates to the values provided. If both inclusion- and exclusion-based filters are provided, and an item relates to both, then the exclusion-based filter wins. For example, a group conversation that contains one contact with an included email address but also another contact with an excluded phone number will get filtered out of the data.

Filter applicability

A filter only applies to the data types it can match, and leaves the others untouched. For example, a lines filter doesn't affect whatsapp.messages, as WhatsApp doesn't record which of the device's lines it used, and a phone_numbers filter doesn't affect wechat.messages, whose handles are never phone numbers. This means a filter can be set on the whole poll without emptying data types it has no bearing on. since, until, exclude and include are not affected by this.

No data-level filters apply to any other data type, including kik.messages, facebook.messages, snapchat.messages, line.messages, tinder.messages and skype.messages.

Once a filter applies to a data type, it applies to every item of that type, including items that don't carry the kind of value it matches. An inclusion filter leaves those items out, and an exclusion filter keeps them. For example, phone_numbers leaves out contacts that only have an email address, and lines leaves out calls in ios_phone.calls that were made through third-party apps, which have no line.

Phone numbers match when the filter's digits occur in the item's number, so 7700900123 matches +44 7700 900123. Email addresses match exactly, ignoring case. Contacts are matched on all their phone numbers and email addresses together, so an inclusion filter needs one of them to match, and an exclusion filter leaves out a contact if any of them match. Calendar events are matched on attendees, who are usually recorded by display name rather than email address, so an email address filter rarely matches an event.

Identifier filters

Use identifiers to filter wechat.messages, which are identified by WeChat account rather than by phone number or email address:

{
  "data_types": [{
    "data_type": "wechat.messages",
    "filters": {
      "identifiers": ["wxid_abc123", "alice_w"]
    }
  }]
}

Identifiers are matched exactly, ignoring case, against both the WeChat ID (wechat_id) and the user-facing alias (wechat_alias). A group message matches if any member of the group matches, so excluding one member excludes the whole group conversation. Display names are not matched.

Line filters

On dual-SIM devices, lines and exclude_lines filter by the line a message, call or voicemail went over. A line can be given as its phone number, in any format, or as its line ID, the line_id value on messages and calls.

Line filters only apply to these data types. Other data types, such as whatsapp.messages, are returned in full.

{
  "data_types": ["ios_messages.messages", "ios_phone.calls", "whatsapp.messages"],
  "filters": {
    "lines": ["+447700900123"]
  }
}

This would return the messages and calls that went over that line, and all WhatsApp messages.

Within these data types, lines leaves out any item whose line isn't known. That includes messages from before iOS 11.3, calls from before iOS 14, calls made through third-party apps, and voicemails in the default folder. With only exclude_lines set, items whose line isn't known are kept.

Unlike phone_numbers, which matches any party to a conversation, lines only matches the device's own line.

Field filters

The exclude and include filters work at the field level rather than the item level. exclude omits the named fields from each extracted item, and include opts in to optional data that is left out by default. Each value only affects the data type it relates to, listed below.

{
  "data_types": [{
    "data_type": "ios_contacts.contacts",
    "filters": {
      "exclude": ["photo"]
    }
  }]
}

This would return contacts data without contact photos.

Any other value is rejected with a validation error. This also applies to stored subscriptions, which are re-validated each time they poll.

Create POST /polls

Create a poll for data against a specific session.

The source parameter should only be used when targeting a child source of the session's primary source. For example, if retrieving data from a rirelay.source the source parameter should be the ID of that source.

Using cURL

curl https://ricloud-api.reincubate.com/polls \
  -X POST \
  -H 'Authorization: Token <your key_token>' \
  -H 'Content-Type: application/json' \
  -d '{
  "session": "<session ID>",
  "payload": {
    "info_types": ["*"]
  }
}'

Using ricloud-py

import ricloud

poll_payload = {
  'info_types': ['*'],
}

poll = ricloud.Poll.create(
  session='<session ID or ricloud.Session instance>',
  payload=poll_payload,
)

Sample response

{
  "id": "54554389-5f1a-4ccf-9bb8-024a031cf948",
  "resource": "poll",
  "organisation": 1,
  "key": 1,
  "user": 1,
  "source": 1,
  "session": "f5a7a7ef-ff21-47fe-9aa6-7ebd08123623",
  "subscription": null,
  "tasks_pending": [],
  "tasks_processing": [],
  "tasks_succeeded": [],
  "tasks_failed": [],
  "tasks_suspended": [],
  "results": {
      "data": [],
      "has_more": false,
      "total_count": 0,
      "url": "/polls/54554389-5f1a-4ccf-9bb8-024a031cf948/results"
  },
  "errors": {
    "data": [],
      "has_more": false,
      "total_count": 0,
      "url": "/polls/54554389-5f1a-4ccf-9bb8-024a031cf948/errors"
  },
  "state": "pending",
  "date_created": "2020-02-20T11:59:14.694337Z",
  "date_started": null,
  "date_completed": null
}

Resume POST /polls/{poll ID}/resume

Resume a poll by re-dispatching any suspended tasks and retrying failed file tasks. This can be used to trigger re-evaluation of requested files from Relay app instances, or for re-attempting file tasks which may have failed due to a transient issue.

Using cURL

curl https://ricloud-api.reincubate.com/polls/<poll ID>/resume \
  -X POST \
  -H 'Authorization: Token <your key_token>' \
  -H 'Content-Type: application/json' \
  -d '{}'

To resume with specific options:

curl https://ricloud-api.reincubate.com/polls/<poll ID>/resume \
  -X POST \
  -H 'Authorization: Token <your key_token>' \
  -H 'Content-Type: application/json' \
  -d '{
  "skip_missing": true,
  "retry_files": false
}'

Retrieve GET /polls/{poll ID}

Using cURL

curl https://ricloud-api.reincubate.com/polls/<poll ID> \
  -H 'Authorization: Token <your key_token>'

Using ricloud-py

import ricloud

poll = ricloud.Poll.retrieve(<poll ID>)

List GET /polls

Using cURL

curl https://ricloud-api.reincubate.com/polls \
  -H 'Authorization: Token <your key_token>'

Using ricloud-py

import ricloud

polls = ricloud.Poll.list()

Changelog

2026-10-16

• Add the identifiers and exclude_identifiers filters, matching WeChat IDs and aliases on wechat.messages. Phone number and email address filters no longer apply to wechat.messages.
• Add the lines and exclude_lines filters, matching the line a message, call or voicemail went over on dual-SIM devices.
• Add the paths and exclude_paths filters for the ios_files.files data type.
• Add the include filter, accepting transcript for .recordings and app_documents for ios_files.files.
• exclude and include now reject unrecognised values with a validation error, where unrecognised exclude values were previously ignored.
• Data-level filters now only apply to the data types they can match, and leave the others untouched. Previously, a filter could empty a data type that never carries its kind of value. See filter applicability.
• Contacts are now matched on all their phone numbers and email addresses together. exclude_phone_numbers and exclude_email_addresses leave out a contact if any of its numbers or addresses match, where previously a contact that also had an unmatched value was kept. They no longer leave out contacts that have no phone number or email address.
• Phone number filters no longer match WhatsApp senders identified only by an unresolved LID, whose digits were previously treated as a phone number.

2026-06-04

• Add support for the exclude filter in poll payloads. This allows named output fields to be omitted from extracted data items. Currently only supported by the ios_contacts.contacts data type, for the photo field.

2026-03-06

• Add POST /polls/{poll ID}/resume endpoint for resuming suspended tasks and retrying failed file tasks. Failed file tasks are retried by default.

2024-12-09

• Add support for excluding data related to specific contact email addresses and phone numbers, via the exclude_phone_numbers and exclude_emails poll payload parameters.

2023-11-28

• Add support for filtering data using contact email addresses and phone numbers via the phone_numbers and emails poll payload parameters.

2022-07-08

• Support for the until filter in poll payloads was added for SMS extraction. This complements the since filter to allow clients to specify an exact datetime range to retrieve data from.

2020-05-05

• The errors attribute was added to the poll object. This is a nested list object containing error objects associated with the poll.

2020-02-20

• Major: The results attribute of the poll object is now a nested list object, rather than a simple list attribute. This makes it possible to paginate results when a poll publishes a large number of results.

2019-10-16

• Adds the subscription attribute to the poll object to indicate whether the poll was triggered by a subscription.

2019-06-01

• The poll object payload attribute can now be composed of multiple operation types. This means a poll can be created with any or all of info-types, data-types and files in the payload.
• Major The type attribute on the poll object is deprecated in favour of composable poll payloads.