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.

Pass Data to ClassMarker (Pre Test)

API request examples

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.

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 lastnext_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 lastnext_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 6 months old, if not, set the finishedAfterTimestamp to 6 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: 6 months ago

For Example

If finishedAfterTimestampIS SET in your request and is younger than 6 months, it will be used as is. (Recommended Usage)

JSON 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

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>

Sample request

JSON 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

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>

What are Groups & Links?

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

GroupsBy registering users into groups (handy for school classrooms or work place employee groups/departments).
Note: The same Exam can be assigned to multiple groups.

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

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.

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

{"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

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

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.

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.

incorrectRequestMethod

The request Method: GET is incorrect for this action. 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 6 months.

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.