Polls

Updated

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

name type description
id poll ID Resource identifier.
resource string, always poll Resource type specifier.
organisation organisation ID The organisation associated with this resource.
key key ID The key associated with this resource.
user user ID The user associated with this resource.
source source ID The source the poll is targeting. This can be a child source of the session's source.
session session ID The session the poll is using.
tasks_pending list of task IDs The tasks associated with the poll that are awaiting processing.
tasks_processing list of task IDs The tasks associated with the poll that are being processed.
tasks_succeeded list of task IDs The tasks associated with the poll that are succeeded.
tasks_failed list of task IDs The tasks associated with the poll that are failed.
state string One of: pending, processing, completed.
date_created datetime When the resource was created.
date_started optional datetime When processing of the resource began.
date_completed optional datetime When processing of the resource finished.

Tasks

The most important role of the pol 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 three task related attributes wherein associated tasks are categorised by their state.

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

Depending on a source's service, a poll may need a payload for the request to be configured fully.

For example, an info type poll requires a payload which specifies the info_types attribute.

{
  "info_types": []
}

In this case we leave the brackets empty to ask for all available info types.

Another example, a data type poll requires a payload which specifies which data types to retrieve.

{
  "data_types": ["photos.backup", "messages.sms", "messages.whatsapp"]
}

While a files type poll requires the identifiers of the files to be retrieved.

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

More complex polls can then be composed using a variety attributes.

Create POST /polls

Create a poll for data against a specific session.

As a session resource is already directly tied to a specific source, you do not have to provide the source parameter. However, it can be provided to specify that the poll target a child source of the primary source the session is tied to. For example, on the iCloud service a session can only be created against iCloud account sources (the primary source of the iCloud service), but you can target data only from a specific iCloud backup (a child source of the iCloud account) by providing its ID.

name type description
key optional, key ID Optionally override the key used for this poll. This is useful when letting users trial new functionality.
source optional, source ID Optionally target a child source of the session linked source.
session session ID The session to be used to authenticate data retrieval.
type string The type of poll being created.
payload optional, dictionary The poll payload used to specify poll

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>",
  "type": "data",
  "payload": {
    "data_types": ["info.account"],
  }
}'

Using ricloud-py

import ricloud

poll_payload = {
  'data': ['info.account'],
}

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

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

name type description
key key ID Filter by associated key. This is the key used by the user at the time.
user user ID Filter by associated user.
source source ID Filter by the target source.
session session ID Filter by the target session.
type string Filter by poll type.
state string Filter by session state.
date_created datetime filter Filter by when the resource was created.
date_completed datetime filter Filter by when the poll was finished.

Using cURL

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

Using ricloud-py

import ricloud

polls = ricloud.Poll.list()

How can we help?

Our support team are here to help!

Our office hours are Monday to Friday, 9am to 5pm GMT.

We aim to reply to all messages within one working day.

Get in touch › Our awesome support team

© 2008 - 2019 Reincubate Ltd. All rights reserved. Registered in England and Wales #5189175, VAT GB151788978. Reincubate® is a registered trademark. Privacy & terms. We recommend 2FA. Built with in London.