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.

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.

Note that for phone numbers, any special characters are ignored when the filter comparison is made, e.g. (415) 555‑0132 is equivalent to 4155550132, and sub-strings may also be used, e.g. 4155550132 will match (415) 555‑0132 and +1 (415) 555‑0132. Typically, using a slightly less specific filter value – by avoiding international calling codes, for example – will yield more consistent results.

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
}

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

2023-11-28

• Support for the email_addresses and phone_numbers filters was added, which allows for retrieval of data relating only to specific contacts.

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.