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.

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.

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 '_'.

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, with optional filters.
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 a given question.
There are three types of AutoCoding available, and will be executed in a certain order.

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.

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}

Get the Responses in the specified Question, including the keys of Codes applied to the Responses.
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.

POST Responses/{QuestionKey}

Add Responses to a Question, optionally coding them automatically.
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 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.

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

Returns information about the 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.