Getting started
with Digitaliser REST 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 document, and one to get the extracted quiz question data.

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 Digitaliser’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 quiz file into JSON data
Converting docx quiz file into JSON data 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. Here's a sample docx file you may use for your testing.

  1. POST your docx file using multipart/form-data to https://digitaliser.getmarked.ai/api/v1.0/job/create_job/
    
    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}/"} }
  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.
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 Digitaliser server.
Test Endpoints
We recommend you test your integration on the test endpoints since the production API will consume credits.
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.