Introduction

CYS is a cloud-based Research, Data management and Data visualisation platform. One software solution for combining all relevant data and feedback from customers, employees and business. Pre-designed customizable programs designed for prioritizing your companies’ improvements like Customer Feedback Monitoring, Employee Engagement Research, Audits and Checklists for quality management and the reporting of business KPI’s.

CYS provides a great user and respondent experience by providing one intelligent and intuitive solution for storytelling, 1-on-1 feedback loops, approachable multi-channel questionnaires, easy to use quality checklists and audits, connecting and improving your companies data and providing cutting-edge reporting and visualizations. Available for every stakeholder on any device at any time.

The CYS API belongs to the Representational State Transfer (REST) category. They allow you to perform 'RESTful' operations such as reading, modifying, adding, or deleting data from your CYS portal.

What API Commands are used by CYS?

CYS APIs returns data into plain JSON over HTTP and use the following HTTP verbs.

Command Purpose
POST Create an object, Imports using file or json.
GET Fetch respective data from CYS Portal.
DELETE Delete an object from CYS Portal
PATCH Update an object by receiving data from CYS Portal.

What Rate Limits are allowed by CYS?

The number of API calls per minute is based on your plan. This limit is applied on an account wide basis irrespective of factors such as the number of agents or IP addresses used to make the calls.

Below are our policies.
Plan Default Medium Large
Rate Limits Per Second – 5
Per Minute – 100
Per Hour – 1000
Per Day – 5000
Per Second – 5
Per Minute – 100
Per Hour – 1000
Per Day – 5000
Per Second – 100
Per Minute – 250
Per Hour – 25000
Per Day – 250000

How do the API keys work?

To allow every customer to work with different suppliers, customers, or stakeholders the CYS portal enables every portal to create multiple API Keys with different access levels. Each key can be given access to any or all imports, any, or all projects, any or all schedulers and in case of the Dashboard Calculate API a key gives access to one dashboard JSON. Make sure that in the portal the correct settings are applied in order to make it work correctly.

NOTE:

At CYS we have extremely flexible databases. Our databases are built around your data and your research. This means that every database, import, and table is unique. This means that it is impossible to explain here which databases fields are available in which projects. Make sure when you start that you have access, or know exactly, what fields are in your project and portal.

Where do you find API Key?

If you click on Data garden left menu in the portal you will find a sub menu called API Management.

find_API

You can create a key by clicking on Add API Key button in the screen. While creating a key you can choose suitable configuration as per your requirement as shown in below image.

find_API_1

You need to copy Generated Key to access CYS APIs. You can select your preferred access level by enabling import, projects, or schedulers to access data from the system. Generated key works on selected configuration.

For example - In the above image I have only enabled imports and I have selected only one import in the drop down. So, with this API key I can only access data from CSD-485T2 Import, I cannot access data from projects, schedulers, or dashboards.

CYS API’s

API Key

All CYS APIs require a API Key Header passed in all requests. For all APIs mentioned below, along with the parameters listed for the API, this API Key will be required as a Header as well.

Parameter Value(Example) Type Data Type
APIKey CvGhP4Ul/qv5BSHb6D/d4oBvoMyc+6atakMhj+atbLU= Header String
Parameter Description
APIKey You will receive an API key from the CYS Portal

Import

With the API import functions you are able to directly add records to your import slot by processing them from a file or by adding individual JSON records. In addition to that, you can also export the records that are available within an import slot.

Get import records

GET/public/api/import

This API will return you the data belongs to specific import slot you have created in your system. There are certain parameters you need to pass as an input to this API.

Parameter Value(Example) Type Data Type
ImportId 1 Query Integer
VersionId 1 Query Integer
Filter sys_importBatchNumber = 1 AND sys_createdOn <= '2022-06-03' Query String
Parameter Description
ImportId Unique Id of an Import
VersionId You need to pass 1 as a default version for imports
Filter You need to pass any data to get filtered results from the system. Example you can see in above table.

Add records

POST/public/api/import

This API you can use to insert new records into an import slot. You need to pass posted file as a parameter to insert records.

Parameter Value(Example) Type Data Type
ImportId 1 Query Integer
VersionId 1 Query Integer
File Upload posted file here FormData File
Parameter Description
ImportId Unique Id of an Import
VersionId You need to pass 1 as a default version for imports
File You can use file upload control to get a file from local computer, Pass the file as posted file/Form data.

POST/public/api/importJSON

This API you can use to insert new records into an import slot using JSON object. JSON format is list of "Key" : "Value" Pair to insert records. Here Key="ColumnName" and Value="Values to Insert under ColumnName"

Parameter Value(Example) Type Data Type
importInfo

Structure

{
"Data": "string",
"importId": 0,
"versionId": 0
}

Example

{

"Data": '[

{

    "first_name": "Aleshia",

    "last_name": "Tomkiewicz",

    "city": "St. Stephens Ward",

    "county": "Kent",

    "postal": "CT2 7PP",

},

{

    "first_name": "Evan",

    "last_name": "Zigomalas",

    "city": "Abbey Ward",

    "county": "Buckinghamshire",

    "postal": "HP11 2AX",

}

]',

  "importId": 640,

  "versionId": 3

}

FormData JSON Object
Parameter Description
ImportId

Data :
- Use ' (single quote) character to enclose JSON data if key : values pair enclosed with " (double quote) else vice-versa.
- Use opening and closing [ ] (square brackets) inside the single quote. For example:
      ‘[ {data1}, {data2},……,{dataN} ]’.

importId : Unique Id of an Import.

versionId : You need to pass 1 as a default version for imports.

Export records from import (Excel)

GET/public/api/import/exportdata

This API will return excel file as a response of the API. Excel file will contain data belongs to specific import slot you have created in your system. There are certain parameters you need to pass as an input to this API.

Parameter Value(Example) Type Data Type
ImportId 1 Query Integer
VersionId 1 Query Integer
Filter sys_importBatchNumber = 1 AND sys_createdOn <= '2022-06-03' Query String
skip 10 Query long
take 20 Query long
columns Column1, Column2 Que1_page5_Text,Que2_page6_Text string
Parameter Description
ImportId Unique Id of an Import
VersionId You need to pass 1 as a default version for imports
Filter You need to pass any data to get filtered results from the system. Example you can see in above table.
skip Skips those many number of records. You also need to pass the value of take to fetch the values after skip
take Picks up those many number of records
columns Name of columns to be exported

Project

With the API project functions you can easily retrieve the data from your project database or export them into an Excel file.

Get project records

GET/public/api/project

This API will return you the data belongs to specific project and version you have created in your system. There are certain parameters you need to pass as an input to this API.

Parameter Value(Example) Type Data Type
projectId 1 Query Integer
versionId 1 Query Integer
filter sys_respondentStatus = 2 AND sys_completedDate <= '2022-03-07' Query String
Parameter Description
projectId Unique Id of a Project
versionId Version Id for project
filter You need to pass any data to get filtered results from the system. Example you can see in above table.

Export records from project

GET/public/api/project/exportdata

This API will return excel file as a response of the API. Excel file will contain data belongs to specific project and version you have created in your system. There are certain parameters you need to pass as an input to this API.

Parameter Value(Example) Type Data Type
projectId 1 Query Integer
versionId 1 Query Integer
filter sys_respondentStatus = 2 AND sys_completedDate <= '2022-03-07' Query String
skip 10 Query long
take 20 Query long
columns Column1, Column2 Que1_page5_Text,Que2_page6_Text string
Parameter Description
projectId Unique Id of a Project
versionId Version Id for project
filter You need to pass any data to get filtered results from the system. Example you can see in above table.
skip Skips those many number of records. You also need to pass the value of take to fetch the values after skip
take Picks up those many number of records
columns Name of columns to be exported

Delete project record, by respondentId

DELETE/public/api/project

Delete one record from a project database. There are certain parameters you need to pass as an input to this API.

Parameter Value(Example) Type Data Type
projectId 1 Query Integer
versionId 1 Query Integer
respondentId b8a27346-ec3c-4ec1-8d5b-d1c1f23023fa Query String
Parameter Description
projectId The projectId of the project that contains the respondentids to delete.
versionId Set to -1 to always get the current live version
respondentId The respondent id to delete.

Delete multiple project records, by respondentId

DELETE/public/api/project/many

Delete one or more records from a project database. There are certain parameters you need to pass as an input to this API.

Parameter Value(Example) Type Data Type
projectId 1 Query Integer
versionId 1 Query Integer
respondentIds ["399ea547-9be1-4b9b-89e3-9ca13e60608b","b8a27346-ec3c-4ec1-8d5b-d1c1f23023fa"] Body Array[string]
Parameter Description
projectId The projectId of the project that contains the respondentids to delete.
versionId Set to -1 to always get the current live version
respondentIds The List of respondentIds to delete.

Export media

POST/public/api/project/exportmedia

Export all media files for a project

Parameter Value(Example) Type Data Type
projectId 1 Query Integer
callbackUrl Query String
Parameter Description
projectId The projectId of the project for which to export the media.
callbackUrl The export of media is an asynchronous action, it returns immediately. Once the export file is ready, the callbackUrl is called with the unique Id and the file url as parameters: callbackUrl?uniqueId=id&url=fileUrl

Blacklist

With the API blacklist functions you can easily retrieve the data from your blacklist as well as add, update and delete blacklist records the list.

List existing blacklists

GET/public/api/blacklist/list

List all available BlackLists in the system.

Find e-mail records in a blacklist

GET/public/api/blacklist/find

Find all recordings of a specific e-mail address within the specified blacklist. There are certain parameters you need to pass as an input to this API.

Parameter Value(Example) Type Data Type
blackListId 1 Query Integer
emailAddress john.baker@gmail.com Query String
Parameter Description
blackListId Unique blacklist id
emailAddress The email address to find

Export complete blacklist

POST/public/api/blacklist/export

Update a single blacklist record, the original record is retrieved by its unique id, the blacklist id is validated against the one passed on the call. Only the e-mail, ExpiredOn and IsActive fields can be amended. There are certain parameters you need to pass as an input to this API.

Parameter Value(Example) Type Data Type
blackListId 1 Query Integer
Parameter Description
blackListId Unique blacklist id

Update a blacklist record

POST/public/api/blacklist/update

Update a single blacklist record, the original record is retrieved by its unique id, the blacklist id is validated against the one passed on the call. Only the e-mail, ExpiredOn and IsActive fields can be amended. There are certain parameters you need to pass as an input to this API.

Parameter Value(Example) Type Data Type
blackListRecord

{
"Id": 1,
"Email": "paul.symonds@gmail.com",
"BlacklistId": 1,
"IsActive": true,
"ExpiredOn": "2021-12-13T06:33:07.965Z"
}

Body Model
Parameter Description
blackListRecord A full BlackListRecord model with the updated information

Add a blacklist record

POST/public/api/blacklist/add

Add a single blacklist record. The record should contain the BlackListId, Email, ExpiredOn, IsActive and Source fields. Other fields are ignored. There are certain parameters you need to pass as an input to this API.

Parameter Value(Example) Type Data Type
blackListRecord

{
"Id": 0,
"Email": "paul.symonds@gmail.com",
"BlacklistId": 1,
"IsActive": true,
"ExpiredOn": "2021-12-13T06:33:07.965Z" }

Body Model
Parameter Description
blackListRecord A full BlackListRecord model with the new information.

Add multiple blacklist records

POSTpublic/api/blacklist/addmany

Add one or more blacklist records. There are certain parameters you need to pass as an input to this API.

Parameter Value(Example) Type Data Type
List

[
{
"Id": 0,
"Email": "david.smith@gmail.com",
"BlacklistId": 1,
"IsActive": true,
"ExpiredOn": "2021-12-13T06:33:07.973Z"
},
{
"Id": 0,
"Email": "stela.stokes@gmail.com",
"BlacklistId": 2,
"IsActive": true,
"ExpiredOn": "2021-12-13T06:33:07.973Z"
}
]

Body Model
Parameter Description
List A list of BlackListRecord passed or null in case of error

Delete blacklist record

POST/public/api/blacklist/delete

Delete a blacklist record. There are certain parameters you need to pass as an input to this API.

Parameter Value(Example) Type Data Type
blackListRecord

{
"Id": 1,
"Email": "david.smith@gmail.com",
"BlacklistId": 1,
"IsActive": true,
"ExpiredOn": "2021-12-13T06:33:07.976Z"
}

Body Model
Parameter Description
blackListRecord The BlackListRecord model of the record you wish to delete.

Delete blacklist record by e-mail address

POST/public/api/blacklist/deletebyemail

Delete one or more blacklist records based e-mail address. There are certain parameters you need to pass as an input to this API.

Parameter Value(Example) Type Data Type
blackListId 1 Query Integer
emailAddress john.baker@gmail.com Query String
Parameter Description
blackListId The unique id of the blacklist that contains the record to delete.
emailAddress The e-mail address you wish to delete from this list

Scheduler

With the API scheduler functions you can easily retrieve the data from your project data schedules as well as add,update and delete schedulers.

Delete specific scheduler

DELETE/public/api/scheduler

Delete a specific scheduler. There are certain parameters you need to pass as an input to this API.

Parameter Value(Example) Type Data Type
projectId 1 Query Integer
schedulerId 1 Query Integer
Parameter Description
projectId The projectId of the project to which the scheduler is linked.
schedulerId The unique id of the scheduler you want to delete

List scheduler for a specific project

GET/public/api/scheduler

Get a list of all schedulers linked to the specified project. There are certain parameters you need to pass as an input to this API.

Parameter Value(Example) Type Data Type
projectId 1 Query Integer
Parameter Description
projectId The projectId for which to retrieve the schedulers.

Create new blank scheduler

POST/public/api/scheduler

Create a new blank scheduler. There are certain parameters you need to pass as an input to this API.

Parameter Value(Example) Type Data Type
projectId 1 Query Integer
name Hospital Survey Query String
typeId 1 Query Integer
Parameter Description
projectId The projectId for which to retrieve the schedulers.
name The name of the schedule
typeId The scheduler type id

Get the configuration of the scheduler

GET/public/api/scheduler/config

Get the configuration for a specific scheduler. There are certain parameters you need to pass as an input to this API.

Parameter Value(Example) Type Data Type
projectId 1 Query Integer
schedulerId 1 Query Integer
Parameter Description
projectId The projectId of the project to which the scheduler should be linked.
schedulerId The unique schedule id

Update the configuration of the scheduler

POST/public/api/scheduler/config

Update the configuration for a specific scheduler. There are certain parameters you need to pass as an input to this API.

Parameter Value(Example) Type Data Type
model

{
"fieldHeaders": [
{
"fieldKey":"EmpName","fieldType":"2","displayName":"Employee Name"
}
],
"ProjectId": 1,
"ScheduleId": 1
}

Body Model
Parameter Description
Model A full SchedulerConfigModel object.

List scheduler groups

POST/public/api/scheduler/groups

List all groups that can be used to set on the scheduler. There are certain parameters you need to pass as an input to this API.

Parameter Value(Example) Type Data Type
projectId 1 Query Integer
Parameter Description
projectId The project that should be used.

List scheduler users

GET/public/api/scheduler/users

List all users that can be used to set on the scheduler. There are certain parameters you need to pass as an input to this API.

Parameter Value(Example) Type Data Type
projectId 1 Query Integer
schedulerId 1 Query Integer
Parameter Description
projectId The project that should be used.
schedulerId The schedulerId to use.

Delete scheduler quota

DELETE/public/api/scheduler/quotas

Delete a specific scheduler quota. There are certain parameters you need to pass as an input to this API.

Parameter Value(Example) Type Data Type
projectId 1 Query Integer
schedulerId 1 Query Integer
quotaId 1 Query Integer
Parameter Description
projectId The project that should be used.
schedulerId The schedulerId to use.
quotaId The unique id of the quota to delete.

Get scheduler quotas for a scheduler

GET/public/api/scheduler/quotas

Get all quotas for a specific schedule. There are certain parameters you need to pass as an input to this API.

Parameter Value(Example) Type Data Type
projectId 1 Query Integer
schedulerId 1 Query Integer
Parameter Description
projectId The project that should be used.
schedulerId The schedulerId to use.

Update quota for a scheduler

PATCH/public/api/scheduler/quotas

Update quota for a specific scheduler. There are certain parameters you need to pass as an input to this API.

Parameter Value(Example) Type Data Type
model

{
"ProjectId": 1,
"QuotaId": 1,
"SchedulerId": 1,
"GroupId": 1,
"StartDate": "2021-12-13T09:34:10.252Z",
"EndDate": "2021-12-24T09:34:10.252Z",
"Quota": 10,
"FieldInstance": [{"fieldKey":"ID_1","fieldType":"1","displayName":"Id1","fieldValue":"IRIS"},{"fieldKey":"ID_2","fieldType":"1","displayName":"Id2","fieldValue":null}],
"Users": [
1,2,3
],
"UserId": 1 }

Body Model
Parameter Description
Module An object of type SchedulerQuotaModel.

Create quota for a schedulerdate quota for a scheduler

POST/public/api/scheduler/quotas

Create quota for a specific scheduler. There are certain parameters you need to pass as an input to this API.

Parameter Value(Example) Type Data Type
model

{
"ProjectId": 1,
"QuotaId": 1,
"SchedulerId": 1,
"GroupId": 1,
"StartDate": "2021-12-13T09:34:10.252Z",
"EndDate": "2021-12-24T09:34:10.252Z",
"Quota": 10,
"FieldInstance": [{"fieldKey":"ID_1","fieldType":"1","displayName":"Id1","fieldValue":"123"},{"fieldKey":"ID_2","fieldType":"1","displayName":"Name","fieldValue":"Brenda Wright"}],
"Users": [
1,2,3
],
"UserId": 1
}

Body Model
Parameter Description
Module An object of type SchedulerQuotaModel.

Create export of all quotas for a scheduler

POST/public/api/scheduler/quotas/export

Create export of all quotas for a specific scheduler. There are certain parameters you need to pass as an input to this API.

Parameter Value(Example) Type Data Type
projectId 1 Query Integer
schedulerId 1 Query Integer
Parameter Description
projectId The unique project id.
schedulerId The unique scheduler id for the export

Dashboard

With the API dashboard functions you are able to retrieve the reported data from your dashboard. This way you are able to obtain calculated results from your project as well.

To call dashboard API, you need to pass details in json format while creating a key in the API key management menu. Json contains details like dashboard Id, Filters, Data point request etc.

Please see below image for more details.

image

Get dashboard data

GET/public/api/dashboard

POST/public/api/dashboard

Sample Code

Request URL
https://api.cys.group/public/api/dashboard
Response Body
                                {
                                    "IsSuccess": true,
                                    "Message": "SUCCESS",
                                    "Data": {
                                      "Request": {
                                        "dashboardId": "4",
                                        "periodType": 0,
                                        "periodCustomVariable": null,
                                        "periodFinishedOnly": true,
                                        "periodStartMonth": 2,
                                        "periodGrouping": "20",
                                        "SelectedFilters": {
                                          "period": {
                                            "selected": true,
                                            "Start": null,
                                            "End": "2021-01-31T00:00:00"
                                          },
                                          "user": []
                                        },
                                        "dataPoints": [
                                          {
                                            "id": "896-b98-6fb-aaa-b1a-88b-0bc-8bb-f29",
                                            "type": "api",
                                            "call": "SPB.1",
                                            "mainType": "2",
                                            "mainTypeReversedScales": false,
                                            "projectId": "10",
                                            "variables": {
                                              "main": "page5_Text",
                                              "compare": {
                                                "name": "",
                                                "exclude": []
                                              },
                                              "group": null,
                                              "oa": null,
                                              "rc1": null,
                                              "rc2": null
                                            },
                                            "SelectedFilters": {
                                              "period": null,
                                              "user": [
                                                {
                                                  "variableName": "Region",
                                                  "value": "1"
                                                }
                                              ]
                                            },
                                            "addMTD": false,
                                            "addQTD": false,
                                            "addYTD": false,
                                            "addStandardDeviation": false,
                                            "addGrowthPP": true,
                                            "addScales": true,
                                            "addBreakDown": false,
                                            "addRanking": 0,
                                            "ExcludeFromMainFilter": false,
                                            "Limit": 0,
                                            "MinimumN": 0,
                                            "PeriodCount": 1,
                                            "IncludeCategories": "",
                                            "Paging": {
                                              "start": 0,
                                              "pageSize": 0
                                            },
                                            "IncludeNew": false,
                                            "IncludeActive": false,
                                            "IncludeCompleted": true
                                          }
                                        ],
                                        "defaultPeriodVariableName": "[sys_completedDate]",
                                        "weightVariable": "1.0"
                                      },
                                      "DataPoints": [
                                        {
                                          "Values": [
                                            {
                                              "MainValue": {
                                                "Value": -40,
                                                "N": 195,
                                                "ValueString": "-40",
                                                "Sign": "NPS {0}",
                                                "GrowthRaw": -10,
                                                "GrowthPercent": 33.33333333333333
                                              },
                                              "MainN": {
                                                "Value": 195,
                                                "N": 195,
                                                "ValueString": "195",
                                                "Sign": "",
                                                "GrowthRaw": null,
                                                "GrowthPercent": null
                                              },
                                              "MainRed": {
                                                "Value": null,
                                                "N": null,
                                                "ValueString": "",
                                                "Sign": "%",
                                                "GrowthRaw": null,
                                                "GrowthPercent": null
                                              },
                                              "MainBlue": {
                                                "Value": null,
                                                "N": null,
                                                "ValueString": "",
                                                "Sign": "%",
                                                "GrowthRaw": null,
                                                "GrowthPercent": null
                                              },
                                              "MainGreen": {
                                                "Value": null,
                                                "N": null,
                                                "ValueString": "",
                                                "Sign": "%",
                                                "GrowthRaw": null,
                                                "GrowthPercent": null
                                              },
                                              "PeriodType": 0,
                                              "Category": null,
                                              "CategoryCode": null,
                                              "Series": "2021 Jan",
                                              "SeriesCode": "1",
                                              "Group": null,
                                              "GroupCode": null,
                                              "DrillDownFilter": null,
                                              "GrowthPreviousPeriod": "2020 Dec",
                                              "StartDate": null,
                                              "Today": "2021-01-31T00:00:00",
                                              "DaysBetween": 0,
                                              "RankingPosition": 0
                                            }
                                          ],
                                          "ScaleMin": -100,
                                          "ScaleMax": 100,
                                          "HasDataBeforeMinN": true,
                                          "DataPointId": "896-b98-6fb-aaa-b1a-88b-0bc-8bb-f29"
                                        }
                                      ]
                                    },
                                    "StatusCode": 200
                                  }
                                  
                            

Best Practices

Rate Limit
  • Whenever possible, please queue API calls at your end. This ensures that you can buffer calls on your end to avoid hitting the rate limit and retry API calls when you hit the rate limit after the retry-after time.
  • Cache non-volatile data on your end whenever it is feasible. For e.g., the mapping between agent name and ID is extremely unlikely to change. Hence, by caching it on the client side, you will be able to avoid API calls.
  • As soon as you recognise that a rate limit increase will be required in the future, contact us. This will make it possible for us to ensure that we are prepared to increase the limit as and when as it is needed.