Web Service

How to read new entries (REST V3)


You have multiples ways to retrieve unread entries using the Web Service.

The first one requires to use those two functions:

  • GET forms/{formId}/data/readnew
  • POST forms/{formId}/data/markasread

The second one requires to use the new function POST forms/{formId}/data/advanced.

First way : Read new / Mark as read

Kizeo Formscan mark an entry that is already been read. The biggest problem with this function is that it does not deal with updated entries (an already marked entry will stay marked).

The first thing to do is call the function GET forms/{formId}/data/readnew. The answer must look like this:

// Output GET forms/{formId}/data/readnew
{
  "status": "ok", // "ok" or "error" expected
  "message": "", // if there is an error, contains the error message.
  "data": [
    // Array of unread data
    {
      "id": DATA_ID, // The data ID you will need in a few moments
      // ...
    },
    // ...
  ]
{

Once you have finish storing/analyzing your entries, you can simply call to POST forms/{formId}/data/markasread with the below parameters:

// Input POST forms/{formId}/data/markasread
{
  "data_ids": [
    DATA_ID, // The data IDs from previous function
    //..
  ]
}

Finally, the function readnew will never return those entries.

Second way : Using the advanced filtering

If you need more control about which entries to retrieve, you can use the function POST forms/{formId}/data/advanced.

This function requires these parameters:

// Input POST forms/{formId}/data/advanced
{
    // "global_filters" is an array of global filters on data.
    'global_filters': [
        'I search for this text in my data'
    ]
    // "filters" is an array of filters on specific part of data.
    // Here is a filter on the update_time of the data to get updated files between two dates
    'filters': [
        {
            "field": "_update_time",
            "operator": ">=",
            "type": "simple", // Always put "simple"
            "val": "2016-03-10" // Use ISO format for date and time
        }, {
            "field": "_update_time",
            "operator": "<=",
            "type": "simple", // Always put "simple"
            "val": "2016-03-10 23:59:59"
        }
    ]
    // "order" is the ordering array.
    'order': [{
        'col': '_id',
        'type': 'asc'
    }
]
}

And will return a json object like this one:

// Output POST forms/{formId}/data/advanced
{
    "recordsTotal": 500, // Total number of entries for the form
    "recordsFiltered": 6, // The amount of entries with the required filters
    "data": [
        // Array data
        {
            "id": DATA_ID, // The data ID you will new in a few moments
            // ...
        },
        // ...
    ]
}