### Sample API GET Request Code (PHP/MySQL)

Source: https://www.classmarker.com/online-testing/api/developers

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.

```APIDOC
### API GET Requests: 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.
```

--------------------------------

### cURL Example for Recent Results

Source: https://www.classmarker.com/online-testing/docs/api

Example of how to make a GET request using cURL to fetch recent results, including authentication parameters.

```curl
curl --location --request GET "https://api.classmarker.com/v1/groups/110928/tests/744533/recent_results.json?api_key=Jtyh4zWiaF9SngWhlpRGElNRDtEnLTC1&signature=713cdae732ac2e0206e7c436bb03f8a0&timestamp=1620999467"
```

--------------------------------

### Get All Categories using PHP Client

Source: https://www.classmarker.com/online-testing/docs/api

PHP example for fetching all categories using the ClassMarkerClient. This snippet demonstrates instantiating the client and calling the getAllCategories method.

```php
$cm_client = new ClassMarkerClient($cm_api_key, $cm_api_secret);
$json_response = $cm_client->getAllCategories();
echo $json_response;
```

--------------------------------

### Access ClassMarker Webhook Examples

Source: https://www.classmarker.com/online-testing/docs/webhooks

Links to official GitHub repositories containing implementation examples for various programming languages.

```text
PHP: https://github.com/classmarker/retrieve-quiz-results-webhooks-php
Ruby: https://github.com/classmarker/retrieve-quiz-results-webhooks-ruby
Python: https://github.com/classmarker/retrieve-quiz-results-webhooks-python
Go: https://github.com/classmarker/retrieve-quiz-results-webhooks-go
Node https://github.com/classmarker/retrieve-quiz-results-webhooks-node
Java: https://github.com/classmarker/retrieve-quiz-results-webhooks-java
C#: https://github.com/classmarker/retrieve-quiz-results-webhooks-csharp
```

--------------------------------

### Webhook Integration Guide

Source: https://www.classmarker.com/online-testing/api/webhooks

Instructions on setting up a webhook endpoint to receive and verify ClassMarker quiz results.

```APIDOC
## Webhook Integration Guide

### Description
This guide explains how to set up a webhook endpoint on your server to receive real-time quiz results from ClassMarker. It covers the steps for creating a webhook in ClassMarker, configuring your endpoint, and verifying incoming payloads.

### Method
POST

### Endpoint
Your publicly accessible URL (e.g., `https://yourdomain.com/classmarker-webhook`)

### Parameters
#### Request Headers
- **X-Classmarker-Hmac-Sha256** (string) - Required - The HMAC-SHA256 signature of the payload, used for verification.

#### Request Body
The request body will contain a JSON payload with quiz results. The structure depends on whether the results are from a 'Group' or a 'Link'.

**Payload Type Indicators:**
- `payload_type`: Indicates if results are from 'Group' or 'Link' options.
- `payload_status`: 'live' for actual results, 'verify' for sample results during setup.

**Group Results Fields:**
- `user_id` (string): Unique ID for the registered user.
- `test_id` (string): Unique ID for the test.
- `group_id` (string): Unique ID for the group.
- `time_started` (string): Timestamp indicating when the test started. Useful for identifying retakes or regrades.

**Link Results Fields:**
- `link_result_id` (string): Unique ID for the link result.
- `view_results_url` (string): URL to view formatted test results on ClassMarker.

**Question Fields (Common for Groups and Links):**
- `question_id` (string): Unique ID for the question.
- `question_type` (string): Type of question (e.g., `multiplechoice`, `truefalse`, `freetext`, `matching`, `essay`, `grammar`).
- `category_id` (string): ID of the category the question belongs to.
- `points_available` (number): Total points available for the question.
- `question` (string): The text of the question (can include HTML).
- `options` (object/array): Answer options for certain question types (can include HTML).
- `points_scored` (number): Points awarded for the user's answer.
- `user_response` (string): The user's submitted answer (omitted if not provided).
- `result` (string): Outcome of the answer (e.g., `correct`, `incorrect`, `unanswered`).
- `feedback` (string): Feedback provided for the answer (omitted if none).
- `custom_feedback` (string): Custom feedback for 'Essay' questions, added during grading.

**Category Results Fields:**
- `category_id` (string): ID of the category.
- `name` (string): Name of the category.
- `percentage` (number): Percentage score for the category.
- `points_available` (number): Total points available in the category.
- `points_scored` (number): Points scored by the user in the category.

### Setup Steps
1.  **Create Endpoint:** Add the provided webhook handling code to a publicly accessible URL on your server.
2.  **Create Webhook in ClassMarker:** Navigate to 'My Account' > 'Webhooks' page in your ClassMarker account.
3.  **Configure Endpoint URL:** Enter your public URL in the 'Endpoint' field.
4.  **Save Webhook:** Click the 'Save' button.
5.  **Obtain Webhook Secret:** Copy your 'WEBHOOK SECRET PHRASE' from the ClassMarker webhook settings.
6.  **Implement Secret in Code:** Replace `YOUR_CLASSMARKER_WEBHOOK_SECRET_PHRASE` in your server-side code with your actual secret phrase.
7.  **Verify Webhook:** Check the 'Save and Verify' checkbox in ClassMarker and click 'Save' again.
8.  **Check Response:** Your server should respond with a 2XX status code (e.g., 200 OK) to confirm the webhook is active.

### Server Response
Your server must respond with a 2XX HTTP status code to acknowledge receipt of the webhook payload. A non-2XX response (e.g., 404) indicates an issue with the endpoint URL.

### Example Request Body (Group Results)
```json
{
  "payload_type": "group",
  "payload_status": "live",
  "results": [
    {
      "user_id": "user123",
      "test_id": "test456",
      "group_id": "group789",
      "time_started": "2023-10-27T10:00:00Z",
      "questions": [
        {
          "question_id": "q1",
          "question_type": "multiplechoice",
          "category_id": "catA",
          "points_available": 10,
          "question": "What is the capital of France?",
          "options": {
            "A": "Berlin",
            "B": "Paris",
            "C": "Madrid"
          },
          "points_scored": 10,
          "user_response": "B",
          "result": "correct",
          "feedback": "Correct!"
        }
      ],
      "category_results": [
        {
          "category_id": "catA",
          "name": "Geography",
          "percentage": 100.0,
          "points_available": 10,
          "points_scored": 10
        }
      ]
    }
  ]
}
```

### Example Request Body (Link Results)
```json
{
  "payload_type": "link",
  "payload_status": "live",
  "results": [
    {
      "link_result_id": "lr12345",
      "view_results_url": "https://example.com/view/result/abcde",
      "questions": [
        {
          "question_id": "q2",
          "question_type": "truefalse",
          "category_id": "catB",
          "points_available": 5,
          "question": "The Earth is flat.",
          "points_scored": 0,
          "user_response": "false",
          "result": "incorrect"
        }
      ],
      "category_results": [
        {
          "category_id": "catB",
          "name": "Science",
          "percentage": 0.0,
          "points_available": 5,
          "points_scored": 0
        }
      ]
    }
  ]
}
```
```

--------------------------------

### Make a GET Request using cURL

Source: https://www.classmarker.com/online-testing/docs/api

Example cURL command to send a GET request to the ClassMarker API, including API key, signature, and timestamp.

```bash
curl --location --request GET "https://api.classmarker.com/v1.json?api_key=$your_api_key&signature=$your_signature&timestamp=$current_unix_timestamp_in_secs"
```

--------------------------------

### Create Question Request Examples

Source: https://www.classmarker.com/online-testing/docs/api

Examples of how to structure the request body for creating a new question using cURL and PHP.

```bash
curl --location --request POST "https://api.classmarker.com/v1/questions.json"
--header "Content-Type: application/json" \
--data '{
  "question", "What is the first step for treating a skin burn?",
  "question_type": "multiplechoice",
  "category_id", "3",
  "random_answers": false,
  "points": 2,
  "correct_feedback": "Well done!",
  "incorrect_feedback": "Sorry, that was incorrect, refer to your training materials for further details."
  "options": {
    "A": {
      "content": "Apply oil or butter"
    },
    "B": {
      "content": "Nothing should be done"
    },
    "C": {
      "content": "Soak in water for five minutes"
    },
    "D": {
      "content": "Apply antibiotic ointment"
  }
  },
  "correct_options": ["C"],
}'
```

```php
$question_json = '{
  "question": "What is the first step for treating a skin burn?",
  "question_type": "multiplechoice",
  "category_id": 3,
  "random_answers": false,
  "points": "2.0",
  "correct_feedback": "Well done!",
  "incorrect_feedback": "Sorry, that was incorrect, refer to your training materials for further details.",
  "options": {
    "A": {
      "content": "Apply oil or butter"
    },
    "B": {
      "content": "Nothing should be done"
    },
    "C": {
      "content": "Soak in water for five minutes"
    },
    "D": {
      "content": "Apply antibiotic ointment"
    }
  },
  "correct_options": ["C"]
}';

$cm_client = new ClassMarkerClient($cm_api_key, $cm_api_secret);
$json_response = $cm_client->addQuestion($question_json);
echo $json_response;
```

--------------------------------

### Get All Categories using cURL

Source: https://www.classmarker.com/online-testing/docs/api

Example request to retrieve all exam categories using cURL. This GET request includes necessary query parameters for authentication and timestamp.

```bash
curl --location --request GET https://api.classmarker.com/v1/categories.json?api_key=d4tsE7SvEgzAKlJPFrlvAz3oe9uFQnxy&signature=4495a14efc483aa5ee2f6d4cd480f968&timestamp=1335783600"
```

--------------------------------

### Fetch All Groups, Links, and Exams (PHP Client)

Source: https://www.classmarker.com/online-testing/docs/api

Instantiate the ClassMarker client and call the `getAllGroupLinkTest` method to retrieve all available groups, links, and exams. This example uses the PHP client library.

```php
$cm_client = new ClassMarkerClient($cm_api_key, $cm_api_secret);
$json_response = $cm_client->getAllGroupLinkTest();
echo $json_response;
```