Paths

Import survey definition.

POST /

Description

Imports survey definition. Definition has to be a zipped XML file. Sample request:

POST /

Responses

HTTP Code Description Schema

200

Accepted, the request has been accepted for processing. The import information is returned.

400

Bad request, the survey import was not successful.

401

Unauthorized

No Content

Produces

  • application/json

Tags

  • Surveys

Example HTTP response

Response 200

{
  "projectId" : "p1234567890"
}

Response 400

{
  "message" : "Bad request. Operation was not successful."
}

Get surveys.

GET /

Description

Returns a list of surveys. Sample request:

GET /

Parameters

Type Name Description Schema Default

Query

companyId
optional

Filter surveys for the given CompanyId.

integer (int32)

0

Query

keyword
optional

Filter surveys where Keywords contains the given value.

string

""

Query

name
optional

Filter surveys where Name contains the given value.

string

""

Query

page
optional

Use this when paging through the surveys (default=1). Optional. Ex: Append page=4 to the query parameters.

integer (int32)

1

Query

pageSize
optional

Number of surveys to retrieve per request (default=100). Optional. Ex: Append pageSize=20 to the query parameters. Max value is 5000.

integer (int32)

100

Query

wiLastGenerated
optional

Filter surveys based on WiLastGenerated. Format should be 'operator YYYY-MM-DD HH:MM:SS'. Ex '> 2024-12-24 23:59:59'. Supported operators are '=,<,>'. NB! When using the '=' operator, hours, minutes and seconds will not be applied.

string

""

Responses

HTTP Code Description Schema

200

Ok, the request has succeeded. The list of surveys is returned.

400

Bad request, the query parameters are not valid.

401

Unauthorized

No Content

Produces

  • application/json

Tags

  • Surveys

Example HTTP response

Response 200

{
  "itemCount" : 3,
  "totalCount" : 301,
  "items" : [ {
    "id" : "p00001",
    "name" : "My first survey",
    "creatorFullName" : "Johnson, Mark",
    "companyId" : 23,
    "companyName" : "Testing Ltd",
    "status" : "production",
    "created" : "2018-08-08T21:22:23+00:00",
    "type" : "survey",
    "keywords" : [ "test1", "test2" ],
    "lastModified" : "2020-08-08T21:22:23+00:00",
    "lastDataStateChange" : "2022-01-03T01:22:23+00:00",
    "wiLastGenerated" : "2021-03-04T22:11:23+00:00"
  }, {
    "id" : "p00002",
    "name" : "My second survey",
    "creatorFullName" : "Hanson, John",
    "companyId" : 23,
    "companyName" : "Testing Ltd",
    "status" : "closed",
    "created" : "2018-08-03T21:22:23+00:00",
    "type" : "survey",
    "keywords" : [ "AA", "BB" ],
    "lastModified" : "2020-08-08T21:22:23+00:00",
    "lastDataStateChange" : "2022-01-03T01:22:23+00:00",
    "wiLastGenerated" : "2021-03-04T22:11:23+00:00"
  }, {
    "id" : "p00003",
    "name" : "AutoCombined survey",
    "creatorFullName" : "Johnson, Mark",
    "companyId" : 23,
    "companyName" : "Testing Ltd",
    "status" : "production",
    "created" : "2018-04-08T21:22:23+00:00",
    "type" : "autoCombinedSurvey",
    "lastModified" : "2020-08-08T21:22:23+00:00",
    "lastDataStateChange" : "2022-01-03T01:22:23+00:00"
  } ],
  "links" : {
    "nextpage" : "http://host/v1/surveys/?pageSize=20&page=5",
    "prevpage" : "http://host/v1/surveys/?pageSize=20&page=3",
    "item" : "http://host/v1/surveys/{surveyId}"
  }
}

Response 400

{
  "message" : "The query parameters are not valid: ... ."
}

Get languages.

GET /languages

Description

Returns languages. Sample request:

GET /languages

Responses

HTTP Code Description Schema

200

Ok, the request has succeeded. The language is returned.

400

Bad request, the query parameters are not valid.

401

Unauthorized

No Content

404

Not found, the language was not found.

Produces

  • application/json

Tags

  • Languages

Example HTTP response

Response 200

{
  "itemCount" : 3,
  "totalCount" : 3,
  "items" : [ {
    "id" : 9,
    "name" : "English",
    "rightToLeft" : false
  }, {
    "id" : 20,
    "name" : "Norwegian",
    "rightToLeft" : false
  }, {
    "id" : 29,
    "name" : "Swedish",
    "rightToLeft" : false
  } ],
  "links" : { }
}

Response 400

{
  "message" : "The query parameters are not valid: ... ."
}

Response 404

{
  "message" : "... not found."
}

Get language by Id.

GET /languages/{id}

Description

Returns language. Sample request:

GET /languages/9

Parameters

Type Name Description Schema

Path

id
required

The Confirmit Language Id of the language.

integer (int32)

Responses

HTTP Code Description Schema

200

Ok, the request has succeeded. The language is returned.

400

Bad request, the query parameters are not valid.

401

Unauthorized

No Content

404

Not found, the language was not found.

Produces

  • application/json

Tags

  • Languages

Example HTTP response

Response 200

{
  "id" : 29,
  "name" : "Swedish",
  "rightToLeft" : false,
  "subLanguages" : [ {
    "id" : 1053,
    "primaryLanguageId" : 29,
    "name" : "Swedish",
    "countryName" : "Sweden",
    "rightToLeft" : false
  }, {
    "id" : 2077,
    "primaryLanguageId" : 29,
    "name" : "Swedish",
    "countryName" : "Finland",
    "rightToLeft" : false
  } ]
}

Response 400

{
  "message" : "The query parameters are not valid: ... ."
}

Response 404

{
  "message" : "... not found."
}

Get language by Name.

GET /languages/{name}

Description

Returns language. Sample request:

GET /languages/English

Parameters

Type Name Description Schema

Path

name
required

The Name of the language.

string

Responses

HTTP Code Description Schema

200

Ok, the request has succeeded. The language is returned.

400

Bad request, the query parameters are not valid.

401

Unauthorized

No Content

404

Not found, the language was not found.

Produces

  • application/json

Tags

  • Languages

Example HTTP response

Response 200

{
  "id" : 29,
  "name" : "Swedish",
  "rightToLeft" : false,
  "subLanguages" : [ {
    "id" : 1053,
    "primaryLanguageId" : 29,
    "name" : "Swedish",
    "countryName" : "Sweden",
    "rightToLeft" : false
  }, {
    "id" : 2077,
    "primaryLanguageId" : 29,
    "name" : "Swedish",
    "countryName" : "Finland",
    "rightToLeft" : false
  } ]
}

Response 400

{
  "message" : "The query parameters are not valid: ... ."
}

Response 404

{
  "message" : "... not found."
}

Get language by CountryName.

GET /languages/{name}/{countryName}

Description

Returns language. Sample request:

GET /languages/English/Belize

Parameters

Type Name Description Schema

Path

countryName
required

The CountryName of the language.

string

Path

name
required

The Name of the language.

string

Responses

HTTP Code Description Schema

200

Ok, the request has succeeded. The language is returned.

400

Bad request, the query parameters are not valid.

401

Unauthorized

No Content

404

Not found, the language was not found.

Produces

  • application/json

Tags

  • Languages

Example HTTP response

Response 200

{
  "id" : 10249,
  "primaryLanguageId" : 9,
  "name" : "English",
  "countryName" : "Belize",
  "rightToLeft" : false
}

Response 400

{
  "message" : "The query parameters are not valid: ... ."
}

Response 404

{
  "message" : "... not found."
}

Get survey.

GET /{surveyId}

Description

Returns information about a survey or zipped xml survey definition. Result is defined by request’s Accept header. Sample request:

GET /p00012334

Parameters

Type Name Description Schema

Path

surveyId
required

The id of the survey

string

Responses

HTTP Code Description Schema

200

Ok, the request has succeeded. The survey is returned. If Accept header was set to application/zip then the survey definition zip file is returned.

400

Bad request, the query parameters are not valid.

401

Unauthorized

No Content

404

Not found, the survey was not found.

Produces

  • application/json

  • application/zip

Tags

  • Surveys

Example HTTP response

Response 200

{
  "status" : "Production",
  "companyId" : 25,
  "companyName" : "Test Inc.",
  "creatorUserName" : "testuser",
  "creatorFullName" : "Tester, John",
  "lastModified" : "2001-01-01 10:11:12",
  "description" : "Used to collect some data",
  "name" : "My test survey",
  "id" : "p0001234"
}
{
  "application/json" : {
    "status" : "Production",
    "companyId" : 25,
    "companyName" : "Test Inc.",
    "creatorUserName" : "testuser",
    "creatorFullName" : "Tester, John",
    "lastModified" : "2001-01-01 10:11:12",
    "description" : "Used to collect some data",
    "name" : "My test survey",
    "id" : "p0001234"
  },
  "application/zip" : {
    "status" : "Production",
    "companyId" : 25,
    "companyName" : "Test Inc.",
    "creatorUserName" : "testuser",
    "creatorFullName" : "Tester, John",
    "lastModified" : "2001-01-01 10:11:12",
    "description" : "Used to collect some data",
    "name" : "My test survey",
    "id" : "p0001234"
  }
}

Response 400

{
  "message" : "The query parameters are not valid: ... ."
}
{
  "application/json" : {
    "message" : "The query parameters are not valid: ... ."
  },
  "application/zip" : {
    "message" : "The query parameters are not valid: ... ."
  }
}

Response 404

{
  "message" : "... not found."
}
{
  "application/json" : {
    "message" : "... not found."
  },
  "application/zip" : {
    "message" : "... not found."
  }
}

Get data state for a survey.

GET /{surveyId}/datastate

Description

Returns data state information for a survey. Sample request:

GET /p00012334/datastate

Parameters

Type Name Description Schema

Path

surveyId
required

The id of the survey

string

Responses

HTTP Code Description Schema

200

Ok, the request has succeeded. The data state is returned.

400

Bad request, the query parameters are not valid.

401

Unauthorized

No Content

404

Not found, the survey was not found.

Produces

  • application/json

Tags

  • Surveys

Example HTTP response

Response 200

{
  "lastLaunch" : "2020-02-04T14:02:34+00:00",
  "lastCreateNew" : "2020-02-01T13:10:10+00:00",
  "maxLastTouched" : "2020-02-25T10:05:04+00:00",
  "currentChangeTrackingVersion" : 12003
}

Response 400

{
  "message" : "The query parameters are not valid: ... ."
}

Response 404

{
  "message" : "... not found."
}

Get survey hierarchies.

GET /{surveyId}/hierarchies/{hierarchyId}

Description

Returns information about a survey’s hierarchies. Sample request:

GET /p00012334/hierarchies/567

Parameters

Type Name Description Schema

Path

hierarchyId
required

The id of the hierarchy to retrieve

integer (int32)

Path

surveyId
required

The id of the survey

string

Responses

HTTP Code Description Schema

200

Ok, the request has succeeded. The survey hierarchy is returned.

400

Bad request, the query parameters are not valid.

401

Unauthorized

No Content

404

Not found, the survey hierarchy was not found.

Produces

  • application/json

Tags

  • Surveys

Example HTTP response

Response 200

{
  "id" : 567,
  "name" : "LookupHierarchy",
  "nodes" : [ {
    "id" : "confirmit",
    "label" : "CONFIRMIT",
    "attributes" : {
      "benchmark" : "survey1",
      "score" : "10"
    },
    "children" : [ {
      "id" : "rd",
      "label" : "RD",
      "attributes" : {
        "benchmark" : "survey2",
        "score" : "3"
      },
      "children" : [ {
        "id" : "rd_Norway",
        "label" : "RD_NORWAY",
        "attributes" : {
          "benchmark" : "survey3",
          "score" : "6"
        }
      }, {
        "id" : "rd_US",
        "label" : "RD_US",
        "attributes" : {
          "benchmark" : "survey4",
          "score" : "1"
        }
      } ]
    }, {
      "id" : "qa",
      "label" : "QA",
      "attributes" : {
        "benchmark" : "survey5",
        "score" : "8"
      }
    } ]
  } ]
}

Response 400

{
  "message" : "The query parameters are not valid: ... ."
}

Response 404

{
  "message" : "... not found."
}

Gets a list of the hubs the survey is added to.

GET /{surveyId}/hubs

Description

It only lists hubs the user has access to. Sample request:

GET /p00012334/hubs

Parameters

Type Name Description Schema

Path

surveyId
required

The id of the survey

string

Responses

HTTP Code Description Schema

200

Ok, the request has succeeded. The data state is returned.

400

Bad request, the query parameters are not valid.

401

Unauthorized

No Content

404

Not found, the survey was not found.

Produces

  • application/json

Tags

  • Surveys

Example HTTP response

Response 200

{
  "itemCount" : 2,
  "totalCount" : 2,
  "items" : [ {
    "hubId" : 3455,
    "name" : "TestHub1",
    "links" : {
      "self" : "http://www.confirmit.com/v1/hubs/3455"
    }
  }, {
    "hubId" : 1718,
    "name" : "TestHub2",
    "links" : {
      "self" : "http://www.confirmit.com/v1/hubs/1718"
    }
  } ],
  "links" : { }
}

Response 400

{
  "message" : "The query parameters are not valid: ... ."
}

Response 404

{
  "message" : "... not found."
}

Create survey launch.

POST /{surveyId}/launches

Description

Requests survey launch. Sample request:

POST /p123123/launches
{
    "mode": "Test",
    "generationMode": "CreateNew",
    "enforceNewVersion": true
}

Parameters

Type Name Description Schema

Path

surveyId
required

The id of the survey

string

Body

body
optional

Survey launch options

Responses

HTTP Code Description Schema

202

Accepted, the request has accepted for processing. The launch information is returned.

401

Unauthorized

No Content

404

Not found, the survey was not found.

Consumes

  • application/json-patch+json

  • application/json

  • text/json

  • application/*+json

Produces

  • application/json

Tags

  • SurveyLaunches

Example HTTP response

Response 202

{
  "id" : 123,
  "status" : "queue",
  "taskId" : 0,
  "links" : {
    "self" : "http://www.confirmit.com/v1/surveys/p456789/launches/123",
    "all" : "http://www.confirmit.com/v1/surveys/p456789/launches",
    "cancel" : "http://www.confirmit.com/v1/surveys/p456789/launches/123/cancel"
  }
}

Response 404

{
  "message" : "Survey 'p123456' not found"
}

Get list of survey launches for one survey.

GET /{surveyId}/launches

Description

Returns list of survey launches for one survey. Sample request:

GET /p123123/launches

Parameters

Type Name Description Schema

Path

surveyId
required

The id of the survey

string

Responses

HTTP Code Description Schema

200

Ok, the list of launches is returned.

401

Unauthorized

No Content

404

Not found, the survey was not found.

Produces

  • application/json

Tags

  • SurveyLaunches

Example HTTP response

Response 200

{
  "itemType" : "surveyLaunches",
  "itemCount" : 3,
  "totalCount" : 10,
  "items" : [ {
    "id" : 234,
    "status" : "error",
    "taskId" : 0
  }, {
    "id" : 345,
    "status" : "aborted",
    "taskId" : 0
  }, {
    "id" : 456,
    "status" : "complete",
    "taskId" : 0
  } ],
  "links" : {
    "self" : "http://www.confirmit.com/v1/surveys/p456789/launches/123",
    "cancel" : "http://www.confirmit.com/v1/surveys/p456789/launches/123/cancel"
  }
}

Response 404

{
  "message" : "Survey 'p123456' not found"
}

Get information about single survey launch.

GET /{surveyId}/launches/{launchId}

Description

Returns information about single survey launch with optional log entries. Sample request:

GET /p123123/launches/456

Parameters

Type Name Description Schema

Path

launchId
required

The id of the launch

integer (int32)

Path

surveyId
required

The id of the survey

string

Query

LogStartDate
optional

Specify to get log entries only after this date. This date is not included.

string (date-time)

Query

LogTypes
optional

Types of log entries to get.

< LogTypes > array(multi)

Query

MaxLogEntries
optional

Maximum number of log entries to get.

integer (int32)

Responses

HTTP Code Description Schema

200

Ok, the launch information is returned.

401

Unauthorized

No Content

404

Not found, the survey or launch was not found.

Produces

  • application/json

Tags

  • SurveyLaunches

Example HTTP response

Response 200

{
  "id" : 123,
  "status" : "executing",
  "taskId" : 0,
  "logs" : {
    "itemType" : "surveyLaunchLogs",
    "itemCount" : 3,
    "totalCount" : 10,
    "items" : [ {
      "type" : "info",
      "timeStamp" : "2024-09-23T08:36:36.1143693+00:00",
      "text" : "Initializing..."
    }, {
      "type" : "info",
      "timeStamp" : "2024-09-23T08:36:37.1144453+00:00",
      "text" : "Generating..."
    }, {
      "type" : "info",
      "timeStamp" : "2024-09-23T08:36:38.114453+00:00",
      "text" : "Verifying..."
    } ],
    "links" : { }
  },
  "links" : {
    "self" : "http://www.confirmit.com/v1/surveys/p456789/launches/123",
    "all" : "http://www.confirmit.com/v1/surveys/p456789/launches",
    "cancel" : "http://www.confirmit.com/v1/surveys/p456789/launches/123/cancel"
  }
}

Response 404

{
  "message" : "Survey 'p123456' not found"
}

Cancel survey launch.

POST /{surveyId}/launches/{launchId}/cancel

Description

Requests survey launch is cancelled. Sample request:

POST /p123123/launches/456/cancel

Parameters

Type Name Description Schema

Path

launchId
required

The id of the launch

integer (int32)

Path

surveyId
required

The id of the survey

string

Responses

HTTP Code Description Schema

202

Accepted, the request has accepted for processing. The launch information is returned.

401

Unauthorized

No Content

404

Not found, the survey or launch was not found.

Produces

  • application/json

Tags

  • SurveyLaunches

Example HTTP response

Response 202

{
  "id" : 123,
  "status" : "queue",
  "taskId" : 0,
  "links" : {
    "self" : "http://www.confirmit.com/v1/surveys/p456789/launches/123",
    "all" : "http://www.confirmit.com/v1/surveys/p456789/launches",
    "cancel" : "http://www.confirmit.com/v1/surveys/p456789/launches/123/cancel"
  }
}

Response 404

{
  "message" : "Survey 'p123456' not found"
}

Get quotas.

GET /{surveyId}/quotas

Description

Returns the quotas for a survey. Sample request:

GET /p123123/quotas

Parameters

Type Name Description Schema

Path

surveyId
required

The id of the survey

string

Responses

HTTP Code Description Schema

200

Ok, the request has succeeded. The quotas are returned.

400

Bad request, the query parameters are not valid.

401

Unauthorized

No Content

404

Not found, the survey was not found.

Produces

  • application/json

Tags

  • Quotas

Example HTTP response

Response 200

{
  "itemCount" : 2,
  "totalCount" : 2,
  "items" : [ {
    "name" : "quota1",
    "emailAddress" : "user1@example.com",
    "isOptimisticQuota" : false,
    "liveLimit" : 0,
    "liveLimitType" : "fixed"
  }, {
    "name" : "quota2",
    "emailAddress" : "user2@example.com",
    "isOptimisticQuota" : true,
    "liveLimit" : 50,
    "liveLimitType" : "percent"
  } ],
  "links" : {
    "item" : "http://host/v1/surveys/p0001234/quotas/{quotaName}"
  }
}

Response 400

{
  "message" : "The query parameters are not valid: ... ."
}

Response 404

{
  "message" : "... not found."
}

Get quota.

GET /{surveyId}/quotas/{quotaName}

Description

Gets the quota for a survey by name. Sample request:

GET /p123123/quotas/quota1

Parameters

Type Name Description Schema

Path

quotaName
required

The name of the quota

string

Path

surveyId
required

The id of the survey

string

Responses

HTTP Code Description Schema

200

Ok, the request has succeeded. The quota are returned.

400

Bad request, the query parameters are not valid.

401

Unauthorized

No Content

404

Not found, the survey or quota was not found.

Produces

  • application/json

Tags

  • Quotas

Example HTTP response

Response 200

{
  "name" : "quota1",
  "emailAddress" : "user@example.com",
  "isOptimisticQuota" : false,
  "liveLimit" : 0,
  "liveLimitType" : "fixed",
  "links" : {
    "self" : "http://host/v1/surveys/p0001234/quotas/quota1",
    "limits" : "http://host/v1/surveys/p0001234/quotas/quota1/limits"
  }
}

Response 400

{
  "message" : "The query parameters are not valid: ... ."
}

Response 404

{
  "message" : "... not found."
}

Get quota limits.

GET /{surveyId}/quotas/{quotaName}/limits

Description

Gets the quota limits with runtime counters for a survey . Sample request:

GET /p123123/quotas/quota1/limits

GET /p123123/quotas/quota1/limits?environment=test

Parameters

Type Name Description Schema Default

Path

quotaName
required

The name of the quota

string

Path

surveyId
required

The id of the survey

string

Query

environment
optional

Include quota counters for test or production environment. Default is 'production'.

enum (Production, Test)

"Production"

Responses

HTTP Code Description Schema

200

Ok, the request has succeeded. The quota limits are returned.

< QuotaLimit > array

400

Bad request, the query parameters are not valid.

401

Unauthorized

No Content

404

Not found, the survey or quota was not found.

Produces

  • application/json

Tags

  • Quotas

Example HTTP response

Response 200

[ {
  "id" : "c5d81ea7-bf51-46dc-87b5-8d27605de5eb",
  "limit" : 10,
  "counter" : 9,
  "fields" : [ {
    "questionId" : "q1_single",
    "answerValue" : "blue",
    "answerValueText" : "Blue color"
  } ]
}, {
  "id" : "ae347f40-5c7b-4b6b-be57-4d05399f3c1b",
  "limit" : 5,
  "counter" : 0,
  "fields" : [ {
    "questionId" : "q2_multi",
    "answerCode" : "blue",
    "answerText" : "Blue color",
    "answerValue" : "1",
    "answerValueText" : "Chosen"
  }, {
    "questionId" : "q2_multi",
    "answerCode" : "green",
    "answerText" : "Green color",
    "answerValue" : "0",
    "answerValueText" : "Not Chosen"
  } ]
}, {
  "id" : "240e19ec-3526-4108-bed5-0cd8fa18688f",
  "limit" : 10,
  "counter" : 5,
  "fields" : [ {
    "questionId" : "q3_grid",
    "answerCode" : "blue",
    "answerText" : "Blue color",
    "answerValue" : "10",
    "answerValueText" : "Very good"
  }, {
    "questionId" : "q3_grid",
    "answerCode" : "green",
    "answerText" : "Green color",
    "answerValue" : "1",
    "answerValueText" : "Bad"
  } ]
}, {
  "id" : "035186f5-8490-4647-96ad-260f4f1e5090",
  "limit" : 2,
  "counter" : 2,
  "fields" : [ ]
} ]

Response 400

{
  "message" : "The query parameters are not valid: ... ."
}

Response 404

{
  "message" : "... not found."
}

Update quota limits.

PATCH /{surveyId}/quotas/{quotaName}/limits

Description

Update quota limit values. Currently only 'Limit' field can be modified. Quota limits for all quotas in a survey will be automatically synchronized between Design and Runtime. To disable quota synchronization, use sync=false querystring parameter. Sample request:

PATCH /p123123/quotas/quota1/limits
[
  { "id": "c574a171-9689-4a71-a13c-45f0cb3f8060", "limit": 99},
  { "id": "60ac6372-cedb-46db-972c-abadef14bece", "limit": 100}
]

PATCH /p123123/quotas/quota1/limits?environment=test
[
  { "id": "c574a171-9689-4a71-a13c-45f0cb3f8060", "limit": 10},
  { "id": "60ac6372-cedb-46db-972c-abadef14bece", "limit": 20}
]

Parameters

Type Name Description Schema Default

Path

quotaName
required

The name of the quota

string

Path

surveyId
required

The id of the survey

string

Query

environment
optional

Update quota limits for test or production environment. Default is 'production'.

enum (Production, Test)

"Production"

Query

sync
optional

Synchronize all quotas in the survey between Design and Runtime. Default is 'true'.

boolean

"true"

Body

body
optional

Quota limits patch payload

< QuotaLimitPatch > array

Responses

HTTP Code Description Schema

204

Ok, the request has succeeded.

No Content

400

Bad request, the query parameters are not valid.

401

Unauthorized

No Content

404

Not found, the survey or quota was not found.

Consumes

  • application/json-patch+json

  • application/json

  • text/json

  • application/*+json

Produces

  • application/json

Tags

  • Quotas

Example HTTP response

Response 400

{
  "message" : "The query parameters are not valid: ... ."
}

Response 404

{
  "message" : "... not found."
}

Add respondent data.

POST /{surveyId}/respondents/data

Description

Add new respondents to the survey database. If request succeeds then the response contains a SurveyDataChangeResponse object with the number of the records added. Sample request:

POST /p00012334/respondents/data
{
    "dataSchema":
    {
        "keys": ["email"],
        "variables": ["SomeChoiceVariable", "SomeTextVariable"]
    },
    "data":
    [
        {"email":"user1@example.com","SomeChoiceVariable":"1","SomeTextVariable":"User1's answer."},
        {"email":"user2@example.com","SomeChoiceVariable":"2","SomeTextVariable":"User2's answer."}
    ]
}

Note: "keys" clause is optional in the example above and should be used with custom keys only.

Parameters

Type Name Description Schema

Path

surveyId
required

The id of the survey

string

Body

body
optional

Survey data schema and data records to add.

Responses

HTTP Code Description Schema

200

Ok, the request has succeeded, the respondent data inserted successfully.

400

Bad request, the write schema or write data are not valid.

401

Unauthorized

No Content

404

Not found, the survey was not found.

Consumes

  • application/json

Produces

  • application/json

Tags

  • SurveyData

Example HTTP request

Request body

{
  "schedulingMode" : "none",
  "dataSchema" : {
    "keys" : [ "email" ],
    "variables" : [ "SomeChoiceQuestion", "SomeTextQuestion" ]
  },
  "data" : [ {
    "email" : "user1@example.com",
    "SomeChoiceQuestion" : "1",
    "SomeTextQuestion" : "User1's answer."
  }, {
    "email" : "user2@example.com",
    "SomeChoiceQuestion" : "2",
    "SomeTextQuestion" : "User2's answer."
  } ]
}

Example HTTP response

Response 200

{
  "insertedRecords" : 5,
  "insertedIds" : [ 4, 5, 6, 7, 8 ]
}

Response 400

{
  "validationMessages" : {
    "level" : "response",
    "rowResults" : [ {
      "rowNumber" : 1,
      "messages" : [ {
        "fields" : [ "q1_2" ],
        "message" : "Invalid byte",
        "value" : "1a",
        "severity" : "Error"
      } ]
    } ]
  }
}

Response 404

{
  "message" : "... not found."
}

Get respondent data.

GET /{surveyId}/respondents/data

Description

Returns a collection or stream of SurveyDataRecord. Sample request:

GET /p00012334/respondents/data

In order to filter variables of the result you can use either <b>variables</b> or <b>variableTemplateId</b> parameter. It’s not allowed to use them simultaneously, so always keep one of them empty. You can also skip both in order to get data for all the respondent variables.

Parameters

Type Name Description Schema

Path

surveyId
required

The id of the survey

string

Query

filterExpression
optional

DataEngine query expression for row filtering.

string

Query

page
optional

Use this to get page N of pageSize records. Default is 1. Only applies to Content-type: application/json.

integer (int32)

Query

pageSize
optional

Use this to limit number of records. Default is 100. Only applies to Content-type: application/json.

integer (int32)

Query

surveyLinkParameters
optional

Extra parameters to append to the survey link. Optional. Ex: l=20

string

Query

variableTemplateId
optional

Id of a variable template to be used to form the list of respondent variables included in each SurveyDataRecord.

integer (int64)

Query

variables
optional

The list of respondent variables to be included in each SurveyDataRecord.

string

Responses

HTTP Code Description Schema

200

Ok, the request has succeeded. All requested respondent records are returned.

400

Bad request, the query parameters are not valid.

401

Unauthorized

No Content

404

Not found, the survey was not found.

Produces

  • application/json

  • application/x-ndjson

Tags

  • SurveyData

Example HTTP response

Response 200

{
  "itemCount" : 0,
  "totalCount" : 355,
  "items" : [ {
    "respid" : 1,
    "CreatedDate" : "2020-01-21T16:00:40.817",
    "LastUpdated" : "2020-01-21T16:09:40.817",
    "email" : "test1@confirmit.com",
    "age" : 23,
    "last_name" : "Smith"
  }, {
    "respid" : 2,
    "CreatedDate" : "2020-01-21T16:00:40.817",
    "LastUpdated" : "2020-01-21T16:09:40.817",
    "email" : "test2@confirmit.com",
    "age" : 44,
    "last_name" : "Doe"
  } ],
  "links" : { }
}
{
  "application/json" : {
    "itemCount" : 0,
    "totalCount" : 355,
    "items" : [ {
      "respid" : 1,
      "CreatedDate" : "2020-01-21T16:00:40.817",
      "LastUpdated" : "2020-01-21T16:09:40.817",
      "email" : "test1@confirmit.com",
      "age" : 23,
      "last_name" : "Smith"
    }, {
      "respid" : 2,
      "CreatedDate" : "2020-01-21T16:00:40.817",
      "LastUpdated" : "2020-01-21T16:09:40.817",
      "email" : "test2@confirmit.com",
      "age" : 44,
      "last_name" : "Doe"
    } ],
    "links" : { }
  },
  "application/x-ndjson" : {
    "itemCount" : 0,
    "totalCount" : 355,
    "items" : [ {
      "respid" : 1,
      "CreatedDate" : "2020-01-21T16:00:40.817",
      "LastUpdated" : "2020-01-21T16:09:40.817",
      "email" : "test1@confirmit.com",
      "age" : 23,
      "last_name" : "Smith"
    }, {
      "respid" : 2,
      "CreatedDate" : "2020-01-21T16:00:40.817",
      "LastUpdated" : "2020-01-21T16:09:40.817",
      "email" : "test2@confirmit.com",
      "age" : 44,
      "last_name" : "Doe"
    } ],
    "links" : { }
  }
}

Response 400

{
  "message" : "The query parameters are not valid: ... ."
}
{
  "application/json" : {
    "message" : "The query parameters are not valid: ... ."
  },
  "application/x-ndjson" : {
    "message" : "The query parameters are not valid: ... ."
  }
}

Response 404

{
  "message" : "... not found."
}
{
  "application/json" : {
    "message" : "... not found."
  },
  "application/x-ndjson" : {
    "message" : "... not found."
  }
}

Update respondent data.

PUT /{surveyId}/respondents/data

Description

Updates existing respondent records matching the given keys. If request succeeds then the response contains a SurveyDataChangeResponse object with the number of the records updated. Sample request:

PUT /p00012334/respondents/data
{
    "dataSchema":
    {
        "keys": ["email"],
        "variables": ["SomeChoiceVariable", "SomeTextVariable"]
    },
    "data":
    [
        {"email":"user1@example.com","SomeChoiceVariable":"1","SomeTextVariable":"Updated User1's answer."},
        {"email":"user2@example.com","SomeChoiceVariable":"2","SomeTextVariable":"Updated User2's answer."}
    ]
}

Note: "keys" clause is obligatory in the example above.

Parameters

Type Name Description Schema

Path

surveyId
required

The id of the survey

string

Body

body
optional

Survey data schema and data records to update.

Responses

HTTP Code Description Schema

200

Ok, the request has succeeded and the respondent data was updated successfully.

400

Bad request, the schema or data are not valid.

401

Unauthorized

No Content

404

Not found, the survey was not found.

Consumes

  • application/json

Produces

  • application/json

Tags

  • SurveyData

Example HTTP request

Request body

{
  "schedulingMode" : "none",
  "dataSchema" : {
    "keys" : [ "email" ],
    "variables" : [ "SomeChoiceQuestion", "SomeTextQuestion" ]
  },
  "data" : [ {
    "email" : "user1@example.com",
    "SomeChoiceQuestion" : "1",
    "SomeTextQuestion" : "Updated User1's answer."
  }, {
    "email" : "user2@example.com",
    "SomeChoiceQuestion" : "2",
    "SomeTextQuestion" : "Updated User2's answer."
  } ]
}

Example HTTP response

Response 200

{
  "updatedRecords" : 100
}

Response 400

{
  "validationMessages" : {
    "level" : "response",
    "rowResults" : [ {
      "rowNumber" : 1,
      "messages" : [ {
        "fields" : [ "q1_2" ],
        "message" : "Invalid byte",
        "value" : "1a",
        "severity" : "Error"
      } ]
    } ]
  }
}

Response 404

{
  "message" : "... not found."
}

Delete respondent data.

DELETE /{surveyId}/respondents/data

Description

Deletes existing respondent records matching the given keys. If request succeeds then the response contains a SurveyDataChangeResponse object with the number of the records deleted. Sample request:

DELETE /p00012334/respondents/data
{
    "dataSchema":
    {
        "name": "respondent",
        "keys": ["email"]
    },
    "data":
    [
        { "email": "user1@example.com"},
        { "email": "user2@example.com"}
    ]
}

Parameters

Type Name Description Schema

Path

surveyId
required

The id of the survey

string

Body

body
optional

Survey data schema and data with keys of records to delete.

Responses

HTTP Code Description Schema

200

Ok, the request has succeeded and the respondent data was deleted.

400

Bad request, the schema or data are not valid.

401

Unauthorized

No Content

404

Not found, the survey was not found.

Consumes

  • application/json

Produces

  • application/json

Tags

  • SurveyData

Example HTTP response

Response 200

{
  "deletedRecords" : 3
}

Response 400

{
  "validationMessages" : {
    "level" : "response",
    "rowResults" : [ {
      "rowNumber" : 1,
      "messages" : [ {
        "fields" : [ "q1_2" ],
        "message" : "Invalid byte",
        "value" : "1a",
        "severity" : "Error"
      } ]
    } ]
  }
}

Response 404

{
  "message" : "... not found."
}

Merge respondent data.

PATCH /{surveyId}/respondents/data

Description

Merges the respondent data from the request with the existing respondents in the survey database by record keys. Updates records matching an existing key in the database. Inserts records not matching an existing key. If request succeeds then the response contains a SurveyDataChangeResponse object with the number of inserted and updated records. Sample request:

PATCH /p00012334/respondents/data
{
    "dataSchema":
    {
        "keys": ["email"],
        "variables": ["SomeChoiceVariable", "SomeTextVariable"]
    },
    "data":
    [
        {"email":"user1@example.com","SomeChoiceVariable":"1","SomeTextVariable":"Updated User1's answer."},
        {"email":"user3@example.com","SomeChoiceVariable":"3","SomeTextVariable":"An answer of the new respondent User3."}
        {"email":"user2@example.com","SomeChoiceVariable":"2","SomeTextVariable":"Updated User2's answer."}
    ]
}

Note: "keys" clause is obligatory in the example above. Note: Set some non-existing keys for the records to be inserted. You have to set different key for each new record.

Parameters

Type Name Description Schema

Path

surveyId
required

The id of the survey

string

Body

body
optional

Survey data schema and data records to merge.

Responses

HTTP Code Description Schema

200

Ok, the request has succeeded, the respondent data updated successfully.

400

Bad request, the write schema or write data are not valid.

401

Unauthorized

No Content

404

Not found, the survey was not found.

Consumes

  • application/json

Produces

  • application/json

Tags

  • SurveyData

Example HTTP request

Request body

{
  "schedulingMode" : "none",
  "dataSchema" : {
    "keys" : [ "email" ],
    "variables" : [ "SomeChoiceQuestion", "SomeTextQuestion" ]
  },
  "data" : [ {
    "email" : "user1@example.com",
    "SomeChoiceQuestion" : "1",
    "SomeTextQuestion" : "Updated User1's answer."
  }, {
    "email" : "user3@example.com",
    "SomeChoiceQuestion" : "3",
    "SomeTextQuestion" : "An answer for the new respondent User3."
  }, {
    "email" : "user2@example.com",
    "SomeChoiceQuestion" : "2",
    "SomeTextQuestion" : "Updated User2's answer."
  } ]
}

Example HTTP response

Response 200

{
  "insertedRecords" : 5,
  "updatedRecords" : 100,
  "insertedIds" : [ 4, 5, 6, 7, 8 ]
}

Response 400

{
  "validationMessages" : {
    "level" : "response",
    "rowResults" : [ {
      "rowNumber" : 1,
      "messages" : [ {
        "fields" : [ "q1_2" ],
        "message" : "Invalid byte",
        "value" : "1a",
        "severity" : "Error"
      } ]
    } ]
  }
}

Response 404

{
  "message" : "... not found."
}

Create a respondent data query.

POST /{surveyId}/respondents/data/query

Description

Creates a respondent data query. Sample request:

POST /p00012334/respondents/data/query

In order to filter variables of the result you can use either <b>variables</b> or <b>variableTemplateId</b> parameter. It’s not allowed to use them simultaneously, so always keep one of them empty. You can also skip them at all in order to receive all the survey variables.

Parameters

Type Name Description Schema Default

Path

surveyId
required

The id of the survey

string

Query

filterExpression
optional

DataEngine query expression for row filtering.

string

Query

format
optional

Format the data will be written as. Default is x-ndjson. Use tsv+zip or csv+zip to write to file.

string

Query

keepAlive
optional

Keep alive timeout for query.

integer (int32)

60000

Query

variableTemplateId
optional

Id of a variable template to be used to form the list of respondent variables included in the query schema.

integer (int64)

Query

variables
optional

The list of respondent variables to be included in the query schema.

string

Responses

HTTP Code Description Schema

201

Ok, the request has succeeded. The created query is returned.

400

Bad request, the query parameters are not valid.

401

Unauthorized

No Content

404

Not found, the survey was not found.

Produces

  • application/json

Tags

  • SurveyData

Example HTTP response

Response 201

{
  "queryId" : 123,
  "queryStatus" : "preparing",
  "targetSurveyId" : "p12345",
  "links" : {
    "self" : "https://host/v1/surveys/p12345/responses/data/query/123"
  }
}

Response 400

{
  "message" : "The query parameters are not valid: ... ."
}

Response 404

{
  "message" : "... not found."
}

Get respondent data query.

GET /{surveyId}/respondents/data/query/{queryId}

Description

Gets a specific respondent data query. Sample request:

GET /p00012334/respondents/data/query/1515

Parameters

Type Name Description Schema

Path

queryId
required

The id of the query to retrieve

integer (int64)

Path

surveyId
required

The id of the survey

string

Responses

HTTP Code Description Schema

200

Ok, The request has succeeded. The respondent data query is returned.

400

Bad request, the query parameters are not valid.

401

Unauthorized

No Content

404

Not found, the survey or the query was not found.

Produces

  • application/json

Tags

  • SurveyData

Example HTTP response

Response 200

{
  "queryId" : 123,
  "queryStatus" : "preparing",
  "targetSurveyId" : "p12345",
  "links" : {
    "self" : "https://host/v1/surveys/p12345/responses/data/query/123"
  }
}

Response 400

{
  "message" : "The query parameters are not valid: ... ."
}

Response 404

{
  "message" : "... not found."
}

Get respondent query data.

GET /{surveyId}/respondents/data/query/{queryId}/data

Description

Returns the SurveyDataRecord part of a SurveyDataQuery. Sample request:

GET /p00012334/respondents/data/query/1515/data

Parameters

Type Name Description Schema Default

Path

queryId
required

The id of the query

integer (int64)

Path

surveyId
required

The id of the survey

string

Query

maxSize
optional

The desired maximum number of records to be returned.

integer (int32)

100

Responses

HTTP Code Description Schema

200

Ok, The request has succeeded. Some respondent data for the specified query might be returned. The query is completed. It will not provide more records.

< string > array

206

Ok, The request has succeeded. Some respondent data for the specified query might be returned. If no data returned then the specified query does not have more records at the moment. The query is still active, run the request again for more records.

< string > array

400

Bad request, the query parameters are not valid.

401

Unauthorized

No Content

404

Not found, the survey or the query was not found.

Produces

  • application/json

Tags

  • SurveyData

Example HTTP response

Response 200

[ {
  "responseid" : 1,
  "respid" : 1,
  "status" : "complete",
  "last_touched" : "2020-01-21T15:09:40.817+00:00",
  "q1" : 1
}, {
  "responseid" : 2,
  "respid" : 2,
  "status" : "complete",
  "last_touched" : "2020-01-21T15:09:40.817+00:00",
  "q1" : 2
} ]

Response 206

[ {
  "responseid" : 1,
  "respid" : 1,
  "status" : "complete",
  "last_touched" : "2020-01-21T15:09:40.817+00:00",
  "q1" : 1
}, {
  "responseid" : 2,
  "respid" : 2,
  "status" : "complete",
  "last_touched" : "2020-01-21T15:09:40.817+00:00",
  "q1" : 2
} ]

Response 400

{
  "message" : "The query parameters are not valid: ... ."
}

Response 404

{
  "message" : "... not found."
}

Get respondent query schema.

GET /{surveyId}/respondents/data/query/{queryId}/schema

Description

Returns the SurveyDataSchema part of a SurveyDataQuery. Sample request:

GET /p00012334/respondents/data/query/1515/schema

Parameters

Type Name Description Schema

Path

queryId
required

The id of the query

integer (int64)

Path

surveyId
required

The id of the survey

string

Responses

HTTP Code Description Schema

200

Ok, The request has succeeded. The respondent data schema for the specified query is returned.

400

Bad request, the query parameters are not valid.

401

Unauthorized

No Content

404

Not found, the survey or the query was not found.

Produces

  • application/json

Tags

  • SurveyData

Example HTTP response

Response 200

{
  "version" : "1",
  "defaultConfirmitLanguageId" : 9,
  "languages" : [ {
    "confirmitLanguageId" : 9
  } ],
  "root" : {
    "name" : "response",
    "keys" : [ {
      "name" : "responseid",
      "isCompound" : false,
      "isBackground" : false,
      "isHidden" : false,
      "variableType" : "numeric",
      "isSystemVariable" : true,
      "isUserVariable" : false,
      "excludeFromReporting" : false
    } ],
    "variables" : [ {
      "name" : "respid",
      "isCompound" : false,
      "isBackground" : false,
      "isHidden" : false,
      "variableType" : "numeric",
      "isSystemVariable" : true,
      "isUserVariable" : false,
      "excludeFromReporting" : false
    }, {
      "name" : "q1",
      "titles" : [ ],
      "texts" : [ ],
      "isCompound" : false,
      "isBackground" : false,
      "isHidden" : false,
      "variableType" : "numeric",
      "isSystemVariable" : false,
      "isUserVariable" : false,
      "precision" : 2,
      "scale" : 0,
      "lowerLimitType" : "noLimit",
      "upperLimitType" : "noLimit",
      "excludeFromReporting" : false
    } ]
  }
}

Response 400

{
  "message" : "The query parameters are not valid: ... ."
}

Response 404

{
  "message" : "... not found."
}

Get a single respondent record.

GET /{surveyId}/respondents/data/{respId}

Description

Returns a SurveyDataRecord. Sample request:

GET /p00012334/respondents/data/234

In order to filter variables of the result you can use either <b>variables</b> or <b>variableTemplateId</b> parameter. It’s not allowed to use them simultaneously, so always keep one of them empty. You can also skip them at all in order to receive all the survey variables.

Parameters

Type Name Description Schema

Path

respId
required

The unique respId.

integer (int32)

Path

surveyId
required

The id of the survey

string

Query

variableTemplateId
optional

Id of a variable template to be used to form the list of respondent variables included in each SurveyDataRecord.

integer (int64)

Query

variables
optional

The list of respondent variables to be included in each SurveyDataRecord.

string

Responses

HTTP Code Description Schema

200

Ok, the request has succeeded. The requested survey data record is returned.

< string, object > map

400

Bad request, the query parameters are not valid.

401

Unauthorized

No Content

404

Not found, the survey was not found.

Produces

  • application/json

Tags

  • SurveyData

Example HTTP response

Response 200

{
  "responseid" : 1,
  "respid" : 1,
  "status" : "complete",
  "last_touched" : "2020-01-21T16:09:40.817",
  "q1" : 1
}

Response 400

{
  "message" : "The query parameters are not valid: ... ."
}

Response 404

{
  "message" : "... not found."
}

Get the survey data schema for respondent data.

GET /{surveyId}/respondents/schema

Description

Returns a SurveyDataSchema for the requested variables. Sample request:

GET /p00012334/respondents/schema

In order to filter variables of the result you can use either <b>variables</b> or <b>variableTemplateId</b> parameter. It’s not allowed to use them simultaneously, so always keep one of them empty. You can also skip them at all in order to receive all the survey variables.

Parameters

Type Name Description Schema Default

Path

surveyId
required

The id of the survey

string

Query

languageSelection
optional

A specification of which variables to include in the schema texts/titles.

enum (All, None, Default, Selected)

"Default"

Query

languages
optional

A comma-separated list of languageIds to be included in the schema. Use in combination with LanguageSelectionType.Selected.

string

Query

variableTemplateId
optional

Id of a variable template to be used to form the list of respondent variables to include in the schema.

integer (int64)

Query

variables
optional

The list of respondent variables to be included in the schema.

string

Responses

HTTP Code Description Schema

200

Ok, the request has succeeded. The survey data schema is returned.

400

Bad request, the query parameters are not valid.

401

Unauthorized

No Content

404

Not found, the survey was not found.

Produces

  • application/json

Tags

  • SurveyData

Example HTTP response

Response 200

{
  "version" : "1",
  "defaultConfirmitLanguageId" : 9,
  "languages" : [ {
    "confirmitLanguageId" : 9
  } ],
  "root" : {
    "name" : "respondent",
    "keys" : [ {
      "name" : "respid",
      "isCompound" : false,
      "isBackground" : false,
      "isHidden" : false,
      "variableType" : "numeric",
      "isSystemVariable" : true,
      "isUserVariable" : false,
      "excludeFromReporting" : false
    } ],
    "variables" : [ {
      "name" : "email",
      "isCompound" : false,
      "isBackground" : true,
      "isHidden" : false,
      "variableType" : "text",
      "isSystemVariable" : false,
      "isUserVariable" : false,
      "length" : 255,
      "excludeFromReporting" : false
    }, {
      "name" : "age",
      "isCompound" : false,
      "isBackground" : true,
      "isHidden" : false,
      "variableType" : "numeric",
      "isSystemVariable" : false,
      "isUserVariable" : false,
      "precision" : 2,
      "scale" : 0,
      "excludeFromReporting" : false
    }, {
      "name" : "last_name",
      "isCompound" : false,
      "isBackground" : false,
      "isHidden" : false,
      "variableType" : "text",
      "isSystemVariable" : false,
      "isUserVariable" : true,
      "length" : 255,
      "excludeFromReporting" : false
    } ]
  }
}

Response 400

{
  "message" : "The query parameters are not valid: ... ."
}

Response 404

{
  "message" : "... not found."
}

Add a respondent variable.

POST /{surveyId}/respondents/uservariables

Description

Add a new user-variable to the respondent table. Sample request:

POST /p00012334/respondents/uservariables
{
    "name": "email",
    "dataType": "text",
    "length": 256
}

Parameters

Type Name Description Schema

Path

surveyId
required

The id of the survey

string

Body

body
optional

The new UserVariable.

Responses

HTTP Code Description Schema

200

Ok, the variable was added successfully.

No Content

400

Bad request, the variable is not valid.

401

Unauthorized

No Content

404

Not found, the survey was not found.

409

There was a conflict adding the variable.

Consumes

  • application/json

Produces

  • application/json

Tags

  • SurveyData

Example HTTP response

Response 400

{
  "message" : "The query parameters are not valid: ... ."
}

Response 404

{
  "message" : "... not found."
}

Response 409

{
  "message" : "There was a conflict executing the request ... ."
}

Delete a respondent variable.

DELETE /{surveyId}/respondents/uservariables/{variableName}

Description

Delete a user-variable from the respondent table. Sample request:

DELETE /p00012334/respondents/uservariables/city

Parameters

Type Name Description Schema

Path

surveyId
required

The id of the survey

string

Path

variableName
required

The name of the variable to delete.

string

Responses

HTTP Code Description Schema

200

Ok, the variable was deleted successfully.

No Content

400

Bad request, the variable is not a user-variable.

401

Unauthorized

No Content

404

Not found, the variable does not exist.

Produces

  • application/json

Tags

  • SurveyData

Example HTTP response

Response 400

{
  "message" : "The query parameters are not valid: ... ."
}

Response 404

{
  "message" : "... not found."
}

Add response data.

POST /{surveyId}/responses/data

Description

Adds new response records to the survey database. If request succeeds then the response contains a SurveyDataChangeResponse object with the number of the records added. Sample request:

POST /p00012334/responses/data
{
    "dataSchema":
    {
        "keys": ["email"],
        "variables": ["SomeChoiceQuestion", "SomeTextQuestion"]
    },
    "data":
    [
        {"email":"user1@example.com","SomeChoiceQuestion":"1","SomeTextQuestion":"User1's answer."},
        {"email":"user2@example.com","SomeChoiceQuestion":"2","SomeTextQuestion":"User2's answer."}
    ],
    "linkRespondentsWithKey": false
}

Note: The "keys" clause is optional in the example above and should be used with custom keys only. Use the linkRespondentsWithKey property to link respid’s from already created respondents to the new responses.

Parameters

Type Name Description Schema

Path

surveyId
required

The id of the survey

string

Body

body
optional

Survey data schema and data records to insert.

Responses

HTTP Code Description Schema

200

Ok, the request has succeeded, the response data was inserted successfully.

400

Bad request, the schema or data are not valid.

401

Unauthorized

No Content

404

Not found, the survey was not found.

Consumes

  • application/json

Produces

  • application/json

Tags

  • SurveyData

Example HTTP request

Request body

{
  "linkRespondentsWithKey" : false,
  "dataSchema" : {
    "keys" : [ "email" ],
    "variables" : [ "SomeChoiceQuestion", "SomeTextQuestion" ]
  },
  "data" : [ {
    "email" : "user1@example.com",
    "SomeChoiceQuestion" : "1",
    "SomeTextQuestion" : "User1's answer."
  }, {
    "email" : "user2@example.com",
    "SomeChoiceQuestion" : "2",
    "SomeTextQuestion" : "User2's answer."
  } ]
}

Example HTTP response

Response 200

{
  "insertedRecords" : 5,
  "insertedIds" : [ 4, 5, 6, 7, 8 ]
}

Response 400

{
  "validationMessages" : {
    "level" : "response",
    "rowResults" : [ {
      "rowNumber" : 1,
      "messages" : [ {
        "fields" : [ "q1_2" ],
        "message" : "Invalid byte",
        "value" : "1a",
        "severity" : "Error"
      } ]
    } ]
  }
}

Response 404

{
  "message" : "... not found."
}

Get response data.

GET /{surveyId}/responses/data

Description

Returns a collection or stream of SurveyDataRecord. Sample request:

GET /p00012334/responses/data

In order to filter variables of the result you can use either <b>variables</b> or <b>variableTemplateId</b> parameter. It’s not allowed to use them simultaneously, so always keep one of them empty. You can also skip them at all in order to receive all the survey variables.

Parameters

Type Name Description Schema

Path

surveyId
required

The id of the survey

string

Query

filterExpression
optional

DataEngine query expression for row filtering.

string

Query

page
optional

Use this to get page N of pageSize records. Default is 1. Only applies to Content-type: application/json.

integer (int32)

Query

pageSize
optional

Use this to limit number of records. Default is 100. Only applies to Content-type: application/json.

integer (int32)

Query

variableTemplateId
optional

Id of a variable template to be used to form the list of survey variables included in each SurveyDataRecord.

integer (int64)

Query

variables
optional

The list of survey variables to be included in each SurveyDataRecord.

string

Responses

HTTP Code Description Schema

200

Ok, the request has succeeded. All requested survey data records are returned.

400

Bad request, the query parameters are not valid.

401

Unauthorized

No Content

404

Not found, the survey was not found.

Produces

  • application/json

  • application/x-ndjson

Tags

  • SurveyData

Example HTTP response

Response 200

{
  "itemCount" : 0,
  "totalCount" : 355,
  "items" : [ {
    "responseid" : 1,
    "respid" : 1,
    "status" : "complete",
    "last_touched" : "2020-01-21T16:09:40.817",
    "q1" : 1
  }, {
    "responseid" : 2,
    "respid" : 2,
    "status" : "complete",
    "last_touched" : "2020-01-21T16:09:40.817",
    "q1" : 2
  }, {
    "responseid" : 3,
    "respid" : 3,
    "status" : "complete",
    "last_touched" : "2020-01-21T16:09:40.817",
    "q1" : 3
  } ],
  "links" : { }
}
{
  "application/json" : {
    "itemCount" : 0,
    "totalCount" : 355,
    "items" : [ {
      "responseid" : 1,
      "respid" : 1,
      "status" : "complete",
      "last_touched" : "2020-01-21T16:09:40.817",
      "q1" : 1
    }, {
      "responseid" : 2,
      "respid" : 2,
      "status" : "complete",
      "last_touched" : "2020-01-21T16:09:40.817",
      "q1" : 2
    }, {
      "responseid" : 3,
      "respid" : 3,
      "status" : "complete",
      "last_touched" : "2020-01-21T16:09:40.817",
      "q1" : 3
    } ],
    "links" : { }
  },
  "application/x-ndjson" : {
    "itemCount" : 0,
    "totalCount" : 355,
    "items" : [ {
      "responseid" : 1,
      "respid" : 1,
      "status" : "complete",
      "last_touched" : "2020-01-21T16:09:40.817",
      "q1" : 1
    }, {
      "responseid" : 2,
      "respid" : 2,
      "status" : "complete",
      "last_touched" : "2020-01-21T16:09:40.817",
      "q1" : 2
    }, {
      "responseid" : 3,
      "respid" : 3,
      "status" : "complete",
      "last_touched" : "2020-01-21T16:09:40.817",
      "q1" : 3
    } ],
    "links" : { }
  }
}

Response 400

{
  "message" : "The query parameters are not valid: ... ."
}

Response 404

{
  "message" : "... not found."
}

Update response data.

PUT /{surveyId}/responses/data

Description

Updates response records in the survey database matching the given keys. If request succeeds then the response contains a SurveyDataChangeResponse object with the number of the records updated. Sample request:

PUT /p00012334/responses/data
{
    "dataSchema":
    {
        "keys": ["email"],
        "variables": ["SomeChoiceQuestion", "SomeTextQuestion"]
    },
    "data":
    [
        {"email":"user1@example.com","SomeChoiceQuestion":"1","SomeTextQuestion":"Updated User1's answer."},
        {"email":"user2@example.com","SomeChoiceQuestion":"2","SomeTextQuestion":"Updated User2's answer."}
    ]
}

Note: "keys" clause is obligatory in the example above.

Parameters

Type Name Description Schema

Path

surveyId
required

The id of the survey

string

Body

body
optional

Survey data schema and data records to update.

Responses

HTTP Code Description Schema

200

Ok, the request has succeeded, the response data was updated successfully.

400

Bad request, the schema or data are not valid.

401

Unauthorized

No Content

404

Not found, the survey was not found.

Consumes

  • application/json

Produces

  • application/json

Tags

  • SurveyData

Example HTTP request

Request body

{
  "schedulingMode" : "none",
  "dataSchema" : {
    "keys" : [ "email" ],
    "variables" : [ "SomeChoiceQuestion", "SomeTextQuestion" ]
  },
  "data" : [ {
    "email" : "user1@example.com",
    "SomeChoiceQuestion" : "1",
    "SomeTextQuestion" : "Updated User1's answer."
  }, {
    "email" : "user2@example.com",
    "SomeChoiceQuestion" : "2",
    "SomeTextQuestion" : "Updated User2's answer."
  } ]
}

Example HTTP response

Response 200

{
  "updatedRecords" : 100
}

Response 400

{
  "validationMessages" : {
    "level" : "response",
    "rowResults" : [ {
      "rowNumber" : 1,
      "messages" : [ {
        "fields" : [ "q1_2" ],
        "message" : "Invalid byte",
        "value" : "1a",
        "severity" : "Error"
      } ]
    } ]
  }
}

Response 404

{
  "message" : "... not found."
}

Delete response data.

DELETE /{surveyId}/responses/data

Description

Deletes response records matching the given keys. If the request succeeds then the response contains a SurveyDataChangeResponse object with the number of the records deleted. Sample request:

DELETE /p00012334/responses/data
{
    "dataSchema":
    {
        "name": "response",
        "keys": ["email"]
    },
    "data":
    [
        { "email": "user1@example.com"},
        { "email": "user2@example.com"}
    ]
}

Parameters

Type Name Description Schema

Path

surveyId
required

The id of the survey

string

Body

body
optional

Survey data schema and data keys of records to delete.

Responses

HTTP Code Description Schema

200

Ok, the request has succeeded, the response data deleted successfully.

400

Bad request, the write schema or write data are not valid.

401

Unauthorized

No Content

404

Not found, the survey was not found.

Consumes

  • application/json

Produces

  • application/json

Tags

  • SurveyData

Example HTTP response

Response 200

{
  "deletedRecords" : 3
}

Response 400

{
  "validationMessages" : {
    "level" : "response",
    "rowResults" : [ {
      "rowNumber" : 1,
      "messages" : [ {
        "fields" : [ "q1_2" ],
        "message" : "Invalid byte",
        "value" : "1a",
        "severity" : "Error"
      } ]
    } ]
  }
}

Response 404

{
  "message" : "... not found."
}

Merge response data.

PATCH /{surveyId}/responses/data

Description

Merges the response data from the request with the existing survey responses in the survey database by record keys. Updates records matching an existing key in the database. Inserts records not matching an existing key. If the request succeeds then the response contains a SurveyDataChangeResponse object with the number of inserted and updated records. Sample request:

PATCH /p00012334/responses/data
{
    "dataSchema":
    {
        "keys": ["email"],
        "variables": ["SomeChoiceQuestion", "SomeTextQuestion"]
    },
    "data":
    [
        {"email":"user1@example.com","SomeChoiceQuestion":"1","SomeTextQuestion":"Updated User1's answer."},
        {"email":"user3@example.com","SomeChoiceQuestion":"3","SomeTextQuestion":"An answer of the new respondent User3."}
        {"email":"user2@example.com","SomeChoiceQuestion":"2","SomeTextQuestion":"Updated User2's answer."}
    ],
    "linkRespondentsWithKey": false
}

Note: The "keys" clause is obligatory in the example above. Use the linkRespondentsWithKey property to link respid’s from already created respondents to the new responses. Note: Set some non-existing keys for the records to be inserted. You have to set different key for each new record.

Parameters

Type Name Description Schema

Path

surveyId
required

The id of the survey

string

Body

body
optional

Survey data schema and data records to merge with existing data.

Responses

HTTP Code Description Schema

200

Ok, the request has succeeded, the response data updated successfully.

400

Bad request, the write schema or write data are not valid.

401

Unauthorized

No Content

404

Not found, the survey was not found.

Consumes

  • application/json

Produces

  • application/json

Tags

  • SurveyData

Example HTTP request

Request body

{
  "linkRespondentsWithKey" : true,
  "dataSchema" : {
    "keys" : [ "email" ],
    "variables" : [ "SomeChoiceQuestion", "SomeTextQuestion" ]
  },
  "data" : [ {
    "email" : "user1@example.com",
    "SomeChoiceQuestion" : "1",
    "SomeTextQuestion" : "Updated User1's answer."
  }, {
    "email" : "user3@example.com",
    "SomeChoiceQuestion" : "3",
    "SomeTextQuestion" : "An answer for the new respondent User3."
  }, {
    "email" : "user2@example.com",
    "SomeChoiceQuestion" : "2",
    "SomeTextQuestion" : "Updated User2's answer."
  } ]
}

Example HTTP response

Response 200

{
  "insertedRecords" : 5,
  "updatedRecords" : 100,
  "insertedIds" : [ 4, 5, 6, 7, 8 ]
}

Response 400

{
  "validationMessages" : {
    "level" : "response",
    "rowResults" : [ {
      "rowNumber" : 1,
      "messages" : [ {
        "fields" : [ "q1_2" ],
        "message" : "Invalid byte",
        "value" : "1a",
        "severity" : "Error"
      } ]
    } ]
  }
}

Response 404

{
  "message" : "... not found."
}

Create a response data query.

POST /{surveyId}/responses/data/query

Description

Creates a response data query. Sample request:

POST /p00012334/responses/data/query

In order to filter variables of the result you can use either <b>variables</b> or <b>variableTemplateId</b> parameter. It’s not allowed to use them simultaneously, so always keep one of them empty. You can also skip them at all in order to receive all the survey variables.

Parameters

Type Name Description Schema Default

Path

surveyId
required

The id of the survey

string

Query

filterExpression
optional

DataEngine query expression for row filtering.

string

Query

format
optional

Format the data will be written as. Default is x-ndjson. Use tsv+zip or csv+zip to write to file.

string

Query

keepAlive
optional

Keep alive timeout for query.

integer (int32)

60000

Query

variableTemplateId
optional

Id of a variable template to be used to form the list of survey variables included in the query.

integer (int64)

Query

variables
optional

The list of survey variables to be included in the query.

string

Responses

HTTP Code Description Schema

201

Ok, the request has succeeded. The created query is returned.

400

Bad request, the query parameters are not valid.

401

Unauthorized

No Content

404

Not found, the survey was not found.

Produces

  • application/json

Tags

  • SurveyData

Example HTTP response

Response 201

{
  "queryId" : 123,
  "queryStatus" : "preparing",
  "targetSurveyId" : "p12345",
  "links" : {
    "self" : "https://host/v1/surveys/p12345/responses/data/query/123"
  }
}

Response 400

{
  "message" : "The query parameters are not valid: ... ."
}

Response 404

{
  "message" : "... not found."
}

Get response data query.

GET /{surveyId}/responses/data/query/{queryId}

Description

Gets a specific response data query. Sample request:

GET /p00012334/responses/data/query/1515

Parameters

Type Name Description Schema

Path

queryId
required

The id of the query to retrieve

integer (int64)

Path

surveyId
required

The id of the survey

string

Responses

HTTP Code Description Schema

200

Ok, The request has succeeded. The survey data query is returned.

400

Bad request, the query parameters are not valid.

401

Unauthorized

No Content

404

Not found, the survey or the query was not found.

Produces

  • application/json

Tags

  • SurveyData

Example HTTP response

Response 200

{
  "queryId" : 123,
  "queryStatus" : "preparing",
  "targetSurveyId" : "p12345",
  "links" : {
    "self" : "https://host/v1/surveys/p12345/responses/data/query/123"
  }
}

Response 400

{
  "message" : "The query parameters are not valid: ... ."
}

Response 404

{
  "message" : "... not found."
}

Get response query data.

GET /{surveyId}/responses/data/query/{queryId}/data

Description

Returns the SurveyDataRecord part of a SurveyDataQuery. Sample request:

GET /p00012334/responses/data/query/1515/data

Parameters

Type Name Description Schema Default

Path

queryId
required

The id of the query

integer (int64)

Path

surveyId
required

The id of the survey

string

Query

maxSize
optional

The desired maximum number of records to be returned.

integer (int32)

100

Responses

HTTP Code Description Schema

200

Ok, The request has succeeded. Some response records for the specified query might be returned. The query has completed, it will not provide more records.

< string > array

206

Ok, The request has succeeded. Some response records for the specified query might be returned. If no data returned then the specified query does not have more records at the moment. The query is still active, run the request again for more records.

< string > array

400

Bad request, the query parameters are not valid.

401

Unauthorized

No Content

404

Not found, the survey or the query was not found.

Produces

  • application/json

Tags

  • SurveyData

Example HTTP response

Response 200

[ {
  "responseid" : 1,
  "respid" : 1,
  "status" : "complete",
  "last_touched" : "2020-01-21T15:09:40.817+00:00",
  "q1" : 1
}, {
  "responseid" : 2,
  "respid" : 2,
  "status" : "complete",
  "last_touched" : "2020-01-21T15:09:40.817+00:00",
  "q1" : 2
} ]

Response 206

[ {
  "responseid" : 1,
  "respid" : 1,
  "status" : "complete",
  "last_touched" : "2020-01-21T15:09:40.817+00:00",
  "q1" : 1
}, {
  "responseid" : 2,
  "respid" : 2,
  "status" : "complete",
  "last_touched" : "2020-01-21T15:09:40.817+00:00",
  "q1" : 2
} ]

Response 400

{
  "message" : "The query parameters are not valid: ... ."
}

Response 404

{
  "message" : "... not found."
}

Get response query schema.

GET /{surveyId}/responses/data/query/{queryId}/schema

Description

Returns the SurveyDataSchema part of a SurveyDataQuery. Sample request:

GET /p00012334/responses/data/query/1515/schema

Parameters

Type Name Description Schema

Path

queryId
required

The id of the query

integer (int64)

Path

surveyId
required

The id of the survey

string

Responses

HTTP Code Description Schema

200

Ok, The request has succeeded. The survey data schema for the specified query is returned.

400

Bad request, the query parameters are not valid.

401

Unauthorized

No Content

404

Not found, the survey or the query was not found.

Produces

  • application/json

Tags

  • SurveyData

Example HTTP response

Response 200

{
  "version" : "1",
  "defaultConfirmitLanguageId" : 9,
  "languages" : [ {
    "confirmitLanguageId" : 9
  } ],
  "root" : {
    "name" : "response",
    "keys" : [ {
      "name" : "responseid",
      "isCompound" : false,
      "isBackground" : false,
      "isHidden" : false,
      "variableType" : "numeric",
      "isSystemVariable" : true,
      "isUserVariable" : false,
      "excludeFromReporting" : false
    } ],
    "variables" : [ {
      "name" : "respid",
      "isCompound" : false,
      "isBackground" : false,
      "isHidden" : false,
      "variableType" : "numeric",
      "isSystemVariable" : true,
      "isUserVariable" : false,
      "excludeFromReporting" : false
    }, {
      "name" : "q1",
      "titles" : [ ],
      "texts" : [ ],
      "isCompound" : false,
      "isBackground" : false,
      "isHidden" : false,
      "variableType" : "numeric",
      "isSystemVariable" : false,
      "isUserVariable" : false,
      "precision" : 2,
      "scale" : 0,
      "lowerLimitType" : "noLimit",
      "upperLimitType" : "noLimit",
      "excludeFromReporting" : false
    } ]
  }
}

Response 400

{
  "message" : "The query parameters are not valid: ... ."
}

Response 404

{
  "message" : "... not found."
}

Get a single response record.

GET /{surveyId}/responses/data/{responseId}

Description

Returns a SurveyDataRecord. Sample request:

GET /p00012334/responses/data/234

In order to filter variables of the result you can use either <b>variables</b> or <b>variableTemplateId</b> parameter. It’s not allowed to use them simultaneously, so always keep one of them empty. You can also skip them at all in order to receive all the survey variables.

Parameters

Type Name Description Schema

Path

responseId
required

The unique responseId.

integer (int32)

Path

surveyId
required

The id of the survey

string

Query

variableTemplateId
optional

Id of a variable template to be used to form the list of survey variables included in each SurveyDataRecord.

integer (int64)

Query

variables
optional

The list of survey variables to be included in each SurveyDataRecord.

string

Responses

HTTP Code Description Schema

200

Ok, the request has succeeded. The requested survey data record is returned.

< string, object > map

400

Bad request, the query parameters are not valid.

401

Unauthorized

No Content

404

Not found, the survey was not found.

Produces

  • application/json

Tags

  • SurveyData

Example HTTP response

Response 200

{
  "responseid" : 1,
  "respid" : 1,
  "status" : "complete",
  "last_touched" : "2020-01-21T16:09:40.817",
  "q1" : 1
}

Response 400

{
  "message" : "The query parameters are not valid: ... ."
}

Response 404

{
  "message" : "... not found."
}

Get survey data schema for responses.

GET /{surveyId}/responses/schema

Description

Returns a SurveyDataSchema with the requested survey variables. Sample request:

GET /p00012334/responses/schema

In order to filter variables of the result you can use either <b>variables</b> or <b>variableTemplateId</b> parameter. It’s not allowed to use them simultaneously, so always keep one of them empty. You can also skip them at all in order to receive all the survey variables.

Parameters

Type Name Description Schema Default

Path

surveyId
required

The id of the survey

string

Query

languageSelection
optional

A specification of which variables to include in the schema texts/titles.

enum (All, None, Default, Selected)

"Default"

Query

languages
optional

A comma-separated list of languageIds to be included in the schema. Use in combination with LanguageSelectionType.Selected.

string

Query

variableTemplateId
optional

Id of a variable template to be used to form the list of survey variables included in the result.

integer (int64)

Query

variables
optional

The list of survey variables to be included in the response.

string

Responses

HTTP Code Description Schema

200

Ok, the request has succeeded. The survey data schema is returned.

400

Bad request, the query parameters are not valid.

401

Unauthorized

No Content

404

Not found, the survey was not found.

Produces

  • application/json

Tags

  • SurveyData

Example HTTP response

Response 200

{
  "version" : "1",
  "defaultConfirmitLanguageId" : 9,
  "languages" : [ {
    "confirmitLanguageId" : 9
  } ],
  "root" : {
    "name" : "response",
    "keys" : [ {
      "name" : "responseid",
      "isCompound" : false,
      "isBackground" : false,
      "isHidden" : false,
      "variableType" : "numeric",
      "isSystemVariable" : true,
      "isUserVariable" : false,
      "excludeFromReporting" : false
    } ],
    "variables" : [ {
      "name" : "respid",
      "isCompound" : false,
      "isBackground" : false,
      "isHidden" : false,
      "variableType" : "numeric",
      "isSystemVariable" : true,
      "isUserVariable" : false,
      "excludeFromReporting" : false
    }, {
      "name" : "q1",
      "titles" : [ ],
      "texts" : [ ],
      "isCompound" : false,
      "isBackground" : false,
      "isHidden" : false,
      "variableType" : "numeric",
      "isSystemVariable" : false,
      "isUserVariable" : false,
      "precision" : 2,
      "scale" : 0,
      "lowerLimitType" : "noLimit",
      "upperLimitType" : "noLimit",
      "excludeFromReporting" : false
    } ]
  }
}

Response 400

{
  "message" : "The query parameters are not valid: ... ."
}

Response 404

{
  "message" : "... not found."
}

Get survey weight models.

GET /{surveyId}/weightmodels

Description

Returns a list of survey weight models. Sample request:

GET /p12345/WeightModels

Parameters

Type Name Description Schema

Path

surveyId
required

The id of the survey

string

Responses

HTTP Code Description Schema

200

Ok, the request has succeeded. The survey weight model list is returned.

400

Bad request, the query parameters are not valid.

401

Unauthorized

No Content

404

Not found, the survey was not found.

Produces

  • application/json

Tags

  • WeightModels

Example HTTP response

Response 200

{
  "itemCount" : 2,
  "totalCount" : 2,
  "items" : [ {
    "id" : "15",
    "name" : "Gender & Age",
    "type" : "sampleBalancing",
    "lastGenerated" : "2021-05-21T15:09:40.817+00:00"
  }, {
    "id" : "16",
    "name" : "SomeSurveyQuestionWeightModel",
    "type" : "surveyQuestion",
    "lastGenerated" : "2021-05-21T15:09:40.817+00:00",
    "questionId" : "q1"
  } ],
  "links" : {
    "self" : "http://host/v1/surveys/{surveyId}/weightmodels"
  }
}

Response 400

{
  "message" : "The query parameters are not valid: ... ."
}

Response 404

{
  "message" : "... not found."
}

Get survey weight model details.

GET /{surveyId}/weightmodels/{weightModelId}

Description

Returns information about a survey weight model by id. Sample request:

GET /p12345/WeightModels/15

Parameters

Type Name Description Schema

Path

surveyId
required

The id of the survey

string

Path

weightModelId
required

The id of the weight model

string

Responses

HTTP Code Description Schema

200

Ok, the request has succeeded. The survey weight model details is returned.

400

Bad request, the query parameters are not valid.

401

Unauthorized

No Content

404

Not found, the survey or the weight model was not found.

Produces

  • application/json

Tags

  • WeightModels

Example HTTP response

Response 200

{
  "id" : "15",
  "name" : "Gender & Age",
  "type" : "sampleBalancing",
  "lastGenerated" : "2021-05-21T15:09:40.817+00:00",
  "dimensions" : [ {
    "name" : "Gender",
    "values" : [ "m", "f" ]
  }, {
    "name" : "Age",
    "values" : [ "Young", "MiddleAged", "Old" ]
  } ],
  "factors" : [ {
    "key" : [ {
      "name" : "Gender",
      "value" : "m"
    }, {
      "name" : "Age",
      "value" : "Young"
    } ],
    "weight" : 0.968
  }, {
    "key" : [ {
      "name" : "Gender",
      "value" : "m"
    }, {
      "name" : "Age",
      "value" : "Young"
    } ],
    "weight" : 0.993
  }, {
    "key" : [ {
      "name" : "Gender",
      "value" : "m"
    }, {
      "name" : "Age",
      "value" : "MiddleAged"
    } ],
    "weight" : 1.087
  }, {
    "key" : [ {
      "name" : "Gender",
      "value" : "f"
    }, {
      "name" : "Age",
      "value" : "Old"
    } ],
    "weight" : 1.028
  }, {
    "key" : [ {
      "name" : "Gender",
      "value" : "f"
    }, {
      "name" : "Age",
      "value" : "MiddleAged"
    } ],
    "weight" : 0.96
  }, {
    "key" : [ {
      "name" : "Gender",
      "value" : "f"
    }, {
      "name" : "Age",
      "value" : "Old"
    } ],
    "weight" : 1.177
  } ]
}

Response 400

{
  "message" : "The query parameters are not valid: ... ."
}

Response 404

{
  "message" : "... not found."
}