Codebooks

This resource provides information about Codebooks.

APIDescription
GET Codebooks/{CodebookKey}?tree={tree}

Get a Codebook by its key
Each Question has exactly one Codebook, which may be shared across multiple Questions.
A Codebook is tree-structured, where the leaf nodes are Codes and non-leaf nodes are Nets. Only Codes may be used to code a Response.

This resource can return the Codes in the Codebook as a flattened list containing only the Codes, or as a tree with the full structure of the Codebook.

GET Codebooks/Question/{QuestionKey}?tree={tree}

Get the Codebook for a Question
Each Question has exactly one Codebook, which may be shared across multiple Questions.
A Codebook is tree-structured, where the leaf nodes are Codes and non-leaf nodes are Nets. Only Codes may be used to code a Response.

This resource can return the Codes in the Codebook as a flattened list containing only the Codes, or as a tree with the full structure of the Codebook.

POST Codebooks/{QuestionKey}

Create a new Codebook for a Question
This operation replaces any existing Codebook for the specified Question with the new Codebook.
This operation is permitted only if there are no coded responses in the Question.

POST Codebooks/{CodebookKey}/codes

Add codes to a codebook
This operation adds the given codes to the specified codebook.

Companies

This resource provides information about Companies.
Companies may be used to organize Studies by the company for which the coding work is being performed.

APIDescription
GET Companies

Get a list of Companies
This operation returns the key and ID of all Companies in the Ascribe Account.

POST Companies

Create a new Company
The id assigned to the company must not already exist.
The maximum length of the id is 100 characters. The id must not begin with an underscore character '_'.

Exports

This resource provides information about the Studies in the Ascribe account of the current session.

APIDescription
GET Exports

Gets a list of all available for current account and all global scripts

POST Exports

Creates a new export job

GET Exports/{jobKey}

Returns status information of specified job

Languages

This resource provides information about the Languages which can be used for translating.

APIDescription
GET Languages

Returns the languages supported for translation
The Code for a language is used to specify the language when translating responses.
The Name for a language is suitable for display on a user interface.

Questions

This resource allows queries for the Questions in a Study, and allows creation of new Questions in a Study.

APIDescription
GET Questions/{StudyKey}?types={types}&tasks={tasks}

Get the Questions in a Study
Retrieves by default all of the Questions in the Study.
You can optionally retrieve only a sub-set of the questions, filtering by the question type or the tasks assigned to the question.

POST Questions/AutoCode/{QuestionKey}

AutoCodes Responses in the specified Question
There are three types of AutoCoding available, and will be executed in a certain order. See the documentation for the body of the POST.

POST Questions/{StudyKey}

Create a new Question in the specified Study
If the codebook key is not specified in the request a new empty codebook is created for the question and its key is returned in the response.

POST Questions/Translate

Translate Responses in a Question

POST Questions/Codebook/{questionKey}/{codebookKey}

Set a codebook for some specified question

Responses

This resource allows addition of new Responses to a Question,
and queries for Responses in a Question, including the Codes applied to those Responses.

APIDescription
GET Responses/{QuestionKey}?includeText={includeText}&status={status}&codedAfter={codedAfter}&codedBefore={codedBefore}&loadedAfter={loadedAfter}&loadedBefore={loadedBefore}

Get the Responses in the specified Question
For coded responses the keys of the applied codes are returned for each response.
These keys can be matched to the keys of the codes returned in a query for the codebook to find the details of each of the applied codes.

The optional date query parameters are UTC date/time values.
These should be specified in the form:
YYYY-MM-DDThh:mm:ss
Where the hour ranges from 0 to 23. For example:
2020-02-23T16:05:17
If the time portion of the date/time value is omitted it is assumed to be 00:00:00 GMT.

POST Responses/{QuestionKey}

Add Responses to a Question
This operation will add new Responses to the Question, optionally autocoding them. It will never modify existing Responses. For each QuestionResponse submitted, if the question does not have a response stored in Ascribe with the specified respondent id, then the response will be added.
Otherwise, the Response stored in Ascribe will not be modified. The QuestionResponse submitted will be ignored, and any codes that have been applied to the Response will be unchanged.

This operation allows the use of a Rule Set to modify or veto the Responses submitted, and automatically coding the responses as they are added.
If a Rule Set is specified it can be passed a Taxonomy for its use.

PUT Responses/{QuestionKey}

Add or update Responses in the specified Question
If the Question does not have a Response stored in Ascribe with the specified respondent id, then the response will be added.
Otherwise, the Response stored in Ascribe will be updated if any of the properties of in the request differ from the values of the current properties of the Response.

RuleSets

This resource provides information about the available Rule Sets and their associated identifiers.

APIDescription
GET RuleSets

Get the available Rule Sets

Sessions

This resource allows creation of a new session for interactions with this API. A POST to this resource is the starting point for all interactions with the API.

APIDescription
POST Sessions

Create a new session for interaction with this API
The credentialed user must have Adminstrator privilege in Ascribe.
The response message contains two tokens, one of which must be passed in a header for all other operations with this API.
You may either use the bearerToken or the authenticationToken. Either send a header with key "authentication" and value the authenticationToken returned in this response, or send a header with key "Authorization" and value the bearerToken returned in this response.
The bearerToken does not expire, but will become invalid if the user's credentials change.
The authenticationToken remains valid until no request is sent to this API using the authenticationToken for 30 minutes.

Studies

This resource provides information about the Studies in the Ascribe account of the current session.

APIDescription
GET Studies/{StudyKey}

Get a Study

POST Studies/Translate

Translate all Responses in a Study

GET Studies?idFilter={idFilter}&statusMask={statusMask}&clientCompanyKey={clientCompanyKey}

Get all Studies
The list of Studies returned may be optionally filtered by id, status, and client company.
When filtering by id the asterisk * character may optionally be used as a leading or trailing wildcard.

POST Studies

Create a new Study

Taxonomies

This resource provides information about the available Taxonomies and their associated identifiers.

APIDescription
GET Taxonomies

Get the available Taxonomies

GET Taxonomies/{TaxonomyKey}

Get the details of a single Taxonomy

Users

This resource provides information about the users defined in the current account and their associated keys.

APIDescription
GET Users

Get all Users