Automating Coding Workflow with the Ascribe Coder API

The Ascribe™ Coder API allows your company to send survey responses to Ascribe and retrieve back the codebooks and coded responses. Using the Ascribe Coder API you can create a study, create questions in the study, load responses to be coded to the question, and get the results of the coding.

Before you can interact with the Ascribe Coder API you must authenticate. See this post for details.

The API interactions for this workflow are:

POST /Studies
Create a new study. Its key is returned.
POST /Questions/{StudyKey}
Create a new question in the study. Its key is returned.
POST /Responses/{QuestionKey}
Put responses to be coded into the question.
Humans code the responses, creating a codebook as they code.
GET /Studies/{StudyKey}
Query for completion of the coding work. Repeat at intervals until coding is complete.
GET /Codebooks/Question/{QuestionKey}
Get the codebook constructed by the coders.
GET /Responses/{QuestionKey}
Get the coding results.

Let’s go through each of these operations a step at a time.

Create a Study with the Ascribe Coder API

Assuming that we want to create a new study in Ascribe we POST to the /Studies resource. The body of the request looks like this:

{
  "id": "S458-3"
}

This creates a new study with the ID S458-3. The ID can be any text. The API responds with:

{
  "key": 544,
  "id": "S458-3",
  "status": "p"
}

The status of "p" means that coding is in progress. This is an indication to the coding team that this job needs to be coded. The key returned is important. That is how we will refer to the study in subsequent interactions with the API.

If we don’t want to create a study, but would rather add a new question to an existing study, we can query the /Studies resource to find the study key given the study ID.

Create a Question with the Ascribe Coder API

Armed with our study key, 544 in the example above, we can create a question in the study. To create the question, we POST to the /Questions/{StudyKey} resource, so in our case we POST to /Questions/544. The body of the request looks like this:

{
  "id": "Q1",
  "type": "o",
  "text": "What did you like about the product?"
}

This creates a new Open question ("type": "o"), with ID “Q1”. The response has this form:

{
  "key": 3487,
  "id": "Q1",
  "type": "o",
  "text": "What did you like about the product?"
}

Now we have the key for the newly created question, and we are ready to load it with responses to be coded.

Load Responses to Code with the Ascribe Coder API

To load responses, we POST to the /Responses/{QuestionKey} resource, so for the example above we would POST to /Responses/3487. The body of the request would look like this:

{
  "responses": [
    {
      "rid": "34-22907",
      "verbatim": "I do not like the red color"
    },
    {
      "rid": "34-22988",
      "verbatim": "This is a fantastic product"
    }
  ]
}

And the response:

{
  "responsesAdded": 2,
  "existingResponsesUnchanged": 0
}

Each response in the array of responses sent to the API must have the rid (respondent ID) and verbatim properties set to strings of one character or more. The rid values must be unique within the array of responses. If the rid value for a given response is already present in the question in Ascribe the response will be ignored. If we do exactly the same POST again to the API, the response would be:

{
  "responsesAdded": 0,
  "existingResponsesUnchanged": 2
}

This is because the respondent ID’s are already present in the question.

You should limit the number of responses sent in a single POST to 1000 or so. If you have more responses to load into the question than that, send them in separate POST operations.

Human Coding

The coding team can now get to work on the question. As the coders do their work they will add codes to the codebook for the question. Once coding of all the questions in the study is complete the coding team will set the status of the study to Completed.

When the coding team has set the status of the study to Completed it is the signal that the coding results are available for retrieval via the API.

Polling for Completion of Coding with the Ascribe Coder API

You can test for completion of the coding work with a GET to the /Studies/{StudyKey} resource. Our study key is 544, so we need to GET from /Studies/544. The response looks like this:

{
  "key": 544,
  "id": "S458-3",
  "status": "p"
}

Whoops! The coding is not yet complete, because the status is "p", meaning coding in progress. Wait for a while and try again, until the status is "c", meaning completed. Now we can get the coding results.

Retrieving a Codebook with the Ascribe Coder API

We need two things to collect the results of coding. The codebook and the codes applied to each response. We can retrieve these in either order. To get the codebook we GET from the /Codebooks/Question/{QuestionKey} resource. In our example we would GET /Codebooks/Question/3487. The response has this form:

{
  "codebookKey": 1499,
  "codebook": [
    {
      "key": 528,
      "description": "Not like red",
      "outputId": "201"
    },
    {
      "key": 529,
      "description": "Fantastic product",
      "outputId": "202"
    }
  ]
}

This codebook contains only two codes. Each has a key, textual description as displayed in the codebook, and an outputId. The output ID identifies the code for the tab department. But to associate these codes with the coding results from the API we want the code keys, 528 and 529.

Retrieving Coding Results with the Ascribe Coder API

The final operation in our workflow is to get the results of the coding. We GET from the /Responses/{QuestionKey} resource. The response has this form:

{
  "responses": [
    {
      "rid": "34-22907",
      "codeKeys": [
        528
      ]
    },
    {
      "rid": "34-22988",
      "codeKeys": [
        529
      ]
    }
  ]
}

The coders have applied code 528, “Not like red”, to respondent “34-22907”. 528 is the key of the code in the codebook. The other respondent has received the “Fantastic product” code. While each response in this example has only one code applied, in general any number of code keys can be returned in the codeKeys arrays.

Note that the text of the responses is not included in the response to reduce the payload size. If you want the response text you can set the includeText property in the request body to true. The response would then look like this:

{
  "responses": [
    {
      "rid": "34-22907",
      "text": "I do not like the red color",
      "codeKeys": [
        528
      ]
    },
    {
      "rid": "34-22988",
      "text": "This is a fantastic product",
      "codeKeys": [
        529
      ]
    }
  ]
}

Summary

The Ascribe Coder API can be used to automate the workflow in your coding department. You can send responses to be coded to Ascribe and retrieve the results of the coding operation.

See the Ascribe Coder API documentation for information on how to automate coding of responses as they are sent to Ascribe.

Ascribe Blog