> For the complete documentation index, see [llms.txt](https://apidocs.d6plus.co.za/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://apidocs.d6plus.co.za/reference/curriculum+/learner/get-learner-year-marks.md).

# Get Learner Year Marks

### Get the year and promotion marks for learners

<mark style="color:blue;">`GET`</mark> `https://integrate.d6plus.co.za/api/v1/currplus/learneryearmarks/{school_login_id}`

Use this endpoint to fetch the year marks and promotion marks for the specified school, for the specified year.\
The results are grouped per mark type ("Promotion mark" and "Year mark"), per grade, per learner, per subject.\
Marks are based on each learner's latest term of enrolment for the year, for the learner's current subjects. Subjects excluded from report cards are not included.\
By default marks are returned for the CAPS curriculum. A different curriculum can be requested with the optional `curriculum_id` parameter.

**Path Parameters**

| Name                                                | Type    | Description                                      |
| --------------------------------------------------- | ------- | ------------------------------------------------ |
| school\_login\_id<mark style="color:red;">\*</mark> | Integer | The login ID of the school to retrieve data from |

**Query Parameters**

| Name                                   | Type    | Description                                               |
| -------------------------------------- | ------- | --------------------------------------------------------- |
| year<mark style="color:red;">\*</mark> | Integer | The administrative year to return marks for               |
| learner\_id                            | Integer | The ID of a specific learner                              |
| subject\_id                            | Integer | Only return marks for the specified subject               |
| curriculum\_id                         | Integer | The ID of the curriculum. Defaults to the CAPS curriculum |

**Headers**

| Name                                              | Type   | Description       |
| ------------------------------------------------- | ------ | ----------------- |
| HTTP-X-USERNAME<mark style="color:red;">\*</mark> | String | As provided by d6 |
| HTTP-X-PASSWORD<mark style="color:red;">\*</mark> | String | As provided by d6 |

{% tabs %}
{% tab title="200 The request was successful." %}

```json
[
    {
        "mark_type": "Promotion mark",
        "grades": {
            "7": {
                "grade_id": "7",
                "grade": "5",
                "learners": {
                    "1": {
                        "learner_id": "1",
                        "subjects": {
                            "327": {
                                "subject_id": "327",
                                "subject_name": "Mathematics (Gr 05)",
                                "moderated_percentage": "68.00",
                                "original_percentage": "72.00",
                                "was_moderated": "1",
                                "threshold": "35.00"
                            },
                            "105": {
                                "subject_id": "105",
                                "subject_name": "English First Additional Language (Gr 05)",
                                "moderated_percentage": "77.14",
                                "original_percentage": "77.14",
                                "was_moderated": "0",
                                "threshold": null
                            }
                        }
                    }
                }
            }
        }
    },
    {
        "mark_type": "Year mark",
        "grades": {
            "7": {
                "grade_id": "7",
                "grade": "5",
                "learners": {
                    "1": {
                        "learner_id": "1",
                        "subjects": {
                            "327": {
                                "subject_id": "327",
                                "subject_name": "Mathematics (Gr 05)",
                                "moderated_percentage": "70.50",
                                "original_percentage": "70.50",
                                "was_moderated": "0",
                                "threshold": null
                            }
                        }
                    }
                }
            }
        }
    }
]
```

Notes on the subject fields:

* `moderated_percentage` is the mark after moderation. If no moderation was applied, it is equal to `original_percentage`.
* `original_percentage` is the calculated mark before any moderation.
* `was_moderated` indicates whether the mark was moderated (`1`) or not (`0`).
* `threshold` is the moderation threshold configured for the subject's marks formula, if any.
  {% endtab %}

{% tab title="404: Not Found The resource was not found." %}

```json
{
    "error": "Not found",
    "error_description": "No subject mark records found"
}
```

{% endtab %}

{% tab title="401: Unauthorized The server understood the request, but is refusing it or access is not allowed." %}

```json
{
    "error": "Unauthorized",
    "error_description": "Client access not authorised"
}
```

{% endtab %}

{% tab title="403: Forbidden The server understood the request, but the requested action is not allowed." %}

```json
{
    "error": "Integration not activated",
    "error_description": "Please activate the Curriculum+ API for this client before making this request"
}
```

{% endtab %}

{% tab title="400: Bad Request The server understood the request, but the request is invalid or malformed." %}

```json
{
    "error": "Bad Request",
    "error_description": "Please specify the year request parameter."
}
```

{% endtab %}
{% endtabs %}

### Examples

{% tabs %}
{% tab title="PHP" %}

```php
<?php

const BASE_URL = 'https://integrate.d6plus.co.za/api/v1/currplus/learneryearmarks';
const SCHOOL_LOGIN_ID = '1000';
const PARAMS = ['year' => 2026, 'learner_id' => 1];
const API_USERNAME = getenv('API_USERNAME'); // Assuming you have these environment variables set
const API_PASSWORD = getenv('API_PASSWORD');

$curl = curl_init();

$query = http_build_query(PARAMS);

$options = [
    CURLOPT_URL => BASE_URL . '/' . SCHOOL_LOGIN_ID . '?' . $query,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_SSL_VERIFYPEER => true,
    CURLOPT_CUSTOMREQUEST => 'GET',
    CURLOPT_HTTPHEADER => [
        "HTTP-X-USERNAME: " . API_USERNAME,
        "HTTP-X-PASSWORD: " . API_PASSWORD
    ],
];

curl_setopt_array($curl, $options);

$response = curl_exec($curl);

if (curl_errno($curl)) {
    throw new Exception('Curl error: ' . curl_error($curl));
}

curl_close($curl);

echo $response;
```

{% endtab %}

{% tab title="cURL" %}

```bash
curl --location 'https://integrate.d6plus.co.za/api/v1/currplus/learneryearmarks/1000?year=2026&learner_id=1' \
--header 'HTTP-X-USERNAME: your_username' \
--header 'HTTP-X-PASSWORD: your_password'
```

{% endtab %}
{% endtabs %}