Log in

Exam and Quiz API for Developers

New documentation available


This page is now replaced with our new and updated developer documentation which has more options available.

Go to our updated Developer documentation

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:

Webhooks Documentation

Webhooks allow your Web developers to have Test results securely delivered to your systems/website in real time.

Example: On completion, Test results are delivered instantly.

Go to: WebHooks Documentation

API Documentation

API keys allow your Web developers to have your systems/website securely request & retrieve recent Test results periodically.

Example: Requests for new Test results can be hourly.

View API Documentation below.

API Documentation

IN A NUTSHELL: Our API allows you to request your Quiz results from ClassMarker. You will specify a timestamp, whereby, you will be returned only Quiz results that were completed after your timestamp (See: finishedAfterTimestamp).

You can also send Quiz Access List Codes to ClassMarker via API requests, to automatically control who can access to your Quizzes.

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/Webhooks section of ClassMarker when logged in.

API GET Requests & Examples

  1. Request: All available Groups, Links & Tests
  2. Request: All Groups recent results
  3. Request: All Links recent results
  4. Request: Specific Group / Test recent results
  5. Request: Specific Link / Test recent results

API POST/DELETE Requests & Examples

  1. Request: Add Access Codes
  2. Request: Remove Access Codes

Authentication

View Fromatted Results

What are Groups & Links?

API Rate Limits

Response Formats & Codes

Error Codes & Examples

API Request: Sample Code

Pass Data to ClassMarker (Pre Test)

API request examples

Request: All available Groups, Links & Tests

^ Top

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 data to see when 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

Sample request

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

JSON response

View example response

Links Note 1: 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.

Links Note 2: The access_list_id is only included if an Access List is currently assigned to the Link.

{
   "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 assessment",
                     "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 assessment",
                     "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",
            "access_list_id":123456,
            "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",
            "access_list_id":637251,
            "assigned_tests":[
               {
                  "test":{
                     "test_name":"Product specials & discounts quiz Sydney Version",
                     "test_id":48758
                  }
               }
            ]
         }
      }
   ]
}

XML response

View example response

Links Note 1: 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.

Links Note 2: The access_list_id is only included if an Access List is currently assigned to the Link.

<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 assessment</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 assessment</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>
      <access_list_id>123456</access_list_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>
      <access_list_id>637251</access_list_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

^ Top

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" whereby, 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.

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 3 months old, if not, set the finishedAfterTimestamp to 3 months old in your request, or leave it off the request completely.


RULES for finishedAfterTimestamp
  • The Default finishedAfterTimestamp used: 2 weeks ago
  • The Oldest finishedAfterTimestamp allowed: 3 months ago
  • Need to receive older results? That's fine. When you're ready, contact us to activate a 7 day period where you can use older finishedAfterTimestamp values to retrieve ALL your results.

For Example
  • If finishedAfterTimestamp IS SET in your request and is younger than 3 months, it will be used as is. (Recommended Usage)
    • Generally, your finishedAfterTimestamp should equal the latest 'time_finished' timestamp, from results already retrieved.
  • If finishedAfterTimestamp IS NOT SET in your request, it will default to a timestamp 2 weeks prior to the 'current time'.
  • If finishedAfterTimestamp IS SET in your request, but is older than 3 months, it will return a 'finishedAfterTimestampTooEarly' error code to warn you of your invalid request.
limit (Optional): By default up to 200 results are returned. You can decrease the amount of returned results if you require but not increase.

Sample request

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",
            "percentage_passmark":50,
            "passed":true,
            "requires_grading":"No",
            "give_certificate_only_when_passed":true,
            "certificate_url":"https://www.classmarker.com/pdf/certificate/SampleCertificate.pdf?required_parameters_here",
            "certificate_serial":"CLPPYQSBSY-ZZVKJGQH-XHWMMRCHYT",
            "view_results_url":"https://www.classmarker.com/view/results/?required_parameters_here"
         }
      },
      {
         "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",
            "percentage_passmark":50,
            "passed":true,
            "requires_grading":"No",
            "give_certificate_only_when_passed":true,
            "certificate_url":"https://www.classmarker.com/pdf/certificate/SampleCertificate.pdf?required_parameters_here",
            "certificate_serial":"CXPWYQSBSY-ZYSVKJGQH-XHWMJUCHYT",
            "view_results_url":"https://www.classmarker.com/view/results/?required_parameters_here"
         }
      }
   ],
   "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>
      <percentage_passmark>50</percentage_passmark>
      <passed>true</passed>
      <requires_grading>No</requires_grading>
      <give_certificate_only_when_passed>true</give_certificate_only_when_passed>
      <certificate_url>https://www.classmarker.com/pdf/certificate/SampleCertificate.pdf?required_parameters_here</certificate_url>
      <certificate_serial>CXPWYQSBSY-ZYSVKJGQH-XHWMJUDDYT</certificate_serial>
      <view_results_url>https://www.classmarker.com/view/results/?required_parameters_here</view_results_url>
    </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>
      <percentage_passmark>50</percentage_passmark>
      <passed>true</passed>
      <requires_grading>No</requires_grading>
      <give_certificate_only_when_passed>true</give_certificate_only_when_passed>
      <certificate_url>https://www.classmarker.com/pdf/certificate/SampleCertificate.pdf?required_parameters_here</certificate_url>
      <certificate_serial>CXPWYQSBSY-ZYSWSJGQH-XHWMJUCHYT</certificate_serial>
      <view_results_url>https://www.classmarker.com/view/results/?required_parameters_here</view_results_url>
    </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

^ Top

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.

Sample request

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

JSON response

View example response

Links Note 1: 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.

Links Note 2: The access_list_id is only included if an Access List is currently assigned to the Link.

{
   "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",
            "access_list_id":123456
         }
      },
       {
         "link":{
            "link_name":"Sydney Sales Staff",
            "link_id":985674,
            "link_url_id":"4mb5243e51cf0b0cswe",
            "access_list_id":637251
         }
      }
   ],
   "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":"abc123",
            "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",
            "percentage_passmark":50,
            "passed":true,
            "requires_grading":"No",
            "link_result_id":22453,
            "cm_user_id":"abc74524",
            "ip_address":"192.0.43.10",
            "give_certificate_only_when_passed":true,
            "certificate_url":"https://www.classmarker.com/pdf/certificate/SampleCertificate.pdf?required_parameters_here",
            "certificate_serial":"CLAQYQSBSY-ZZVKJGQH-XHWMMRCHYT",
            "view_results_url":"https://www.classmarker.com/view/results/?required_parameters_here"
         }
      },
      {
         "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":"abc123",
            "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",
            "percentage_passmark":50,
            "passed":true,
            "requires_grading":"No",
            "link_result_id":22463,
            "cm_user_id":"ttr45613",
            "ip_address":"192.0.43.10",
            "give_certificate_only_when_passed":true,
            "certificate_url":"https://www.classmarker.com/pdf/certificate/SampleCertificate.pdf?required_parameters_here",
            "certificate_serial":"CLPERQSBSY-ZZVKJGQH-XHWMMRCHYT",
            "view_results_url":"https://www.classmarker.com/view/results/?required_parameters_here"
         }
      },
      {
         "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":"abc123",
            "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",
            "percentage_passmark":50,
            "passed":true,
            "requires_grading":"No",
            "link_result_id":22522,
            "cm_user_id":"u7y45t",
			"ip_address":"192.0.43.10",
            "give_certificate_only_when_passed":true,
            "certificate_url":"https://www.classmarker.com/pdf/certificate/SampleCertificate.pdf?required_parameters_here",
            "certificate_serial":"CLPPYQSBSY-ZZVKJGQH-XHWMMRCHYT",
            "view_results_url":"https://www.classmarker.com/view/results/?required_parameters_here"
         }
      }
   ],
   "num_results_available":3,
   "num_results_returned":3,
   "more_results_exist":false,
   "next_finished_after_timestamp":1339836709
}

XML response

View example response

Links Note 1: 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.

Links Note 2: The access_list_id is only included if an Access List is currently assigned to the Link.

<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>
      <access_list_id>123456</access_list_id>
    </link>
    <link>
      <link_name>Sydney Sales Staff</link_name>
      <link_id>985674</link_id>
      <link_url_id>4mb5243e51cf0b0cswe</link_url_id>
      <access_list_id>637251</access_list_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>abc123</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>
      <percentage_passmark>50</percentage_passmark>
      <passed>true</passed>
      <requires_grading>No</requires_grading>
      <link_result_id>22453</link_result_id>
      <cm_user_id>abc74524</cm_user_id>
      <ip_address>192.0.43.10</ip_address>
      <give_certificate_only_when_passed>true</give_certificate_only_when_passed>
      <certificate_url>https://www.classmarker.com/pdf/certificate/SampleCertificate.pdf?required_parameters_here</certificate_url>
      <certificate_serial>CXPWYFGBSY-ZYSVKJGQH-XHWMJUCHYT</certificate_serial>
      <view_results_url>https://www.classmarker.com/view/results/?required_parameters_here</view_results_url>
    </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>abc123</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>
      <percentage_passmark>50</percentage_passmark>
      <passed>true</passed>
      <requires_grading>No</requires_grading>
      <link_result_id>22453</link_result_id>
      <cm_user_id>ttr45613</cm_user_id>
      <ip_address>192.0.43.10</ip_address>
      <give_certificate_only_when_passed>true</give_certificate_only_when_passed>
      <certificate_url>https://www.classmarker.com/pdf/certificate/SampleCertificate.pdf?required_parameters_here</certificate_url>
      <certificate_serial>CXPWYQSBSY-ZYSVSGGQH-XHWMJUCHYT</certificate_serial>
      <view_results_url>https://www.classmarker.com/view/results/?required_parameters_here</view_results_url>
    </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>abc123</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>
      <percentage_passmark>50</percentage_passmark>
      <passed>true</passed>
      <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>
      <give_certificate_only_when_passed>true</give_certificate_only_when_passed>
      <certificate_url>https://www.classmarker.com/pdf/certificate/SampleCertificate.pdf?required_parameters_here</certificate_url>
      <certificate_serial>CXPWYQSBSY-ZYSVKJGQH-XHWMSUCHYT</certificate_serial>
      <view_results_url>https://www.classmarker.com/view/results/?required_parameters_here</view_results_url>
    </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

^ Top

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.

Sample request

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",
            "percentage_passmark":50,
            "passed":true,
            "requires_grading":"No",
            "give_certificate_only_when_passed":true,
            "certificate_url":"https://www.classmarker.com/pdf/certificate/SampleCertificate.pdf?required_parameters_here",
            "certificate_serial":"CAQPYQSBSY-ZZVKJGQH-XHWMMRCHYT",
            "view_results_url":"https://www.classmarker.com/view/results/?required_parameters_here"
         }
      },
      {
         "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",
            "percentage_passmark":50,
            "passed":true,
            "requires_grading":"No",
            "give_certificate_only_when_passed":true,
            "certificate_url":"https://www.classmarker.com/pdf/certificate/SampleCertificate.pdf?required_parameters_here",
            "certificate_serial":"CLPPYQSBSY-ZZVKJGQH-XHWMMRDFYT",
            "view_results_url":"https://www.classmarker.com/view/results/?required_parameters_here"
         }
      }
   ],
   "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>
      <percentage_passmark>50</percentage_passmark>
      <passed>true</passed>
      <requires_grading>No</requires_grading>
      <give_certificate_only_when_passed>true</give_certificate_only_when_passed>
      <certificate_url>https://www.classmarker.com/pdf/certificate/SampleCertificate.pdf?required_parameters_here</certificate_url>
      <certificate_serial>CXPWYQSBSY-ZYSVKJGQH-XHAAJUCHYT</certificate_serial>
      <view_results_url>https://www.classmarker.com/view/results/?required_parameters_here</view_results_url>
    </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>
      <percentage_passmark>50</percentage_passmark>
      <passed>true</passed>
      <requires_grading>No</requires_grading>
      <give_certificate_only_when_passed>true</give_certificate_only_when_passed>
      <certificate_url>https://www.classmarker.com/pdf/certificate/SampleCertificate.pdf?required_parameters_here</certificate_url>
      <certificate_serial>CXPWYQSBSY-PPSVKJGQH-XHWMJUCHYT</certificate_serial>
      <view_results_url>https://www.classmarker.com/view/results/?required_parameters_here</view_results_url>
    </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

^ Top

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.

Sample request

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

Request: Add Access codes

^ Top

Post one or more Access codes to an Access list.

Each Link can have one Access list assigned to it.

Find your specific Access List numeric ID from either:

A maximum of 100 Codes can be Added per request.

Maximum of 20,000 Access codes of up to 255 characters per Access list allowed.

API Rate Limits do not apply when adding or removing Access codes.

Request URL
POST https://api.classmarker.com/v1/accesslists/123456.json?api_key=XXXX&signature=XXXX&timestamp=XXXX
accesslists/123456 The Access List "ID" (Not Name) is set in the request path as above
Example: 123456
Parameters Value
api_key As above
signature How to create a signature
timestamp As above
Request Body String ["Code1","Code2","Code3","Code4"] (This is a JSON Encoded Array of Access Codes to Add)

Sample request

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

Request Body String: ["Code1","Code2","Code3","Code4"]

JSON response

View example response 
{
    "status": "ok",
    "request_path": "v1/accesslists/123456",
    "server_timestamp": 1335783600,
    "access_lists": {
        "access_list": {
            "access_list_id": 123456,
            "access_list_name": "New York Staff",
            "num_codes_added": 4,
            "num_codes_total": 16
        }
    }
}

XML response

View example response

Links Note 1: 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.

Links Note 2: The access_list_id is only included if an Access List is currently assigned to the Link.

<response>
  <status>ok</status>
  <request_path>v1/accesslists/123456</request_path>
  <server_timestamp>1335783600</server_timestamp>
  <access_lists>
    <access_list>
      <access_list_id>123456</access_list_id>
      <access_list_name>New York Staff</access_list_name>
      <num_codes_added>4</num_codes_added>
      <num_codes_total>16</num_codes_total>
    </access_list>
  </access_lists>
</response>

Code Examples: View PHP Code examples for Adding and Removing Access codes.

How to Pass Access codes with Quiz Start URL:

You have the option to add Access Codes to the Quiz Start URLs.

This means you do not need to give each Test taker an Access code, instead, you can have their unique Access code appended to the Start URL to give them access.

https://www.classmarker.com/online-test/start?quiz={QUIZ_ID}
&cm_fn=John (optional)
&cm_ln=Smith (optional)
&cm_e=john@example.com (optional)
&cm_access_list_item=their_access_code (optional)

See: View Integration overview documentation for more details.

Request: Remove Access codes

^ Top

Post one or more Access codes to an Access list.

Each Link can have one Access list assigned to it.

Find your specific Access List numeric ID from either:

A maximum of 100 Codes can be Removed per request.

API Rate Limits do not apply when adding or removing Access codes.

Request URL
DELETE https://api.classmarker.com/v1/accesslists/123456.json?api_key=XXXX&signature=XXXX&timestamp=XXXX
accesslists/123456 The Access List "ID" (Not Name) is set in the request path as above
Example: 123456
Parameters Value
api_key As above
signature How to create a signature
timestamp As above
Request Body String ["Code1","Code2","Code3","Code4"] (This is a JSON Encoded Array of Access Codes to Remove)

Sample request

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

JSON response

View example response 
{
    "status": "ok",
    "request_path": "v1/accesslists/123456",
    "server_timestamp": 1335783600,
    "access_lists": {
        "access_list": {
            "access_list_id": 123456,
            "access_list_name": "New York Staff",
            "num_codes_deleted": 4,
            "num_codes_total": 16
        }
    }
}

XML response

View example response

Links Note 1: 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.

Links Note 2: The access_list_id is only included if an Access List is currently assigned to the Link.

<response>
  <status>ok</status>
  <request_path>v1/accesslists/123456</request_path>
  <server_timestamp>1335783600</server_timestamp>
  <access_lists>
    <access_list>
      <access_list_id>123456</access_list_id>
      <access_list_name>New York Staff</access_list_name>
      <num_codes_deleted>4</num_codes_deleted>
      <num_codes_total>16</num_codes_total>
    </access_list>
  </access_lists>
</response>

Code Examples: View PHP Code examples for Adding and Removing Access codes.

Authentication

^ Top

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.

Sample 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.

View Results URL

Give access to colleagues who need to review Formatted Test Results (including Questions and Answers) without them needing a ClassMarker account..

See parameter: view_results_url

Including this URL is optional and needs to be turned on in the API settings pages. Each URL is unique and unguessable.

IMPORTANT: Allow Viewing Access to: view_results_url

  1. Go to your My account page in ClassMarker
  2. Scroll down to the 'API' setting box
  3. Select your control settings
  4. Save: Select 'Update Access Settings' button

Access Control options include:

  • Password Protection
  • Expire URL after X Days or Months
  • Hide Test Taker Details for Anonymous grading
  • Allow Grading
  • Allow Submitting New Graded Results via Webhooks

Download our: Quiz API Integration Guide for your Web developers.

What are Groups & Links?

^ Top
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.

Learn More: Giving access to exams.

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

^ Top

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 (on a random minute of your choice).

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

^ Top

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)

^ Top

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
            "view_results_url":"https://...",         // Unique URL Per Test Result (Password protected)
         }
      },...]

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

Test Result Response (Links)

^ Top

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":"abc123",                   // 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":"abc74524",                  // cm_user_id Parameter value
            "ip_address":"192.0.43.10",               // Users IP address
            "view_results_url":"https://...",         // Unique URL Per Test Result (Password protected)

         }
      },...]

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

Error Codes & Examples

^ Top

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/docs/ for more information. Some issues could be: Incorrect URL, Incorrect ID used, Incorrect HTTP METHOD used.
incorrectUrlVersionNumber The requested URL version number is incorrect or missing. Please refer to https://www.classmarker.com/online-testing/docs/ for more information.
incorrectUrlId A requested URL ID is incorrect or missing. Please refer to https://www.classmarker.com/online-testing/docs/ for more information.
incorrectRequestMethod The request Method: GET is incorrect for this action. Please refer to https://www.classmarker.com/online-testing/docs/ 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 3 months. Contact Us to activate a 7 day period to download all your results.
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.
invalidJson Invalid JSON. Please check your payload
NotAllowedActionForQuestionType This operation is not supported this question type
payloadValidationError The payload has invalid data.
requestParamValidationError the request parameter has invalid data
custom_error A custom message will display applicable to the action taken.

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 GET Requests: Sample Code (PHP/MySQL)

^ Top

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.

Github Code Example Also Available

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

Quiz Maker API code from Github

Included files:

  1. README.md Detailed setup instructions.
  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.

API POST Request: Sample Code

^ Top

This PHP code can be used to Add or Remove access codes from your access lists.

Fill in your API Key and Secret and Access list ID, and add your array of Access codes to add or delete as required.

<?php

// PHP API Access Lists code example by ClassMarker.com


$your_api_key =              'yourApiKey';

$your_api_secret =           'keepThisSecret';

$current_unix_timestamp =     time();

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


// Create Access Codes Array
$access_codes_array = array('Code1', 'Code2', 'Code3', 'Code4');

// Convert to JSON string
$json_string_payload = json_encode($access_codes_array);

// Which Access list to update
$your_access_list_id = 123456;


// Adding Codes
$method = 'POST';

// Removing Codes
// $method =  'DELETE';


$request_baseurl = 'https://api.classmarker.com/v1/accesslists/' . $your_access_list_id . '.json?api_key='.$your_api_key . '&signature=' . $signature . '&timestamp=' . $current_unix_timestamp;


// create curl resource
$ch = curl_init();

// set url
curl_setopt($ch, CURLOPT_URL, $request_baseurl);

$headers = array(
	'Content-type: application/json; charset=utf-8'
);


curl_setopt($ch, CURLOPT_HTTPHEADER,     $headers);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST,  $method); // REQUEST METHOD MUST BE POST OR DELETE
curl_setopt($ch, CURLOPT_POSTFIELDS,     $json_string_payload);

// Catch JSON Response String from ClassMarker
$json_response_string = curl_exec($ch);

// close curl resource to free up system resources
curl_close($ch);

?>

Pass Data to ClassMarker (Pre Test)

^ Top

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 Your Find With Colleagues

Visit ClassMarker on Facebook

Forgot password? / Register free