Getting started
with GETMARKED Quiz Import API

Overview
GETMARKED Digitaliser has an easy-to-use REST API. At its core, there is only two endpoints that you would ever call. One to upload the quiz file, and one to get the extracted quiz question data. You can get familiar with it using our API Playground first before proceeding with the rest of this guide.

Here's a quickstart python code file that contains all the instruction below on how to use our API.
Installation
To get started, install your favourite http library in any programming language that you like. Alternatively, you may also follow through the steps using http request tools like Postman or Nightingale.

In our code examples we will be using the Requests HTTP library and Python 3. If you do not have Requests installed, you can install it using pip:

pip install requests

Creating API Keys
All requests to GETMARKED's REST API need to be authenticated. We support authentication via API Keys. You can create and revoke them in the Developer Dashboard.

  1. Create your API Keys at the API Keys page. Please keep the keys secret. For security reasons, we cannot show it to you again if you lose it.

  2. You may issue separate API Keys to different developers or to different subsystems within your application. For security reasons, you should delete the keys that are not in use to prevent unauthorized access!
Setting the API Key in the request header
To authorise your HTTP request, set the API Key in the AUTHORIZATION header of the HTTP request.

  1. Using Postman
  2. Under Headers, you should fill in the following information:
    KEY VALUE
    AUTHORIZATION
    Api-Key YOUR-SECRET-API-KEY
  3. Using Python
  4. 
    import requests
    
    API_URL = "Some API-ENDPOINT"
    headers = {"AUTHORIZATION": "Api-Key YOUR-SECRET-API-KEY"}
    response = requests.get(API_URL, headers=headers)
    print(response.json())
    
    
Converting your quiz file into JSON data
We accept the following quiz file formats:
  1. DOCX
  2. QTI zip file (exported from Canvas, Brightspace, itslearning, Cognero, NEO LMS)
  3. Common Cartridge QTI zip file
  4. Blackboard pool and test zip file
  5. QTI 2.1 zip file
  6. Moodle XML
  7. JSON Google Form
Converting a quiz file into our JSON data format is an async process and will take at least two request/response cycle. This is because the conversion is a long running process that will take anywhere between 10s to 240s depending on the size of the file. As an estimate, conversion will usually take 500ms per page for docx file.

In this getting started guide, we will be converting from a docx quiz file. Conversion from a QTI zip file or JSON Google form will work in exactly the same way.

Also, here's some sample docx quizzes you can use for testing:

  1. POST your file using multipart/form-data to https://digitaliser.getmarked.ai/api/v1.0/job/create_job/
    NOTE: DO NOT USE Transfer-Encoding: chunked in your HTTP POST. Transfer-Encoding should be removed from your HTTP headers.
    
    import requests
    
    with open(filepath, 'rb') as file:
    
        API_URL = "https://digitaliser.getmarked.ai/api/v1.0/job/create_job/"
        files = {"file": file}
        headers = {"AUTHORIZATION": "Api-Key YOUR-SECRET-API-KEY"}
        response = requests.post(API_URL, files=files, headers=headers)
        print(response.json())
    
    
    You will receive a JSON response structured like so, if successful:
    { "status": "accepted", "message": "your file has been aceepted", "data": {"result_endpoint": "https://digitaliser.getmarked.ai/api/v1.0/job/{id}/"} }
    If you are facing issues sending your file data to our API via HTTP POST, you can direct your HTTP POST request to http://httpbin.org/post to help you debug your POST request. http://httpbin.org/post will return with a JSON response of your POST data and it should look like the following:
    {
      "args": {},
      "data": "",
      "files": {
        "file": "data:application/vnd.openxmlformats-officedocument.wordprocessingml.document;base64,U...."
      },
      "form": {},
      "headers": {
        "Accept-Encoding": "gzip, deflate",
        "Authorization": "Api-Key YOUR_SECRET_KEY",
        "Cache-Control": "no-cache",
        "Content-Length": "195603",
        "Content-Type": "multipart/form-data; boundary=\"c46ede9c-af3d-4baf-a9e9-c8a627ebfdae\"",
        "Host": "httpbin.org",
        "X-Amzn-Trace-Id": "Root=1-61d90a6d-2233f13f505cf8c95c69e44c"
      },
      "json": null,
      "origin": "XXX.XX.XXX.XX",
      "url": "http://httpbin.org/post"
    }
                                            

    Please note that the Content-Length must be specified. Also, we do not accept Transfer-Encoding of chunked. Transfer-Encoding should be stripped from your HTTP header.

    Alternatively, you may provide the URL of your question bank file instead of attaching the entire file in the POST request.

    
    import requests
    
    API_URL = "https://digitaliser.getmarked.ai/api/v1.0/job/create_job/"
    data = {"url": "https://CDN.YOUR-DOMAIN.COM/YOUR-QUESTION-BANK.docx"}
    headers = {"AUTHORIZATION": "Api-Key YOUR-SECRET-API-KEY"}
    response = requests.post(API_URL, data=data, headers=headers)
    
    
  2. GET the JSON data via polling
    Poll the returned result_endpoint for the extracted questions data at 15s intervals.
    
    import requests
    
    API_URL = "https://digitaliser.getmarked.ai/api/v1.0/job/{id}/"
    headers = {"AUTHORIZATION": "Api-Key YOUR-SECRET-API-KEY"}
    response = requests.get(API_URL, headers=headers)
    print(response.json())
    
    
    And you would receive the questions data. Please refer to question schema on how to render the data.
And that's it! In 2 simple HTTP request, you have converted your quiz docx file into questions JSON data. You can try it now using our API Playground.
Structure of HTTP Responses
Response body from our API endpoints should be read in JSON format, and all have the following structure:

{
    "status": "some status",
    "message": "some message",
    "data": response data,
}

  1. Status is a string and refers to whether the request was successfully received by the create_job API (accepted, error), or the status of conversion job in the result_endpoint (converting, success, failure).
  2. Message is a short description of the status.
  3. Data contains either the URL of the result_endpoint or the questions data.
Status Codes
Responses from our API endpoints come with status codes. Here is a quick cheat sheet to help you understand what is going on at our side when you send in your request.
Status Code Meaning Description
200
OK
The request has succeeded, and you should look into the data field to obtain the relevant information.
202
Accepted
Accepted. The request has succeed, but we need time to act on it.
400
Bad Request
Your request may have been formed badly (for eg. incorrect file type), or your previous created job failed due to a variety of reasons.
403
Forbidden
You are not authenticated for that resource. You have not have provided an authenticable API Key, or you might be requesting for a resource that does not belong to you.
404
Not Found
The resource which you have requested for cannot be found.
500
Server Error
There was a problem on GETMARKED's server.
Payment Plans
Signing up for a developer account gives you free credits that you can use on the production endpoint. If the free credits is insufficient, please contact us and we can offer even more generous amount of credits to help you get going.

Once exhausted, we recommend that you purchase a paid subscription plan.
Need some help?
Whether you have problems with the web application or with code interfacing with our endpoints, please do not hesitate to reach out and contact us.