Paths

Get Hubs

GET /

Description

Returns list of hubs Sample request:

GET

Parameters

Type Name Description Schema Default

Query

page
optional

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

integer (int32)

1

Query

pageSize
optional

Number of hubs to retrieve per request (default=100). Optional. Ex: Append pageSize=20 to the query parameters.

integer (int32)

100

Responses

HTTP Code Description Schema

200

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

ResourceCollectionWithLinks[Hub]

400

Bad request, the query parameters are not valid.

PublicApiError

401

Unauthorized

No Content

Produces

  • application/json

Tags

  • Hubs

Example HTTP response

Response 200

{
  "itemType" : "Hub",
  "itemCount" : 2,
  "totalCount" : 10,
  "items" : [ {
    "hubId" : 1,
    "name" : "MyHub",
    "description" : "My Hub to aggregate all surveys from a particular research.",
    "companyId" : 1,
    "companyName" : "Forsta"
  }, {
    "hubId" : 2,
    "name" : "MyHub 2 ",
    "description" : "My Hub to aggregate all surveys from another research.",
    "companyId" : 1,
    "companyName" : "Forsta"
  } ],
  "links" : {
    "nextpage" : "<host>/v1/hubs/?page=3&pageSize=2",
    "prevpage" : "<host>/v1/hubs/?page=1&pageSize=2",
    "item" : "<host>/v1/hubs/{HubId}"
  }
}

Response 400

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

Get Hub

GET /{hubId}

Description

Returns Hub Sample request:

GET /1866

Parameters

Type Name Description Schema

Path

hubId
required

Owner Hub Id

integer (int64)

Responses

HTTP Code Description Schema

200

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

Hub

400

Bad request, the query parameters are not valid.

PublicApiError

401

Unauthorized

No Content

404

Not found, Hub was not found.

PublicApiError

Produces

  • application/json

Tags

  • Hubs

Example HTTP response

Response 200

{
  "hubId" : 1,
  "name" : "MyHub",
  "description" : "My Hub to aggregate all surveys from a particular research.",
  "companyId" : 1,
  "companyName" : "Forsta",
  "links" : {
    "self" : "<host>/v1/hubs/1",
    "enduserlists" : "<host>/v1/hubs/1/enduserlists",
    "surveys" : "<host>/v1/hubs/1/surveys",
    "tables" : "<host>/v1/hubs/1/tables"
  }
}

Response 400

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

Response 404

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

Read auto-combined survey respondents.

GET /{hubId}/auto-combined-surveys/{surveyId}/respondents/data

Description

Returns auto-combined survey respondents as stream. Sample requests:

GET /4410/auto-combined-surveys/p240597392086/respondents/data
GET /4410/auto-combined-surveys/p240597392086/respondents/data?stateId=100500

Parameters

Type Name Description Schema

Path

hubId
required

Owner Hub Id

integer (int64)

Path

surveyId
required

Id of auto-combined survey

string

Query

stateId
optional

Survey StateId. Optional. Provides incremental data load. Use this parameter in order to get only changes to the survey respondents made after the pointed survey StateId. Ignore this parameter in order to get all survey respondents.

integer (int64)

Responses

HTTP Code Description Schema

200

Ok, the request has succeeded. All requested survey respondents are returned. The API provides the data either as a stream or a resource collection depending on the request accept header.

ResourceCollection[SurveyDataRecord]

400

Bad request, the query parameters are not valid.

PublicApiError

401

Unauthorized

No Content

404

Not found, Hub or survey was not found.

PublicApiError

412

Failed to read incremental data. Retry with no 'stateId' parameter.

No Content

Produces

  • application/json

  • application/x-ndjson

Tags

  • AutoCombinedSurveyData

Example HTTP response

Response 200

{
  "itemType" : "SurveyDataRecord",
  "itemCount" : 5,
  "totalCount" : 5,
  "items" : [ {
    "combined_sourceid" : "p750209410546",
    "respid" : 1,
    "CreatedDate" : "2021-02-15T17:58:22.35+01:00"
  }, {
    "combined_sourceid" : "p750209410546",
    "respid" : 2,
    "CreatedDate" : "2021-02-15T17:58:32.473+01:00"
  }, {
    "combined_sourceid" : "p601884965518",
    "respid" : 1,
    "CreatedDate" : "2021-02-15T17:57:16.4+01:00"
  }, {
    "combined_sourceid" : "p601884965518",
    "respid" : 2,
    "CreatedDate" : "2021-02-15T17:57:32.51+01:00"
  }, {
    "combined_sourceid" : "p601884965518",
    "respid" : 3,
    "CreatedDate" : "2021-02-15T17:57:52.227+01:00"
  } ],
  "links" : {
    "self" : "<host>/v1/hubs/4410/automapped-surveys/p240597392086/respondents/data"
  }
}
{
  "application/json" : {
    "itemType" : "SurveyDataRecord",
    "itemCount" : 5,
    "totalCount" : 5,
    "items" : [ {
      "combined_sourceid" : "p750209410546",
      "respid" : 1,
      "CreatedDate" : "2021-02-15T17:58:22.35+01:00"
    }, {
      "combined_sourceid" : "p750209410546",
      "respid" : 2,
      "CreatedDate" : "2021-02-15T17:58:32.473+01:00"
    }, {
      "combined_sourceid" : "p601884965518",
      "respid" : 1,
      "CreatedDate" : "2021-02-15T17:57:16.4+01:00"
    }, {
      "combined_sourceid" : "p601884965518",
      "respid" : 2,
      "CreatedDate" : "2021-02-15T17:57:32.51+01:00"
    }, {
      "combined_sourceid" : "p601884965518",
      "respid" : 3,
      "CreatedDate" : "2021-02-15T17:57:52.227+01:00"
    } ],
    "links" : {
      "self" : "<host>/v1/hubs/4410/automapped-surveys/p240597392086/respondents/data"
    }
  },
  "application/x-ndjson" : {
    "itemType" : "SurveyDataRecord",
    "itemCount" : 5,
    "totalCount" : 5,
    "items" : [ {
      "combined_sourceid" : "p750209410546",
      "respid" : 1,
      "CreatedDate" : "2021-02-15T17:58:22.35+01:00"
    }, {
      "combined_sourceid" : "p750209410546",
      "respid" : 2,
      "CreatedDate" : "2021-02-15T17:58:32.473+01:00"
    }, {
      "combined_sourceid" : "p601884965518",
      "respid" : 1,
      "CreatedDate" : "2021-02-15T17:57:16.4+01:00"
    }, {
      "combined_sourceid" : "p601884965518",
      "respid" : 2,
      "CreatedDate" : "2021-02-15T17:57:32.51+01:00"
    }, {
      "combined_sourceid" : "p601884965518",
      "respid" : 3,
      "CreatedDate" : "2021-02-15T17:57:52.227+01:00"
    } ],
    "links" : {
      "self" : "<host>/v1/hubs/4410/automapped-surveys/p240597392086/respondents/data"
    }
  }
}

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."
  }
}

Read auto-combined survey respondents schema.

GET /{hubId}/auto-combined-surveys/{surveyId}/respondents/schema

Description

Returns auto-combined survey respondents full schema. Sample request:

GET /4410/auto-combined-surveys/p240597392086/respondents/schema

Parameters

Type Name Description Schema

Path

hubId
required

Owner Hub Id

integer (int64)

Path

surveyId
required

Id of auto-combined survey

string

Responses

HTTP Code Description Schema

200

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

SurveyDataSchema

400

Bad request, the query parameters are not valid.

PublicApiError

401

Unauthorized

No Content

404

Not found, Hub or survey was not found.

PublicApiError

Produces

  • application/json

Tags

  • AutoCombinedSurveyData

Example HTTP response

Response 200

{
  "defaultConfirmitLanguageId" : 9,
  "languages" : [ {
    "confirmitLanguageId" : 9
  } ],
  "root" : {
    "name" : "respondent",
    "keys" : [ {
      "name" : "combined_sourceid",
      "isCompound" : false,
      "isBackground" : false,
      "isHidden" : false,
      "variableType" : "singleChoice",
      "isSystemVariable" : false,
      "isRespondentVariable" : false,
      "options" : [ {
        "code" : "p601884965518",
        "hasOtherField" : false,
        "texts" : [ {
          "languageId" : 9,
          "text" : "Name of the first survey included into auto-mapping"
        } ]
      }, {
        "code" : "p750209410546",
        "hasOtherField" : false,
        "texts" : [ {
          "languageId" : 9,
          "text" : "Name of the second survey included into auto-mapping"
        } ]
      } ],
      "excludeFromReporting" : false
    }, {
      "name" : "respid",
      "isCompound" : false,
      "isBackground" : false,
      "isHidden" : false,
      "variableType" : "numeric",
      "isSystemVariable" : true,
      "isRespondentVariable" : false,
      "excludeFromReporting" : false
    } ],
    "variables" : [ {
      "name" : "CreatedDate",
      "isCompound" : false,
      "isBackground" : false,
      "isHidden" : false,
      "variableType" : "dateTime",
      "isSystemVariable" : true,
      "isRespondentVariable" : false,
      "excludeFromReporting" : false
    } ]
  }
}

Response 400

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

Response 404

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

Read auto-combined survey response data.

GET /{hubId}/auto-combined-surveys/{surveyId}/responses/data

Description

Returns auto-combined survey responses . Sample requests:

GET /4410/auto-combined-surveys/p240597392086/responses/data
GET /4410/auto-combined-surveys/p240597392086/responses/data?stateId=100500

Parameters

Type Name Description Schema

Path

hubId
required

Owner Hub Id

integer (int64)

Path

surveyId
required

Id of auto-combined survey

string

Query

stateId
optional

Survey StateId. Optional. Provides incremental data load. Use this parameter in order to get only changes to the survey responses made after the pointed survey StateId. Ignore this parameter in order to get all survey responses.

integer (int64)

Responses

HTTP Code Description Schema

200

Ok, the request has succeeded. All requested survey responses are returned. The API provides the data either as a stream or a resource collection depending on the request accept header.

ResourceCollection[SurveyDataRecord]

400

Bad request, the query parameters are not valid.

PublicApiError

401

Unauthorized

No Content

404

Not found, Hub or survey was not found.

PublicApiError

412

Failed to read incremental data. Retry with no 'stateId' parameter.

No Content

Produces

  • application/json

  • application/x-ndjson

Tags

  • AutoCombinedSurveyData

Example HTTP response

Response 200

{
  "itemType" : "SurveyDataRecord",
  "itemCount" : 5,
  "totalCount" : 5,
  "items" : [ {
    "combined_sourceid" : "p750209410546",
    "responseid" : 1,
    "respid" : 1,
    "status" : "complete",
    "q1" : "First answer from first survey included into auto-mapping"
  }, {
    "combined_sourceid" : "p750209410546",
    "responseid" : 2,
    "respid" : 2,
    "status" : "complete",
    "q1" : "Second answer from first survey included into auto-mapping"
  }, {
    "combined_sourceid" : "p601884965518",
    "responseid" : 1,
    "respid" : 1,
    "status" : "complete",
    "q1" : "First answer from second survey included into auto-mapping"
  }, {
    "combined_sourceid" : "p601884965518",
    "responseid" : 2,
    "respid" : 2,
    "status" : "complete",
    "q1" : "Second from second survey included into auto-mapping"
  }, {
    "combined_sourceid" : "p601884965518",
    "responseid" : 3,
    "respid" : 3,
    "status" : "complete",
    "q1" : "Third answer from second survey included into auto-mapping"
  } ],
  "links" : {
    "self" : "<host>/v1/hubs/4410/automapped-surveys/p240597392086/responses/data"
  }
}
{
  "application/json" : {
    "itemType" : "SurveyDataRecord",
    "itemCount" : 5,
    "totalCount" : 5,
    "items" : [ {
      "combined_sourceid" : "p750209410546",
      "responseid" : 1,
      "respid" : 1,
      "status" : "complete",
      "q1" : "First answer from first survey included into auto-mapping"
    }, {
      "combined_sourceid" : "p750209410546",
      "responseid" : 2,
      "respid" : 2,
      "status" : "complete",
      "q1" : "Second answer from first survey included into auto-mapping"
    }, {
      "combined_sourceid" : "p601884965518",
      "responseid" : 1,
      "respid" : 1,
      "status" : "complete",
      "q1" : "First answer from second survey included into auto-mapping"
    }, {
      "combined_sourceid" : "p601884965518",
      "responseid" : 2,
      "respid" : 2,
      "status" : "complete",
      "q1" : "Second from second survey included into auto-mapping"
    }, {
      "combined_sourceid" : "p601884965518",
      "responseid" : 3,
      "respid" : 3,
      "status" : "complete",
      "q1" : "Third answer from second survey included into auto-mapping"
    } ],
    "links" : {
      "self" : "<host>/v1/hubs/4410/automapped-surveys/p240597392086/responses/data"
    }
  },
  "application/x-ndjson" : {
    "itemType" : "SurveyDataRecord",
    "itemCount" : 5,
    "totalCount" : 5,
    "items" : [ {
      "combined_sourceid" : "p750209410546",
      "responseid" : 1,
      "respid" : 1,
      "status" : "complete",
      "q1" : "First answer from first survey included into auto-mapping"
    }, {
      "combined_sourceid" : "p750209410546",
      "responseid" : 2,
      "respid" : 2,
      "status" : "complete",
      "q1" : "Second answer from first survey included into auto-mapping"
    }, {
      "combined_sourceid" : "p601884965518",
      "responseid" : 1,
      "respid" : 1,
      "status" : "complete",
      "q1" : "First answer from second survey included into auto-mapping"
    }, {
      "combined_sourceid" : "p601884965518",
      "responseid" : 2,
      "respid" : 2,
      "status" : "complete",
      "q1" : "Second from second survey included into auto-mapping"
    }, {
      "combined_sourceid" : "p601884965518",
      "responseid" : 3,
      "respid" : 3,
      "status" : "complete",
      "q1" : "Third answer from second survey included into auto-mapping"
    } ],
    "links" : {
      "self" : "<host>/v1/hubs/4410/automapped-surveys/p240597392086/responses/data"
    }
  }
}

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."
  }
}

Read auto-combined survey response data schema.

GET /{hubId}/auto-combined-surveys/{surveyId}/responses/schema

Description

Returns auto-combined survey responses full schema. Sample request:

GET /4410/auto-combined-surveys/p240597392086/responses/schema

Parameters

Type Name Description Schema

Path

hubId
required

Owner Hub Id

integer (int64)

Path

surveyId
required

Id of auto-combined survey

string

Responses

HTTP Code Description Schema

200

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

SurveyDataSchema

400

Bad request, the query parameters are not valid.

PublicApiError

401

Unauthorized

No Content

404

Not found, Hub or survey was not found.

PublicApiError

Produces

  • application/json

Tags

  • AutoCombinedSurveyData

Example HTTP response

Response 200

{
  "defaultConfirmitLanguageId" : 9,
  "languages" : [ {
    "confirmitLanguageId" : 9
  } ],
  "root" : {
    "name" : "response",
    "keys" : [ {
      "name" : "combined_sourceid",
      "isCompound" : false,
      "isBackground" : false,
      "isHidden" : false,
      "variableType" : "singleChoice",
      "isSystemVariable" : false,
      "isRespondentVariable" : false,
      "options" : [ {
        "code" : "p601884965518",
        "hasOtherField" : false,
        "texts" : [ {
          "languageId" : 9,
          "text" : "Name of the first survey included into auto-mapping"
        } ]
      }, {
        "code" : "p750209410546",
        "hasOtherField" : false,
        "texts" : [ {
          "languageId" : 9,
          "text" : "Name of the second survey included into auto-mapping"
        } ]
      } ],
      "excludeFromReporting" : false
    }, {
      "name" : "responseid",
      "isCompound" : false,
      "isBackground" : false,
      "isHidden" : false,
      "variableType" : "numeric",
      "isSystemVariable" : true,
      "isRespondentVariable" : false,
      "excludeFromReporting" : false
    } ],
    "variables" : [ {
      "name" : "respid",
      "isCompound" : false,
      "isBackground" : false,
      "isHidden" : false,
      "variableType" : "numeric",
      "isSystemVariable" : true,
      "isRespondentVariable" : false,
      "excludeFromReporting" : false
    }, {
      "name" : "q1",
      "isCompound" : false,
      "isBackground" : false,
      "isHidden" : false,
      "variableType" : "text",
      "isSystemVariable" : false,
      "isRespondentVariable" : false,
      "excludeFromReporting" : false
    } ]
  }
}

Response 400

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

Response 404

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

Read auto-combined survey state.

GET /{hubId}/auto-combined-surveys/{surveyId}/state

Description

Returns auto-combined survey state. Note. Any change to a survey leads to the survey state change (survey StateId increment). You can use this stateId to get survey respondents or responses incrementally, see GetAutoCombinedSurveyRespondents and GetAutoCombinedSurveyResponses methods for more details. Sample request:

GET /4410/auto-combined-surveys/p240597392086/state

Parameters

Type Name Description Schema

Path

hubId
required

Owner Hub Id

integer (int64)

Path

surveyId
required

Id of auto-combined survey

string

Responses

HTTP Code Description Schema

200

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

SurveyState

400

Bad request, the query parameters are not valid.

PublicApiError

401

Unauthorized

No Content

404

Not found, Hub or survey was not found.

PublicApiError

Produces

  • application/json

Tags

  • AutoCombinedSurveyData

Example HTTP response

Response 200

{
  "stateId" : 100500,
  "links" : {
    "self" : "<host>/v1/hubs/4410/automapped-surveys/p240597392086/state"
  }
}

Response 400

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

Response 404

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

Add a custom data table

POST /{hubId}/customdata/tables

Description

Sample request:

POST /1866/customdata/tables/
{
   "name": "East_Region",
   "languageIds": [9, 20],
   "defaultLanguageId": 9,
   "dataSetName": "clients",
   "fields":[
      {"name": "Name", "dataType": "Text", "isPrimaryKey": "true", "length": 255},
      {"name": "City", "dataType": "Text"},
      {"name": "Contact", "dataType": "Text"}
   ]
}

Parameters

Type Name Description Schema

Path

hubId
required

Hub Id

integer (int64)

Body

body
optional

Object containing properties for the new table

AddCustomTable

Responses

HTTP Code Description Schema

201

A table is created. The table is returned.

CustomTable

400

Bad request. The record is not valid.

PublicApiError

401

Unauthorized

No Content

404

Not found, Hub or table was not found.

PublicApiError

Consumes

  • application/json

Produces

  • application/json

Tags

  • CustomData

Example HTTP response

Response 201

{
  "links" : { },
  "hubId" : 1234,
  "dataSetId" : "Ds1",
  "name" : "MyHubCustomTable",
  "publicName" : "MyHubCustomTable",
  "subType" : "TextAnalysis",
  "id" : 123,
  "dataSetPublicName" : "Public DataSet Name",
  "created" : "0001-01-01T00:00:00+00:00",
  "createdByUserId" : 0,
  "lastModified" : "0001-01-01T00:00:00+00:00"
}

Response 400

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

Response 404

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

Get custom data tables

GET /{hubId}/customdata/tables

Description

Returns custom data tables Sample request:

GET /1866/customdata/tables

Parameters

Type Name Description Schema Default

Path

hubId
required

Hub Id

integer (int64)

Query

$filter
optional

OData filter to limit the result set. Optional. Ex: $filter=Name eq 'test'.

string

Query

$orderby
optional

Optional. Ex: $orderby=Name to order the tables per Name.

string

Query

$skip
optional

Use this when paging through the tables (default=0). Optional. Ex:$skip=4 to skip the 40 first tables.

integer (int32)

0

Query

$top
optional

Number of tables to retrieve per request (default=100). Optional. Ex: $top=10.

integer (int32)

100

Responses

HTTP Code Description Schema

200

Ok, the request has succeeded. The list of custom data tables for hub is returned.

ResourceCollection[CustomTable]

400

Bad request, the query parameters are not valid.

PublicApiError

401

Unauthorized

No Content

404

Not found, Hub or survey was not found.

PublicApiError

Produces

  • application/json

Tags

  • CustomData

Example HTTP response

Response 200

{
  "itemType" : "CustomTable",
  "itemCount" : 2,
  "totalCount" : 2,
  "items" : [ {
    "links" : { },
    "hubId" : 1234,
    "dataSetId" : "Ds1",
    "name" : "MyHubCustomTable",
    "publicName" : "MyHubCustomTable",
    "subType" : "TextAnalysis",
    "id" : 123,
    "dataSetPublicName" : "Public DataSet Name",
    "created" : "0001-01-01T00:00:00+00:00",
    "createdByUserId" : 0,
    "lastModified" : "0001-01-01T00:00:00+00:00"
  }, {
    "links" : { },
    "hubId" : 1234,
    "dataSetId" : "Ds2",
    "name" : "MyHubCustomTable",
    "publicName" : "MyHubCustomTable",
    "subType" : "TextAnalysis",
    "id" : 124,
    "dataSetPublicName" : "Public DataSet Name",
    "created" : "0001-01-01T00:00:00+00:00",
    "createdByUserId" : 0,
    "lastModified" : "0001-01-01T00:00:00+00:00"
  } ],
  "links" : { }
}

Response 400

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

Response 404

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

Get custom data table

GET /{hubId}/customdata/tables/{tableId}

Description

Returns custom data table by id Sample request:

GET /1866/customdata/tables/1

Parameters

Type Name Description Schema

Path

hubId
required

Hub Id

integer (int64)

Path

tableId
required

Table Id

integer (int32)

Responses

HTTP Code Description Schema

200

Ok, the request has succeeded. The custom data table is returned.

CustomTable

400

Bad request, the query parameters are not valid.

PublicApiError

401

Unauthorized

No Content

404

Not found, Hub or survey was not found.

PublicApiError

Produces

  • application/json

Tags

  • CustomData

Example HTTP response

Response 200

{
  "links" : { },
  "hubId" : 1234,
  "dataSetId" : "Ds1",
  "name" : "MyHubCustomTable",
  "publicName" : "MyHubCustomTable",
  "subType" : "TextAnalysis",
  "id" : 123,
  "dataSetPublicName" : "Public DataSet Name",
  "created" : "0001-01-01T00:00:00+00:00",
  "createdByUserId" : 0,
  "lastModified" : "0001-01-01T00:00:00+00:00"
}

Response 400

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

Response 404

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

Delete custom data table

DELETE /{hubId}/customdata/tables/{tableId}

Description

Deletes custom data table by id Sample request:

DELETE /1866/customdata/tables/1

Parameters

Type Name Description Schema

Path

hubId
required

Hub Id

integer (int64)

Path

tableId
required

Table Id

integer (int32)

Responses

HTTP Code Description Schema

204

Ok, the request has succeeded. The custom data table is deleted.

No Content

400

Bad request, the query parameters are not valid.

PublicApiError

401

Unauthorized

No Content

404

Not found, table was not found.

PublicApiError

Produces

  • application/json

Tags

  • CustomData

Get changed table records

GET /{hubId}/customdata/tables/{tableId}/changed-records

Description

Returns list of changed table records Sample request:

GET /1866/customdata/tables/1/changed-records

Parameters

Type Name Description Schema

Path

hubId
required

Hub Id

integer (int64)

Path

tableId
required

Table Id

integer (int32)

Query

allowTimestampFallback
optional

Allow Timestamp Fallback

boolean

Query

includeDeletes
optional

Include Deletes. Ex: When the response type is json, "IsDeleted" flag return true if the record is deleted. When the response type is x-ndjson, "__IsDeleted" flag return true if the record is deleted.

boolean

Query

stateId
optional

Table Data State Id

integer (int64)

Responses

HTTP Code Description Schema

200

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

ResourceCollection[CustomTableRecord]

400

Bad request, the query parameters are not valid.

PublicApiError

401

Unauthorized

No Content

404

Not found, Hub or table was not found.

PublicApiError

412

Incremental data read fail

No Content

Produces

  • application/json

  • application/x-ndjson

Tags

  • CustomData

Example HTTP response

Response 200

{
  "itemType" : "CustomTableRecord",
  "itemCount" : 1,
  "totalCount" : 0,
  "items" : [ {
    "__recordId" : 1,
    "field1" : "value1",
    "field2" : 1,
    "field3" : "f31"
  } ],
  "links" : { }
}
{
  "application/json" : {
    "itemType" : "CustomTableRecord",
    "itemCount" : 1,
    "totalCount" : 0,
    "items" : [ {
      "__recordId" : 1,
      "field1" : "value1",
      "field2" : 1,
      "field3" : "f31"
    } ],
    "links" : { }
  },
  "application/x-ndjson" : {
    "itemType" : "CustomTableRecord",
    "itemCount" : 1,
    "totalCount" : 0,
    "items" : [ {
      "__recordId" : 1,
      "field1" : "value1",
      "field2" : 1,
      "field3" : "f31"
    } ],
    "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."
  }
}

Get table data state

GET /{hubId}/customdata/tables/{tableId}/datastate

Description

Returns data state Sample request:

GET /1866/customdata/tables/1/datastate

Parameters

Type Name Description Schema

Path

hubId
required

Hub Id

integer (int64)

Path

tableId
required

Table Id

integer (int32)

Responses

HTTP Code Description Schema

200

Ok, The request has succeeded. The last saved table’s state Id is returned.

integer (int64)

400

Bad request

No Content

401

Unauthorized

No Content

404

Table not found

No Content

Produces

  • application/json

Tags

  • CustomData

Add table field

POST /{hubId}/customdata/tables/{tableId}/fields

Description

Returns table field by fieldId Sample request:

POST /1866/customdata/tables/1/fields

Parameters

Type Name Description Schema

Path

hubId
required

Hub Id

integer (int64)

Path

tableId
required

Table Id

integer (int32)

Body

body
optional

Field to add

CustomTableField

Responses

HTTP Code Description Schema

200

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

CustomTableField

400

Bad request, the query parameters are not valid.

PublicApiError

401

Unauthorized

No Content

404

Not found, Hub or table was not found.

PublicApiError

Consumes

  • application/json-patch+json

  • application/json

  • text/json

  • application/*+json

Produces

  • application/json

Tags

  • CustomData

Example HTTP response

Response 200

{
  "id" : 1,
  "name" : "Field1",
  "label" : "My field1",
  "isPrimaryKey" : true,
  "dataType" : "text",
  "length" : 255,
  "isLanguageDependent" : false,
  "links" : {
    "self" : "<host>/v1/hubs/1866/customdata/tables/15/fields/1"
  }
}

Response 400

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

Response 404

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

Get table fields

GET /{hubId}/customdata/tables/{tableId}/fields

Description

Returns list of table fields Sample request:

GET /1866/customdata/tables/1/fields

Parameters

Type Name Description Schema

Path

hubId
required

Hub Id

integer (int64)

Path

tableId
required

Table Id

integer (int32)

Responses

HTTP Code Description Schema

200

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

ResourceCollection[CustomTableField]

400

Bad request, the query parameters are not valid.

PublicApiError

401

Unauthorized

No Content

404

Not found, Hub or table was not found.

PublicApiError

Produces

  • application/json

Tags

  • CustomData

Example HTTP response

Response 200

{
  "itemType" : "CustomTableField",
  "itemCount" : 1,
  "totalCount" : 1,
  "items" : [ {
    "id" : 1,
    "name" : "Field1",
    "label" : "My field1",
    "isPrimaryKey" : true,
    "dataType" : "text",
    "length" : 255,
    "isLanguageDependent" : false,
    "links" : { }
  }, {
    "id" : 2,
    "name" : "Field2",
    "label" : "My field2",
    "isPrimaryKey" : true,
    "dataType" : "numeric",
    "precision" : 8,
    "scale" : 2,
    "isLanguageDependent" : false,
    "links" : { }
  }, {
    "id" : 3,
    "name" : "Field3",
    "label" : "My field3",
    "isPrimaryKey" : false,
    "dataType" : "date",
    "isLanguageDependent" : false,
    "links" : { }
  }, {
    "id" : 4,
    "name" : "Field4",
    "label" : "My field4",
    "isPrimaryKey" : false,
    "dataType" : "dateTime",
    "isLanguageDependent" : false,
    "links" : { }
  } ],
  "links" : {
    "item" : "<host>/v1/hubs/1866/customdata/tables/15/fields/1"
  }
}

Response 400

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

Response 404

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

Get table field

GET /{hubId}/customdata/tables/{tableId}/fields/{fieldId}

Description

Returns table field by fieldId Sample request:

GET /1866/customdata/tables/1/fields/3

Parameters

Type Name Description Schema

Path

fieldId
required

Field Id

integer (int32)

Path

hubId
required

Hub Id

integer (int64)

Path

tableId
required

Table Id

integer (int32)

Responses

HTTP Code Description Schema

200

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

CustomTableField

400

Bad request, the query parameters are not valid.

PublicApiError

401

Unauthorized

No Content

404

Not found, Hub or table was not found.

PublicApiError

Produces

  • application/json

Tags

  • CustomData

Example HTTP response

Response 200

{
  "id" : 1,
  "name" : "Field1",
  "label" : "My field1",
  "isPrimaryKey" : true,
  "dataType" : "text",
  "length" : 255,
  "isLanguageDependent" : false,
  "links" : {
    "self" : "<host>/v1/hubs/1866/customdata/tables/15/fields/1"
  }
}

Response 400

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

Response 404

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

Delete table field

DELETE /{hubId}/customdata/tables/{tableId}/fields/{fieldId}

Description

Deletes table field by fieldId Sample request:

DELETE /1866/customdata/tables/1/fields/3

Parameters

Type Name Description Schema

Path

fieldId
required

Field Id

integer (int32)

Path

hubId
required

Hub Id

integer (int64)

Path

tableId
required

Table Id

integer (int32)

Responses

HTTP Code Description Schema

204

Ok, the request has succeeded. The field is deleted.

No Content

400

Bad request, the query parameters are not valid.

PublicApiError

401

Unauthorized

No Content

404

Not found, table or field was not found.

PublicApiError

Produces

  • application/json

Tags

  • CustomData

Example HTTP response

Response 400

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

Response 404

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

Add table field categories

POST /{hubId}/customdata/tables/{tableId}/fields/{fieldId}/categories

Description

Add categories to a table field Sample request:

POST /1866/customdata/tables/15/fields/2/categories

Parameters

Type Name Description Schema

Path

fieldId
required

Field Id

integer (int32)

Path

hubId
required

Hub Id

integer (int64)

Path

tableId
required

Table Id

integer (int32)

Body

body
optional

Categories to add

< CustomTableFieldCategory > array

Responses

HTTP Code Description Schema

200

Ok, the field categories were added

string

400

Bad request, the query parameters are not valid.

PublicApiError

401

Unauthorized

No Content

404

Not found, Hub, table or field was not found.

PublicApiError

Consumes

  • application/json-patch+json

  • application/json

  • text/json

  • application/*+json

Produces

  • application/json

Tags

  • CustomData

Example HTTP response

Response 200

{
  "itemType" : "CustomTableFieldCategory",
  "itemCount" : 1,
  "totalCount" : 1,
  "items" : [ {
    "labels" : [ {
      "language" : 5,
      "label" : "First answer"
    } ],
    "code" : "A1",
    "links" : { }
  } ],
  "links" : { }
}

Response 400

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

Response 404

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

Get table field categories

GET /{hubId}/customdata/tables/{tableId}/fields/{fieldId}/categories

Description

Returns table field categories Sample request:

GET /1866/customdata/tables/15/fields/2/categories

Parameters

Type Name Description Schema

Path

fieldId
required

Field Id

integer (int32)

Path

hubId
required

Hub Id

integer (int64)

Path

tableId
required

Table Id

integer (int32)

Responses

HTTP Code Description Schema

200

Ok, the request has succeeded. The custom table field category list is returned.

CustomTableFieldCategory

400

Bad request, the query parameters are not valid.

PublicApiError

401

Unauthorized

No Content

404

Not found, Hub, table or field was not found.

PublicApiError

Produces

  • application/json

Tags

  • CustomData

Example HTTP response

Response 200

{
  "itemType" : "CustomTableFieldCategory",
  "itemCount" : 1,
  "totalCount" : 1,
  "items" : [ {
    "labels" : [ {
      "language" : 5,
      "label" : "First answer"
    } ],
    "code" : "A1",
    "links" : { }
  } ],
  "links" : { }
}

Response 400

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

Response 404

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

Update table field categories

PUT /{hubId}/customdata/tables/{tableId}/fields/{fieldId}/categories

Description

Update categories for a table field Sample request:

PUT /1866/customdata/tables/15/fields/2/categories

Parameters

Type Name Description Schema

Path

fieldId
required

Field Id

integer (int32)

Path

hubId
required

Hub Id

integer (int64)

Path

tableId
required

Table Id

integer (int32)

Body

body
optional

Categories to update

< CustomTableFieldCategory > array

Responses

HTTP Code Description Schema

200

Ok, the field categories were updated.

string

400

Bad request, the query parameters are not valid.

PublicApiError

401

Unauthorized

No Content

404

Not found, Hub, table or field was not found.

PublicApiError

Consumes

  • application/json-patch+json

  • application/json

  • text/json

  • application/*+json

Produces

  • application/json

Tags

  • CustomData

Example HTTP response

Response 200

{
  "itemType" : "CustomTableFieldCategory",
  "itemCount" : 1,
  "totalCount" : 1,
  "items" : [ {
    "labels" : [ {
      "language" : 5,
      "label" : "First answer"
    } ],
    "code" : "A1",
    "links" : { }
  } ],
  "links" : { }
}

Response 400

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

Response 404

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

Add records to table

POST /{hubId}/customdata/tables/{tableId}/records

Description

Sample request:

POST /1866/customdata/tables/1/records
{
   "dataSchema":
   {
        fieldNames: ["AKeyField", "AFieldField"]
   },
   "data":[
      {"AKeyField": "Key2", "AFieldName": "A2"},
      {"AKeyField": "Key3", "AFieldName": "A3"},
      {"AKeyField": "Key4", "AFieldName": "A4"}
   ]
}

Parameters

Type Name Description Schema

Path

hubId
required

Hub Id

integer (int64)

Path

tableId
required

Table Id

integer (int32)

Body

body
optional

Object containing new records

CustomDataWriteObject

Responses

HTTP Code Description Schema

200

New records were added.

CustomTableRecord

400

Bad request. The record is not valid.

PublicApiError

401

Unauthorized

No Content

404

Not found, Hub or table was not found.

PublicApiError

Consumes

  • application/json

Produces

  • application/json

Tags

  • CustomData

Example HTTP response

Response 200

{
  "insertedRecords" : 0,
  "updatedRecords" : 1,
  "deletedRecords" : 0
}

Response 400

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

Response 404

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

Get table records

GET /{hubId}/customdata/tables/{tableId}/records

Description

Returns list of table records Sample request:

GET /1866/customdata/tables/1/records

Parameters

Type Name Description Schema Default

Path

hubId
required

Hub Id

integer (int64)

Path

tableId
required

Table Id

integer (int32)

Query

$filter
optional

OData filter to limit the result set. Optional. Ex: $filter=Name eq 'test'.

string

Query

$orderby
optional

Optional. Ex: $orderby=Name to order the records per Name.

string

Query

$skip
optional

Use this when paging through the records (default=0). Optional. Ex: $skip=4 to skip the 40 first records.

integer (int32)

0

Query

$top
optional

Number of records to retrieve per request (default=100). Optional. Ex: $top=10.

integer (int32)

100

Responses

HTTP Code Description Schema

200

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

ResourceCollection[CustomTableRecord]

400

Bad request, the query parameters are not valid.

PublicApiError

401

Unauthorized

No Content

404

Not found, Hub or table was not found.

PublicApiError

Produces

  • application/json

Tags

  • CustomData

Example HTTP response

Response 200

{
  "itemType" : "CustomTableRecord",
  "itemCount" : 1,
  "totalCount" : 1,
  "items" : [ {
    "__recordId" : 23,
    "field1" : "value1",
    "field2" : 1,
    "field3" : "f31"
  } ],
  "links" : {
    "self" : "<host>/v1/hubs/1866/tables/1/records",
    "item" : "<host>/v1/hubs/1866/tables/1/records/23"
  }
}

Response 400

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

Response 404

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

Update table record collection with the new record set.

PUT /{hubId}/customdata/tables/{tableId}/records

Description

Sample request:

PUT /1866/customdata/tables/1/records
{
   "dataSchema":
   {
        fieldNames: ["AKeyField", "AFieldField"]
   },
   "data":[
      {"AKeyField": "Key2", "AFieldName": "A2"},
      {"AKeyField": "Key3", "AFieldName": "A3"},
      {"AKeyField": "Key4", "AFieldName": "A4"}
   ]
}

Parameters

Type Name Description Schema

Path

hubId
required

Hub Id

integer (int64)

Path

tableId
required

table Id

integer (int32)

Body

body
optional

Object containing new records

CustomDataWriteObject

Responses

HTTP Code Description Schema

200

Ok. Records are updated.

No Content

204

Update completed successfully

No Content

400

Bad request. The record set is not valid.

PublicApiError

401

Unauthorized

No Content

404

Not found, Hub or table was not found.

PublicApiError

Consumes

  • application/json

Produces

  • application/json

Tags

  • CustomData

Example HTTP response

Response 400

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

Response 404

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

Delete records from table

DELETE /{hubId}/customdata/tables/{tableId}/records

Description

Deletes records from table Sample request:

DELETE /1866/customdata/tables/15/records
{
   "dataSchema":
   {
        keys: ["AKeyField"]
   },
   "data":[
      {"AKeyField": "Key2"},
      {"AKeyField": "Key3"},
      {"AKeyField": "Key4"}
   ]
}

Parameters

Type Name Description Schema

Path

hubId
required

Hub Id

integer (int64)

Path

tableId
required

Table Id

integer (int32)

Body

body
optional

Records

CustomDataDeleteObject

Responses

HTTP Code Description Schema

204

Ok, the request has succeeded. The record has been deleted.

No Content

400

Bad request, the query parameters are not valid.

PublicApiError

401

Unauthorized

No Content

404

Not found, Hub, table or record was not found.

PublicApiError

Consumes

  • application/json-patch+json

  • application/json

  • text/json

  • application/*+json

Produces

  • application/json

Tags

  • CustomData

Example HTTP response

Response 400

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

Response 404

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

Patch table record collection

PATCH /{hubId}/customdata/tables/{tableId}/records

Description

Sample request:

PATCH /1866/customdata/tables/1/records
{
   "dataSchema":
   {
        fieldNames: ["AKeyField", "AFieldField"]
   },
   "data":[
      {"AKeyField": "Key2", "AFieldName": "A2"},
      {"AKeyField": "Key3", "AFieldName": "A3"},
      {"AKeyField": "Key4", "AFieldName": "A4"}
   ]
}

Parameters

Type Name Description Schema

Path

hubId
required

Hub Id

integer (int64)

Path

tableId
required

table Id

integer (int32)

Body

body
optional

Object containing new records

CustomDataWriteObject

Responses

HTTP Code Description Schema

200

Ok. Patch completed successfully.

No Content

400

Bad request. Input json patch document is not valid.

PublicApiError

401

Unauthorized

No Content

404

Not found, Hub or table was not found.

PublicApiError

Consumes

  • application/json

Produces

  • application/json

Tags

  • CustomData

Example HTTP response

Response 400

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

Response 404

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

Get table record

GET /{hubId}/customdata/tables/{tableId}/records/{recordId}

Description

Returns record by recordId Sample request:

GET /1866/customdata/tables/1/records/3

Parameters

Type Name Description Schema

Path

hubId
required

Hub Id

integer (int64)

Path

recordId
required

Record Id

integer (int64)

Path

tableId
required

Table Id

integer (int32)

Responses

HTTP Code Description Schema

200

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

CustomTableRecord

400

Bad request, the query parameters are not valid.

PublicApiError

401

Unauthorized

No Content

404

Not found, Hub or table was not found.

PublicApiError

Produces

  • application/json

Tags

  • CustomData

Example HTTP response

Response 200

{
  "__recordId" : 1,
  "field1" : "value1",
  "field2" : 1,
  "field3" : "f31"
}

Response 400

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

Response 404

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

Update table record

PUT /{hubId}/customdata/tables/{tableId}/records/{recordId}

Description

Sample request:

PUT /1866/customdata/tables/1/records/2
{
    "field1":"value2",
    "field2":6,
    "field3":"f323"
}

Parameters

Type Name Description Schema

Path

hubId
required

Hub Id

integer (int64)

Path

recordId
required

Record Id

integer (int64)

Path

tableId
required

table Id

integer (int32)

Body

body
optional

Record to patch into the table

CustomTableRecord

Responses

HTTP Code Description Schema

204

No content. Record is patched.

No Content

400

Bad request. The record is not valid.

PublicApiError

401

Unauthorized

No Content

404

Not found, Hub or table was not found.

PublicApiError

Consumes

  • application/json

Produces

  • application/json

Tags

  • CustomData

Example HTTP response

Response 400

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

Response 404

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

Delete record from table

DELETE /{hubId}/customdata/tables/{tableId}/records/{recordId}

Description

Deletes record from table Sample request:

DELETE /1866/customdata/tables/15/records/3

Parameters

Type Name Description Schema

Path

hubId
required

Hub Id

integer (int64)

Path

recordId
required

Record Id

integer (int64)

Path

tableId
required

Table Id

integer (int32)

Responses

HTTP Code Description Schema

200

Ok, the request has succeeded. The record has been deleted.

No Content

400

Bad request, the query parameters are not valid.

PublicApiError

401

Unauthorized

No Content

404

Not found, Hub, table or record was not found.

PublicApiError

Produces

  • application/json

Tags

  • CustomData

Example HTTP response

Response 400

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

Response 404

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

Create End User List

POST /{hubId}/enduserlists

Description

Returns a new end user list. Sample request:

POST /1866/enduserlists
{
    "name":"My end user list"
}

Parameters

Type Name Description Schema

Path

hubId
required

Owner Hub Id

integer (int64)

Body

body
optional

List to create

EndUserList

Responses

HTTP Code Description Schema

200

Ok, the request has succeeded. The end user list is returned.

EndUserList

400

Bad request, the query parameters are not valid.

PublicApiError

401

Unauthorized

No Content

404

Not found, Hub was not found.

PublicApiError

Consumes

  • application/json-patch+json

  • application/json

  • text/json

  • application/*+json

Produces

  • application/json

Tags

  • EndUserLists

Example HTTP response

Response 200

{
  "id" : 1,
  "name" : "MyEndUserList1",
  "links" : { }
}

Response 400

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

Response 404

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

Get End User Lists

GET /{hubId}/enduserlists

Description

Returns list of end user lists. Sample request:

GET /1866/enduserlists

Parameters

Type Name Description Schema

Path

hubId
required

Owner Hub Id

integer (int64)

Responses

HTTP Code Description Schema

200

Ok, the request has succeeded. The list of end user lists is returned.

ResourceCollection[EndUserList]

400

Bad request, the query parameters are not valid.

PublicApiError

401

Unauthorized

No Content

404

Not found, Hub was not found.

PublicApiError

Produces

  • application/json

Tags

  • EndUserLists

Example HTTP response

Response 200

{
  "itemType" : "EndUserList",
  "itemCount" : 1,
  "totalCount" : 1,
  "items" : [ {
    "id" : 1,
    "name" : "MyEndUserList1",
    "links" : { }
  } ],
  "links" : {
    "item" : "<host>/v1/hubs/1866/enduserlists/1"
  }
}

Response 400

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

Response 404

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

Update End User List

PUT /{hubId}/enduserlists/{listId}

Description

Update an existing end user list. Sample request:

PUT /1866/enduserlists/1
{
    "name":"New list name"
}

Parameters

Type Name Description Schema

Path

hubId
required

Owner Hub Id

integer (int64)

Path

listId
required

listId to update

integer (int32)

Body

body
optional

List to update

EndUserList

Responses

HTTP Code Description Schema

200

Ok, the request has succeeded. The end user list is returned.

EndUserList

400

Bad request, the query parameters are not valid.

PublicApiError

401

Unauthorized

No Content

404

Not found, Hub was not found.

PublicApiError

Consumes

  • application/json-patch+json

  • application/json

  • text/json

  • application/*+json

Produces

  • application/json

Tags

  • EndUserLists

Example HTTP response

Response 200

{
  "id" : 1,
  "name" : "MyEndUserList1",
  "links" : { }
}

Response 400

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

Response 404

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

Delete End User List

DELETE /{hubId}/enduserlists/{listId}

Description

Sample request:

DELETE /1866/enduserlists/1

Parameters

Type Name Description Schema

Path

hubId
required

Owner Hub Id

integer (int64)

Path

listId
required

List to delete

integer (int32)

Responses

HTTP Code Description Schema

204

Ok, the request has succeeded. The end user list is deleted.

EndUserList

400

Bad request, the query parameters are not valid.

PublicApiError

401

Unauthorized

No Content

404

Not found, Hub was not found.

PublicApiError

Produces

  • application/json

Tags

  • EndUserLists

Example HTTP response

Response 204

{
  "id" : 1,
  "name" : "MyEndUserList1",
  "links" : { }
}

Response 400

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

Response 404

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

Create End User

POST /{hubId}/enduserlists/{listId}/users

Description

Create a new End User within an End User List.

Parameters

Type Name Description Schema

Path

hubId
required

The hub where the user will be added

integer (int64)

Path

listId
required

The end user list where the user will be added

integer (int32)

Body

body
optional

The end user to add

EndUser

Responses

HTTP Code Description Schema

201

Ok, the request has succeeded. New User has been created.

EndUser

400

Bad request, the query parameters are not valid.

PublicApiError

401

Unauthorized

No Content

404

Not found, Hub or List was not found.

PublicApiError

409

Conflict, End User UserName already exists.

PublicApiError

Consumes

  • application/json-patch+json

  • application/json

  • text/json

  • application/*+json

Produces

  • application/json

Tags

  • EndUsers

Example HTTP response

Response 201

{
  "id" : 1,
  "firstName" : "first name",
  "lastName" : "last name",
  "userName" : "username",
  "email" : "email@example.com",
  "language" : 9,
  "isActive" : true,
  "comment" : "comment",
  "links" : {
    "item" : "<host>/v1/hubs/1866/enduser/1"
  }
}

Response 400

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

Response 404

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

Response 409

{
  "message" : "... already exists."
}

Get End Users

POST /{hubId}/enduserlists/{listId}/users/query

Description

Returns a list of end users based on a query.

Parameters

Type Name Description Schema

Path

hubId
required

Hub id

integer (int64)

Path

listId
required

End user list id

integer (int32)

Body

body
optional

End user filter query

EndUserFilterQuery

Responses

HTTP Code Description Schema

200

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

ResourceCollection[EndUser]

400

Bad request, the query parameters are not valid.

PublicApiError

401

Unauthorized

No Content

404

Not found, Hub, List or User was not found.

PublicApiError

Consumes

  • application/json-patch+json

  • application/json

  • text/json

  • application/*+json

Produces

  • application/json

Tags

  • EndUsers

Example HTTP response

Response 200

{
  "itemType" : "EndUser",
  "itemCount" : 1,
  "totalCount" : 1,
  "items" : [ {
    "id" : 1,
    "firstName" : "first name",
    "lastName" : "last name",
    "userName" : "username",
    "email" : "email@example.com",
    "language" : 9,
    "isActive" : true,
    "comment" : "comment",
    "links" : { }
  } ],
  "links" : {
    "item" : "<host>/v1/hubs/1866/enduser/{id}"
  }
}

Response 400

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

Response 404

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

Get End User

GET /{hubId}/enduserlists/{listId}/users/{id}

Description

Return an end user.

Parameters

Type Name Description Schema

Path

hubId
required

The hub the user is associated with

integer (int64)

Path

id
required

The ID of the user

integer (int32)

Path

listId
required

The list the user is associated with

integer (int32)

Responses

HTTP Code Description Schema

200

Ok, Request is valid, end user returned.

EndUser

401

Unauthorized

No Content

404

Not found, Hub, List or User was not found.

PublicApiError

Produces

  • application/json

Tags

  • EndUsers

Example HTTP response

Response 200

{
  "id" : 1,
  "firstName" : "first name",
  "lastName" : "last name",
  "userName" : "username",
  "email" : "email@example.com",
  "language" : 9,
  "isActive" : true,
  "comment" : "comment",
  "links" : {
    "item" : "<host>/v1/hubs/1866/enduser/1"
  }
}

Response 404

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

Delete End User

DELETE /{hubId}/enduserlists/{listId}/users/{id}

Description

Deletes an end user.

Parameters

Type Name Description Schema

Path

hubId
required

the hub associated with the user

integer (int64)

Path

id
required

the ID of the user

integer (int32)

Path

listId
required

the list associated with the user

integer (int32)

Responses

HTTP Code Description Schema

204

No content, Request is valid, end user has been deleted

No Content

401

Unauthorized

No Content

404

Not found, Hub, List or User was not found.

PublicApiError

Produces

  • application/json

Tags

  • EndUsers

Example HTTP response

Response 404

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

Update End User

PUT /{hubId}/enduserlists/{listId}/users/{userId}

Description

Update an existing end user.

Parameters

Type Name Description Schema

Path

hubId
required

The hub where the user to be updated exists

integer (int64)

Path

listId
required

The end user list where the user to be updated exists

integer (int32)

Path

userId
required

The end user id to be updated

integer (int32)

Body

body
optional

The end user to update. UserName must be unique

EndUser

Responses

HTTP Code Description Schema

201

Ok, the request has succeeded. User has been updated.

EndUser

400

Bad request, the query parameters are not valid.

PublicApiError

401

Unauthorized

No Content

404

Not found, Hub or List was not found.

PublicApiError

409

Conflict, End User UserName already exists.

PublicApiError

Consumes

  • application/json-patch+json

  • application/json

  • text/json

  • application/*+json

Produces

  • application/json

Tags

  • EndUsers

Example HTTP response

Response 201

{
  "id" : 1,
  "firstName" : "first name",
  "lastName" : "last name",
  "userName" : "username",
  "email" : "email@example.com",
  "language" : 9,
  "isActive" : true,
  "comment" : "comment",
  "links" : {
    "item" : "<host>/v1/hubs/1866/enduser/1"
  }
}

Response 400

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

Response 404

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

Response 409

{
  "message" : "... already exists."
}

Add a hierarchy to the hub.

POST /{hubId}/hierarchies

Description

Sample request:

POST /1866/hierarchies/
{
    "Name":"TestHierarchy"
}

Parameters

Type Name Description Schema

Path

hubId
required

Hub Id

integer (int64)

Body

body
optional

Object containing new hierarchy properties

AddHierarchyResource

Responses

HTTP Code Description Schema

201

A new hierarchy is being added. The new hierarchy is returned.

HierarchyResource

400

Bad request. The hierarchy is not valid.

ProblemDetails

401

Unauthorized

No Content

403

No access to this feature.

No Content

404

Not found, Hub was not found.

No Content

Consumes

  • application/json

Produces

  • application/json

Tags

  • Hierarchies

Example HTTP response

Response 201

{
  "id" : 322,
  "name" : "Hier 1",
  "companyId" : 0,
  "defaultLanguage" : 0,
  "schemaId" : 0,
  "nodeAssignmentsEnabled" : false,
  "hierarchyGuid" : "00000000-0000-0000-0000-000000000000",
  "schemaGuid" : "00000000-0000-0000-0000-000000000000",
  "tableId" : 0
}

Response 400

{
  "type" : "hub-hierarchies/bad-request",
  "title" : "Something went wrong.",
  "detail" : "Invalid result when adding object.",
  "extensions" : { }
}

Get Hub hierarchies

GET /{hubId}/hierarchies

Description

Returns a list of hierarchies linked to the hub Sample request:

GET /1866/hierarchies

Parameters

Type Name Description Schema Default

Path

hubId
required

Hub Id

integer (int64)

Query

page
optional

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

integer (int32)

1

Query

pageSize
optional

Number of hierarchies to retrieve per request (default=100). Optional. Ex: Append pageSize=20 to the query parameters.

integer (int32)

100

Responses

HTTP Code Description Schema

200

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

ResourceCollectionWithLinks[HierarchyListResource]

400

Bad request, the query parameters are not valid.

ProblemDetails

401

Unauthorized

No Content

Produces

  • application/json

Tags

  • Hierarchies

Example HTTP response

Response 200

{
  "itemType" : "HierarchyListResource",
  "itemCount" : 1,
  "totalCount" : 1,
  "items" : [ {
    "id" : 322,
    "name" : "Hier 1"
  }, {
    "id" : 54,
    "name" : "Hier 2"
  } ]
}

Response 400

{
  "type" : "hub-hierarchies/bad-request",
  "title" : "Something went wrong.",
  "detail" : "Invalid result when adding object.",
  "extensions" : { }
}

Get a specific hierarchy in the hub

GET /{hubId}/hierarchies/{hierarchyId}

Description

Returns hierarchy Sample request:

GET /1866/hierarchies/145

Parameters

Type Name Description Schema

Path

hierarchyId
required

Hierarchy Id

integer (int32)

Path

hubId
required

Hub Id

integer (int64)

Responses

HTTP Code Description Schema

200

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

HierarchyResource

400

Bad request, the query parameters are not valid.

ProblemDetails

401

Unauthorized

No Content

404

Not found, Hub or hierarchy was not found.

No Content

Produces

  • application/json

Tags

  • Hierarchies

Example HTTP response

Response 200

{
  "id" : 322,
  "name" : "Hier 1",
  "companyId" : 0,
  "defaultLanguage" : 0,
  "schemaId" : 0,
  "nodeAssignmentsEnabled" : false,
  "hierarchyGuid" : "00000000-0000-0000-0000-000000000000",
  "schemaGuid" : "00000000-0000-0000-0000-000000000000",
  "tableId" : 0
}

Response 400

{
  "type" : "hub-hierarchies/bad-request",
  "title" : "Something went wrong.",
  "detail" : "Invalid result when adding object.",
  "extensions" : { }
}

Get hierarchy nodes

GET /{hubId}/hierarchies/{hierarchyId}/nodes

Description

Returns nodes Sample request:

GET /1866/hierarchies/145/nodes

Parameters

Type Name Description Schema

Path

hierarchyId
required

Hierarchy Id

integer (int32)

Path

hubId
required

Hub Id

integer (int64)

Responses

HTTP Code Description Schema

200

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

ResourceCollection[HierarchyNodeResource]

400

Bad request, the query parameters are not valid.

ProblemDetails

401

Unauthorized

No Content

404

The hierarchy was not found.

No Content

Produces

  • application/json

Tags

  • Hierarchies

Example HTTP response

Response 200

{
  "itemType" : "HierarchyNodeResource",
  "itemCount" : 3,
  "totalCount" : 0,
  "items" : [ {
    "id" : "rooot",
    "label" : "Root Node"
  }, {
    "id" : "l1",
    "label" : "Level 1",
    "parentId" : "rooot"
  }, {
    "id" : "l2",
    "label" : "Level 2",
    "parentId" : "rooot"
  } ],
  "links" : { }
}

Response 400

{
  "type" : "hub-hierarchies/bad-request",
  "title" : "Something went wrong.",
  "detail" : "Invalid result when adding object.",
  "extensions" : { }
}

Add a hierarchy upload job.

POST /{hubId}/hierarchies/{hierarchyId}/uploads

Description

Sample request:

POST /1866/hierarchies/123/uploads
{
    "ImportMode":"UpdateExistingAndAddNew"
}

Parameters

Type Name Description Schema

Path

hierarchyId
required

Hierarchy Id

integer (int32)

Path

hubId
required

Hub Id

integer (int64)

Body

body
optional

Object containing new upload properties

AddHierarchyUploadJobResource

Responses

HTTP Code Description Schema

201

A new hierarchy upload job is being added. The new job is returned.

HierarchyUploadJobResource

400

Bad request. The upload job is not valid.

ProblemDetails

401

Unauthorized

No Content

403

No access to this feature.

No Content

404

The hierarchy was not found.

No Content

Consumes

  • application/json

Produces

  • application/json

Tags

  • Hierarchies

Example HTTP response

Response 201

{
  "id" : 322,
  "name" : "Hier 1",
  "companyId" : 0,
  "defaultLanguage" : 0,
  "schemaId" : 0,
  "nodeAssignmentsEnabled" : false,
  "hierarchyGuid" : "00000000-0000-0000-0000-000000000000",
  "schemaGuid" : "00000000-0000-0000-0000-000000000000",
  "tableId" : 0
}

Response 400

{
  "type" : "hub-hierarchies/bad-request",
  "title" : "Something went wrong.",
  "detail" : "Invalid result when adding object.",
  "extensions" : { }
}

Get a specific hierarchy upload job

GET /{hubId}/hierarchies/{hierarchyId}/uploads/{jobId}

Description

Returns job Sample request:

GET /1866/hierarchies/145/uploads/13

Parameters

Type Name Description Schema

Path

hierarchyId
required

Hierarchy Id

integer (int32)

Path

hubId
required

Hub Id

integer (int64)

Path

jobId
required

Job Id

integer (int32)

Responses

HTTP Code Description Schema

200

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

HierarchyUploadJobResource

400

Bad request, the query parameters are not valid.

ProblemDetails

401

Unauthorized

No Content

404

The hierarchy or job was not found.

No Content

Produces

  • application/json

Tags

  • Hierarchies

Example HTTP response

Response 200

{
  "id" : 322,
  "status" : "complete"
}

Response 400

{
  "type" : "hub-hierarchies/bad-request",
  "title" : "Something went wrong.",
  "detail" : "Invalid result when adding object.",
  "extensions" : { }
}

Patch status on a specific job

PATCH /{hubId}/hierarchies/{hierarchyId}/uploads/{jobId}

Description

Sample request:

PATCH /1866/hierarchies/123/uploads/31
[
    {
        "op": "replace",
        "path": "/status",
        "value": "execute"
    }
]

Parameters

Type Name Description Schema

Path

hierarchyId
required

Hierarchy Id

integer (int32)

Path

hubId
required

Hub Id

integer (int64)

Path

jobId
required

Job Id

integer (int32)

Body

body
optional

Values to be updated

< Operation > array

Responses

HTTP Code Description Schema

204

NoContent, the request has succeeded.

No Content

400

Bad request, the query parameters are not valid.

ProblemDetails

401

Unauthorized

No Content

404

The hierarchy or job was not found.

No Content

Consumes

  • application/json

Produces

  • application/json

Tags

  • Hierarchies

Example HTTP response

Response 400

{
  "type" : "hub-hierarchies/bad-request",
  "title" : "Something went wrong.",
  "detail" : "Invalid result when adding object.",
  "extensions" : { }
}

Add data to upload job.

POST /{hubId}/hierarchies/{hierarchyId}/uploads/{jobId}/data

Description

Sample request:

POST /1866/hierarchies/123/uploads/123/data

Parameters

Type Name Description Schema

Path

hierarchyId
required

Hierarchy Id

integer (int32)

Path

hubId
required

Hub Id

integer (int64)

Path

jobId
required

Job Id

integer (int32)

Responses

HTTP Code Description Schema

204

Data has been uploaded to the job.

No Content

400

Bad request. The upload job is not valid.

ProblemDetails

401

Unauthorized

No Content

404

The hierarchy or job was not found.

No Content

Produces

  • application/json

Tags

  • Hierarchies

Example HTTP response

Response 400

{
  "type" : "hub-hierarchies/bad-request",
  "title" : "Something went wrong.",
  "detail" : "Invalid result when adding object.",
  "extensions" : { }
}

Get hierarchy upload job results

GET /{hubId}/hierarchies/{hierarchyId}/uploads/{jobId}/results

Description

Returns job-results Sample request:

GET /1866/hierarchies/145/uploads/13/results

Parameters

Type Name Description Schema

Path

hierarchyId
required

Hierarchy Id

integer (int32)

Path

hubId
required

Hub Id

integer (int64)

Path

jobId
required

Job Id

integer (int32)

Responses

HTTP Code Description Schema

200

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

< ProblemDetails > array

400

Bad request. The upload job is not valid.

ProblemDetails

401

Unauthorized

No Content

404

The hierarchy or job was not found.

No Content

Produces

  • application/json

Tags

  • Hierarchies

Example HTTP response

Response 200

[ {
  "type" : "hub-hierarchies/validation-result",
  "title" : "Info",
  "detail" : "Row-1,Column-1: Blank value",
  "extensions" : { }
}, {
  "type" : "hub-hierarchies/validation-result",
  "title" : "Fatal",
  "detail" : "Row-2,Column-4: Invalid parent",
  "extensions" : { }
} ]

Response 400

{
  "type" : "hub-hierarchies/bad-request",
  "title" : "Something went wrong.",
  "detail" : "Invalid result when adding object.",
  "extensions" : { }
}

Add survey to hub. (Not yet released).

POST /{hubId}/surveys

Description

Sample request:

POST /1866/surveys/
{
    "Name":"SurveyName"
    "OriginUrn":"urn:forsta:surveys:id123123"
    "PublicName":"SurveyPublicName",
    "Levels": ["response", "respondent"]
}

Parameters

Type Name Description Schema

Path

hubId
required

Owner Hub Id

integer (int64)

Body

body
optional

Object containing new survey properties

AddSurveyProperties

Responses

HTTP Code Description Schema

201

A new survey is being added. The new survey is returned.

HubSurvey

400

Bad request. The survey is not valid.

PublicApiError

401

Unauthorized

No Content

403

No access to this feature.

No Content

404

Not found, Hub was not found.

PublicApiError

Consumes

  • application/json

Produces

  • application/json

Tags

  • Surveys

Example HTTP response

Response 201

{
  "surveyId" : "p000123",
  "sourceType" : "survey",
  "links" : {
    "self" : "<host>/v1/hubs/1/surveys/p000123"
  }
}

Response 400

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

Response 404

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

Get Hub surveys

GET /{hubId}/surveys

Description

Returns list of hub surveys Sample request:

GET /1866/surveys

Parameters

Type Name Description Schema Default

Path

hubId
required

Hub Id

integer (int64)

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.

integer (int32)

100

Responses

HTTP Code Description Schema

200

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

ResourceCollection[HubSurvey]

400

Bad request, the query parameters are not valid.

PublicApiError

401

Unauthorized

No Content

404

Not found, Hub was not found.

PublicApiError

Produces

  • application/json

Tags

  • Surveys

Example HTTP response

Response 200

{
  "itemType" : "HubSurvey",
  "itemCount" : 1,
  "totalCount" : 1,
  "items" : [ {
    "surveyId" : "p000123",
    "sourceType" : "survey"
  }, {
    "surveyId" : "p000456",
    "sourceType" : "autoMappedCombined"
  } ],
  "links" : {
    "nextpage" : "<host>/v1/hubs/1866/surveys?page=3&pageSize=100",
    "prevpage" : "<host>/v1/hubs/1866/surveys?page=1&pageSize=100",
    "item" : "<host>/v1/hubs/1866/surveys/{SurveyId}"
  }
}

Response 400

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

Response 404

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

Get Hub survey

GET /{hubId}/surveys/{surveyId}

Description

Returns Hub survey Sample request:

GET /1866/surveys/p00012345

Parameters

Type Name Description Schema

Path

hubId
required

Hub Id

integer (int64)

Path

surveyId
required

Survey Id

string

Responses

HTTP Code Description Schema

200

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

HubSurvey

400

Bad request, the query parameters are not valid.

PublicApiError

401

Unauthorized

No Content

404

Not found, Hub or survey was not found.

PublicApiError

Produces

  • application/json

Tags

  • Surveys

Example HTTP response

Response 200

{
  "surveyId" : "p000123",
  "sourceType" : "survey",
  "links" : {
    "self" : "<host>/v1/hubs/1/surveys/p000123"
  }
}

Response 400

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

Response 404

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

Get survey related data sets

GET /{hubId}/surveys/{surveyId}/related-datasets

Description

Returns survey related data sets Sample request:

GET /1866/surveys/p00012345/related-datasets

Parameters

Type Name Description Schema Default

Path

hubId
required

Hub Id

integer (int64)

Path

surveyId
required

Survey Id

string

Query

$filter
optional

OData filter to limit the result set. Optional. Ex: $filter=Name eq 'test'.

string

Query

$orderby
optional

Optional. Ex: $orderby=Name to order the data sets per Name.

string

Query

$skip
optional

Use this when paging through the data sets (default=0). Optional. Ex: $skip=4 to skip the 40 first data sets.

integer (int32)

0

Query

$top
optional

Number of data sets to retrieve per request (default=100). Optional. Ex: $top=10.

integer (int32)

100

Responses

HTTP Code Description Schema

200

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

ResourceCollection[RelatedDataSet]

400

Bad request, the query parameters are not valid.

PublicApiError

401

Unauthorized

No Content

404

Not found, Hub or survey was not found.

PublicApiError

Produces

  • application/json

Tags

  • Surveys

Example HTTP response

Response 200

{
  "itemType" : "RelatedDataSet",
  "itemCount" : 2,
  "totalCount" : 2,
  "items" : [ {
    "sourceId" : "s123",
    "name" : "MyHubRelatedDataSet",
    "publicName" : "MyHubRelatedDataSet",
    "sourceType" : "survey",
    "subType" : "TextAnalysis"
  }, {
    "sourceId" : "s124",
    "name" : "MyHubRelatedDataSet",
    "publicName" : "MyHubRelatedDataSet",
    "sourceType" : "survey",
    "subType" : "TextAnalysis"
  } ],
  "links" : { }
}

Response 400

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

Response 404

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

Get upload job

GET /{hubId}/vault-surveys/uploads/{jobId}

Description

Sample request:

GET /1866/vault-surveys/uploads/1234

Parameters

Type Name Description Schema

Path

hubId
required

Owner Hub Id

integer (int64)

Path

jobId
required

Job Id

integer (int64)

Responses

HTTP Code Description Schema

200

A job is returned

JobResource

400

Bad request.

PublicApiError

401

Unauthorized

No Content

403

No access to this feature.

No Content

404

Not found, Hub or job was not found.

PublicApiError

Produces

  • application/json

Tags

  • VaultSurveys

Example HTTP response

Response 200

{
  "id" : 98345,
  "created" : "2024-10-21T11:07:34.7015057+00:00",
  "dataSetId" : "s1",
  "status" : 0,
  "levels" : [ {
    "name" : "respondent",
    "schemaVersion" : 1,
    "dataVersion" : 1
  }, {
    "name" : "response",
    "schemaVersion" : 2,
    "dataVersion" : 8
  } ],
  "links" : { }
}

Response 400

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

Response 404

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

Update job

PATCH /{hubId}/vault-surveys/uploads/{jobId}

Description

Sample request:

PATCH /1866/vault-surveys/uploads/321123
{
    "status": "commit"
}

Parameters

Type Name Description Schema

Path

hubId
required

Owner Hub Id

integer (int64)

Path

jobId
required

Job Id

integer (int64)

Body

body
optional

Values to be updated

< string, string > map

Responses

HTTP Code Description Schema

200

Job status updated

No Content

204

No content, job is updated.

No Content

400

Bad request.

PublicApiError

401

Unauthorized

No Content

403

No access to this feature.

No Content

404

Not found, Job was not found.

PublicApiError

Consumes

  • application/json

Produces

  • application/json

Tags

  • VaultSurveys

Example HTTP response

Response 400

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

Response 404

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

Update job level

PATCH /{hubId}/vault-surveys/uploads/{jobId}/levels/{levelName}

Description

Sample request:

PATCH /1866/vault-surveys/uploads/212/levels/response
{
    "strategy": "incremental" | "full"
}

Parameters

Type Name Description Schema

Path

hubId
required

Owner Hub Id

integer (int64)

Path

jobId
required

Job Id

integer (int64)

Path

levelName
required

Level Name

string

Body

body
optional

Values to be updated

< string, string > map

Responses

HTTP Code Description Schema

204

No content, level is updated.

No Content

400

Bad request.

PublicApiError

401

Unauthorized

No Content

403

No access to this feature.

No Content

404

Not found, Job was not found.

PublicApiError

Consumes

  • application/json

Produces

  • application/json

Tags

  • VaultSurveys

Example HTTP response

Response 400

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

Response 404

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

Add data

POST /{hubId}/vault-surveys/uploads/{jobId}/levels/{levelName}/data

Description

Sample request:

POST /1866/vault-surveys/uploads/1231/levels/response/data
{
    "documents": [
        {
            "isDeleted": "true",
            "document": {
                "responseid": 12
            }
        },
        {
            "isDeleted": "false",
            "version": 4321234,
            "document": {
                "responseid": 12,
                "gender": "male",
                "city": "Oslo",
            }
        }
    ]
}

Parameters

Type Name Description Schema

Path

hubId
required

Owner Hub Id

integer (int64)

Path

jobId
required

Job Id

integer (int64)

Path

levelName
required

Level Name

string

Body

body
optional

Document data

AddDataResource

Responses

HTTP Code Description Schema

204

No content, data has been added.

No Content

400

Bad request.

PublicApiError

401

Unauthorized

No Content

403

No access to this feature.

No Content

404

Not found, Job was not found.

PublicApiError

Consumes

  • application/json

Produces

  • application/json

Tags

  • VaultSurveys

Example HTTP response

Response 400

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

Response 404

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

Replace level schema

POST /{hubId}/vault-surveys/uploads/{jobId}/levels/{levelName}/schema

Description

Sample request:

POST /1866/vault-surveys/uploads/2343/levels/response/schema
{
    "name": "SurveySchema",
    "defaultConfirmitLanguageId": 9,
    "languages": [{"confirmitLanguageId": 9}, {"confirmitLanguageId": 20},"confirmitLanguageId": 1044}],
    "root": {
        "name": "response",
        "keys": [ {"name": "responseid"}],
        "variables": [
            {
                "name": "responseid",
                "variableType": "numeric",
                "titles": [{"languageId": 9, "text": "responseid"}],
                "texts": [{"languageId": 9, "text": "responseid"}],
            },
            {
                "name": "gender",
                "variableType": "singleChoice",
                "titles": [{"languageId": 9, "text": "Gender"}],
                "texts": [{"languageId": 9, "text": "State your gender"}],
                "options": [{"code": "male"}, {"code": "female"}],
            }
        ],
        "children": [
        ]
    }
}

Parameters

Type Name Description Schema

Path

hubId
required

Owner Hub Id

integer (int64)

Path

jobId
required

Job Id

integer (int64)

Path

levelName
required

Level Name

string

Body

body
optional

Schema

SurveyDataSchema

Responses

HTTP Code Description Schema

200

Ok. The schema has been linked to the job.

AddSchemaResponse

400

Bad request.

PublicApiError

401

Unauthorized

No Content

403

No access to this feature.

No Content

404

Not found, Job was not found.

PublicApiError

Consumes

  • application/json

Produces

  • application/json

Tags

  • VaultSurveys

Example HTTP response

Response 400

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

Response 404

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

Read schema levels.

GET /{hubId}/vault-surveys/{dataSetId}/levels

Description

Returns schema-levels for a given survey. Sample request:

GET /4410/vault-surveys/s3/levels

Parameters

Type Name Description Schema

Path

dataSetId
required

DataSetId for the survey.

string

Path

hubId
required

Hub Id

integer (int64)

Responses

HTTP Code Description Schema

200

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

< DataSetLevel > array

400

Bad request, the query parameters are not valid.

PublicApiError

401

Unauthorized

No Content

404

Not found, Hub or dataSet was not found.

PublicApiError

Produces

  • application/json

Tags

  • VaultSurveys

Example HTTP response

Response 200

[ {
  "name" : "response",
  "schemaVersion" : 13,
  "dataVersion" : 7
}, {
  "name" : "respondent",
  "schemaVersion" : 0,
  "dataVersion" : 0
} ]

Response 400

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

Response 404

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

Read vault survey data for given level.

GET /{hubId}/vault-surveys/{dataSetId}/levels/{level}/data

Description

Returns vault data. Sample requests:

GET /4410/vault-surveys/s1/levels/response/data

Parameters

Type Name Description Schema

Path

dataSetId
required

DataSetId for the survey.

string

Path

hubId
required

Hub Id

integer (int64)

Path

level
required

The name of the level for which to get data.

string

Query

filterExpression
optional

DataEngine query expression for row filtering.

string

Query

stateId
optional

Survey StateId. Optional. Provides incremental data load. Use this parameter in order to get only changes to the survey data made after the pointed survey StateId. Ignore this parameter in order to get all survey data.

integer (int64)

Query

variables
optional

The list of variables to be included.

string

Responses

HTTP Code Description Schema

200

Ok, the request has succeeded. All requested survey data is returned. The API provides the data either as a stream or a resource collection depending on the request accept header.

ResourceCollection[SurveyDataRecord]

400

Bad request, the query parameters are not valid.

PublicApiError

401

Unauthorized

No Content

404

Not found, Hub or survey was not found.

PublicApiError

412

Failed to read incremental data. Retry with no 'stateId' parameter.

No Content

Produces

  • application/json

  • application/x-ndjson

Tags

  • VaultSurveys

Example HTTP response

Response 200

{
  "itemType" : "SurveyDataRecord",
  "itemCount" : 5,
  "totalCount" : 5,
  "items" : [ {
    "combined_sourceid" : "p750209410546",
    "respid" : 1,
    "CreatedDate" : "2021-02-15T17:58:22.35+01:00"
  }, {
    "combined_sourceid" : "p750209410546",
    "respid" : 2,
    "CreatedDate" : "2021-02-15T17:58:32.473+01:00"
  }, {
    "combined_sourceid" : "p601884965518",
    "respid" : 1,
    "CreatedDate" : "2021-02-15T17:57:16.4+01:00"
  }, {
    "combined_sourceid" : "p601884965518",
    "respid" : 2,
    "CreatedDate" : "2021-02-15T17:57:32.51+01:00"
  }, {
    "combined_sourceid" : "p601884965518",
    "respid" : 3,
    "CreatedDate" : "2021-02-15T17:57:52.227+01:00"
  } ],
  "links" : {
    "self" : "<host>/v1/hubs/4410/automapped-surveys/p240597392086/respondents/data"
  }
}
{
  "application/json" : {
    "itemType" : "SurveyDataRecord",
    "itemCount" : 5,
    "totalCount" : 5,
    "items" : [ {
      "combined_sourceid" : "p750209410546",
      "respid" : 1,
      "CreatedDate" : "2021-02-15T17:58:22.35+01:00"
    }, {
      "combined_sourceid" : "p750209410546",
      "respid" : 2,
      "CreatedDate" : "2021-02-15T17:58:32.473+01:00"
    }, {
      "combined_sourceid" : "p601884965518",
      "respid" : 1,
      "CreatedDate" : "2021-02-15T17:57:16.4+01:00"
    }, {
      "combined_sourceid" : "p601884965518",
      "respid" : 2,
      "CreatedDate" : "2021-02-15T17:57:32.51+01:00"
    }, {
      "combined_sourceid" : "p601884965518",
      "respid" : 3,
      "CreatedDate" : "2021-02-15T17:57:52.227+01:00"
    } ],
    "links" : {
      "self" : "<host>/v1/hubs/4410/automapped-surveys/p240597392086/respondents/data"
    }
  },
  "application/x-ndjson" : {
    "itemType" : "SurveyDataRecord",
    "itemCount" : 5,
    "totalCount" : 5,
    "items" : [ {
      "combined_sourceid" : "p750209410546",
      "respid" : 1,
      "CreatedDate" : "2021-02-15T17:58:22.35+01:00"
    }, {
      "combined_sourceid" : "p750209410546",
      "respid" : 2,
      "CreatedDate" : "2021-02-15T17:58:32.473+01:00"
    }, {
      "combined_sourceid" : "p601884965518",
      "respid" : 1,
      "CreatedDate" : "2021-02-15T17:57:16.4+01:00"
    }, {
      "combined_sourceid" : "p601884965518",
      "respid" : 2,
      "CreatedDate" : "2021-02-15T17:57:32.51+01:00"
    }, {
      "combined_sourceid" : "p601884965518",
      "respid" : 3,
      "CreatedDate" : "2021-02-15T17:57:52.227+01:00"
    } ],
    "links" : {
      "self" : "<host>/v1/hubs/4410/automapped-surveys/p240597392086/respondents/data"
    }
  }
}

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."
  }
}

Read vault survey schema for given level.

GET /{hubId}/vault-surveys/{dataSetId}/levels/{level}/schema

Description

Returns vault survey schema for given level. Sample request:

GET /4410/vault-surveys/s3/levels/response/schema

Parameters

Type Name Description Schema

Path

dataSetId
required

DataSetId for the survey.

string

Path

hubId
required

Hub Id

integer (int64)

Path

level
required

The name of the level for which to get schema.

string

Query

variables
optional

The list of variables to be included.

string

Responses

HTTP Code Description Schema

200

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

SurveyDataSchema

400

Bad request, the query parameters are not valid.

PublicApiError

401

Unauthorized

No Content

404

Not found, Hub or dataSet was not found.

PublicApiError

Produces

  • application/json

Tags

  • VaultSurveys

Example HTTP response

Response 200

{
  "defaultConfirmitLanguageId" : 9,
  "languages" : [ {
    "confirmitLanguageId" : 9
  } ],
  "root" : {
    "name" : "response",
    "keys" : [ {
      "name" : "combined_sourceid",
      "isCompound" : false,
      "isBackground" : false,
      "isHidden" : false,
      "variableType" : "singleChoice",
      "isSystemVariable" : false,
      "isRespondentVariable" : false,
      "options" : [ {
        "code" : "p601884965518",
        "hasOtherField" : false,
        "texts" : [ {
          "languageId" : 9,
          "text" : "Name of the first survey included into auto-mapping"
        } ]
      }, {
        "code" : "p750209410546",
        "hasOtherField" : false,
        "texts" : [ {
          "languageId" : 9,
          "text" : "Name of the second survey included into auto-mapping"
        } ]
      } ],
      "excludeFromReporting" : false
    }, {
      "name" : "responseid",
      "isCompound" : false,
      "isBackground" : false,
      "isHidden" : false,
      "variableType" : "numeric",
      "isSystemVariable" : true,
      "isRespondentVariable" : false,
      "excludeFromReporting" : false
    } ],
    "variables" : [ {
      "name" : "respid",
      "isCompound" : false,
      "isBackground" : false,
      "isHidden" : false,
      "variableType" : "numeric",
      "isSystemVariable" : true,
      "isRespondentVariable" : false,
      "excludeFromReporting" : false
    }, {
      "name" : "q1",
      "isCompound" : false,
      "isBackground" : false,
      "isHidden" : false,
      "variableType" : "text",
      "isSystemVariable" : false,
      "isRespondentVariable" : false,
      "excludeFromReporting" : false
    } ]
  }
}

Response 400

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

Response 404

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

Read vault survey state.

GET /{hubId}/vault-surveys/{dataSetId}/state

Description

Returns vault survey state. Note. Any change to a survey leads to the survey state change (survey StateId increment). You can use this stateId to get survey data incrementally, see GetVaultSurveyData method for more details. Sample request:

GET /4410/vault-surveys/s3/state

Parameters

Type Name Description Schema

Path

dataSetId
required

DataSetId for the survey

string

Path

hubId
required

Owner Hub Id

integer (int64)

Responses

HTTP Code Description Schema

200

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

SurveyState

400

Bad request, the query parameters are not valid.

PublicApiError

401

Unauthorized

No Content

404

Not found, Hub or survey was not found.

PublicApiError

Produces

  • application/json

Tags

  • VaultSurveys

Example HTTP response

Response 200

{
  "stateId" : 100500,
  "links" : {
    "self" : "<host>/v1/hubs/4410/automapped-surveys/p240597392086/state"
  }
}

Response 400

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

Response 404

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

Add upload job

POST /{hubId}/vault-surveys/{dataSetId}/uploads

Description

Sample request:

POST /1866/vault-surveys/s3/uploads
{
    "Levels": [
        {
            "Name":"response"
            "SchemaVersion": 1
            "DataVersion": 2
        },
        {
            "Name":"respondent"
            "SchemaVersion": 1
            "DataVersion": 2
        }
    ]
}

Parameters

Type Name Description Schema

Path

dataSetId
required

DataSet Id

string

Path

hubId
required

Owner Hub Id

integer (int64)

Body

body
optional

A job with levels

AddJobResource

Responses

HTTP Code Description Schema

201

An upload Job is created. The Job is returned.

JobResource

400

Bad request. Level for upload job are not valid.

PublicApiError

401

Unauthorized

No Content

404

Not found, Hub was not found.

PublicApiError

Consumes

  • application/json

Produces

  • application/json

Tags

  • VaultSurveys

Example HTTP response

Response 201

{
  "id" : 98345,
  "created" : "2024-10-21T11:07:34.6989484+00:00",
  "dataSetId" : "s1",
  "status" : 0,
  "levels" : [ {
    "name" : "respondent",
    "schemaVersion" : 1,
    "dataVersion" : 1
  }, {
    "name" : "response",
    "schemaVersion" : 2,
    "dataVersion" : 8
  } ],
  "links" : { }
}

Response 400

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

Response 404

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