Base address

The base address for interactions with this API is

https://webservices.goascribe.com/coder/

For example, a query to the Studies resource would use the URL

https://webservices.goascribe.com/coder/studies

Security and authentication

This API supports secure connections only.

The starting point for interactions with this API is a POST to the Sessions resource to obtain an authentication or authorization token.

The bearerToken value can be used in a header whose key is "authorization". This token does not expire, but will become invalid if the user's credentials change.

Alternatively, the authenticationToken value can be used in a header whose key is "authentication". This token will expire when 30 minutes elapse between requests to this API using the token.

Getting started

The Ascribe Coder API Swagger documentation supports interactive use of this API.

Alternatively, the Postman app available at https://www.getpostman.com/ is a convenient tool to use for interactive experimentation with this API.

Resources

Codebooks

This resource provides information about Codebooks.

API	Description
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.

API	Description
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.

API	Description
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.

API	Description
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.

API	Description
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.

API	Description
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.

API	Description
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.

API	Description
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.

API

Description

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.

API	Description
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.

API	Description
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.

API	Description
GET Users	Get all Users