Exam and Quiz API for Developers

Exam and Quiz API for Developers

ClassMarker has two integration options for automatically receiving Test results back to your systems/website, Webhooks or API.

You can select which option best suits your requirements, or even use both if you need:

API Documentation

A ClassMarker API key and API secret is required for API access.

An API key and API secret can be created under the My Account / API section of ClassMarker when logged in.

API request examples

Request: All available Groups, Links & Tests


Retrieve a list of Group, Link & Test Names and IDs your API key has permission to access.

If for example, your API key has access to all Groups & Links, you can use this see if extra Groups or Links have been added.

You can either use a specific Group/Link and Test ID combination to retrieve results for a specific Test OR simply use the Recent results API calls (All Groups recent results or All Links recent results) to retrieve recent results from all Groups or Links available to your API key.

Links unique Quiz ID:
If your API key has permission, you will also receive the unique value for the quiz_id parameter. The quiz_id parameter tell ClassMarker which Exam to give. Each Link has a unique quiz_id parameter. This allow you to retrieve and give access to new Links as they are created right from your system.

Exam results are not retrieved with this call, only Group, Link & Test names and IDs available to your API key.

Response formats include: json & xml.

Request URL
GET https://api.classmarker.com/v1.json? api_key=XXXX
&signature=XXXX& timestamp=XXXX
Parameters Value
api_key Your API key
Example: Yt5Rtgf6Gtyokj76Gf3rHGfY9KJ0H2
signature Your encrypted signature
Example: d4tsE7SvEgzAKlJPFrlvAz3oe9uFQnxy
timestamp Current UNIX timestamp. Valid for 5 minutes.
Example: 1335783600
https://api.classmarker.com/v1.json?api_key=d4tsE7SvEgzAKlJPFrlvAz3oe9uFQnxy
&signature=4495a14efc483aa5ee2f6d4cd480f968&timestamp=1335783600

JSON response

View example response

Note: The link_url_id field is only included if it is allowed in the API Key permissions when the API Key is Created or Edited.

Example: URL to start or resume a Link Test: https://www.classmarker.com/online-test/start/?quiz=link_url_id

link_url_id is not included by default.

{
   "status":"ok",
   "request_path":"v1",
   "server_timestamp":1339769771,
   "groups":[
      {
         "group":{
            "group_name":"Internal Accounts department",
            "group_id":29765,
            "assigned_tests":[
               {
                  "test":{
                     "test_name":"Health and safety exam",
                     "test_id":"64776"
                  }
               },
               {
                  "test":{
                     "test_name":"March Quarter Skills assesment",
                     "test_id":"273864"
                  }
               },
               {
                  "test":{
                     "test_name":"Billing system exam",
                     "test_id":"38676"
                  }
               },
               {
                  "test":{
                     "test_name":"Customer complaints responses quiz",
                     "test_id":"95645"
                  }
               }
            ]
         }
      },
      {
         "group":{
            "group_name":"Internal Sales Staff",
            "group_id":73645,
            "assigned_tests":[
               {
                  "test":{
                     "test_name":"Health and safety",
                     "test_id":"64776"
                  }
               },
               {
                  "test":{
                     "test_name":"Product specials & discounts quiz",
                     "test_id":"48756"
                  }
               },
               {
                  "test":{
                     "test_name":"March Quarter Skills assesment",
                     "test_id":"273864"
                  }
               },
               {
                  "test":{
                     "test_name":"Billing system exam",
                     "test_id":"38676"
                  }
               }
            ]
         }
      }
   ],
   "links":[
      {
         "link":{
            "link_name":"New York Sales Staff",
            "link_id":2343765,
            "link_url_id":"g6v533a63444719ce32",
            "assigned_tests":[
               {
                  "test":{
                     "test_name":"Product specials & discounts quiz",
                     "test_id":"48756"
                  }
               }
            ]
         }
      },
      {
         "link":{
            "link_name":"Sydney Sales Staff",
            "link_id":985674,
            "link_url_id":"4mb5243e51cf0b0cswe",
            "assigned_tests":[
               {
                  "test":{
                     "test_name":"Product specials & discounts quiz Sydney Version",
                     "test_id":"48758"
                  }
               }
            ]
         }
      }
   ]
}

XML response

View example response

Note: The link_url_id field is only included if it is allowed in the API Key permissions when the API Key is Created or Edited.

Example: URL to start or resume a Link Test: https://www.classmarker.com/online-test/start/?quiz=link_url_id

link_url_id is not included by default.

<response>
  <status>ok</status>
  <request_path>v1</request_path>
  <server_timestamp>1339769771</server_timestamp>
  <groups>
    <group>
      <group_name>Internal Accounts department</group_name>
      <group_id>29765</group_id>
      <assigned_tests>
        <test>
          <test_name>Health and safety exam</test_name>
          <test_id>64776</test_id>
        </test>
        <test>
          <test_name>March Quarter Skills assesment</test_name>
          <test_id>40811</test_id>
        </test>
        <test>
          <test_name>Billing system exam</test_name>
          <test_id>38676</test_id>
        </test>
        <test>
          <test_name>Customer complaints responses quiz</test_name>
          <test_id>95645</test_id>
        </test>
      </assigned_tests>
    </group>
    <group>
      <group_name>Internal Sales Staff</group_name>
      <group_id>73645</group_id>
      <assigned_tests>
        <test>
          <test_name>Health and safety exam</test_name>
          <test_id>64776</test_id>
        </test>
        <test>
          <test_name>March Quarter Skills assesment</test_name>
          <test_id>40811</test_id>
        </test>
        <test>
          <test_name>Billing system exam</test_name>
          <test_id>38676</test_id>
        </test>
      </assigned_tests>
    </group>
  </groups>
  <links>
    <link>
      <link_name>New York Sales Staff</link_name>
      <link_id>2343765</link_id>
      <link_url_id>g6v533a63444719ce32</link_url_id>
      <assigned_tests>
        <test>
          <test_name>Product specials & discounts quiz</test_name>
          <test_id>48756</test_id>
        </test>
      </assigned_tests>
    </link>
    <link>
      <link_name>Sydney Sales Staff</link_name>
      <link_id>985674</link_id>
      <link_url_id>4mb5243e51cf0b0cswe</link_url_id>
      <assigned_tests>
        <test>
          <test_name>Product specials & discounts quiz</test_name>
          <test_id>48756</test_id>
        </test>
      </assigned_tests>
    </link>
  </links>
</response>

Request: All Groups recent results


Retrieve a list of recent Test results from all Groups your API key has permission to access.

Request URL
GET https://api.classmarker.com/v1/groups/recent_results.json?api_key=XXXX&signature=XXXX
&timestamp=XXXX&finishedAfterTimestamp=XXXX
Parameters Value
api_key As above
signature How to create a signature
timestamp As above
finishedAfterTimestamp Only results finished after this UNIX timestamp will be returned.
Example: 1339780142
IMPORTANT: This parameter is used to give you control (and responsibility) over which results you receive next (so as to not receive duplicate results).

Think of this parameter as an "offset" where by, each time you make a request, you should ensure your finishedAfterTimestamp is set to the value of the last next_finished_after_timestamp you received which is returned by ClassMarker in the request response (when results exist). This way, only results that have been completed, 'after' the last result you received from the ClassMarker API, will be returned to you.

finishedAfterTimestamp, if not set in your request, defaults to a timestamp 2 weeks prior to the 'current time'.

To avoid downloading the same results on multiple requests, you should either:
  • Keep a reference to the last next_finished_after_timestamp value returned to you by the API, to use for the finishedAfterTimestamp value, on your next request to ClassMarker.
    E.g. Store it in a database for example.
  • Or, scan your own table of saved results from ClassMarker and use the highest test results "time_finished" timestamp as your next requests finishedAfterTimestamp value.

What if no results are received in a request?
If no results are received in a request, the next_finished_after_timestamp parameter is not returned to you. So on your next request, you should use the last next_finished_after_timestamp you received.
E.g. ...&finishedAfterTimestamp=1388498400.

Note: Your request script should always check that the finishedAfterTimestamp you are about to use is younger than 2 weeks old, if not, set the finishedAfterTimestamp to two weeks old in your request, or leave it off the request completely.

limit (Optional): By default up to 200 results are returned. You can decrease the amount of returned results if you require but not increase.
https://api.classmarker.com/v1/groups/recent_results.json?api_key=d4tsE7SvEgzAKlJPFrlvAz3oe9uFQnxy&signature=4495a14efc483aa5ee2f6d4cd480f968
&timestamp=1335783600&finishedAfterTimestamp=1339779290

JSON response

View example response
{
   "status":"ok",
   "request_path":"v1/groups/recent_results",
   "request_type":"groups_recent_results",
   "server_timestamp":1339782640,
   "finished_after_timestamp_used":1338908448,
   "groups":[
      {
         "group":{
            "group_id":29765,
            "group_name":"Internal Accounts department"
         }
      },
      {
         "group":{
            "group_id":73645,
            "group_name":"Internal Sales Staff"
         }
      }
   ],
   "tests":[
      {
         "test":{
            "test_id":"64776",
            "test_name":"Health and safety exam"
         }
      }
   ],
   "results":[
      {
         "result":{
            "user_id":"319118",
            "first":"Paul",
            "last":"Smith",
            "email":"paul@example.com",
            "test_id":"64776",
            "group_id":"29765",
            "percentage":"90",
            "points_scored":18,
            "points_available":20,
            "time_started":"1339778290",
            "time_finished":"1339781298",
            "status": "f",
            "duration":"00:50:08",
            "requires_grading":"No"
         }
      },
      {
         "result":{
            "user_id":"319119",
            "first":"Tracy",
            "last":"Thompson",
            "email":"tracey@example.com",
            "test_id":"64776",
            "group_id":"73645",
            "percentage":"95",
            "points_scored":19,
            "points_available":20,
            "time_started":"133977830",
            "time_finished":"133978998",
            "status": "f",
            "duration":"00:19:47",
            "requires_grading":"No"
         }
      }
   ],
   "num_results_available":2,
   "num_results_returned":2,
   "more_results_exist":false,
   "next_finished_after_timestamp":133978998
}

XML response

View example response
<response>
  <status>ok</status>
  <request_path>v1/groups/recent_results</request_path>
  <server_timestamp>1339841380</server_timestamp>
  <finished_after_timestamp_used>1338908448</finished_after_timestamp_used>
  <groups>
    <group>
      <group_id>29765</group_id>
      <group_name>Internal Accounts department</group_name>
    </group>
    <group>
      <group_id>73645</group_id>
      <group_name>Internal Sales Staff</group_name>
    </group>
  </groups>
  <tests>
    <test>
      <test_id>64776</test_id>
      <test_name>Health and safety exam</test_name>
    </test>
  </tests>
  <results>
    <result>
      <user_id>319118</user_id>
      <first>Paul</first>
      <last>Smith</last>
      <email>paul@example.com</email>
      <test_id>64776</test_id>
      <group_id>29765</group_id>
      <percentage>90</percentage>
      <points_scored>18</points_scored>
      <points_available>20</points_available>
      <time_started>1339778290</time_started>
      <time_finished>1339781298</time_finished>
      <status>f</status>
      <duration>"00:50:08</duration>
      <requires_grading>No</requires_grading>
    </result>
     <result>
      <user_id>319118</user_id>
      <first>Tracy</first>
      <last>Thompson</last>
      <email>tracey@example.com</email>
      <test_id>64776</test_id>
      <group_id>73645</group_id>
      <percentage>95</percentage>
      <points_scored>19</points_scored>
      <points_available>20</points_available>
      <time_started>133977830</time_started>
      <time_finished>133978998</time_finished>
      <status>f</status>
      <duration>"00:19:47</duration>
      <requires_grading>No</requires_grading>
    </result>
  </results>
  <num_results_available>2</num_results_available>
  <num_results_returned>2</num_results_returned>
  <more_results_exist></more_results_exist>
  <next_finished_after_timestamp>1338785035</next_finished_after_timestamp>
</response>

Request: All Links recent results


Retrieve a list of recent Test results from all Links your API key has permission to access.

Request URL
GET https://api.classmarker.com/v1/links/recent_results.json?api_key=XXXX&signature=XXXX
&timestamp=XXXX&finishedAfterTimestamp=XXXX
Parameters Value
api_key As above
signature How to create a signature
timestamp As above
finishedAfterTimestamp Only results finished after this UNIX timestamp will be returned.
As above
limit (Optional): By default up to 200 results are returned. You can decrease the amount of returned results if you require.
https://api.classmarker.com/v1/links/recent_results.json?api_key=d4tsE7SvEgzAKlJPFrlvAz3oe9uFQnxy&signature=4495a14efc483aa5ee2f6d4cd480f968
&timestamp=1335783600&finishedAfterTimestamp=1339779290

JSON response

View example response

Note: The link_url_id field is only included if it is allowed in the API Key permissions when the API Key is Created or Edited.

Example: URL to start or resume a Link Test: https://www.classmarker.com/online-test/start/?quiz=link_url_id

link_url_id is not included by default.

{
   "status":"ok",
   "request_path":"v1/links/recent_results",
   "server_timestamp":1339838367,
   "finished_after_timestamp_used":1338908448,
   "links":[
      {
         "link":{
            "link_name":"New York Sales Staff",
            "link_id":"38676"
            "link_url_id":"g6v533a63444719ce32"
         }
      },
       {
         "link":{
            "link_name":"Sydney Sales Staff",
            "link_id":"985674"
            "link_url_id":"4mb5243e51cf0b0cswe"
         }
      }
   ],
   "tests":[
      {
         "test":{
            "test_name":"Product specials and discounts quiz",
            "test_id":"48756"
         }
      }
   ],
   "results":[
      {
         "result":{
            "first":"Mary",
            "last":"Simmons",
            "test_id":"48756",
            "link_id":"38676",
            "percentage":"70",
            "points_scored":28,
            "points_available":40,
            "time_started":"1339836668",
            "time_finished":"1339836849",
            "status": "f",
            "email":"mary@example.com",
            "access_code":"123",
            "extra_info":"Demographic answer 1",
            "extra_info2":"Demographic answer 2",
            "extra_info3":"Demographic answer 3",
            "extra_info4":"Demographic answer 4",
            "extra_info5":"Demographic answer 5",
            "duration":"00:02:41",
            "requires_grading":"No",
            "link_result_id":22453,
            "cm_user_id":"74524",
            "ip_address":"192.0.43.10"
         }
      },
      {
         "result":{
            "first":"Gary",
            "last":"Carter",
            "test_id":"48756",
            "link_id":"38676",
            "percentage":"81",
            "points_scored":32.4,
            "points_available":40,
            "time_started":"1339836668",
            "time_finished":"1339836849",
            "status": "f",
            "email":"mary@example.com",
            "access_code":"123",
            "extra_info":"Demographic answer 1",
            "extra_info2":"Demographic answer 2",
            "extra_info3":"Demographic answer 3",
            "extra_info4":"Demographic answer 4",
            "extra_info5":"Demographic answer 5",
            "duration":"00:02:41",
            "requires_grading":"No",
            "link_result_id":22463,
            "cm_user_id":"45613",
            "ip_address":"192.0.43.10"
         }
      },
      {
         "result":{
            "first":"Carl",
            "last":"Bright",
            "test_id":"48756",
            "link_id":"985674",
            "percentage":"80",
            "points_scored":32,
            "points_available":40,
            "time_started":"1339836668",
            "time_finished":"1339836849",
            "status": "f",
            "email":"carl@example.com",
            "access_code":"123",
            "extra_info":"Demographic answer 1",
            "extra_info2":"Demographic answer 2",
            "extra_info3":"Demographic answer 3",
            "extra_info4":"Demographic answer 4",
            "extra_info5":"Demographic answer 5",
            "duration":"00:02:41",
            "requires_grading":"No",
            "link_result_id":22522,
            "cm_user_id":"u7y45t",
            "ip_address":"192.0.43.10"
         }
      }
   ],
   "num_results_available":3,
   "num_results_returned":3,
   "more_results_exist":false,
   "next_finished_after_timestamp":1339836709
}

XML response

View example response

Note: The link_url_id field is only included if it is allowed in the API Key permissions when the API Key is Created or Edited.

Example: URL to start or resume a Link Test: https://www.classmarker.com/online-test/start/?quiz=link_url_id

link_url_id is not included by default.

<response>
  <status>ok</status>
  <request_path>v1/links/recent_results</request_path>
  <server_timestamp>1339782640</server_timestamp>
<finished_after_timestamp_used>1338908448</finished_after_timestamp_used>
  <links>
    <link>
      <link_name>New York Sales Staff</link_name>
      <link_id>2343765</link_id>
      <link_url_id>g6v533a63444719ce32</link_url_id>
    </link>
    <link>
      <link_name>Sydney Sales Staff</link_name>
      <link_id>985674</link_id>
      <link_url_id>4mb5243e51cf0b0cswe</link_url_id>
	</link>
  </links>
  <tests>
    <test>
      <test_name>Product specials and discounts quiz</test_name>
      <test_id>48756</test_id>
    </test>
  </tests>
  <results>
    <result>
      <first>Mary</first>
      <last>Simmons</last>
      <test_id>48756</test_id>
      <link_id>2343765</link_id>
      <percentage>70</percentage>
      <points_scored>28</points_scored>
      <points_available>40</points_available>
      <time_started>1339775290</time_started>
      <time_finished>1339776622</time_finished>
      <status>f</status>
      <email>mary@example.com</email>
      <access_code>1</access_code>
      <extra_info>Demographic answer 1</extra_info>
      <extra_info2>Demographic answer 2</extra_info2>
      <extra_info3>Demographic answer 3</extra_info3>
      <extra_info4>Demographic answer 4</extra_info4>
      <extra_info5>Demographic answer 5</extra_info5>
      <duration>00:22:20</duration>
      <requires_grading>No</requires_grading>
      <link_result_id>22453</link_result_id>
      <cm_user_id>74524</cm_user_id>
      <ip_address>192.0.43.10</ip_address>
    </result>
    <result>
      <first>Gary</first>
      <last>Carter</last>
      <test_id>48756</test_id>
      <link_id>2343765</link_id>
      <percentage>80</percentage>
      <points_scored>32</points_scored>
      <points_available>40</points_available>
      <time_started>1339776290</time_started>
      <time_finished>1339776822</time_finished>
      <status>f</status>
      <email>gary@example.com</email>
      <access_code>1</access_code>
      <extra_info>Demographic answer 1</extra_info>
      <extra_info2>Demographic answer 2</extra_info2>
      <extra_info3>Demographic answer 3</extra_info3>
      <extra_info4>Demographic answer 4</extra_info4>
      <extra_info5>Demographic answer 5</extra_info5>
      <duration>00:09:26</duration>
      <requires_grading>No</requires_grading>
      <link_result_id>22453</link_result_id>
      <cm_user_id>45613</cm_user_id>
      <ip_address>192.0.43.10</ip_address>
    </result>
    <result>
      <first>Carl</first>
      <last>Bright</last>
      <test_id>48756</test_id>
      <link_id>985674</link_id>
      <percentage>80</percentage>
      <points_scored>32</points_scored>
      <points_available>40</points_available>
      <time_started>1339776290</time_started>
      <time_finished>1339776822</time_finished>
      <status>f</status>
      <email>gary@example.com</email>
      <access_code>154</access_code>
      <extra_info>Demographic answer 1</extra_info>
      <extra_info2>Demographic answer 2</extra_info2>
      <extra_info3>Demographic answer 3</extra_info3>
      <extra_info4>Demographic answer 4</extra_info4>
      <extra_info5>Demographic answer 5</extra_info5>
      <duration>00:09:26</duration>
      <requires_grading>No</requires_grading>
      <link_result_id>22453</link_result_id>
      <cm_user_id>u7y45t</cm_user_id>
      <ip_address>192.0.43.10</ip_address>
    </result>
  </results>
  <num_results_available>3</num_results_available>
  <num_results_returned>3</num_results_returned>
  <more_results_exist/>
  <next_finished_after_timestamp>1339776622</next_finished_after_timestamp>
</response>

Request: Specific group / test recent results


Retrieve a list of recent test results from a specific Group and Test your API key has permission to access.

The group ID and test ID can be extracted from the Group & test request.

Request URL
GET https://api.classmarker.com/v1/groups/XXXX/tests/XXXX/recent_results.json?api_key=XXXX&signature=XXXX
&timestamp=XXXX&finishedAfterTimestamp=XXXX
groups/29765 The group ID is set in the request path as above
Example: 29765
tests/64776 The test ID is set in the request path as above
Example: 64776
Parameters Value
api_key As above
signature How to create a signature
timestamp As above
finishedAfterTimestamp Only results finished after this UNIX timestamp will be returned.
As above
limit (Optional): By default up to 200 results are returned. You can decrease the amount of returned results if you require.
https://api.classmarker.com/v1/groups/29765/tests/64776/recent_results.json?api_key=d4tsE7SvEgzAKlJPFrlvAz3oe9uFQnxy
&signature=4495a14efc483aa5ee2f6d4cd480f968&timestamp=1335783600&finishedAfterTimestamp=1339779290

JSON response

View example response
{
   "status":"ok",
   "request_path":"v1/groups/29765/tests/64776/recent_results",
   "server_timestamp":1339782640,
   "finished_after_timestamp_used":1338908448,
   "groups":[
      {
         "group":{
            "group_id":29765,
            "group_name":"Internal Accounts department"
         }
      }
   ],
   "tests":[
      {
         "test":{
            "test_id":"64776",
            "test_name":"Health and safety exam"
         }
      }
   ],
   "results":[
      {
         "result":{
            "user_id":"319118",
            "first":"Paul",
            "last":"Smith",
            "email":"paul@example.com",
            "test_id":"64776",
            "group_id":"29765",
            "percentage":"90",
            "points_scored":18,
            "points_available":20,
            "time_started":"1339778290",
            "time_finished":"1339781298",
            "status": "f",
            "duration":"00:50:08",
            "requires_grading":"No"
         }
      },
      {
         "result":{
            "user_id":"319119",
            "first":"Tracy",
            "last":"Thompson",
            "email":"tracey@example.com",
            "test_id":"64776",
            "group_id":"29765",
            "percentage":"95",
            "points_scored":19,
            "points_available":20,
            "time_started":"133977830",
            "time_finished":"133978998",
            "status": "f",
            "duration":"00:19:47",
            "requires_grading":"No"
         }
      }
   ],
   "num_results_available":2,
   "num_results_returned":2,
   "more_results_exist":false,
   "next_finished_after_timestamp":133978998
}

XML response

View example response
<response>
  <status>ok</status>
  <request_path>v1/groups/29765/tests/64776/recent_results</request_path>
  <server_timestamp>1339841380</server_timestamp>
  <finished_after_timestamp_used>1338908448</finished_after_timestamp_used>
  <groups>
    <group>
      <group_id>29765</group_id>
      <group_name>Internal Accounts department</group_name>
    </group>
  </groups>
  <tests>
    <test>
      <test_id>64776</test_id>
      <test_name>Health and safety exam</test_name>
    </test>
  </tests>
  <results>
    <result>
      <user_id>319118</user_id>
      <first>Paul</first>
      <last>Smith</last>
      <email>paul@example.com</email>
      <test_id>64776</test_id>
      <group_id>29765</group_id>
      <percentage>90</percentage>
      <points_scored>18</points_scored>
      <points_available>20</points_available>
      <time_started>1339778290</time_started>
      <time_finished>1339781298</time_finished>
      <status>f</status>
      <duration>"00:50:08</duration>
      <requires_grading>No</requires_grading>
    </result>
     <result>
      <user_id>319118</user_id>
      <first>Tracy</first>
      <last>Thompson</last>
      <email>tracey@example.com</email>
      <test_id>64776</test_id>
      <group_id>29765</group_id>
      <percentage>95</percentage>
      <points_scored>19</points_scored>
      <points_available>20</points_available>
      <time_started>133977830</time_started>
      <time_finished>133978998</time_finished>
      <status>f</status>
      <duration>"00:19:47</duration>
      <requires_grading>No</requires_grading>
    </result>
  </results>
  <num_results_available>2</num_results_available>
  <num_results_returned>2</num_results_returned>
  <more_results_exist></more_results_exist>
  <next_finished_after_timestamp>1338785035</next_finished_after_timestamp>
</response>

Request: Specific link / test recent results


Retrieve a list of recent test results from a specific link and test your API key has permission to access.

The link ID and test ID can be extracted from the Group & test request.

Request URL
GET https://api.classmarker.com/v1/links/XXXX/tests/XXXX/recent_results.json?
api_key=XXXX&signature=XXXX&timestamp=XXXX
&finishedAfterTimestamp=XXXX
links/29765 The link ID is set in the request path as above
Example: 29765
tests/64776 The test ID is set in the request path as above
Example: 64776
Parameters Value
api_key As above
signature How to create a signature
timestamp As above
finishedAfterTimestamp Only results finished after this UNIX timestamp will be returned.
As above
limit (Optional): By default up to 200 results are returned. You can decrease the amount of returned results if you require.
https://api.classmarker.com/v1/links/29765/tests/64776/recent_results.json?api_key=d4tsE7SvEgzAKlJPFrlvAz3oe9uFQnxy
&signature=4495a14efc483aa5ee2f6d4cd480f968&timestamp=1335783600&finishedAfterTimestamp=1339779290

JSON response

View example response

XML response

View example response

Authentication

ClassMarker's API requires authorization with each request.

Basic request

Each API request should contain an api_key, signature and timestamp. It is recommended to use a finishedAfterTimestamp parameter to download only results taken since your last request.

https://api.classmarker.com/v1.json?api_key=d4tsE7SvEgzAKlJPFrlvAz3oe9uFQnxy
&signature=4495a14efc483aa5ee2f6d4cd480f968&timestamp=1335783600

API Key & API Secret

  • An API key & API secret are created from within ClassMarker's administration pages under the My Account section.
  • Each API key has permissions set on which groups it is allowed to request quiz results from.
  • Your API secret should be kept private and secure. ClassMarker holds a copy of your API secret to authenticate your requests.
  • ClassMarker accounts can have multiple API key & API secret combinations created for separate groups/test access.

How to create a signature

Each request should create a new signature and timestamp using the following method.

PHP Code Example:
Note: The periods (.) in the "$signature" MD5 example below are PHP concatenation operators.

<?php

$your_api_key =              'd4tsE7SvEgzAKlJPFrlvAz3oe9uFQnxy';

$your_api_secret =           'keepThisSecret';

$current_unix_timestamp =    time();

$signature = md5($your_api_key . $your_api_secret . $current_unix_timestamp);

?>

Where:
https://api.classmarker.com/v1.json?api_key=$your_api_key&signature=$signature
&timestamp=$current_unix_timestamp

Note:
The md5() signature hash should be created in lowercase.

Timestamp

  • Each request should use the current timestamp.
  • There is a 5-minute window of time variance allowed from the sent timestamp.
  • Use seconds since the UNIX Epoch, not milliseconds.
  • Make sure your server calling our service is in sync with an atomic clock.

What are Groups & Links?

Groups & Links explained

ClassMarker administrators have the opportunity to assign (distribute) exams in two ways:

  1. Groups
    By registering users into groups (handy for school classrooms or work place employee groups/departments).
    Note: The same Exam can be assigned to multiple groups.
  2. Links
    By creating a unique direct link and distributing this link either via email or by adding/embedding it in a web page (no pre registration required for Test takers).
    Note: The same Exam can have multiple direct links to help keep results separated for different groups of users.

When retrieving Exam results from ClassMarker's API, results are returned from their respective Groups or Links depending on how they were taken. To retrieve results for a particular Exam, your API key must have access to the Group or Link the Exam is in.

  1. Groups (Registered users)

    Referenced as: Groups

    Each Group can have multiple Exams assigned to them. Group members log into ClassMarker.com to take Exams assigned to their Group.
    Registered users can also be registered in multiple Groups, which allows them to change between Groups when they are logged in and take any Exams available to their Groups.

  2. Links (Non registered Users)

    Referenced as: Links

    Each Link can only contain one Exam and has a unique link (quiz_id parameter) to access the Exam. (Public and private access options are available when administering Exams via Direct link).

API Rate Limits

The ClassMarker API is built to allow developers to download and store results in their own databases. (See PHP Code examples for PHP class and scripts, including database table schemas to help get you started or as a guide for coding in other languages).

Each API key can make up to 30 requests per hour.

As tests are generally not taken around the clock, we recommend running a cron to request "recent results" once an hour.

If you receive a rate limit, the next_request_after value (see example responses below) gives you a timestamp for when you are next allowed to make a request. The next_request_after timestamp will be within one hour.

JSON response

View example response
{
   "status":"error",
   "request_path":"v1",
   "server_timestamp":1339857211,
   "finished_after_timestamp_used":1338908448,
   "error":{
      "error_code":"rateLimitExceeded",
      "error_message":"You have reached the rate limit of 30 requests per hour.
	               You can next make a request after the UNIX epoch timestamp
	               value set in: next_request_after",
      "next_request_after":1339859100
   }
}

XML response

View example response
<response>
  <status>error</status>
  <request_path>v1</request_path>
  <server_timestamp>1339857715</server_timestamp>
  <finished_after_timestamp_used>1338908448</finished_after_timestamp_used>
  <error>
    <error_code>rateLimitExceeded</error_code>
    <error_message>
	You have reached the rate limit of 30 requests per hour.
	You can next make a request after the UNIX epoch timestamp
	value set in: next_request_after</error_message>
    <next_request_after>1339859100</next_request_after>
  </error>
</response>

Response Formats & Codes

Response formats include: json & xml.

Select which format to return by using .json or .xml at the end of your request URLs.

See examples of URLs and response formats on this page.

API Controller responses

The codes below are be used to check the response status / error codes / and if more results exist so you can make subsequent API calls.

Checking the return status value is the first thing your application should check.

You can see the status node and other response formats throughout examples on this page.

status

The three status responses you can receive are:

  1. ok Request was successful and results have been found and returned to you.
  2. no_results Request was successful, however, no results have been found.
  3. error An error has occurred in your request. Refer to Error codes table for possible values.
request_path The request path you requested - useful for debugging.
Example: v1/groups/29765/tests/64776/recent_results.json
server_timestamp ClassMarker's server timestamp - useful for keeping in sync with our 5 minute timestamp allowance.
Example: 1339779290
finished_after_timestamp_used This is the finishedAfterTimestamp you sent ClassMarker with your request - useful for debugging.
Example: 1335783600
num_results_available The number of available results ClassMarker found in total.
Example: 45
num_results_returned The number of results returned in this response (Maximum and Default returned results per request is 200).
Use the Limit parameter in your request to modify.
Example: 45
more_results_exist More results will be returned if you make another request using the next_finished_after_timestamp value as your next request parameters finishedAfterTimestamp so as to not download the same results twice.
Example: true or false
next_finished_after_timestamp When making your next request, use this timestamp as your next request parameters finishedAfterTimestamp so as to not re-download the same results twice.

See finishedAfterTimestamp for more information.
Example: 1339779290

Error code formats

Refer to the JSON and XML examples for the included error code formats.

Test Result Response (Groups)

Response elements explained:

...,
"results":[
      {
         "result":{
            "user_id":"319118",                       // ClassMarker 'User ID'
            "first":"Mary",                           // First name
            "last":"Simmons",                         // Last name
            "email":"paul@example.com",               // Users email
            "test_id":"48756",                        // ClassMarker 'Test ID'
            "group_id":"29765",                       // ClassMarker 'Group ID'
            "percentage":"70",                        // Percentage
            "points_scored":28,                       // Points Scored
            "points_available":40,                    // Points Available
            "time_started":"1339836668",              // Time Started (Unix Timestamp)
            "time_finished":"1339836849",             // Time Finished (Unix Timestamp)
            "status": "f",                            // f: Finished
            "duration":"00:32:41",                    // Test duration
            "requires_grading":"No",                  // Yes or  No
         }
      },...]

Note: To also retrieve individuals Test Questions, User Responses & Category results, use our WebHooks option instead.

Test Result Response (Links)

Response elements explained:

...,
"results":[
      {
         "result":{
            "link_result_id":22455,                   // Unique 'Test Result ID'
            "first":"Mary",                           // First name
            "last":"Simmons",                         // Last name
            "email":"mary@example.com",               // Users email
            "test_id":"48756",                        // ClassMarker 'Test ID'
            "link_id":"38676",                        // ClassMarker 'Link ID'
            "percentage":"70",                        // Percentage
            "points_scored":28,                       // Points Scored
            "points_available":40,                    // Points Available
            "time_started":"1339836668",              // Time Started (Unix Timestamp)
            "time_finished":"1339836849",             // Time Finished (Unix Timestamp)
            "status": "f",                            // f: Finished Finished
            "access_code":"123",                      // Access code used to access test
            "extra_info":"Demographic answer 1",      // Users answer 1
            "extra_info2":"Demographic answer 2",     // Users answer 2
            "extra_info3":"Demographic answer 3",     // Users answer 3
            "extra_info4":"Demographic answer 4",     // Users answer 4
            "extra_info5":"Demographic answer 5",     // Users answer 5
            "duration":"00:02:41",                    // Test duration
            "requires_grading":"No",                  // Yes or  No
            "cm_user_id":"74524",                     // cm_user_id Parameter value
            "ip_address":"192.0.43.10"                // Users IP address
         }
      },...]

Note: To also retrieve individuals Test Questions, User Responses & Category results, use our WebHooks option instead.

Error Codes & Examples

All ClassMarker's requests return a HTTP 200 Success header even if an API system error occurs such as the errors listed below.

Standard HTTP 404, 500 series error messages will return as normal if applicable.

Look for error messages as described below to handle accordingly.

Key Value
apiKeyAuthFail Access denied. Your API key authorization failed. Check your API key and API SECRET and try again.
apiKeyInactive Access denied. Your API key authorization is currently not active. Check with the person in charge of the your API key to check the keys active state or its start and finish active dates.
apiKeyNoGroupPermission Access denied. Your API key does not have permission to access the group id.
incorrectUrl The requested URL you have tried to access does not exist. Please refer to https://www.classmarker.com/online-testing/api/developers/ for more information.
incorrectUrlVersionNumber The requested URL version number is incorrect or missing. Please refer to https://www.classmarker.com/online-testing/api/developers/ for more information.
incorrectUrlId A requested URL ID is incorrect or missing. Please refer to https://www.classmarker.com/online-testing/api/developers/ for more information.
rateLimitExceeded You have reached the rate limit of 30 requests per hour. You can next make a request after the UNIX epoch timestamp value set in: next_request_after
timeStampOutOfRange Access denied. Timestamp issue. Recalculate the digital signature with each call. (There is a 5-minute window of time variance allowed.) Use seconds since the UNIX Epoch, not milliseconds. Make sure your server calling our service is in sync with an atomic clock.
finishedAfterTimestampTooEarly Your finishedAfterTimestamp is too early. It can only be within the last two weeks.
offlineMaintenance Access denied. ClassMarker is currently down for maintenance. Check https://www.classmarker.com/msg/ for more details
noApiKeyExists Access denied. No API key exists.
accountNotUpgraded Access denied. The ClassMarker account is not currently upgraded. Upgrade for API access.
internalError100 Internal error. Contact ClassMarker with API Error code 100 if error persists.
internalError101 Internal database error. Contact ClassMarker with API Error code 101 if error persists.

JSON response

View example response
{
   "status":"error",
   "request_path":"v1",
   "server_timestamp":1339857211,
   "finished_after_timestamp_used":1338908448,
   "error":{
      "error_code":"apiKeyAuthFail",
      "error_message":"Access denied. Your API KEY authorization failed.
      Check your API KEY and API SECRET and try again."
   }
}

XML response

View example response
<response>
  <status>error</status>
  <request_path>v1</request_path>
  <server_timestamp>1339857715</server_timestamp>
  <finished_after_timestamp_used>1338908448</finished_after_timestamp_used>
  <error>
    <error_code>apiKeyAuthFail</error_code>
    <error_message>Access denied. Your API KEY authorization failed.
    Check your API KEY and API SECRET and try again.</error_message>
  </error>
</response>

API Request: Sample Code (PHP/MySQL)

This is working PHP code ready to install and start making requests and save exam results from ClassMarker to your own database. Just add your API credentials.

Our code example zip file currently only includes PHP code examples, however these can be used as a guide for coding in other languages.

Download: Example code zip

Included files:

  1. README.txt Detailed setup instructions. Read in new browser window
  2. create_classmarker_tables.txt SQL for creating 4 relational database tables to store your results for internal use
  3. classmarker_api.class.php PHP API class for connecting to ClassMarker API and receiving results
  4. request_classmarker_results.php PHP script that includes the classmarker_api.class.php to either:
    1. formats results into arrays (useful for testing purposes)
    2. inserts returned results into the 4 relational database tables (Recommended due to API Rate Limits)
  5. view_classmarker_results.php PHP script to display your stored results from your 4 relational database tables
  6. 10 valid JSON and XML files which you can host & request locally to easily debug your applications before making requests to ClassMarker.

Pass Data to ClassMarker (Pre Test)

When testing with our Links option, you can pass your Test takers data such as their Name, Email or their user_id from your system.

This data is saved in ClassMarker and returned with respective results via this API.

This makes passing Test takers tracking details to ClassMarker easy to reference exam results back in your system.

More about Integrating your online testing

Share on Twitter