> This is part 1 of 2 of the full documentation (pages 1–100 of 110).
> The content is paginated: fetch every part to see all of it.
> Next part: https://apidocs.d6plus.co.za/llms-full.txt/1
> Page index: https://apidocs.d6plus.co.za/llms.txt

# Getting Started

Hi and welcome!

d6 Integrate provides a RESTful API to interact with the d6+ School Administration and Management System (SAMS).

This API documentation will provide you with everything you need in order to take advantage of the capabilities that d6 Integrate offers.

Please read the entire Getting Started section before diving into the Reference section, as it provides the necessary context and detail you will need to implement an effective integration.

We are always looking to improve, so please email any suggestions to <apidocs@d6.co.za>


# Authorisation & Activation

Each school that makes use of the d6+ SAMS is able the manage the list of integrations they would like to make use of.&#x20;

Before you (our d6 Integrate partner) can interact with a school's data via the d6 Integrate API, the school must first authorise your integration in their d6+ SAMS instance.&#x20;

During your d6 Integrate partner onboarding process, you will receive introductory training on how schools manage their integrations on the d6+ SAMS. This will ensure that you are equipped to assist your new clients to authorise your integration.

This authorisation should ideally only be done once the school has entered into an agreement with you as a service provider, since the school is authorising the sharing of their information with you.

In order keep you updated about which schools are choosing to make use of your service, each time a school authorises or de-authorises your integration, you will receive a notification email. This will be sent to the technical contact email address specified on your d6 Integrate License Agreement.&#x20;

In order to avoid being billed for schools that are not (yet) your client, you have the ability to activate the integration once it has been authorised by the school. This ensures that you retain control over who your active, legitimate clients are. You will need to activate an integration before you are able to interact with the school's data.&#x20;

Billing of a school will only commence after you activate the integration for the first time. Once an integration has been activated, billing will continue for the duration of your license agreement and active subscription, regardless of whether you subsequently de-activate the integration. However, should a school choose to de-authorise your integration, you will no longer be billed for that school.

Please see the [Settings](/reference/settings) section in the Reference area for the relevant API endpoints to view and manage your authorised integrations.

Once a school has authorised your integration and you have activated it, you are free to interact with their data via the the d6 integration API's that are included in your subscription. If you de-activate the integration, or the school de-authorises it, the d6 integration API will not allow access to that school's data.


# API URL

The base URL for all endpoints in this API collection is shown below.

`https://integrate.d6plus.co.za/api/`


# Versioning

d6 Integrate utilises versioning in order to:

* Ensure backward compatibility
* Facilitate feature enhancements and testing
* Manage the deprecation of outdated endpoints
* Ultimately provide a more reliable and consistent user experience for developers

The version number is independent per endpoint.

The version is specified by a number with a ‘v’ prefix (eg: v1, v2) - for example:&#x20;

`https://integrate.d6plus.co.za/api/`**`v1`**`/adminplus/learners`

`https://integrate.d6plus.co.za/api/`**`v3`**`/adminplus/parents`

`https://integrate.d6plus.co.za/api/`**`v2`**`/currplus/learnersubjects`


# Authentication

d6 Integrate requires authentication via username and password credentials which are provided to you by d6 after successful completion of a data sharing license agreement.

The credentials must be passed in the request header using the following parameters:

> HTTP-X-USERNAME
>
> HTTP-X-PASSWORD

{% hint style="warning" %}
All API requests must be made over HTTPS. Requests made over plain HTTP will fail and may risk exposing your key. Your credentials must never be shared. Do not use your credentials in client side code as you may risk exposing it to third parties.
{% endhint %}


# Response Status Codes

d6 Integrate uses status codes that adhere to the HTTP/1.1 standard (RFC 7231):

| Code | Name                  | Description                                                                                               |
| ---- | --------------------- | --------------------------------------------------------------------------------------------------------- |
| 200  | OK                    | The request was successful.                                                                               |
| 400  | Bad Request           | The request was invalid. Normally due to missing or malformed parameters.                                 |
| 401  | Unauthorized          | The server understood the request, but is refusing it.                                                    |
| 403  | Forbidden             | The server understood the request, but access is not allowed.                                             |
| 404  | Not Found             | The resource was not found.                                                                               |
| 429  | Too Many Requests     | Rate limits have been reached, please slow down your requests.                                            |
| 500  | Internal Server Error | Internal server error which has been logged and being attended to. Please try again later.                |
| 501  | Not Implemented       | The server does not support the functionality required to fulfill the request.                            |
| 503  | Service Unavailable   | The server is currently unable to handle the request due to a temporary overload or scheduled maintenance |


# Rate Limiting

Please be aware that should you exceed these limits you will receive a 429 (Too Many Requests).

The current rate limits are:

* 300 requests per 60 seconds per unique IP address


# Errors and Bad Requests

Errors or bad requests caught by the API will always return an appropriate HTTP response as described in the [Response Status Codes](/getting-started/response-status-codes) section, as well as a body containing a JSON object with 2 attributes:

* `error` - The HTTP status name
* `error_description` - A description of the actual problem encountered

The values of these attributes will always be a string.


# Settings

This section details the REST endpoints to interact with the d6 Integrate settings on your account as well as for clients who have authorised your integration.

## Endpoint

The base URL for all endpoints in this module is shown below. The version number is independent per endpoint.

`https://integrate.d6plus.co.za/api/v1/`**`settings`**`/`


# Clients


# Get Clients

## Get the list of clients with integrations authorised

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

Use this endpoint to fetch the information of clients who have authorised your integration in their d6+ SAMS instance. By default, all clients with authorised integrations will be returned.&#x20;

It is possible to retrieve the information for a single client by providing the optional `school_login_id` query parameter.

#### Path Parameters

| Name              | Type    | Description                                      |
| ----------------- | ------- | ------------------------------------------------ |
| school\_login\_id | Integer | The login ID of the school to retrieve data from |

#### 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
[
    {
        "school_login_id": "1000",
        "school_name": "d6+ Primary School",
        "admin_email_address": "support@d6plus.co.za",
        "telephone_calling_code": "27",
        "telephone_number": "0123334444",
        "api_type_id": 8,
        "api_type": "Admin+ API",
        "activated_by_integrator": "No"
    },
    {
        "school_login_id": "1000",
        "school_name": "d6+ Primary School",
        "admin_email_address": "support@d6plus.co.za",
        "telephone_calling_code": "27",
        "telephone_number": "0123334444",
        "api_type_id": 9,
        "api_type": "Curriculum+ API",
        "activated_by_integrator": "Yes"
    }    
]
```

{% endtab %}

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

```json
{
    "error": "Not found",
    "error_description": "No client-authorised integrations found"
}
```

{% endtab %}

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

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

{% endtab %}
{% endtabs %}

## Examples

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

```php
<?php

const BASE_URL = 'https://integrate.d6plus.co.za/api/v1/settings/clients';
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,
    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/settings/clients' \
--header 'HTTP-X-USERNAME: your_username' \
--header 'HTTP-X-PASSWORD: your_password'
```

{% endtab %}
{% endtabs %}


# Change Client Integration State

## Change the state of the client integration

<mark style="color:purple;">`PATCH`</mark> `https://integrate.d6plus.co.za/api/v1/settings/clients/{school_login_id}`

Use this endpoint to change the state of the integration for a client who has authorised your integration in their d6+ SAMS instance. This state indicates whether you are actively servicing the client or not.

#### Path Parameters

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

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

#### Request Body

| Name                                            | Type    | Description                                            |
| ----------------------------------------------- | ------- | ------------------------------------------------------ |
| state<mark style="color:red;">\*</mark>         | Integer | The state you would like to set the integration to     |
| api\_type\_id<mark style="color:red;">\*</mark> | Integer | The api\_type\_id returned by the Get Clients endpoint |

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

```json
[]
```

{% endtab %}

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

```json
{
    "error": "Not found",
    "error_description": "No client-authorised integrations found"
}
```

{% endtab %}

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

```json
{
    "error": "Unauthorized",
    "error_description": "Client access not authorised for this API type"
}
```

{% endtab %}

{% tab title="500: Internal Server Error The server experienced an error while attempting to perform the requested action." %}

```json
{
    "error": "Internal Server Error",
    "error_description": "Failed to update the integration state"
}
```

{% endtab %}

{% tab title="400: Bad Request The request was invalid. Normally due to missing or malformed parameters." %}

```json
{
    "error": "Bad Request",
    "error_description": "Invalid integration state provided"
}
```

{% endtab %}

{% tab title="204: No Content The request was understood and processed, but no changes were made." %}

```json
[]
```

{% endtab %}
{% endtabs %}

## Examples

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

```php
<?php

const BASE_URL = 'https://integrate.d6plus.co.za/api/v1/settings/clients';
const SCHOOL_LOGIN_ID = '1000';
const API_USERNAME = getenv('API_USERNAME'); // Assuming you have these environment variables set
const API_PASSWORD = getenv('API_PASSWORD');

$data = [
    "api_type_id" => 8,
    "state" => 1
]; 
$jsonData = json_encode($data);

$curl = curl_init();

$query = http_build_query(PARAMS);

$options = [
    CURLOPT_URL => BASE_URL . '/' . SCHOOL_LOGIN_ID,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_SSL_VERIFYPEER => true,
    CURLOPT_CUSTOMREQUEST => 'PATCH',
    CURLOPT_POSTFIELDS => $jsonData,    
    CURLOPT_HTTPHEADER => [
        "HTTP-X-USERNAME: " . API_USERNAME,
        "HTTP-X-PASSWORD: " . API_PASSWORD,
        "Content-Type: application/json",
        "Content-Length: " . strlen($jsonData)        
    ],
];

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" %}

<pre class="language-bash"><code class="lang-bash"><strong>curl --location --request PATCH 'https://integrate.d6plus.co.za/api/v1/settings/clients/1000' \
</strong>--header 'HTTP-X-USERNAME: YOUR_API_USERNAME' \
--header 'HTTP-X-PASSWORD: YOUR_API_PASSWORD' \
--header 'Content-Type: application/json' \
--data '{"api_type_id": 8, "state": 1}'
</code></pre>

{% endtab %}
{% endtabs %}


# Administration+

This section details the REST endpoints to interact with the Administration+ module.

## Endpoint

The base URL for all endpoints in this module is shown below. The version number is independent per endpoint.

`https://integrate.d6plus.co.za/api/v1/`**`adminplus`**`/`


# Lookups

A number of the API endpoints return values for attributes which are list items in d6+, for example a language or grade, which can be selected from a dropdown in d6+. In order to manage and facilitate these attributes more effectively, there are a number of endpoints available to lookup one or all of the available values in the list.

Some of these lists are generic across all schools, but some can be customised per school, in which case it will be necessary to specify the desired school's Login ID in the request URL, as illustrated in the relevant endpoint documentation.


# Ethnic Group(s)

## Get the list of available ethnic groups

<mark style="color:blue;">`GET`</mark> `https://integrate.d6plus.co.za/api/v1/adminplus/lookup/ethnicgroup/{ethnic_group_id}`

Use this endpoint to retrieve the list of available ethnic groups within the d6+ SAMS. The list is generic across all d6+ SAMS clients. By default all available ethnic groups are returned.&#x20;

It is possible to retrieve the information for a single ethnic group by providing the optional `ethnic_group_id` query parameter.

#### Path Parameters

| Name              | Type    | Description                            |
| ----------------- | ------- | -------------------------------------- |
| ethnic\_group\_id | Integer | The ID of the ethnic group to retrieve |

#### 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
[
    {
        "id": "1",
        "name": "African/Black"
    },
    {
        "id": "2",
        "name": "Coloured"
    },
    {
        "id": "3",
        "name": "Indian"
    },
    {
        "id": "4",
        "name": "White"
    },
    {
        "id": "5",
        "name": "Other"
    },
    {
        "id": "6",
        "name": "Asian"
    }
]
```

{% endtab %}

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

```json
{
    "error": "Not found",
    "error_description": "No ethnic group(s) found"
}
```

{% endtab %}

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

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

{% endtab %}
{% endtabs %}

## Examples

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

```php
<?php

const BASE_URL = 'https://integrate.d6plus.co.za/api/v1/adminplus/lookup/ethnicgroup';
const ETHNIC_GROUP_ID = '1';

const API_USERNAME = getenv('API_USERNAME'); // Assuming you have these environment variables set
const API_PASSWORD = getenv('API_PASSWORD');

$curl = curl_init();

$options = [
    CURLOPT_URL => BASE_URL . '/' . ETHNIC_GROUP_ID,
    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/adminplus/lookup/ethnicgroup/1' \
--header 'HTTP-X-USERNAME: your_username' \
--header 'HTTP-X-PASSWORD: your_password'
```

{% endtab %}
{% endtabs %}


# Genders

## Get the list of available genders

<mark style="color:blue;">`GET`</mark> `https://integrate.d6plus.co.za/api/v1/adminplus/lookup/genders`

Use this endpoint to retrieve the list of available genders within the d6+ SAMS. The list is generic across all d6+ SAMS clients. All available genders are returned.&#x20;

#### 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
[
    {
        "id": "M",
        "name": "Male"
    },
    {
        "id": "F",
        "name": "Female"
    }
]
```

{% endtab %}

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

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

{% endtab %}
{% endtabs %}

## Examples

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

```php
<?php

const BASE_URL = 'https://integrate.d6plus.co.za/api/v1/adminplus/lookup/genders';

const API_USERNAME = getenv('API_USERNAME'); // Assuming you have these environment variables set
const API_PASSWORD = getenv('API_PASSWORD');

$curl = curl_init();

$options = [
    CURLOPT_URL => BASE_URL,
    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/adminplus/lookup/genders' \
--header 'HTTP-X-USERNAME: your_username' \
--header 'HTTP-X-PASSWORD: your_password'
```

{% endtab %}
{% endtabs %}


# Grade(s)

## Get the list of available grades

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

Use this endpoint to retrieve the list of available grades within the d6+ SAMS.&#x20;

The list is not generic across all d6+ SAMS clients, and could be customised per school. This endpoint allows you to specify a school Login ID in order to retrieve the list of grades offered by the school, along with their potentially customised names.&#x20;

By default all available grades are returned.&#x20;

It is also possible to retrieve the information for a single grade by providing the optional `grade_id` query 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                |
| --------- | ------ | -------------------------- |
| grade\_id | String | The ID of a specific grade |

#### 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
[
    {
        "id": "1",
        "name": "Grade RR"
    },
    {
        "id": "2",
        "name": "Grade R"
    },
    {
        "id": "3",
        "name": "Grade 1"
    },
    {
        "id": "4",
        "name": "Grade 2"
    },
    {
        "id": "5",
        "name": "Grade 3"
    },
    {
        "id": "6",
        "name": "Grade 4"
    },
    {
        "id": "7",
        "name": "Grade 5"
    },
    {
        "id": "8",
        "name": "Grade 6"
    }
]
```

{% endtab %}

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

```json
{
    "error": "Not found",
    "error_description": "No grade(s) found"
}
```

{% endtab %}

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

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

{% endtab %}
{% endtabs %}

## Examples

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

```php
<?php

const BASE_URL = 'https://integrate.d6plus.co.za/api/v1/adminplus/lookup/grade';
const SCHOOL_LOGIN_ID = '1000';
const PARAMS = [
    'grade_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/adminplus/lookup/grade/1000?grade_id=1' \
--header 'HTTP-X-USERNAME: your_username' \
--header 'HTTP-X-PASSWORD: your_password'
```

{% endtab %}
{% endtabs %}


# Language(s)

## Get the list of available languages

<mark style="color:blue;">`GET`</mark> `https://integrate.d6plus.co.za/api/v1/adminplus/lookup/language/{language_id}`

Use this endpoint to retrieve the list of available languages within the d6+ SAMS. The list is generic across all d6+ SAMS clients. By default all available languages are returned.&#x20;

It is possible to retrieve the information for a single languages by providing the optional `language_id` query parameter.

#### Path Parameters

| Name         | Type    | Description                        |
| ------------ | ------- | ---------------------------------- |
| language\_id | Integer | The ID of the language to retrieve |

#### 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
[
    {
        "id": "1",
        "name": "Afrikaans"
    },
    {
        "id": "2",
        "name": "English"
    },
    {
        "id": "3",
        "name": "Ndebele"
    },
    {
        "id": "4",
        "name": "Swazi"
    },
    {
        "id": "5",
        "name": "Xhosa"
    }
]
```

{% endtab %}

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

```json
{
    "error": "Not found",
    "error_description": "No language(s) found"
}
```

{% endtab %}

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

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

{% endtab %}
{% endtabs %}

## Examples

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

```php
<?php

const BASE_URL = 'https://integrate.d6plus.co.za/api/v1/adminplus/lookup/language';
const LANGUAGE_ID = '1';

const API_USERNAME = getenv('API_USERNAME'); // Assuming you have these environment variables set
const API_PASSWORD = getenv('API_PASSWORD');

$curl = curl_init();

$options = [
    CURLOPT_URL => BASE_URL . '/' . LANGUAGE_ID,
    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/adminplus/lookup/language/1' \
--header 'HTTP-X-USERNAME: your_username' \
--header 'HTTP-X-PASSWORD: your_password'
```

{% endtab %}
{% endtabs %}


# Marital Status(')

## Get the list of available marital status'

<mark style="color:blue;">`GET`</mark> `https://integrate.d6plus.co.za/api/v1/adminplus/lookup/maritalstatus/{marital_status_id}`

Use this endpoint to retrieve the list of available marital status' within the d6+ SAMS. The list is generic across all d6+ SAMS clients. By default all available marital status' are returned.&#x20;

It is possible to retrieve the information for a single marital status by providing the optional `marital_status_id` query parameter.

#### Path Parameters

| Name                | Type    | Description                              |
| ------------------- | ------- | ---------------------------------------- |
| marital\_status\_id | Integer | The ID of the marital status to retrieve |

#### 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
[
    {
        "id": "1",
        "name": "Divorced"
    },
    {
        "id": "2",
        "name": "Married"
    },
    {
        "id": "3",
        "name": "Single"
    },
    {
        "id": "4",
        "name": "Widowed"
    },
    {
        "id": "6",
        "name": "Separated"
    },
    {
        "id": "7",
        "name": "Common law marriage"
    }
]
```

{% endtab %}

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

```json
{
    "error": "Not found",
    "error_description": "No marital status' found"
}
```

{% endtab %}

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

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

{% endtab %}
{% endtabs %}

## Examples

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

```php
<?php

const BASE_URL = 'https://integrate.d6plus.co.za/api/v1/adminplus/lookup/maritalstatus';
const MARITAL_STATUS_ID = '1';

const API_USERNAME = getenv('API_USERNAME'); // Assuming you have these environment variables set
const API_PASSWORD = getenv('API_PASSWORD');

$curl = curl_init();

$options = [
    CURLOPT_URL => BASE_URL . '/' . MARITAL_STATUS_ID,
    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/adminplus/lookup/maritalstatus/1' \
--header 'HTTP-X-USERNAME: your_username' \
--header 'HTTP-X-PASSWORD: your_password'
```

{% endtab %}
{% endtabs %}


# School


# Get School Info

## Get the school information

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

Use this endpoint to fetch the information for the specified school.

#### Path Parameters

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

#### 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
{
    "school_name": "d6+ Primary School",
    "admin_email_address": "support@d6plus.co.za",
    "telephone_calling_code": "27",
    "telephone_number": "0123334444",
    "website": "https://d6.co.za/",
    "physical_address": "Pegasus Building 1, 3rd Floor\r\nMercy Avenue\r\nWaterkloof Glen Ext 2
\r\nPretoria",
    "quantile": "4",
    "medium": "Dual medium",
    "emis_number": "999999999",
    "country": "South Africa",
    "province": "Gauteng",
    "tuition_languages": [
        "Afrikaans",
        "English"
    ]
}
```

{% endtab %}

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

```json
{
    "error": "Not found",
    "error_description": "No school record found"
}
```

{% endtab %}

{% tab title="401: Unauthorized The server understood the request, but 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 Admin+ API for this client before making this request"
}
```

{% endtab %}
{% endtabs %}

## Examples

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

```php
<?php

const BASE_URL = 'https://integrate.d6plus.co.za/api/v1/adminplus/school';
const SCHOOL_LOGIN_ID = '1000';

const API_USERNAME = getenv('API_USERNAME'); // Assuming you have these environment variables set
const API_PASSWORD = getenv('API_PASSWORD');

$curl = curl_init();

$options = [
    CURLOPT_URL => BASE_URL . '/' . SCHOOL_LOGIN_ID,
    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/adminplus/school/1000' \
--header 'HTTP-X-USERNAME: your_username' \
--header 'HTTP-X-PASSWORD: your_password'
```

{% endtab %}
{% endtabs %}


# Learner


# Get Learner(s)

## Get one or more learner records

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

Use this endpoint to fetch one or more learner records for the specified school.  By default, all current enrolled learners will be returned.&#x20;

It is possible to retrieve non-current learners by providing the optional `status` query parameter. &#x20;

When retrieving left learners, additional optional `since` and `until` query parameters will allow you to specify a date range, and only learners who have left in this date range will be returned. By default, learners who have left in the last month will be returned. The `since` - `until` range may not be more than 1 year.

It is possible to retrieve a single learner by providing the optional `learner_id` query parameter.&#x20;

It is possible to retrieve the learners for a specific grade or grades, by providing the optional `grade_id` query parameter. This can be a single grade ID or a comma-separated list of grade ID's. The list of available grade ID's for a school can be obtained by making use of the [Grade(s) Lookup](/reference/administration+/lookups/grade-s) endpoint.&#x20;

If your subscription includes the Parent API, it is possible to include the parent/guardian data directly in the learner response payload by providing the optional `include_parents` query parameter. The parent/guardian data will be included in a sub-array per learner, with  parent/guardian 1 followed by parent/guardian 2.

#### 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                                                                                                                                                                                 |
| ---------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| status           | String  | <p>The status of the learners to return. Acceptable values are:<br>\* current (default)<br>\* left<br>\* waitlist</p>                                                                       |
| since            | String  | The date to which left learner transfer dates should be limited, when using the `status` parameter. Defaults to 1 month ago. May not be more than 1 year before `until`. Format: YYYY-MM-DD |
| until            | String  | The date until which left learner transfer dates should be limited, when using the `status` parameter. Defaults to today. May not be more than 1 year after `since`. Format: YYYY-MM-DD     |
| learner\_id      | Integer | The ID of a specific learner                                                                                                                                                                |
| grade\_id        | Integer | A comma-separated list of grade ID's to filter by                                                                                                                                           |
| include\_parents | String  | Whether to include the parent data in the response                                                                                                                                          |
| name             | String  | Search for a learner by their name, surname or name and surname combination                                                                                                                 |
| family\_code     | Integer | Search for a learner(s) by their family code                                                                                                                                                |

#### 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
[
    {
        "id": "1",
        "first_name": "John",
        "last_name": "Smith",
        "mobile_calling_code": "27",
        "mobile_number": "0823456789",
        "email_address": "jsmith@example.com",
        "date_of_birth": "2018-01-01",
        "gender": "M",
        "ethnic_group_id": "4",
        "ethnic_group": "White",        
        "home_language_id": "1",
        "home_language": "Afrikaans",
        "tuition_language_id": "1",        
        "tuition_language": "Afrikaans",
        "nationality": "South Africa",
        "admission_number": "12345",
        "family_code": "1001",
        "id_number": "1801015005084",
        "passport_number": "",
        "grade_id": "9",
        "grade": "7",
        "register_class_name": "5A",
        "register_class_teacher_id": "4",
        "country": "South Africa",
        "province": "Gauteng",        
        "education_stream": "Mainstream",
        "photo_url": "",
        "parent1_id": "40",
        "parent2_id": "41",
        "parents": [
            {
                "id": "40",
                "title": "Mr",
                "first_name": "John James",
                "last_name": "Smith",
                "mobile_calling_code": "27",
                "mobile_number": "0823456789",
                "email_address": "jjsmith@example.com",
                "date_of_birth": "1967-02-14",
                "gender": "M",
                "ethnic_group_id": "4",
                "ethnic_group": "White",
                "residential_address": "Plot 101\r\nDaffodil Street\r\nPretoria",
                "postal_address": "PO Box 12\r\nMenlyn\r\nPretoria",
                "home_language_id": "2",                
                "home_language": "English",
                "nationality": "South Africa",
                "family_code": "1001",
                "id_number": "6702145076084",
                "passport_number": "A0176543",
                "marital_status_id": "2",
                "marital_status": "Married",                
                "occupation_status": "Full Time Employed",
                "occupation": "Salesman",
                "employment_sector": "Selling",
                "gross_annual_income": "120000.00"            
            },
            {
                "id": "41",
                "title": "Mrs",
                "first_name": "Jane Jenny",
                "last_name": "Smith",
                "mobile_calling_code": "27",
                "mobile_number": "0798765432",
                "email_address": "smith.jj@example.org",
                "date_of_birth": "1955-06-17",
                "gender": "F",
                "ethnic_group_id": "1",                
                "ethnic_group": "African/Black",
                "residential_address": "Plot 101\r\nDaffodil Street\r\nPretoria",
                "postal_address": "PO Box 12\r\nMenlyn\r\nPretoria",
                "home_language_id": "2",                
                "home_language": "English",
                "nationality": "South Africa",
                "family_code": "1001",
                "id_number": "5506170079082",
                "passport_number": "",
                "marital_status_id": "2",
                "marital_status": "Married",                
                "occupation_status": "Unemployed",
                "occupation": "",
                "employment_sector": "Other",
                "gross_annual_income": "0.00"            
            }
        ]
    },
    {
        "id": "2",
        "first_name": "Jane",
        "last_name": "Doe",
        "mobile_calling_code": "27",
        "mobile_number": "0798765432",
        "email_address": "jane@example.org",
        "date_of_birth": "2018-06-13",
        "gender": "F",
        "ethnic_group_id": "1",
        "ethnic_group": "African/Black",
        "home_language_id": "1",        
        "home_language": "Afrikaans",
        "tuition_language_id": "1",        
        "tuition_language": "Afrikaans",
        "nationality": "South Africa",
        "admission_number": "12346",
        "family_code": "1001",
        "id_number": "1806130110087",
        "passport_number": "",
        "grade_id": "7",        
        "grade": "5",
        "register_class_name": "4C",
        "register_class_teacher_id": "13"
        "country": "South Africa",
        "province": "Gauteng",        
        "education_stream": "Mainstream",
        "photo_url": "",
        "parent1_id": "40",
        "parent2_id": "41",
        "parents": [
            {
                "id": "40",
                "title": "Mr",
                "first_name": "John James",
                "last_name": "Smith",
                "mobile_calling_code": "27",
                "mobile_number": "0823456789",
                "email_address": "jjsmith@example.com",
                "date_of_birth": "1967-02-14",
                "gender": "M",
                "ethnic_group_id": "4",                
                "ethnic_group": "White",
                "residential_address": "Plot 101\r\nDaffodil Street\r\nPretoria",
                "postal_address": "PO Box 12\r\nMenlyn\r\nPretoria",
                "home_language_id": "2",                
                "home_language": "English",
                "nationality": "South Africa",
                "family_code": "1001",
                "id_number": "6702145076084",
                "passport_number": "A0176543",
                "marital_status_id": "2",
                "marital_status": "Married",
                "occupation_status": "Full Time Employed",
                "occupation": "Salesman",
                "employment_sector": "Selling",
                "gross_annual_income": "120000.00"            
            },
            {
                "id": "41",
                "title": "Mrs",
                "first_name": "Jane Jenny",
                "last_name": "Smith",
                "mobile_calling_code": "27",
                "mobile_number": "0798765432",
                "email_address": "smith.jj@example.org",
                "date_of_birth": "1955-06-17",
                "gender": "F",
                "ethnic_group_id": "1",                
                "ethnic_group": "African/Black",
                "residential_address": "Plot 101\r\nDaffodil Street\r\nPretoria",
                "postal_address": "PO Box 12\r\nMenlyn\r\nPretoria",
                "home_language_id": "2",                
                "home_language": "English",
                "nationality": "South Africa",
                "family_code": "1001",
                "id_number": "5506170079082",
                "passport_number": "",
                "marital_status_id": "2",
                "marital_status": "Married",
                "occupation_status": "Unemployed",
                "occupation": "",
                "employment_sector": "Other",
                "gross_annual_income": "0.00"            
            }
        ]
    }
]
```

{% endtab %}

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

```json
{
    "error": "Not found",
    "error_description": "No learner 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 Admin+ API for this client before making this request"
}
```

{% endtab %}
{% endtabs %}

## Examples

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

```php
<?php

const BASE_URL = 'https://integrate.d6plus.co.za/api/v1/adminplus/learners';
const SCHOOL_LOGIN_ID = '1000';
const PARAMS = [
    'learner_id' => 1, 
    'include_parents' => 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/adminplus/learners/1000?learner_id=1&include_parents=1' \
--header 'HTTP-X-USERNAME: your_username' \
--header 'HTTP-X-PASSWORD: your_password'
```

{% endtab %}
{% endtabs %}


# Get Learner Absentees

## Get learner absentee records

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

Use this endpoint to fetch absentee records for one or more learners for the specified school.  By default, all absentee records for the last month will be returned, regardless of the associated learners current status.

It is possible to retrieve absentee records for a single learner by providing the optional `learner_id` query parameter.

It is possible to specify a different date range by providing the optional `from_date` and `to_date` query parameters. \
The following validation applies:\
\- The `to_date` may not be before the `from_date`. \
\- The date range may not span more than 31 days.

#### 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                           |
| ----------- | ------- | ------------------------------------- |
| learner\_id | Integer | The ID of a specific learner          |
| to\_date    | String  | Range end date in format YYYY-MM-DD   |
| from\_date  | String  | Range start date in format YYYY-MM-DD |

#### 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
[
    {
        "id": "399910",
        "learner_id": "6273",
        "absent_date": "2023-06-01",
        "absent_reason": "Illness"
    },
    {
        "id": "399912",
        "learner_id": "6273",
        "absent_date": "2023-06-02",
        "absent_reason": "Illness"
    }
]
```

{% endtab %}

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

```json
{
    "error": "Not found",
    "error_description": "No learner absentee 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="400: Bad Request The request was invalid. Normally due to missing or malformed parameters." %}

```json
{
    "error": "Bad Request",
    "error_description": "The specified date range may not be more than 31 days"
}
```

{% 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 Admin+ API for this client before making this request"
}
```

{% endtab %}
{% endtabs %}

## Examples

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

```php
<?php

const BASE_URL = 'https://integrate.d6plus.co.za/api/v1/adminplus/learnerabsentees';
const SCHOOL_LOGIN_ID = '1000';
const PARAMS = [
    'learner_id' => 1,
    'from_date' => '2023-06-01',
    'to_date' => '2023-06-14'
];
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/adminplus/learnerabsentees/1000?learner_id=1&from_date=2023-06-01&to_date=2023-06-14' \
--header 'HTTP-X-USERNAME: your_username' \
--header 'HTTP-X-PASSWORD: your_password'
```

{% endtab %}
{% endtabs %}


# Get Learner Discipline

## Get learner discipline records

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

Use this endpoint to fetch discipline records for one or more learners for the specified school.  By default, all discipline records for the last month will be returned, regardless of the associated learners current status.&#x20;

It is possible to retrieve discipline records for a single learner by providing the optional `learner_id` query parameter.

It is possible to specify a different date range by providing the optional `from_date` and `to_date` query parameters. \
The following validation applies:\
\- The `to_date` may not be before the `from_date`. \
\- The date range may not span more than 31 days.

#### 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                           |
| ----------- | ------- | ------------------------------------- |
| learner\_id | Integer | The ID of a specific learner          |
| to\_date    | String  | Range end date in format YYYY-MM-DD   |
| from\_date  | String  | Range start date in format YYYY-MM-DD |

#### 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
[
    {
        "id": "1",
        "learner_id": "2",
        "discipline_date": "2023-06-30",
        "discipline_category": "Level 1",
        "discipline_reason": "Appearance : Hair / Nails",
        "discipline_points": "-1",
        "discipline_remarks": "",
        "staff_member_id": "3"
    },
    {
        "id": "2",
        "learner_id": "1",
        "discipline_date": "2023-07-03",
        "discipline_category": "General",
        "discipline_reason": "Handed in lost goods/money",
        "discipline_points": "3",
        "discipline_remarks": "",
        "staff_member_id": "4"
    }
]
```

{% endtab %}

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

```json
{
    "error": "Not found",
    "error_description": "No learner discipline 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="400: Bad Request The request was invalid. Normally due to missing or malformed parameters." %}

```json
{
    "error": "Bad Request",
    "error_description": "The specified date range may not be more than 31 days"
}
```

{% 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 Admin+ API for this client before making this request"
}
```

{% endtab %}
{% endtabs %}

## Examples

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

```php
<?php

const BASE_URL = 'https://integrate.d6plus.co.za/api/v1/adminplus/learnerdiscipline';
const SCHOOL_LOGIN_ID = '1000';
const PARAMS = [
    'learner_id' => 1,
    'from_date' => '2023-06-01',
    'to_date' => '2023-06-14'
];
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/adminplus/learnerdiscipline/1000?learner_id=1&from_date=2023-06-01&to_date=2023-06-14' \
--header 'HTTP-X-USERNAME: your_username' \
--header 'HTTP-X-PASSWORD: your_password'
```

{% endtab %}
{% endtabs %}


# Parent


# Get Parent(s)

## Get one or more parent records

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

Use this endpoint to fetch one or more parent records for the specified school.  By default, parents of all current active learners will be returned.&#x20;

It is possible to retrieve a single parent by providing the optional `parent_id` query 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                 |
| ---------- | ------- | --------------------------- |
| parent\_id | Integer | The ID of a specific parent |

#### 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
[
    {
        "id": "40",
        "title": "Mr",
        "first_name": "John James",
        "last_name": "Smith",
        "mobile_calling_code": "27",
        "mobile_number": "0823456789",
        "email_address": "jjsmith@example.com",
        "date_of_birth": "1967-02-14",
        "gender": "M",
        "ethnic_group_id": "4",
        "ethnic_group": "White",
        "residential_address": "Plot 101\r\nDaffodil Street\r\nPretoria",
        "postal_address": "PO Box 12\r\nMenlyn\r\nPretoria",
        "home_language_id": "2",
        "home_language": "English",
        "nationality": "South Africa",
        "family_code": "1001",
        "id_number": "6702145076084",
        "passport_number": "A0176543",
        "marital_status_id": "2",
        "marital_status": "Married",
        "occupation_status": "Full Time Employed",
        "occupation": "Salesman",
        "employment_sector": "Selling",
        "gross_annual_income": "120000.00"
    },
    {
        "id": "41",
        "title": "Mrs",
        "first_name": "Jane Jenny",
        "last_name": "Smith",
        "mobile_calling_code": "27",
        "mobile_number": "0798765432",
        "email_address": "smith.jj@example.org",
        "date_of_birth": "1955-06-17",
        "gender": "F",
        "ethnic_group_id": "1",
        "ethnic_group": "African/Black",
        "residential_address": "Plot 101\r\nDaffodil Street\r\nPretoria",
        "postal_address": "PO Box 12\r\nMenlyn\r\nPretoria",
        "home_language_id": "2",
        "home_language": "English",
        "nationality": "South Africa",
        "family_code": "1001",
        "id_number": "5506170079082",
        "passport_number": "",
        "marital_status_id": "2",
        "marital_status": "Married",
        "occupation_status": "Unemployed",
        "occupation": "",
        "employment_sector": "Other",
        "gross_annual_income": "0.00"
    }
]
```

{% endtab %}

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

```json
{
    "error": "Not found",
    "error_description": "No parent 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 Admin+ API for this client before making this request"
}
```

{% endtab %}
{% endtabs %}

## Examples

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

```php
<?php

const BASE_URL = 'https://integrate.d6plus.co.za/api/v1/adminplus/parents';
const SCHOOL_LOGIN_ID = '1000';
const PARAMS = ['parent_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/adminplus/parents/1000?parent_id=1' \
--header 'HTTP-X-USERNAME: your_username' \
--header 'HTTP-X-PASSWORD: your_password'
```

{% endtab %}
{% endtabs %}


# Staff Member


# Get Staff Member(s)

## Get one or more staff member records

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

Use this endpoint to fetch one or more staff member records for the specified school.  By default all current active staff members will be returned.&#x20;

It is possible to retrieve a single staff member by providing the optional `staff_member_id` query 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                       |
| ----------------- | ------- | --------------------------------- |
| staff\_member\_id | Integer | The ID of a specific staff member |

#### 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
[
    {
        "id": "1",
        "title": "Mr",
        "first_name": "John",
        "last_name": "Smith",
        "mobile_calling_code": "27",
        "mobile_number": "0823456789",
        "email_address": "jjsmith@example.com",
        "date_of_birth": "1967-02-14",
        "gender": "M",
        "ethnic_group": "White",
        "residential_address": "Plot 101\r\nDaffodil Street\r\nPretoria",
        "postal_address": "PO Box 12\r\nMenlyn\r\nPretoria",
        "home_language": "English",
        "nationality": "South Africa",
        "id_number": "6702145076084",
        "passport_number": "A0176543",
        "marital_status_id": "Married",
        "employment_category": "Finance",
        "is_educator": "Yes",
        "appointment_type": "Temporary",
        "paid_by": "Department of Education",
        "sace_number": "123456",
        "register_classes": "2A"
    },
    {
        "id": "2",
        "title": "Mrs",
        "first_name": "Jane",
        "last_name": "Smith",
        "mobile_calling_code": "27",
        "mobile_number": "0798765432",
        "email_address": "smith.jj@example.org",
        "date_of_birth": "1955-06-17",
        "gender": "F",
        "ethnic_group": "African/Black",
        "residential_address": "Plot 101\r\nDaffodil Street\r\nPretoria",
        "postal_address": "PO Box 12\r\nMenlyn\r\nPretoria",
        "home_language": "English",
        "nationality": "South Africa",
        "id_number": "5506170079082",
        "passport_number": "",
        "marital_status_id": "Married",
        "employment_category": "Head Of Department",
        "is_educator": "No",
        "appointment_type": "Permanent",
        "paid_by": "Governing Body",
        "sace_number": "234567",
        "register_classes": "1A,2B,5A"
    }
]
```

{% endtab %}

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

```json
{
    "error": "Not found",
    "error_description": "No staff member 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 Admin+ API for this client before making this request"
}
```

{% endtab %}
{% endtabs %}

## Examples

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

```php
<?php

const BASE_URL = 'https://integrate.d6plus.co.za/api/v1/adminplus/staffmembers';
const SCHOOL_LOGIN_ID = '1000';
const PARAMS = ['staff_member_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/adminplus/staffmembers/1000?staff_member_id=1' \
--header 'HTTP-X-USERNAME: your_username' \
--header 'HTTP-X-PASSWORD: your_password'
```

{% endtab %}
{% endtabs %}


# Curriculum+

This section details the REST endpoints to interact with the Curriculum+ module.

## Endpoint

The base URL for all endpoints in this module is shown below. The version number is independent per endpoint.

`https://integrate.d6plus.co.za/api/v1/`**`currplus`**`/`


# Learner


# Get Learner Subjects

## Get the subject records for one or more learners

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

Use this endpoint to fetch the list of subjects for the current year for one or more learner for the specified school.  By default, the subjects for all current active learners will be returned.&#x20;

It is possible to retrieve the subjects for a single learner by providing the optional `learner_id` query 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                  |
| ----------- | ------- | ---------------------------- |
| learner\_id | Integer | The ID of a specific learner |

#### 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
[
    {
        "learner_id": "1",
        "first_name": "Janey",
        "last_name": "Smith",
        "subject_id": 101,
        "subject_name": "Afrikaans Home Language (Gr 05)"
    },
    {
        "learner_id": "1",
        "first_name": "Janey",
        "last_name": "Smith",
        "subject_id": 105,        
        "subject_name": "English First Additional Language (Gr 05)"
    },
    {
        "learner_id": "1",
        "first_name": "Janey",
        "last_name": "Smith",
        "subject_id": 201,        
        "subject_name": "Life Skills (Gr 05)"
    },
    {
        "learner_id": "1",
        "first_name": "Janey",
        "last_name": "Smith",
        "subject_id": 135,        
        "subject_name": "Mathematics (Gr 05)"
    },
    {
        "learner_id": "1",
        "first_name": "Janey",
        "last_name": "Smith",
        "subject_id": 322,
        "subject_name": "Natural Sciences and Technology (Gr 05)"
    },
    {
        "learner_id": "1",
        "first_name": "Janey",
        "last_name": "Smith",
        "subject_id": 49,        
        "subject_name": "Social Sciences (Gr 05)"
    }
]
```

{% endtab %}

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

```json
{
    "error": "Not found",
    "error_description": "No learner subject 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 %}
{% endtabs %}

## Examples

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

```php
<?php

const BASE_URL = 'https://integrate.d6plus.co.za/api/v1/currplus/learnersubjects';
const SCHOOL_LOGIN_ID = '1000';
const PARAMS = ['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/learnersubjects/1000?learner_id=1' \
--header 'HTTP-X-USERNAME: your_username' \
--header 'HTTP-X-PASSWORD: your_password'
```

{% endtab %}
{% endtabs %}


# Get Learner Subjects Per Term

## Get the subject records for a learner per term

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

Use this endpoint to fetch the subjects per term for the specified learner, for the specified school.  \
All subjects for all terms will be return, for the current d6+ administrative year. \
The results are grouped per term, per subject, for the current administrative year.&#x20;

#### 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                  |
| --------------------------------------------- | ------- | ---------------------------- |
| learner\_id<mark style="color:red;">\*</mark> | Integer | The ID of a specific learner |

#### 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
[
    {
        "year": "2025",
        "subject_id": "10",
        "subject_name": "Afrikaans First Additional Language (Gr 07)",
        "super_subject_id": "1",
        "super_subject_name": "Afrikaans First Additional Language",
        "grade_id": "9",
        "grade": "7",
        "terms": [
            {
                "term_id": 98,
                "term": "1",
                "subject_group_id": "118",
                "subject_group_name": "Afrikaans Group 1",
                "classroom_id": "1",
                "classroom_name": "1",
                "subject_group_teacher_id": "13"
            },
            {
                "term_id": 99,
                "term": "2",
                "subject_group_id": "118",
                "subject_group_name": "Afrikaans Group 1",
                "classroom_id": "1",
                "classroom_name": "1",
                "subject_group_teacher_id": "13"
            },
            {
                "term_id": 100,
                "term": "3",
                "subject_group_id": "270",
                "subject_group_name": "Afrikaans Group 2",
                "classroom_id": "4",
                "classroom_name": "3A",
                "subject_group_teacher_id": "17"
            },
            {
                "term_id": 101,
                "term": "4",
                "subject_group_id": "270",
                "subject_group_name": "Afrikaans Group 2",
                "classroom_id": "4",
                "classroom_name": "3A",
                "subject_group_teacher_id": "17"
            }
        ]
    },
    {
        "year": "2025",
        "subject_id": "3418",
        "subject_name": "Coding and Robotics (Gr 07)",
        "super_subject_id": "2334",
        "super_subject_name": "Coding and Robotics",
        "grade_id": "9",
        "grade": "7",
        "terms": [
            {
                "term_id": 98,
                "term": "1",
                "subject_group_id": "119",
                "subject_group_name": "Coding 1A",
                "classroom_id": "2",
                "classroom_name": "2",
                "subject_group_teacher_id": "4"
            },
            {
                "term_id": 99,
                "term": "2",
                "subject_group_id": "119",
                "subject_group_name": "Coding 1A",
                "classroom_id": "2",
                "classroom_name": "2",
                "subject_group_teacher_id": "4"
            },
            {
                "term_id": 100,
                "term": "3",
                "subject_group_id": "322",
                "subject_group_name": "Coding 1B",
                "classroom_id": "9",
                "classroom_name": "K4",
                "subject_group_teacher_id": "17"
            },
            {
                "term_id": 101,
                "term": "4",
                "subject_group_id": "322",
                "subject_group_name": "Coding 1B",
                "classroom_id": "9",
                "classroom_name": "K4",
                "subject_group_teacher_id": "17"
            }
        ]
    }
]
```

{% endtab %}

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

```json
{
    "error": "Not found",
    "error_description": "No learner subject 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 learner_id request parameter."
}
```

{% endtab %}
{% endtabs %}

## Examples

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

```php
<?php

const BASE_URL = 'https://integrate.d6plus.co.za/api/v1/currplus/learnersubjectsperterm';
const SCHOOL_LOGIN_ID = '1000';
const PARAMS = ['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/learnersubjectsperterm/1000?learner_id=1' \
--header 'HTTP-X-USERNAME: your_username' \
--header 'HTTP-X-PASSWORD: your_password'
```

{% endtab %}
{% endtabs %}


# Get Learner Subject Marks

## Get the subject marks records for a learner

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

Use this endpoint to fetch the marks for the specified learner, for the specified school.  \
All marks for all terms will be return, for the current d6+ administrative year. \
The results are grouped per term, per subject, for the current administrative year.&#x20;

#### 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                  |
| --------------------------------------------- | ------- | ---------------------------- |
| learner\_id<mark style="color:red;">\*</mark> | Integer | The ID of a specific learner |

#### 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
[
    {
        "year": "2023",
        "subject_id": "21",
        "subject_name": "Afrikaans Home Language (Gr 05)",
        "grade_id": "7",
        "grade": "5",
        "terms": [
            {
                "term": "1",
                "mark": "80.00"
            },
            {
                "term": "2",
                "mark": "72.86"
            }
        ]
    },
    {
        "year": "2023",
        "subject_id": "105",
        "subject_name": "English First Additional Language (Gr 05)",
        "grade_id": "7",
        "grade": "5",
        "terms": [
            {
                "term": "1",
                "mark": "70.00"
            },
            {
                "term": "2",
                "mark": "77.14"
            }
        ]
    },
    {
        "year": "2023",
        "subject_id": "314",
        "subject_name": "Life Skills (Gr 05)",
        "grade_id": "7",
        "grade": "5",
        "terms": [
            {
                "term": "1",
                "mark": "60.00"
            },
            {
                "term": "2",
                "mark": "96.00"
            }
        ]
    },
    {
        "year": "2023",
        "subject_id": "327",
        "subject_name": "Mathematics (Gr 05)",
        "grade_id": "7",
        "grade": "5",
        "terms": [
            {
                "term": "1",
                "mark": "75.00"
            },
            {
                "term": "2",
                "mark": "96.00"
            }
        ]
    },
    {
        "year": "2023",
        "subject_id": "355",
        "subject_name": "Natural Sciences and Technology (Gr 05)",
        "grade_id": "7",
        "grade": "5",
        "terms": [
            {
                "term": "1",
                "mark": "65.00"
            },
            {
                "term": "2",
                "mark": "88.33"
            }
        ]
    },
    {
        "year": "2023",
        "subject_id": "533",
        "subject_name": "Social Sciences (Gr 05)",
        "grade_id": "7",
        "grade": "5",
        "terms": [
            {
                "term": "1",
                "mark": "85.00"
            },
            {
                "term": "2",
                "mark": "90.00"
            }
        ]
    }
]
```

{% 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 learner_id request parameter."
}
```

{% endtab %}
{% endtabs %}

## Examples

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

```php
<?php

const BASE_URL = 'https://integrate.d6plus.co.za/api/v1/currplus/learnersubjectmarks';
const SCHOOL_LOGIN_ID = '1000';
const PARAMS = ['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/learnersubjectmarks/1000?learner_id=1' \
--header 'HTTP-X-USERNAME: your_username' \
--header 'HTTP-X-PASSWORD: your_password'
```

{% endtab %}
{% endtabs %}


# Get Learner Assessment Marks

### Get the assessment marks records for a learner or grade

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

Use this endpoint to fetch the individual assessment marks for the specified learner or grade, for the specified school.\
The results are grouped per grade, per year, per term, per learner, per subject, per learning outcome, with the assessments listed under each learning outcome.\
At least one of the `learner_id` or `grade_id` query parameters must be provided. If no `year` is provided, the current d6+ administrative year is used.\
Assessment marks are only included once the marks for the learning program have been released (the learning program's mark release date, or the end of the term if no release date is set). Use the `structure` parameter to retrieve the assessment structure (assessments, dates and weights) without any marks.

**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                                                                              |
| --------------------- | ------- | ---------------------------------------------------------------------------------------- |
| learner\_id           | Integer | The ID of a specific learner. Required if `grade_id` is not provided                     |
| grade\_id             | Integer | The ID of a specific grade. Required if `learner_id` is not provided                     |
| subject\_id           | Integer | Only return marks for the specified subject                                              |
| year                  | Integer | The administrative year to return marks for. Defaults to the current administrative year |
| term                  | Integer | Only return marks for the specified term                                                 |
| learning\_outcome\_id | Integer | Only return marks for the specified learning outcome                                     |
| assessment\_id        | Integer | Only return marks for the specified assessment                                           |
| structure             | Boolean | When set to 1, only the assessment structure is returned, without any marks              |

**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
{
    "7": {
        "grade": "5",
        "years": {
            "2026": {
                "year": "2026",
                "year_name": "2026",
                "terms": {
                    "1": {
                        "term": "1",
                        "learners": {
                            "1": {
                                "learner_id": "1",
                                "subjects": {
                                    "327": {
                                        "subject_id": "327",
                                        "subject_name": "Mathematics (Gr 05)",
                                        "learning_outcomes": {
                                            "12": {
                                                "learning_outcome_id": "12",
                                                "learning_outcome_name": "Numbers, Operations and Relationships",
                                                "assessments": {
                                                    "45": {
                                                        "assessment_id": "45",
                                                        "assessment_name": "Test 1",
                                                        "assessment_date": "2026-03-15",
                                                        "weight": "40.00",
                                                        "dtime": "2026-03-20 10:15:00",
                                                        "percentage": "75.00",
                                                        "mark": "30.00",
                                                        "mark_out_of": "40.00",
                                                        "captured": "1"
                                                    },
                                                    "46": {
                                                        "assessment_id": "46",
                                                        "assessment_name": "Assignment 1",
                                                        "assessment_date": "2026-02-20",
                                                        "weight": "60.00",
                                                        "dtime": "2026-02-25 08:30:00",
                                                        "percentage": "82.50",
                                                        "mark": "33.00",
                                                        "mark_out_of": "40.00",
                                                        "captured": "1"
                                                    }
                                                }
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    }
                }
            }
        }
    }
}
```

Notes on the assessment fields:

* `percentage` contains the value `"a"` when the learner was marked as absent for the assessment.
* `captured` indicates whether a mark has been captured for the assessment (`1`) or not (`0`).
* `dtime` is the date and time the mark was last updated.
* When the `structure` parameter is used, only `assessment_id`, `assessment_name`, `assessment_date` and `weight` are returned per assessment.
  {% 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 learner_id or grade_id request parameter."
}
```

{% endtab %}
{% endtabs %}

### Examples

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

```php
<?php

const BASE_URL = 'https://integrate.d6plus.co.za/api/v1/currplus/learnerassessmentmarks';
const SCHOOL_LOGIN_ID = '1000';
const PARAMS = ['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/learnerassessmentmarks/1000?learner_id=1' \
--header 'HTTP-X-USERNAME: your_username' \
--header 'HTTP-X-PASSWORD: your_password'
```

{% endtab %}
{% endtabs %}


# 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 %}


# Finance+

This section details the REST endpoints to interact with the Finance+ module.

## Endpoint

The base URL for all endpoints in this module is shown below. The version number is independent per endpoint.

`https://integrate.d6plus.co.za/api/v1/`**`finplus`**`/`


# Debt Management


# Debtor Notes


# Get Communication Type(s)

## Retrieve debtor note types

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

Use this endpoint to retrieve the list of available debtor note communication types. By default all available communication types are returned.&#x20;

It is possible to retrieve the information for a single communication type by providing the optional `communication_type_id` query parameter.

#### Path Parameters

<table><thead><tr><th width="247">Name</th><th width="102">Type</th><th>Description</th></tr></thead><tbody><tr><td>school_login_id<mark style="color:red;">*</mark></td><td>Integer</td><td>The login ID of the school to retrieve data from</td></tr></tbody></table>

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

#### Query Parameters

<table><thead><tr><th width="249">Name</th><th width="114">Type</th><th>Description</th></tr></thead><tbody><tr><td>communication_type_id</td><td>Integer</td><td>The id of the communication type to retrieve</td></tr></tbody></table>

#### Reponse Examples

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

```json
[
    {
        "id": "1",
        "name": "SMS"
    },
    {
        "id": "2",
        "name": "E-mail"
    },
    {
        "id": "3",
        "name": "Telephonic"
    },
    ...
]
```

{% endtab %}

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

```json
{
    "error": "Not Found",
    "error_description": "The communication type does not exist"
}
```

{% 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 Finance+ API for this client before making this request"
}
```

{% endtab %}
{% endtabs %}

## Code Samples

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

```php
<?php

const BASE_URL = 'https://integrate.d6plus.co.za/api/v1/finplus/debtmanagement/debtornotes/notetypes';
const SCHOOL_LOGIN_ID = '1000';
const PARAMS = [
    'note_type_id' => 2
    ];
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/finplus/debtmanagement/debtornotes/notetypes/1000?note_type_id=2' \
--header 'HTTP-X-USERNAME: your_username' \
--header 'HTTP-X-PASSWORD: your_password'
```

{% endtab %}
{% endtabs %}


# Get Note Type(s)

## Retrieve debtor note types

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

Use this endpoint to retrieve the list of available debtor note types. By default all available note types are returned.&#x20;

It is possible to retrieve the information for a single note type by providing the optional `note_type_id` query parameter.

#### Path Parameters

<table><thead><tr><th width="247">Name</th><th width="102">Type</th><th>Description</th></tr></thead><tbody><tr><td>school_login_id<mark style="color:red;">*</mark></td><td>Integer</td><td>The login ID of the school to retrieve data from</td></tr></tbody></table>

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

#### Query Parameters

<table><thead><tr><th width="249">Name</th><th width="114">Type</th><th>Description</th></tr></thead><tbody><tr><td>note_type_id</td><td>Integer</td><td>The id of the note type to retrieve</td></tr></tbody></table>

#### Response Examples

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

```json
[
    {
        "id": "1",
        "name": "Text note"
    },
    {
        "id": "2",
        "name": "Promise to pay"
    },
    {
        "id": "3",
        "name": "Internal note"
    }
]
```

{% endtab %}

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

```json
{
    "error": "Not Found",
    "error_description": "The note type does not exist"
}
```

{% 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 Finance+ API for this client before making this request"
}
```

{% endtab %}
{% endtabs %}

## Code Samples

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

```php
<?php

const BASE_URL = 'https://integrate.d6plus.co.za/api/v1/finplus/debtmanagement/debtornotes/notetypes';
const SCHOOL_LOGIN_ID = '1000';
const PARAMS = [
    'note_type_id' => 2
    ];
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/finplus/debtmanagement/debtornotes/notetypes/1000?note_type_id=2' \
--header 'HTTP-X-USERNAME: your_username' \
--header 'HTTP-X-PASSWORD: your_password'
```

{% endtab %}
{% endtabs %}


# Get Note(s)

## Get one or more debtor note records

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

Use this endpoint to fetch one or more debtor note records for the specified school.  By default, all  active debtor notes will be returned. To include deleted debtor notes in the results, provide the `include_deleted` query parameter.

It is possible to retrieve a single debtor note by providing the optional `note_id` query parameter.

Additionally it is also possible to search for a debtor note(s) using the `debtor_code`, `accountable_person_id` and/or `note_type_id` query parameters. To return notes for only a specific year, use the `year` query parameter.

To include the "Promise to Pay" payment arrangement data directly in the notes response payload, providing the additional `include_promise_to_pays` query parameter. The payment arrangement data will be included in a sub-array per note.

#### Path Parameters

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

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

#### Query Parameters

| Name                       | Type    | Description                                             |
| -------------------------- | ------- | ------------------------------------------------------- |
| note\_id                   | Integer | The ID of a specific note                               |
| note\_type\_id             | Integer | To only return notes of a given note type               |
| communication\_type\_id    | Integer | To only return notes of a given communication type      |
| accountable\_person\_id    | Integer | To only return a specific accountable person's notes    |
| debtor\_code               | Integer | To only return a given debtor code's notes              |
| year                       | Integer | To filter on a specific year                            |
| include\_deleted           | Boolean | Whether to include notes that have been deleted already |
| include\_promise\_to\_pays | Boolean | Whether to include promise-to-pay data in the response  |

#### Response Examples

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

```json
[
    {
        "note_id": "6",
        "accountable_person_id": "40",
        "accountable_person": "Mr James, John",
        "debtor_code": "1001",
        "debtor_reference": "James",
        "date": "2024-03-03",
        "note_type_id": "2",
        "note_type": "Promise to Pay",
        "communication_type_id": "2",
        "communication_type": "E-mail",
        "note": "Payment arrangement of R1000 to be paid off on outstanding school fees",
        "status": "Created"
    },
    {
        "note_id": "7",
        "accountable_person_id": "3",
        "accountable_person": "Mr Webster, Nic",
        "debtor_code": "1002",
        "debtor_reference": "Webster",
        "date": "2024-04-15",
        "note_type_id": "3",
        "note_type": "Internal",
        "communication_type_id": "7",
        "communication_type": "Internal",
        "note": "Mr Webster asked to be phoned back tomorrow at 2pm",
        "status": "Created"
    }
]
```

{% endtab %}

{% tab title="200 Including Promise to Pays" %}

```json
[
    {
        "note_id": "6",
        "accountable_person_id": "40",
        "accountable_person": "Mr James, John",
        "debtor_code": "1001",
        "debtor_reference": "James",
        "date": "2024-03-03",
        "note_type_id": "2",
        "note_type": "Promise to Pay",
        "communication_type_id": "2",
        "communication_type": "E-mail",
        "note": "Payment arrangement of R1000 to be paid off on outstanding school fees",
        "status": "Created",
        "promise_to_pays": [
            {
                "promise_to_pay_id": "8",
                "date_promised": "2024-03-31",
                "amount_promised": "1000.00",
                "amount_paid": "1000.00",
                "promise_completed": "Yes"
            },
            {
                "promise_to_pay_id": "10",
                "date_promised": "2024-04-30",
                "amount_promised": "1000.00",
                "amount_paid": "750.00",
                "promise_completed": "Partial"
            },
            {
                "promise_to_pay_id": "12",
                "date_promised": "2020-05-31",
                "amount_promised": "1000.00",
                "amount_paid": "",
                "promise_completed": "No"
            }
        ]
    }
]
```

{% endtab %}

{% tab title="204 No Content" %}

```json
```

{% endtab %}

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

```json
{
    "error": "Not Found",
    "error_description": "The note does not exist"
}
```

{% 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 Admin+ API for this client before making this request"
}
```

{% endtab %}
{% endtabs %}

## Code Samples

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

```php
<?php

const BASE_URL = 'https://integrate.d6plus.co.za/api/v1/finplus/debtmanagement/debtornotes/notes';
const SCHOOL_LOGIN_ID = '1000';
const PARAMS = [
    'note_id' => 133,
    'debtor_code' => 1270,
    'accountable_person_id' => 380,
    'note_type_id' => 2,
    'year' => 2024,
    'include_deleted' => 1,
    'include_promise_to_pays' => 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/finplus/debtmanagement/debtornotes/notes/1000?note_id=133&debtor_code=1270&accountable_person_id=380&note_type_id=2&year=2024&include_deleted=1&include_promise_to_pays=1' \
--header 'HTTP-X-USERNAME: your_username' \
--header 'HTTP-X-PASSWORD: your_password'
```

{% endtab %}
{% endtabs %}


# Create Note

## Create a new debtor note

<mark style="color:yellow;">`POST`</mark> `https://integrate.d6plus.co.za/api/v1/finplus/debtmanagement/debtornotes/notes/{school_login_id}`

Use this endpoint to create a new debtor note for the specified school.&#x20;

The note must be linked to an accountable person and requires an `accountable_person_id`. The accountable person id can be retrieved using either the [Get School Debtors](/reference/finance+/debt-management/get-school-debtors) or [Get Learner Parent Info](/reference/finance+/debt-management/get-learner-parent-info) calls.

The `date` of the note is expected in a "yyyy-mm-dd" format and may not be earlier than the start of last year or later than the end of next year.

The `note_type_id` is also required and can be found using the [Get Note Type(s)](/reference/finance+/debt-management/debtor-notes/get-note-type-s) call. The `communication_type_id`, which can be found using the [Get Communication Type(s)](/reference/finance+/debt-management/debtor-notes/get-communication-type-s) call, is required for all types of note types except for `Internal` notes.

The actual text of the note should provided using the `note` field.

If you are creating a "Promise to Pay" note (note\_type\_id: 2), the payment arrangement data should  be included in the request body under the `promise_to_pays` array (see below for more information).

A promise-to-pay requires a `date_promised` (between the start of this year and the end of next year) and an `amount_promised` (without a currency symbol i.e. "100.00"). **Important:** The `amount_paid` value and the `promise_completed` flag may only be set by the school.

#### Path Parameters

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

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

#### Request Body

<table><thead><tr><th width="261">Name</th><th width="98">Type</th><th>Description</th></tr></thead><tbody><tr><td>accountable_person_id<mark style="color:red;">*</mark></td><td>Integer</td><td>The id of the accountable person who the note belongs to.</td></tr><tr><td>date<mark style="color:red;">*</mark></td><td>String</td><td>The date of the note in "yyyy-mm-dd" format.</td></tr><tr><td>note_type_id<mark style="color:red;">*</mark></td><td>Integer</td><td>The id of the note type.</td></tr><tr><td>communication_type_id</td><td>Integer</td><td>The id of the communication type (not required for internal notes).</td></tr><tr><td>note</td><td>String</td><td>The note text</td></tr><tr><td>promise_to_pays</td><td>Array</td><td>An array of payment arrangement data for promise-to-pay notes</td></tr></tbody></table>

#### Request Examples

{% tabs %}
{% tab title="Promise-to-Pay Note" %}

```json
{
    "accountable_person_id": "40",
    "date": "2024-03-03",
    "note_type_id": "2",
    "communication_type_id": "2",
    "note": "Payment arrangement of R1000 to be paid off on outstanding school fees",
    "promise_to_pays": [
        {
            "date_promised": "2024-03-31",
            "amount_promised": "1000.00"
        },
        {
            "date_promised": "2024-04-30",
            "amount_promised": "1000.00"
        },
        {
            "date_promised": "2020-05-31",
            "amount_promised": "1000.00"
        }
    ]
}
```

{% endtab %}

{% tab title="Internal Note" %}

```json
{
    "accountable_person_id": "3",
    "date": "2024-04-15",
    "note_type_id": "3",
    "note": "Mr Webster asked to be phoned back tomorrow at 2pm",
    "status": "Created"
}
```

{% endtab %}
{% endtabs %}

#### Response Examples

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

```json
{
    "note_id": "6"
}
```

{% endtab %}

{% tab title="200 Including Promise to Pays" %}

```json
{
    "note_id": "7",
    "promise_to_pays": [
        {
            "promise_to_pay_id": "11",
            "date_promised": "2024-03-31",
            "amount_promised": "1000.00"
        },
        {
            "promise_to_pay_id": "12",
            "date_promised": "2024-04-30",
            "amount_promised": "1000.00"
        },
        {
            "promise_to_pay_id": "13",
            "date_promised": "2020-05-31",
            "amount_promised": "1000.00"
        }
    ]
}
```

{% endtab %}

{% tab title="204 No Content" %}

```json
```

{% endtab %}

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

```json
{
    "error": "Not Found",
    "error_description": "The note does not exist"
}
```

{% 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 Admin+ API for this client before making this request"
}
```

{% endtab %}
{% endtabs %}

## Code Samples

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

```php
<?php

const BASE_URL = 'https://integrate.d6plus.co.za/api/v1/finplus/debtmanagement/debtornotes/notes';
const SCHOOL_LOGIN_ID = '1000';
const PARAMS = [
    'accountable_person_id' => 40,
    'date' => '2024-03-03',
    'note_type_id' => 2,
    'communication_type_id' => 2,
    'note' => 'Payment arrangement of R1000 to be paid off on outstanding school fees',
    'promise_to_pays' => [
        [
            'date_promised' => '2024-03-31',
            'amount_promised' => '1000.00'
        ]
    ]
];
const API_USERNAME = getenv('API_USERNAME'); // Assuming you have these environment variables set
const API_PASSWORD = getenv('API_PASSWORD');

$curl = curl_init();

$options = [
    CURLOPT_URL => BASE_URL . '/' . SCHOOL_LOGIN_ID,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_SSL_VERIFYPEER => true,
    CURLOPT_CUSTOMREQUEST => 'POST',
    CURLOPT_POSTFIELDS => json_encode(PARAMS),
    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/finplus/debtmanagement/debtornotes/notes/1000' \
--header 'HTTP-X-USERNAME: your_username' \
--header 'HTTP-X-PASSWORD: your_password' \
--header 'Content-Type: application/json' \
--data '{
    "accountable_person_id": "40",
    "date": "2024-03-03",
    "note_type_id": "2",
    "communication_type_id": "2",
    "note": "Payment arrangement of R1000 to be paid off on outstanding school fees",
    "promise_to_pays": [
        {
            "date_promised": "2024-03-31",
            "amount_promised": "1000.00"
        }
    ]
}'
```

{% endtab %}
{% endtabs %}


# Update Note

## Update an existing debtor note

<mark style="color:purple;">`PATCH`</mark> `https://integrate.d6plus.co.za/api/v1/finplus/debtmanagement/debtornotes/notes/{school_login_id}`

Use this endpoint to update an existing debtor note for the specified school.&#x20;

The `note_id` is required and can be found using the [Get Note(s)](/reference/finance+/debt-management/debtor-notes/get-note-s) call.

If you need to update the payment arrangements attached to a promise-to-pay note, you must include the updated data in the `promise_to_pays` array (see below for more information). To update an existing promise-to-pay's data, the `promise_to_pay_id` needs to be included. This can be found either under the [Get Note(s)](/reference/finance+/debt-management/debtor-notes/get-note-s) call or the [Get Promise To Pay(s)](/reference/finance+/debt-management/debtor-notes/get-promise-to-pay-s). If a `promise_to_pay_id` is not included, a new promise-to-pay will be created. The API will not allow a promise-to-pay to be added to the note if the `date_promised` and `amount_promised` matches an existing record.

To restore a deleted note, provide the `note_id` and set the `status` to "Created".

To see more information about the individual fields, please refer to the [Create Note](/reference/finance+/debt-management/debtor-notes/create-note) page.

#### Path Parameters

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

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

#### Request Body

<table><thead><tr><th width="261">Name</th><th width="98">Type</th><th>Description</th></tr></thead><tbody><tr><td>note_id<mark style="color:red;">*</mark></td><td>Integer</td><td>The id of the debtor note</td></tr><tr><td>accountable_person_id</td><td>Integer</td><td>The id of the accountable person who the note belongs to.</td></tr><tr><td>date</td><td>String</td><td>The date of the note in "yyyy-mm-dd" format.</td></tr><tr><td>note_type_id</td><td>Integer</td><td>The id of the note type.</td></tr><tr><td>communication_type_id</td><td>Integer</td><td>The id of the communication type (not required for internal notes).</td></tr><tr><td>note</td><td>String</td><td>The note text</td></tr><tr><td>status</td><td>String</td><td>The status of the note (either "Created" or "Deleted")</td></tr><tr><td>promise_to_pays</td><td>Array</td><td>An array of payment arrangement data for promise-to-pay notes</td></tr></tbody></table>

#### Request Examples

{% tabs %}
{% tab title="Update a note" %}

```json
{
    "note_id": "7",
    "date": "2024-04-16",
    "note": "Mr Webster asked to be phoned back tomorrow at 10am"
}
```

{% endtab %}

{% tab title="Update / Add Promise-to-Pay" %}

```json
{
    "note_id": "6",
    "promise_to_pays": [
        {
            // Updating an existing promise to pay
            "promise_to_pay_id": "12",
            "date_promised": "2020-05-31",
            "amount_promised": "1500.00"
        },
        {
            // Create a new promise to pay
            "date_promised": "2020-06-30",
            "amount_promised": "500.00"
        }
    ]
}
```

{% endtab %}

{% tab title="Restore a deleted note" %}

```json
{
    "note_id": "6",
    "status": "Created"
}
```

{% endtab %}
{% endtabs %}

#### Response Examples

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

```json
{
    "note_id": "7",
    "accountable_person_id": "3",
    "accountable_person": "Mr Webster, Nic",
    "debtor_code": "1002",
    "debtor_reference": "Webster",
    "date": "2024-04-15",
    "note_type_id": "3",
    "note_type": "Internal",
    "communication_type_id": "7",
    "communication_type": "Internal",
    "note": "Mr Webster asked to be phoned back tomorrow at 10am",
    "status": "Created"
}
```

{% endtab %}

{% tab title="200 Including Promise to Pays" %}

```json
{
    "note_id": "6",
    "accountable_person_id": "40",
    "accountable_person": "Mr James, John",
    "debtor_code": "1001",
    "debtor_reference": "James",
    "date": "2024-03-03",
    "note_type_id": "2",
    "note_type": "Promise to Pay",
    "communication_type_id": "2",
    "communication_type": "E-mail",
    "note": "Payment arrangement of R1000 to be paid off on outstanding school fees",
    "status": "Created",
    "promise_to_pays": [
        {
            "promise_to_pay_id": "8",
            "date_promised": "2024-03-31",
            "amount_promised": "1000.00",
            "amount_paid": "1000.00",
            "promise_completed": "Yes"
        },
        {
            "promise_to_pay_id": "10",
            "date_promised": "2024-04-30",
            "amount_promised": "1000.00",
            "amount_paid": "750.00",
            "promise_completed": "Partial"
        },
        {
            "promise_to_pay_id": "12",
            "date_promised": "2020-05-31",
            "amount_promised": "1500.00",
            "amount_paid": "",
            "promise_completed": "No"
        },
        {
            "promise_to_pay_id": "13",
            "date_promised": "2020-06-30",
            "amount_promised": "500.00"
            "amount_paid": "",
            "promise_completed": "No"
        }
    ]
}
```

{% endtab %}

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

```json
{
    "error": "Not Found",
    "error_description": "The note does not exist"
}
```

{% 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 Admin+ API for this client before making this request"
}
```

{% endtab %}
{% endtabs %}

## Code Samples

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

```php
<?php

const BASE_URL = 'https://integrate.d6plus.co.za/api/v1/finplus/debtmanagement/debtornotes/notes';
const SCHOOL_LOGIN_ID = '1000';
const PARAMS = [
    'note_id' => 7,
    'date' => '2024-04-16',
    'note' => 'Mr Webster asked to be phoned back tomorrow at 10am'
];
const API_USERNAME = getenv('API_USERNAME'); // Assuming you have these environment variables set
const API_PASSWORD = getenv('API_PASSWORD');

$curl = curl_init();

$options = [
    CURLOPT_URL => BASE_URL . '/' . SCHOOL_LOGIN_ID,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_SSL_VERIFYPEER => true,
    CURLOPT_CUSTOMREQUEST => 'PATCH',
    CURLOPT_POSTFIELDS => json_encode(PARAMS),
    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 --request PATCH 'https://integrate.d6plus.co.za/api/v1/finplus/debtmanagement/debtornotes/notes/1000' \
--header 'HTTP-X-USERNAME: your_username' \
--header 'HTTP-X-PASSWORD: your_password' \
--header 'Content-Type: application/json' \
--data '{
    "accountable_person_id": "40",
    "date": "2024-03-03",
    "note_type_id": "2",
    "communication_type_id": "2",
    "note": "Payment arrangement of R1000 to be paid off on outstanding school fees",
    "promise_to_pays": [
        {
            "date_promised": "2024-03-31",
            "amount_promised": "1000.00"
        }
    ]
}'
```

{% endtab %}
{% endtabs %}


# Delete Note

## Delete a debtor note

<mark style="color:red;">`DELETE`</mark> `https://integrate.d6plus.co.za/api/v1/finplus/debtmanagement/debtornotes/notes/{school_login_id}`

Use this endpoint to delete a debtor note for the specified school.&#x20;

The `note_id` is required and can be found using the [Get Note(s)](/reference/finance+/debt-management/debtor-notes/get-note-s) call.

If you need to restore a deleted debtor note, see [Update Note](/reference/finance+/debt-management/debtor-notes/update-note).

#### Path Parameters

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

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

#### Query Parameters

<table><thead><tr><th width="261">Name</th><th width="98">Type</th><th>Description</th></tr></thead><tbody><tr><td>note_id<mark style="color:red;">*</mark></td><td>Integer</td><td>The id of the debtor note to delete</td></tr></tbody></table>

#### Response Examples

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

```json
{
    "status": "Deleted"
}
```

{% endtab %}

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

```json
{
    "error": "Not Found",
    "error_description": "The note does not exist or has already been deleted."
}
```

{% 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 Admin+ API for this client before making this request"
}
```

{% endtab %}
{% endtabs %}

## Code Samples

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

```php
<?php

const BASE_URL = 'https://integrate.d6plus.co.za/api/v1/finplus/debtmanagement/debtornotes/notes';
const SCHOOL_LOGIN_ID = '1000';
const PARAMS = [
    'note_id' => 7
    ];
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 => 'DELETE',
    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 --request DELETE 'https://integrate.d6plus.co.za/api/v1/finplus/debtmanagement/debtornotes/notes/1000?note_id=7' \
--header 'HTTP-X-USERNAME: your_username' \
--header 'HTTP-X-PASSWORD: your_password'
```

{% endtab %}
{% endtabs %}


# Get Promise To Pay(s)

## Get one or more Promise To Pay records

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

Use this endpoint to fetch one or more promise-to-pay records for the specified school.

It is possible to retrieve a single promise to pay record by providing the optional `promise_to_pay_id` query parameter.

To find promise-to-pay records belonging to a specific person, us the `debtor_code` or `accountable_person_id` query parameters.

Additionally, it's possible to filter on the status of the promise to pay record by using the `promise_completed` query parameter. The possible values are "Yes", "No" and "Partial".

It is also possible to return only a specific year's promise to pay records. Use the `year_promised` query parameter to do so.

To include the debtor note the promise to pay belongs to, directly in the response, providing the additional `include_debtor_note` query 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 |

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

#### Query Parameters

| Name                    | Type    | Description                                                    |
| ----------------------- | ------- | -------------------------------------------------------------- |
| promise\_to\_pay\_id    | Integer | The ID of a promise to pay record                              |
| accountable\_person\_id | Integer | To only return a specific accountable person's promise to pays |
| debtor\_code            | Integer | To only return a specific debtor code's promise to pays        |
| promise\_completed      | String  | To filter on the status of the promise to pay                  |
| year\_promised          | Integer | To filter on a specific year                                   |
| include\_debtor\_note   | Boolean | Whether to include debtor note data in the response            |

#### Response Examples

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

```json
[
    {
        "promise_to_pay_id": "8",
        "accountable_person_id": "40",
        "accountable_person": "Mr James, John",
        "debtor_code": "1001",
        "debtor_reference": "James",
        "date_promised": "2024-03-31",
        "amount_promised": "1000.00",
        "amount_paid": "1000.00",
        "promise_completed": "Yes"
    },
    {
        "promise_to_pay_id": "10",
        "accountable_person_id": "40",
        "accountable_person": "Mr James, John",
        "debtor_code": "1001",
        "debtor_reference": "James",
        "date_promised": "2024-04-30",
        "amount_promised": "1000.00",
        "amount_paid": "750.00",
        "promise_completed": "Partial"
    },
    {
        "promise_to_pay_id": "12",
        "accountable_person_id": "40",
        "accountable_person": "Mr James, John",
        "debtor_code": "1001",
        "debtor_reference": "James",
        "date_promised": "2020-05-31",
        "amount_promised": "1000.00",
        "amount_paid": "",
        "promise_completed": "No"
    }
]
```

{% endtab %}

{% tab title="200 Including Debtor Notes" %}

```json
[
    {
        "promise_to_pay_id": "8",
        "accountable_person_id": "40",
        "accountable_person": "Mr James, John",
        "debtor_code": "1001",
        "debtor_reference": "James",
        "date_promised": "2024-03-31",
        "amount_promised": "1000.00",
        "amount_paid": "1000.00",
        "promise_completed": "Yes",
        "debtor_note": {
            "note_id": "6",
            "date": "2024-03-03",
            "note_type_id": "2",
            "note_type": "Promise to Pay",
            "communication_type_id": "2",
            "communication_type": "E-mail",
            "note": "Payment arrangement of R1000 to be paid off on outstanding school fees"
        }
    },
    {
        "promise_to_pay_id": "10",
        "accountable_person_id": "40",
        "accountable_person": "Mr James, John",
        "debtor_code": "1001",
        "debtor_reference": "James",
        "date_promised": "2024-04-30",
        "amount_promised": "1000.00",
        "amount_paid": "750.00",
        "promise_completed": "Partial",
        "debtor_note": {
            "note_id": "6",
            "date": "2024-03-03",
            "note_type_id": "2",
            "note_type": "Promise to Pay",
            "communication_type_id": "2",
            "communication_type": "E-mail",
            "note": "Payment arrangement of R1000 to be paid off on outstanding school fees"
        }
    },
    {
        "promise_to_pay_id": "12",
        "accountable_person_id": "40",
        "accountable_person": "Mr James, John",
        "debtor_code": "1001",
        "debtor_reference": "James",
        "date_promised": "2020-05-31",
        "amount_promised": "1000.00",
        "amount_paid": "",
        "promise_completed": "No",
        "debtor_note": {
            "note_id": "6",
            "date": "2024-03-03",
            "note_type_id": "2",
            "note_type": "Promise to Pay",
            "communication_type_id": "2",
            "communication_type": "E-mail",
            "note": "Payment arrangement of R1000 to be paid off on outstanding school fees"
        }
    }
]
```

{% endtab %}

{% tab title="204 No Content" %}

```json
```

{% endtab %}

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

```json
{
    "error": "Not found",
    "error_description": "The promise_to_pay_id does not exist"
}
```

{% 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 Admin+ API for this client before making this request"
}
```

{% endtab %}
{% endtabs %}

## Code Samples

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

```php
<?php

const BASE_URL = 'https://integrate.d6plus.co.za/api/v1/finplus/debtmanagement/promisetopays/notes';
const SCHOOL_LOGIN_ID = '1000';
const PARAMS = [
    'promise_to_pay_id' => 12,
    'accountable_person_id' => 40,
    'debtor_code' => 1001,
    'promise_completed' => 'Partial',
    'year_promised' => 2024,
    'include_debtor_note' => 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/finplus/debtmanagement/debtornotes/promisetopays/1000?```javascript
promise_to_pay_id=291&accountable_person_id=380&debtor_code=1270&promise_completed=Partial&year_promised=2024&include_debtor_note=1
```' \
--header 'HTTP-X-USERNAME: your_username' \
--header 'HTTP-X-PASSWORD: your_password'
````

{% endtab %}
{% endtabs %}


# Delete Promise To Pay

## Delete a Promise To Pay record

<mark style="color:red;">`DELETE`</mark> `https://integrate.d6plus.co.za/api/v1/finplus/debtmanagement/debtornotes/promisetopays/{school_login_id}`

Use this endpoint to delete a promise-to-pay record for the specified school.&#x20;

The `promise_to_pay_id` is required and can be found using the [Get Promise To Pay(s) ](/reference/finance+/debt-management/debtor-notes/get-promise-to-pay-s)or [Get Note(s)](/reference/finance+/debt-management/debtor-notes/get-note-s) call.

#### Path Parameters

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

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

#### Query Parameters

<table><thead><tr><th width="261">Name</th><th width="98">Type</th><th>Description</th></tr></thead><tbody><tr><td>promise_to_pay_id<mark style="color:red;">*</mark></td><td>Integer</td><td>The id of the promise-to-pay to delete</td></tr></tbody></table>

#### Response Examples

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

```json
{
    "status": "Deleted"
}
```

{% endtab %}

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

```json
{
    "error": "Not found",
    "error_description": "The Promise To Pay does not exist"
}
```

{% 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 Admin+ API for this client before making this request"
}
```

{% endtab %}
{% endtabs %}

## Code Samples

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

```php
<?php

const BASE_URL = 'https://integrate.d6plus.co.za/api/v1/finplus/debtmanagement/debtornotes/promisetopays';
const SCHOOL_LOGIN_ID = '1000';
const PARAMS = [
    'promise_to_pay_id' => 7
    ];
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 => 'DELETE',
    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 --request DELETE 'https://integrate.d6plus.co.za/api/v1/finplus/debtmanagement/debtornotes/promisetopays/1000?promise_to_pay_id=7' \
--header 'HTTP-X-USERNAME: your_username' \
--header 'HTTP-X-PASSWORD: your_password'
```

{% endtab %}
{% endtabs %}


# Age Analysis Report

## Get a school's age analysis report

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

Use this endpoint to generate an age analysis report for the specified school.

By default, only active accounts (current learners or accounts with an outstanding balance) will be returned. You can use the `all_accounts` query parameter to generate the report for all accounts (includes left learners and 0 balance accounts).

The report, by default, will be grouped by family and parent. Use the `per_learner` or `per_category` query parameter to group the data accordingly. If the `per_learner` and the `per_category` parameters are used in combination, the results will be grouped per learner, per category.

Additionally it is possible to filter on a specific `debtor_code` , `learner_id` , `accountable_person_id` and/or `category_id`.

#### Path Parameters

<table><thead><tr><th>Name</th><th width="152">Type</th><th>Description</th></tr></thead><tbody><tr><td>school_login_id<mark style="color:red;">*</mark></td><td>Integer</td><td>The login ID of the school to retrieve data from</td></tr></tbody></table>

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

#### Query Parameters

<table><thead><tr><th>Name</th><th width="151">Type</th><th>Description</th></tr></thead><tbody><tr><td>all_accounts</td><td>Boolean</td><td>Whether to include all accounts</td></tr><tr><td>per_learner</td><td>Boolean</td><td>Whether to group the data per learner</td></tr><tr><td>per_category</td><td>Boolean</td><td>Whether to group the data per category (can be used in conjunction with per_learner)</td></tr><tr><td>debtor_code</td><td>Integer</td><td>To filter on a specific Debtor Code</td></tr><tr><td>learner_id</td><td>Integer</td><td>To filter on a specific Learner ID</td></tr><tr><td>accountable_person_id</td><td>Integer</td><td>To filter on a specific Accountable Person ID</td></tr><tr><td>category_id</td><td>Integer</td><td>To filter on a specific Category ID</td></tr></tbody></table>

#### Response Examples

{% tabs %}
{% tab title="200: Per family and parent" %}

```json
[
    {
        "debtor_code": "1001",
        "accountable_person_id": "40",
        "date": "2024-04-10",
        "balance_current": "3500.00",
        "balance_30days": "3500.00",
        "balance_60days": "3500.00",
        "balance_90days": "3500.00",
        "balance_120days": "850.00",
        "balance_150days": "5850.00",
        "balance_180days": "4500.00",
        "balance_total": "25200.00"
    },
    {
        "debtor_code": "1002",
        "accountable_person_id": "3",
        "date": "2024-04-10",
        "balance_current": "3500.00",
        "balance_30days": "3500.00",
        "balance_60days": "3500.00",
        "balance_90days": "3500.00",
        "balance_120days": "850.00",
        "balance_150days": "5850.00",
        "balance_180days": "20000.00",
        "balance_total": "40700.00"
    }
]
```

{% endtab %}

{% tab title="200: Per Learner" %}

```json
[
    {
        "debtor_code": "1001",
        "accountable_person_id": "40",
        "date": "2024-04-10",
        "balance_current": "3500.00",
        "balance_30days": "3500.00",
        "balance_60days": "3500.00",
        "balance_90days": "3500.00",
        "balance_120days": "850.00",
        "balance_150days": "5850.00",
        "balance_180days": "4500.00",
        "balance_total": "25200.00",
        "learners": [
            {
                "learner_id": "1",
                "learner_first_name": "Jordan",
                "learner_last_name": "Smith",
                "balance_current": "1750.00",
                "balance_30days": "1750.00",
                "balance_60days": "1750.00",
                "balance_90days": "1750.00",
                "balance_120days": "0.00",
                "balance_150days": "850.00",
                "balance_180days": "4500.00",
                "balance_total": "12350.00"
            },
            {
                "learner_id": "2",
                "learner_first_name": "Samantha",
                "learner_last_name": "Smith",
                "balance_current": "1750.00",
                "balance_30days": "1750.00",
                "balance_60days": "1750.00",
                "balance_90days": "1750.00",
                "balance_120days": "850.00",
                "balance_150days": "5000.00",
                "balance_180days": "0.00",
                "balance_total": "12850.00"
            }
        ]
    },
    {
        "family_code": "1002",
        "accountable_person_id": "3",
        "date": "2024-04-10",
        "balance_current": "3500.00",
        "balance_30days": "3500.00",
        "balance_60days": "3500.00",
        "balance_90days": "3500.00",
        "balance_120days": "850.00",
        "balance_150days": "5850.00",
        "balance_180days": "20000.00",
        "balance_total": "40700.00",
        "learners": [
            {
                "learner_id": "3",
                "learner_first_name": "Nick",
                "learner_last_name": "Webster",
                "balance_current": "3500.00",
                "balance_30days": "3500.00",
                "balance_60days": "3500.00",
                "balance_90days": "3500.00",
                "balance_120days": "850.00",
                "balance_150days": "5850.00",
                "balance_180days": "20000.00",
                "balance_total": "40700.00",
            }
        ]
    }
]
```

{% endtab %}

{% tab title="200: Per Category" %}

<pre class="language-json"><code class="lang-json">[
    {
        "debtor_code": "1001",
        "accountable_person_id": "40",
        "date": "2024-04-10",
        "balance_current": "3500.00",
        "balance_30days": "3500.00",
        "balance_60days": "3500.00",
        "balance_90days": "3500.00",
        "balance_120days": "850.00",
        "balance_150days": "5850.00",
        "balance_180days": "4500.00",
        "balance_total": "25200.00",
        "categories": [
<strong>            {
</strong>                "category_id": "1",
                "category_name": "School Fees",
                "balance_current": "2750.00",
                "balance_30days": "2750.00",
                "balance_60days": "2750.00",
                "balance_90days": "2750.00",
                "balance_120days": "0.00",
                "balance_150days": "4500.00",
                "balance_180days": "4500.00",
                "balance_total": "20000.00"
            },
            {
                "category_id": "6",
                "category_name": "Hostel Fees",
                "balance_current": "500.00",
                "balance_30days": "500.00",
                "balance_60days": "500.00",
                "balance_90days": "500.00",
                "balance_120days": "500.00",
                "balance_150days": "500.00",
                "balance_180days": "0.00",
                "balance_total": "3000.00"
            },
            {
                "category_id": "8",
                "category_name": "Sport",
                "balance_current": "250.00",
                "balance_30days": "250.00",
                "balance_60days": "250.00",
                "balance_90days": "250.00",
                "balance_120days": "250.00",
                "balance_150days": "850.00",
                "balance_180days": "0.00",
                "balance_total": "2100.00"
            }
        ]
    },
    {
        "family_code": "1002",
        "accountable_person_id": "3",
        "date": "2024-04-10",
        "balance_current": "3500.00",
        "balance_30days": "3500.00",
        "balance_60days": "3500.00",
        "balance_90days": "3500.00",
        "balance_120days": "850.00",
        "balance_150days": "5850.00",
        "balance_180days": "20000.00",
        "balance_total": "40700.00",
        "categories": [
            {
                "category_id": "1",
                "category_name": "School Fees",
                "balance_current": "3500.00",
                "balance_30days": "3500.00",
                "balance_60days": "3500.00",
                "balance_90days": "3500.00",
                "balance_120days": "850.00",
                "balance_150days": "5850.00",
                "balance_180days": "20000.00",
                "balance_total": "40700.00",
            }
        ]
    }
]
</code></pre>

{% endtab %}

{% tab title="200: Per learner, per category" %}

```json
[
    {
        "debtor_code": "1001",
        "accountable_person_id": "40",
        "date": "2024-04-10",
        "balance_current": "3500.00",
        "balance_30days": "3500.00",
        "balance_60days": "3500.00",
        "balance_90days": "3500.00",
        "balance_120days": "850.00",
        "balance_150days": "5850.00",
        "balance_180days": "4500.00",
        "balance_total": "25200.00",
        "learners": [
            {
                "learner_id": "1",
                "learner_first_name": "Jordan",
                "learner_last_name": "Smith",
                "balance_current": "1750.00",
                "balance_30days": "1750.00",
                "balance_60days": "1750.00",
                "balance_90days": "1750.00",
                "balance_120days": "0.00",
                "balance_150days": "850.00",
                "balance_180days": "4500.00",
                "balance_total": "12350.00",
                "categories": [
                    {
                        "category_id": "1",
                        "category_name": "School Fees",
                        "balance_current": "1000.00",
                        "balance_30days": "1000.00",
                        "balance_60days": "1000.00",
                        "balance_90days": "1000.00",
                        "balance_120days": "0.00",
                        "balance_150days": "0.00",
                        "balance_180days": "4500.00",
                        "balance_total": "8500.00"
                    },
                    {
                        "category_id": "6",
                        "category_name": "Hostel Fees",
                        "balance_current": "500.00",
                        "balance_30days": "500.00",
                        "balance_60days": "500.00",
                        "balance_90days": "500.00",
                        "balance_120days": "0.00",
                        "balance_150days": "500.00",
                        "balance_180days": "0.00",
                        "balance_total": "2500.00"
                    },
                    {
                        "category_id": "8",
                        "category_name": "Sport",
                        "balance_current": "250.00",
                        "balance_30days": "250.00",
                        "balance_60days": "250.00",
                        "balance_90days": "250.00",
                        "balance_120days": "0.00",
                        "balance_150days": "350.00",
                        "balance_180days": "0.00",
                        "balance_total": "1350.00"
                    }
                ]
            },
            {
                "learner_id": "2",
                "learner_first_name": "Samantha",
                "learner_last_name": "Smith",
                "balance_current": "1750.00",
                "balance_30days": "1750.00",
                "balance_60days": "1750.00",
                "balance_90days": "1750.00",
                "balance_120days": "850.00",
                "balance_150days": "5000.00",
                "balance_180days": "0.00",
                "balance_total": "12850.00",
                "categories": [
                    {
                        "category_id": "1",
                        "category_name": "School Fees",
                        "balance_current": "1000.00",
                        "balance_30days": "1000.00",
                        "balance_60days": "1000.00",
                        "balance_90days": "1000.00",
                        "balance_120days": "0.00",
                        "balance_150days": "4500.00",
                        "balance_180days": "0.00",
                        "balance_total": "8500.00"
                    },
                    {
                        "category_id": "6",
                        "category_name": "Hostel Fees",
                        "balance_current": "500.00",
                        "balance_30days": "500.00",
                        "balance_60days": "500.00",
                        "balance_90days": "500.00",
                        "balance_120days": "500.00",
                        "balance_150days": "500.00",
                        "balance_180days": "0.00",
                        "balance_total": "3000.00"
                    },
                    {
                        "category_id": "8",
                        "category_name": "Sport",
                        "balance_current": "250.00",
                        "balance_30days": "250.00",
                        "balance_60days": "250.00",
                        "balance_90days": "250.00",
                        "balance_120days": "350.00",
                        "balance_150days": "0.00",
                        "balance_180days": "0.00",
                        "balance_total": "1350.00"
                    }
                ]
            }
        ]
    },
    {
        "family_code": "1002",
        "accountable_person_id": "3",
        "date": "2024-04-10",
        "balance_current": "3500.00",
        "balance_30days": "3500.00",
        "balance_60days": "3500.00",
        "balance_90days": "3500.00",
        "balance_120days": "850.00",
        "balance_150days": "5850.00",
        "balance_180days": "20000.00",
        "balance_total": "40700.00",
        "learners": [
            {
                "learner_id": "3",
                "learner_first_name": "Nick",
                "learner_last_name": "Webster",
                "balance_current": "3500.00",
                "balance_30days": "3500.00",
                "balance_60days": "3500.00",
                "balance_90days": "3500.00",
                "balance_120days": "850.00",
                "balance_150days": "5850.00",
                "balance_180days": "20000.00",
                "balance_total": "40700.00",
                "categories": [
                    {
                        "category_id": "1",
                        "category_name": "School Fees",
                        "balance_current": "3500.00",
                        "balance_30days": "3500.00",
                        "balance_60days": "3500.00",
                        "balance_90days": "3500.00",
                        "balance_120days": "850.00",
                        "balance_150days": "5850.00",
                        "balance_180days": "20000.00",
                        "balance_total": "40700.00",
                    }
                ]
            }
        ]
    }
]
```

{% endtab %}

{% tab title="204: No Content" %}

```json
```

{% 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 Finance+ API for this client before making this request"
}
```

{% endtab %}
{% endtabs %}

## Code Samples

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

```php
<?php

const BASE_URL = 'https://integrate.d6plus.co.za/api/v1/finplus/debtmanagement/ageanalysis';
const SCHOOL_LOGIN_ID = '1000';
const PARAMS = [
    'per_learner' => 1, 
    'all_accounts' => 1,
    'debtor_code' => 1001,
    'learner_id' => 2,
    'accountable_person_id' => 3
    ];
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/finplus/debtmanagement/ageanalysis/1000?per_learner=1&all_accounts=1&debtor_code=1001&learner_id=2&accountable_person_id=3' \
--header 'HTTP-X-USERNAME: your_username' \
--header 'HTTP-X-PASSWORD: your_password'
```

{% endtab %}
{% endtabs %}


# Financial Transactions Report

## Retrieve debtor financial transactions

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

This report provides a comprehensive view of transactions, offering the ability to group data by family/parent while also allowing for further breakdowns per learner using the `per_learner` parameter. When `per_learner` is specified, the family/parent object is extended to include learner-specific transaction details. The API supports flexible filtering options, such as date ranges, category IDs, debtor codes, learners, and accountable persons, enabling precise and targeted reporting. Additionally, the `all_accounts` parameter provides control over whether to include only active accounts or a complete financial history.

#### Path Parameters

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

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

#### Query Parameters

| Name                    | Type    | Description                                                                                                               |
| ----------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------- |
| all\_accounts           | Boolean | Whether to include all accounts                                                                                           |
| per\_learner            | Boolean | Whether to include a break-down of transactions per learner                                                               |
| debtor\_code            | Integer | To filter on a specific Debtor Code                                                                                       |
| learner\_id             | Integer | To filter on a specific Learner ID                                                                                        |
| accountable\_person\_id | Integer | To filter on a specific Accountable Person ID                                                                             |
| category\_id            | Integer | To filter on a specific Category ID                                                                                       |
| start\_date             | String  | The start date for filtering transactions (format: YYYY-MM-DD)                                                            |
| end\_date               | String  | The end date for filtering transactions (format: `YYYY-MM-DD`). The `start_date` is required when specifying an end date. |

#### Response Examples

{% tabs %}
{% tab title="200: Per family and parent" %}

```json
[
    {
        "debtor_code": "1001",
        "accountable_person_id": "40",
        "transactions": [
            {
                "category_id": null,
                "category_name": null,
                "transaction_date": "2024-04-01",
                "transaction_type_id": null,
                "transaction_type_name": null,
                "transaction_reference": null,
                "transaction_description": "Opening balance",
                "part_of_base_fee": null,
                "debit_amount": "17200.00",
                "credit_amount": "0.00",
                "accumulated_balance": "17200.00"
            },
            {
                "category_id": "1",
                "category_name": "School Fees",
                "transaction_date": "2024-04-01",
                "transaction_type_id": "14",
                "transaction_type_name": "Debtor Invoice",
                "transaction_reference": "663",
                "transaction_description": "Invoice - School Fees Jordan Smith - 00002 Apr2024",
                "part_of_base_fee": "1",
                "debit_amount": "2000.00",
                "credit_amount": "0.00",
                "accumulated_balance": "19200.00"
            },
            {
                "category_id": "6",
                "category_name": "Hostel Fees",
                "transaction_date": "2024-04-01",
                "transaction_type_id": "14",
                "transaction_type_name": "Debtor Invoice",
                "transaction_reference": "872",
                "transaction_description": "Invoice - Hostel Fees Jordan Smith - 00002 Apr2024",
                "part_of_base_fee": "0",
                "debit_amount": "1000.00",
                "credit_amount": "0.00",
                "accumulated_balance": "20200.00"
            },
            {
                "category_id": "1",
                "category_name": "School Fees",
                "transaction_date": "2024-05-01",
                "transaction_type_id": "14",
                "transaction_type_name": "Debtor Invoice",
                "transaction_reference": "682",
                "transaction_description": "Invoice - School Fees Jordan Smith - 00002 May2024",
                "part_of_base_fee": "1",
                "debit_amount": "2000.00",
                "credit_amount": "0.00",
                "accumulated_balance": "22700.00"
            },
            {
                "category_id": "6",
                "category_name": "Hostel Fees",
                "transaction_date": "2024-05-01",
                "transaction_type_id": "14",
                "transaction_type_name": "Debtor Invoice",
                "transaction_reference": "891",
                "transaction_description": "Invoice - Hostel Fees Jordan Smith - 00002 May2024",
                "part_of_base_fee": "0",
                "debit_amount": "1000.00",
                "credit_amount": "0.00",
                "accumulated_balance": "23700.00"
            }
        ]
    },
    {
        "debtor_code": "1002",
        "accountable_person_id": "3",
        "transactions": [
            {
                "category_id": null,
                "category_name": null,
                "transaction_date": "2024-04-01",
                "transaction_type_id": null,
                "transaction_type_name": null,
                "transaction_reference": null,
                "transaction_description": "Opening balance",
                "part_of_base_fee": null,
                "debit_amount": "21700.00",
                "credit_amount": "0.00",
                "accumulated_balance": "21700.00"
            },
            {
                "category_id": "1",
                "category_name": "School Fees",
                "transaction_date": "2024-04-01",
                "transaction_type_id": "14",
                "transaction_type_name": "Debtor Invoice",
                "transaction_reference": "662",
                "transaction_description": "Invoice - School Fees Nic Webster - 00001 Apr2024",
                "part_of_base_fee": "1",
                "debit_amount": "2000.00",
                "credit_amount": "0.00",
                "accumulated_balance": "23700.00"
            }
        ]
    }
]
```

{% endtab %}

{% tab title="200: Per learner" %}

```json
[
    {
        "debtor_code": "1001",
        "accountable_person_id": "40",
        "learners": [
            {
                "learner_id": "1",
                "learner_first_name": "Jordan",
                "learner_last_name": "Smith",
                "transactions": [
                    {
                        "category_id": null,
                        "category_name": null,
                        "transaction_date": "2024-04-01",
                        "transaction_type_id": null,
                        "transaction_type_name": null,
                        "transaction_reference": null,
                        "transaction_description": "Opening balance",
                        "part_of_base_fee": null,
                        "debit_amount": "21700.00",
                        "credit_amount": "0.00",
                        "accumulated_balance": "21700.00"
                    },
                    {
                        "category_id": "1",
                        "category_name": "School Fees",
                        "transaction_date": "2024-04-01",
                        "transaction_type_id": "14",
                        "transaction_type_name": "Debtor Invoice",
                        "transaction_reference": "662",
                        "transaction_description": "Invoice - School Fees Jordan Smith - 00001 Apr2024",
                        "part_of_base_fee": "1",
                        "debit_amount": "2000.00",
                        "credit_amount": "0.00",
                        "accumulated_balance": "23700.00"
                    },
                    {
                        "category_id": "6",
                        "category_name": "Hostel Fees",
                        "transaction_date": "2024-04-01",
                        "transaction_type_id": "14",
                        "transaction_type_name": "Debtor Invoice",
                        "transaction_reference": "871",
                        "transaction_description": "Invoice - Hostel Fees Jordan Smith - 00001 Apr2024",
                        "part_of_base_fee": "0",
                        "debit_amount": "1000.00",
                        "credit_amount": "0.00",
                        "accumulated_balance": "24700.00"
                    },
                    {
                        "category_id": "1",
                        "category_name": "School Fees",
                        "transaction_date": "2024-05-01",
                        "transaction_type_id": "14",
                        "transaction_type_name": "Debtor Invoice",
                        "transaction_reference": "681",
                        "transaction_description": "Invoice - School Fees Jordan Smith - 00001 May2024",
                        "part_of_base_fee": "1",
                        "debit_amount": "2000.00",
                        "credit_amount": "0.00",
                        "accumulated_balance": "27200.00"
                    },
                    {
                        "category_id": "6",
                        "category_name": "Hostel Fees",
                        "transaction_date": "2024-05-01",
                        "transaction_type_id": "14",
                        "transaction_type_name": "Debtor Invoice",
                        "transaction_reference": "890",
                        "transaction_description": "Invoice - Hostel Fees Jordan Smith - 00001 May2024",
                        "part_of_base_fee": "0",
                        "debit_amount": "1000.00",
                        "credit_amount": "0.00",
                        "accumulated_balance": "28200.00"
                    }
                ]
            }
        ]
    },
    {
        "debtor_code": "1002",
        "accountable_person_id": "3",
        "learners": [
            {
                "learner_id": "3",
                "learner_first_name": "Nick",
                "learner_last_name": "Webster",
                "transactions": [
                    {
                        "category_id": null,
                        "category_name": null,
                        "transaction_date": "2024-04-01",
                        "transaction_type_id": null,
                        "transaction_type_name": null,
                        "transaction_reference": null,
                        "transaction_description": "Opening balance",
                        "part_of_base_fee": null,
                        "debit_amount": "17200.00",
                        "credit_amount": "0.00",
                        "accumulated_balance": "17200.00"
                    },
                    {
                        "category_id": "1",
                        "category_name": "School Fees",
                        "transaction_date": "2024-04-01",
                        "transaction_type_id": "14",
                        "transaction_type_name": "Debtor Invoice",
                        "transaction_reference": "663",
                        "transaction_description": "Invoice - School Fees Nick Webster - 00002 Apr2024",
                        "part_of_base_fee": "1",
                        "debit_amount": "2000.00",
                        "credit_amount": "0.00",
                        "accumulated_balance": "19200.00"
                    },
                    {
                        "category_id": "1",
                        "category_name": "School Fees",
                        "transaction_date": "2024-05-01",
                        "transaction_type_id": "14",
                        "transaction_type_name": "Debtor Invoice",
                        "transaction_reference": "682",
                        "transaction_description": "Invoice - School Fees Nick Webster - 00002 May2024",
                        "part_of_base_fee": "1",
                        "debit_amount": "2000.00",
                        "credit_amount": "0.00",
                        "accumulated_balance": "22700.00"
                    }
                ]
            }
        ]
    }
]
```

{% endtab %}

{% tab title="204: No Content" %}

```json
```

{% 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 Finance+ API for this client before making this request"
}
```

{% endtab %}
{% endtabs %}

## Code Samples

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

```php
<?php

const BASE_URL = 'https://integrate.d6plus.co.za/api/v1/finplus/debtmanagement/financialtransactions';
const SCHOOL_LOGIN_ID = '1000';
const PARAMS = [
    'per_learner' => 1, 
    'all_accounts' => 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/finplus/debtmanagement/financialtransactions/1000?per_learner=1&all_accounts=1' \
--header 'HTTP-X-USERNAME: your_username' \
--header 'HTTP-X-PASSWORD: your_password'
```

{% endtab %}
{% endtabs %}


# Get Schools

## Retrieve debtor financial transactions

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

Use this endpoint to fetch schools and their details. The inclusion of the `/{school_login_id}` is optional and if it is not included, all schools will be returned.

#### Path Parameters

<table><thead><tr><th width="247">Name</th><th width="102">Type</th><th>Description</th></tr></thead><tbody><tr><td>school_login_id<mark style="color:red;">*</mark></td><td>Integer</td><td>The login ID of the school to retrieve data from (optional)</td></tr></tbody></table>

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

#### Response Examples

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

```json
[
    {
        "school_id": "1000",
        "school_name": "d6+ Primary School",
        "school_short_name": "primary",
        "ownership_type": "Public",
        "country": "South Africa",
        "province": "Gauteng",
        "town": "Pretoria",
        "suburb": "Waterkloof Glen",
        "district": "METRO EAST",
        "district_code": "D1",
        "circuit": "Circuit 2",
        "quantile": "4",
        "emis_number": "600000001",
        "telephone_number": "0123334444",
        "lowest_grade": "Grade R",
        "highest_grade": "Grade 7",
        "admin_email_address": "info@d6.co.za",
        "debtors_email_address": "accounts@d6.co.za",
        "finance_email_address": "accounts@d6.co.za",
        "physical_address": "Spaces Building, Floor 3,/r/n210 Amarand Ave,/r/nWaterkloof Glen,/r/nPretoria,/r/n0010",
        "postal_address": "Spaces Building, Floor 3,/r/n210 Amarand Ave,/r/nWaterkloof Glen,/r/nPretoria,/r/n0010",
        "has_after_school_center": "Yes",
        "has_hostel": "No",
        "uses_debit_orders": "No",
        "uses_cashless": "Yes"
    },
    {
        "school_id": "1001",
        "school_name": "d6+ Secondary School",
        "school_short_name": "secondary",
        "ownership_type": "Public",
        "country": "South Africa",
        "province": "Western Cape",
        "town": "Stellenbosch",
        "suburb": "Techno Park",
        "district": "CAPE WINELANDS",
        "district_code": "D1",
        "circuit": "Circuit 10",
        "quantile": "5",
        "emis_number": "600000002",
        "telephone_number": "0213337654",
        "lowest_grade": "Grade 8",
        "highest_grade": "Grade 12",
        "admin_email_address": "info@d6.co.za",
        "debtors_email_address": "accounts@d6.co.za",
        "finance_email_address": "accounts@d6.co.za",
        "physical_address": "Octo Place, Block B\r\nElektron Road\r\nTechno Park\r\nStellenbosch\r\n7600",
        "postal_address": "Octo Place, Block B\r\nElektron Road\r\nTechno Park\r\nStellenbosch\r\n7600",
        "has_after_school_center": "No",
        "has_hostel": "Yes",
        "uses_debit_orders": "Yes",
        "uses_cashless": "No"
    }
]
```

{% endtab %}

{% tab title="200 Including Learners" %}

```json
[
    {
        "accountable_person_id": "40",
        "title": "Mr",
        "first_name": "John",
        "full_names": "John James",
        "last_name": "Smith",
        "debtor_code": "1001",
        "mobile_calling_code": "27",
        "mobile_number": "0821237654",
        "work_tel_number": "0124567890",
        "home_tel_number": "0123214567",
        "email_address": "jjsmith@example.com",
        "residential_address": "Moneytow Street\r\nNow Village\r\n0123\r\nSouth Africa",
        "postal_address": "Moneytow Street\r\nNow Village\r\n0123\r\nSouth Africa",
        "home_language": "English",
        "nationality": "South Africa",
        "id_number": "8104050240082",
        "passport_number": "A456732243",
        "employer": "Greenholt Group",
        "employer_address": "3 School Lane\r\nBig City\r\nSouth Africa",
        "account_closing_date": "0000-00-00",
        "account_start_date": "2023-01-01",
        "learners": [
            {
                "learner_id": "1",
                "first_name": "John",
                "last_name": "Smith",
                "gender": "M",
                "grade": "7"
            }
        ]
    },
    {
        "accountable_person_id": "3",
        "title": "Mr",
        "first_name": "Nic",
        "full_names": "Nicholas Nigel",
        "last_name": "Webster",
        "debtor_code": "1002",
        "mobile_calling_code": "27",
        "mobile_number": "0678901234",
        "work_tel_number": "",
        "home_tel_number": "",
        "email_address": "nicnwebster@example.co.za",
        "residential_address": "7th Street\r\nSmall Town\r\n0123\r\nSouth Africa",
        "postal_address": "7th Street\r\nSmall Town\r\n0123\r\nSouth Africa",
        "home_language": "English",
        "nationality": "South Africa",
        "id_number": "",
        "passport_number": "",
        "employer": "",
        "employer_address": "",
        "account_closing_date": "0000-00-00",
        "account_start_date": "2023-01-01",
        "learners": [
            {
                "learner_id": "51",
                "first_name": "Michelle",
                "last_name": "Webster",
                "gender": "F",
                "grade": "3"
            }
        ]
    }
]
```

{% endtab %}

{% tab title="204: No Content" %}

```json
```

{% 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 Finance+ API for this client before making this request"
}
```

{% endtab %}
{% endtabs %}

## Code Samples

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

```php
<?php

const BASE_URL = 'https://integrate.d6plus.co.za/api/v1/finplus/debtmanagement/schools';
const SCHOOL_LOGIN_ID = '1000';
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,
    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/finplus/debtmanagement/schooldebtors/1000?all_persons=1' \
--header 'HTTP-X-USERNAME: your_username' \
--header 'HTTP-X-PASSWORD: your_password'
```

{% endtab %}
{% endtabs %}


# Get School Debtors

## Retrieve debtor financial transactions

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

Use this endpoint to fetch the school debtor accounts.

By default, only active debtors accounts (current learners or accounts with an outstanding balance) will be returned. You can use the `all_accounts` query parameter to fetch all debtor accounts (includes left learners and 0 balance accounts).

To include learners data in the response use the `include_learners` query parameter.

Optionally it is possible to filter on a specific `debtor_code` or `accountable_person_id`.

#### Path Parameters

<table><thead><tr><th width="247">Name</th><th width="102">Type</th><th>Description</th></tr></thead><tbody><tr><td>school_login_id<mark style="color:red;">*</mark></td><td>Integer</td><td>The login ID of the school to retrieve data from</td></tr></tbody></table>

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

#### Query Parameters

<table><thead><tr><th width="249">Name</th><th width="114">Type</th><th>Description</th></tr></thead><tbody><tr><td>all_accounts</td><td>Boolean</td><td>Whether to include all accounts</td></tr><tr><td>include_learners</td><td>Boolean</td><td>Whether to include the learner data in the response</td></tr><tr><td>debtor_code</td><td>Integer</td><td>To filter on a specific Debtor Code</td></tr><tr><td>accountable_person_id</td><td>Integer</td><td>To filter on a specific Accountable Person ID</td></tr></tbody></table>

#### Response Examples

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

```json
[
    {
        "accountable_person_id": "40",
        "title": "Mr",
        "first_name": "John",
        "full_names": "John James",
        "last_name": "Smith",
        "debtor_code": "1001",
        "mobile_calling_code": "27",
        "mobile_number": "0821237654",
        "work_tel_number": "0124567890",
        "home_tel_number": "0123214567",
        "email_address": "jjsmith@example.com",
        "residential_address": "Moneytow Street\r\nNow Village\r\n0123\r\nSouth Africa",
        "postal_address": "Moneytow Street\r\nNow Village\r\n0123\r\nSouth Africa",
        "home_language": "English",
        "correspondence_language": "English",
        "communication_method": "E-Mail",
        "include_in_debtor_comms": "Yes",
        "nationality": "South Africa",
        "id_number": "8104050240082",
        "passport_number": "A456732243",
        "employer": "Greenholt Group",
        "employer_address": "3 School Lane\r\nBig City\r\nSouth Africa",
        "account_closing_date": "0000-00-00",
        "account_start_date": "2023-01-01"
    }
    {
        "accountable_person_id": "3",
        "title": "Mr",
        "first_name": "Nic",
        "full_names": "Nicholas Nigel",
        "last_name": "Webster",
        "debtor_code": "1002",
        "mobile_calling_code": "27",
        "mobile_number": "0678901234",
        "work_tel_number": "",
        "home_tel_number": "",
        "email_address": "nicnwebster@example.co.za",
        "residential_address": "7th Street\r\nSmall Town\r\n0123\r\nSouth Africa",
        "postal_address": "7th Street\r\nSmall Town\r\n0123\r\nSouth Africa",
        "home_language": "English",
        "correspondence_language": "English",
        "communication_method": "SMS",
        "include_in_debtor_comms": "Yes",
        "nationality": "South Africa",
        "id_number": "",
        "passport_number": "",
        "employer": "",
        "employer_address": "",
        "account_closing_date": "0000-00-00",
        "account_start_date": "2023-01-01"
    }
]
```

{% endtab %}

{% tab title="200 Including Learners" %}

```json
[
    {
        "accountable_person_id": "40",
        "title": "Mr",
        "first_name": "John",
        "full_names": "John James",
        "last_name": "Smith",
        "debtor_code": "1001",
        "mobile_calling_code": "27",
        "mobile_number": "0821237654",
        "work_tel_number": "0124567890",
        "home_tel_number": "0123214567",
        "email_address": "jjsmith@example.com",
        "residential_address": "Moneytow Street\r\nNow Village\r\n0123\r\nSouth Africa",
        "postal_address": "Moneytow Street\r\nNow Village\r\n0123\r\nSouth Africa",
        "home_language": "English",
        "correspondence_language": "English",
        "communication_method": "E-Mail",
        "include_in_debtor_comms": "Yes",
        "nationality": "South Africa",
        "id_number": "8104050240082",
        "passport_number": "A456732243",
        "employer": "Greenholt Group",
        "employer_address": "3 School Lane\r\nBig City\r\nSouth Africa",
        "account_closing_date": "0000-00-00",
        "account_start_date": "2023-01-01",
        "learners": [
            {
                "learner_id": "1",
                "first_name": "John",
                "last_name": "Smith",
                "gender": "M",
                "grade": "7"
            }
        ]
    },
    {
        "accountable_person_id": "3",
        "title": "Mr",
        "first_name": "Nic",
        "full_names": "Nicholas Nigel",
        "last_name": "Webster",
        "debtor_code": "1002",
        "mobile_calling_code": "27",
        "mobile_number": "0678901234",
        "work_tel_number": "",
        "home_tel_number": "",
        "email_address": "nicnwebster@example.co.za",
        "residential_address": "7th Street\r\nSmall Town\r\n0123\r\nSouth Africa",
        "postal_address": "7th Street\r\nSmall Town\r\n0123\r\nSouth Africa",
        "home_language": "English",
        "correspondence_language": "English",
        "communication_method": "SMS",
        "include_in_debtor_comms": "Yes",
        "nationality": "South Africa",
        "id_number": "",
        "passport_number": "",
        "employer": "",
        "employer_address": "",
        "account_closing_date": "0000-00-00",
        "account_start_date": "2023-01-01",
        "learners": [
            {
                "learner_id": "51",
                "first_name": "Michelle",
                "last_name": "Webster",
                "gender": "F",
                "grade": "3"
            }
        ]
    }
]
```

{% endtab %}

{% tab title="204: No Content" %}

```json
```

{% 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 Finance+ API for this client before making this request"
}
```

{% endtab %}
{% endtabs %}

## Code Samples

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

```php
<?php

const BASE_URL = 'https://integrate.d6plus.co.za/api/v1/finplus/debtmanagement/schooldebtors';
const SCHOOL_LOGIN_ID = '1000';
const PARAMS = [
    'all_persons' => 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/finplus/debtmanagement/schooldebtors/1000?all_persons=1' \
--header 'HTTP-X-USERNAME: your_username' \
--header 'HTTP-X-PASSWORD: your_password'
```

{% endtab %}
{% endtabs %}


# Get Learner Parent Info

## Retrieve debtor financial transactions

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

Use this endpoint to fetch a school's learners and optionally include the parent info and the accountable person's details.

By default, only persons with active accounts (current learners or accounts with an outstanding balance) will be returned. You can use the `all_accounts` query parameter to fetch accountable persons for all accounts (includes left learners and 0 balance accounts).

To include parent info use the `include_parents` query parameter to include parent info in the response. For including the accountable person's details, use the `include_accountable_person` query parameter.

Optionally it is possible to filter on a specific `learner_id`, `debtor_code` or `accountable_person_id`. &#x20;

#### Path Parameters

<table><thead><tr><th width="258">Name</th><th width="134">Type</th><th>Description</th></tr></thead><tbody><tr><td>school_login_id<mark style="color:red;">*</mark></td><td>Integer</td><td>The login ID of the school to retrieve data from</td></tr></tbody></table>

#### Headers

<table><thead><tr><th width="265">Name</th><th width="121">Type</th><th>Description</th></tr></thead><tbody><tr><td>HTTP-X-USERNAME<mark style="color:red;">*</mark></td><td>String</td><td>As provided by d6</td></tr><tr><td>HTTP-X-PASSWORD<mark style="color:red;">*</mark></td><td>String</td><td>As provided by d6</td></tr></tbody></table>

#### Query Parameters

<table><thead><tr><th width="258">Name</th><th width="134">Type</th><th>Description</th></tr></thead><tbody><tr><td>learner_id</td><td>Integer</td><td>The ID of a specific learner</td></tr><tr><td>all_accounts</td><td>Boolean</td><td>Whether to include all accounts</td></tr><tr><td>include_parents</td><td>Boolean</td><td>Whether to include the parent data in the response</td></tr><tr><td>include_accountable_person</td><td>Boolean</td><td>Whether to include the accountable person's data in the response</td></tr><tr><td>learner_id</td><td>Integer</td><td>To filter on a specific Learner ID</td></tr><tr><td>debtor_code</td><td>Integer</td><td>To filter on a specific Debtor Code</td></tr><tr><td>accountable_person_id</td><td>Integer</td><td>To filter on a specific Accountable Person ID</td></tr></tbody></table>

#### Response Examples

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

```json
[
    {
        "learner_id": "1",
        "first_name": "John",
        "last_name": "Smith",
        "gender": "M",
        "grade": "7",
        "debtor_code": "1001",
        "parent1_id": "40",
        "parent2_id": "41",
        "accountable_person_id": "40"
    },
    {
        "learner_id": "2",
        "first_name": "Jane",
        "last_name": "Doe",
        "gender": "F",
        "grade": "5",
        "debtor_code": "1001",
        "parent1_id": "40",
        "parent2_id": "41",
        "accountable_person_id": "40"
    }
]
```

{% endtab %}

{% tab title="200 Including Parent Info" %}

```json
[
    {
        "learner_id": "1",
        "first_name": "John",
        "last_name": "Smith",
        "gender": "M",
        "grade": "7",
        "debtor_code": "1001",
        "parent1_id": "40",
        "parent2_id": "41",
        "accountable_person_id": "40",
        "parents": [
            {
                "parent_id": "40",
                "title": "Mr",
                "first_name": "John",
                "full_names": "John James",
                "last_name": "Smith",
                "mobile_calling_code": "27",
                "mobile_number": "0823456789",
                "work_tel_number": "0860010012",
                "home_tel_number": "0123456789",
                "email_address": "jjsmith@example.com",
                "date_of_birth": "1967-02-14",
                "gender": "M",
                "residential_address": "Plot 101\r\nDaffodil Street\r\nPretoria",
                "postal_address": "PO Box 12\r\nMenlyn\r\nPretoria",
                "home_language": "English",
                "correspondence_language": "English",
                "communication_method": "E-Mail",
                "include_in_debtor_comms": "Yes",
                "nationality": "South Africa",
                "debtor_code": "1001",
                "id_number": "6702145076084",
                "passport_number": "A0176543",
                "employer": "Smith Attorneys",
                "employer_address": "Suite 101\r\nSmith Street\r\nSouth Africa"
            },
            {
                "parent_id": "41",
                "title": "Mrs",
                "first_name": "Jane",
                "full_names": "Jane Jenny",
                "last_name": "Smith",
                "mobile_calling_code": "27",
                "mobile_number": "0798765432",
                "work_tel_number": "0860010012",
                "home_tel_number": "0123456789",
                "email_address": "smith.jj@example.org",
                "date_of_birth": "1955-06-17",
                "gender": "F",
                "residential_address": "Plot 101\r\nDaffodil Street\r\nPretoria",
                "postal_address": "PO Box 12\r\nMenlyn\r\nPretoria",
                "home_language": "English",
                "correspondence_language": "English",
                "communication_method": "SMS",
                "include_in_debtor_comms": "Yes",
                "nationality": "South Africa",
                "debtor_code": "1001",
                "id_number": "5506170079082",
                "passport_number": "",
                "employer": "Smith Attorneys",
                "employer_address": "Suite 101\r\nSmith Street\r\nSouth Africa"
            }
        ]
    },
    {
        "learner_id": "2",
        "first_name": "Jane",
        "last_name": "Doe",
        "gender": "F",
        "grade": "5",
        "debtor_code": "1002",
        "parent1_id": "55",
        "parent2_id": "56",
        "accountable_person_id": "40",
        "parents": [
            {
                "parent_id": "55",
                "title": "Mr",
                "first_name": "Jonathan",
                "full_names": "Jonathan Andrew",
                "last_name": "Doe",
                "mobile_calling_code": "27",
                "mobile_number": "0813456789",
                "work_tel_number": "0860010012",
                "home_tel_number": "0123456789",
                "email_address": "jd@example.com",
                "date_of_birth": "1969-03-11",
                "gender": "M",
                "residential_address": "91 Monument Street\r\nMonument Park\r\nPretoria",
                "postal_address": "PO Box 12\r\nMonument Park\r\nPretoria",
                "home_language": "English",
                "correspondence_language": "English",
                "communication_method": "E-Mail",
                "include_in_debtor_comms": "Yes",
                "nationality": "South Africa",
                "debtor_code": "1002",
                "id_number": "6903115013085",
                "passport_number": "",
                "employer": "Happy Car Hire",
                "employer_address": "10 Happy Street\r\nJohannesburg\r\nSouth Africa"
            },
            {
                "parent_id": "56",
                "title": "Mrs",
                "first_name": "Janine",
                "full_names": "Janine",
                "last_name": "Doe",
                "mobile_calling_code": "27",
                "mobile_number": "0798124678",
                "work_tel_number": "0860010012",
                "home_tel_number": "0123456789",
                "email_address": "jd2@example.org",
                "date_of_birth": "1984-10-07",
                "gender": "F",
                "residential_address": "91 Monument Street\r\nMonument Park\r\nPretoria",
                "postal_address": "PO Box 12\r\nMonument Park\r\nPretoria",
                "home_language": "English",
                "correspondence_language": "English",
                "communication_method": "SMS",
                "include_in_debtor_comms": "Yes",
                "nationality": "South Africa",
                "debtor_code": "1002",
                "id_number": "8410070079082",
                "passport_number": "",
                "employer": "Happy Car Hire",
                "employer_address": "10 Happy Street\r\nJohannesburg\r\nSouth Africa"
            }
        ]
    }
]
```

{% endtab %}

{% tab title="200 Including Accountable Person" %}

```json
[
    {
        "learner_id": "1",
        "first_name": "John",
        "last_name": "Smith",
        "gender": "M",
        "grade": "7",
        "debtor_code": "1001",
        "parent1_id": "40",
        "parent2_id": "41",
        "accountable_person_id": "40",
        "accountable_person": {
            "accountable_person_id": "40",
            "title": "Mr",
            "full_names": "John James",
            "first_name": "John",
            "last_name": "Smith",
            "mobile_calling_code": "27",
            "mobile_number": "0823456789",
            "work_tel_number": "0860010012",
            "home_tel_number": "0123456789",
            "email_address": "jjsmith@example.com",
            "date_of_birth": "1967-02-14",
            "gender": "M",
            "residential_address": "Plot 101\r\nDaffodil Street\r\nPretoria",
            "postal_address": "PO Box 12\r\nMenlyn\r\nPretoria",
            "home_language": "English",
            "correspondence_language": "English",
            "communication_method": "E-Mail",
            "include_in_debtor_comms": "Yes",
            "nationality": "South Africa",
            "debtor_code": "1001",
            "id_number": "6702145076084",
            "passport_number": "A0176543",
            "employer": "Smith Attorneys",
            "employer_address": "Suite 101\r\nSmith Street\r\nSouth Africa"
        }
    },
    {
        "learner_id": "2",
        "first_name": "Jane",
        "last_name": "Doe",
        "gender": "F",
        "grade": "5",
        "debtor_code": "1002",
        "parent1_id": "55",
        "parent2_id": "56",
        "accountable_person_id": "55",
        "accountable_person": {
            "accountable_person_id": "55",
            "title": "Mr",
            "full_names": "Jonathan Andrew",
            "first_name": "Jonathan",
            "last_name": "Doe",
            "mobile_calling_code": "27",
            "mobile_number": "0813456789",
            "work_tel_number": "0860010012",
            "home_tel_number": "0123456789",
            "email_address": "jd@example.com",
            "date_of_birth": "1969-03-11",
            "gender": "M",
            "residential_address": "91 Monument Street\r\nMonument Park\r\nPretoria",
            "postal_address": "PO Box 12\r\nMonument Park\r\nPretoria",
            "home_language": "English",
            "correspondence_language": "English",
            "communication_method": "SMS",
            "include_in_debtor_comms": "Yes",
            "nationality": "South Africa",
            "debtor_code": "1002",
            "id_number": "6903115013085",
            "passport_number": "",
            "employer": "Happy Car Hire",
            "employer_address": "10 Happy Street\r\nJohannesburg\r\nSouth Africa"
        }
    }
]
```

{% endtab %}

{% tab title="204: No Content" %}

```json
```

{% 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 Finance+ API for this client before making this request"
}
```

{% endtab %}
{% endtabs %}

## Code Samples

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

```php
<?php

const BASE_URL = 'https://integrate.d6plus.co.za/api/v1/finplus/debtmanagement/learnerparentinfo';
const SCHOOL_LOGIN_ID = '1000';
const PARAMS = [
    'all_persons' => 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/finplus/debtmanagement/learnerparentinfo/1000?all_persons=1' \
--header 'HTTP-X-USERNAME: your_username' \
--header 'HTTP-X-PASSWORD: your_password'
```

{% endtab %}
{% endtabs %}


# Get Transaction Type(s)

## Retrieve transaction types

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

Use this endpoint to retrieve the list of available transaction types. By default all available transaction types are returned.&#x20;

It is possible to retrieve the information for a single transaction type by providing the optional `transaction_type_id` query parameter.

#### Path Parameters

<table><thead><tr><th width="247">Name</th><th width="102">Type</th><th>Description</th></tr></thead><tbody><tr><td>school_login_id<mark style="color:red;">*</mark></td><td>Integer</td><td>The login ID of the school to retrieve data from</td></tr></tbody></table>

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

#### Query Parameters

<table><thead><tr><th width="249">Name</th><th width="114">Type</th><th>Description</th></tr></thead><tbody><tr><td>transaction_type_id</td><td>Integer</td><td>The id of the transaction type to retrieve</td></tr></tbody></table>

#### Response Examples

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

```json
[
    {
        "id": "1",
        "name": "General Journal"
    },
    {
        "id": "2",
        "name": "Receipt"
    },
    {
        "id": "3",
        "name": "Payment"
    },
    {
        "id": "4",
        "name": "Deposit"
    }
]
```

{% endtab %}

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

```json
{
    "error": "Not Found",
    "error_description": "The transaction type does not exist"
}
```

{% 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 Finance+ API for this client before making this request"
}
```

{% endtab %}
{% endtabs %}

## Code Samples

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

```php
<?php

const BASE_URL = 'https://integrate.d6plus.co.za/api/v1/finplus/debtmanagement/transactiontypes';
const SCHOOL_LOGIN_ID = '1000';
const PARAMS = [
    'transaction_type_id' => 2
];
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/finplus/debtmanagement/debtornotes/notetypes/1000?note_type_id=2' \
--header 'HTTP-X-USERNAME: your_username' \
--header 'HTTP-X-PASSWORD: your_password'
```

{% endtab %}
{% endtabs %}


# Get Transaction Category(s)

## Retrieve transaction types

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

Use this endpoint to retrieve the list of available transaction categories. By default all available transaction categories are returned.&#x20;

It is possible to retrieve the information for a single category by providing the optional `category_id` query parameter.

#### Path Parameters

<table><thead><tr><th width="247">Name</th><th width="102">Type</th><th>Description</th></tr></thead><tbody><tr><td>school_login_id<mark style="color:red;">*</mark></td><td>Integer</td><td>The login ID of the school to retrieve data from</td></tr></tbody></table>

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

#### Query Parameters

<table><thead><tr><th width="249">Name</th><th width="114">Type</th><th>Description</th></tr></thead><tbody><tr><td>category_id</td><td>Integer</td><td>The id of the category to retrieve</td></tr></tbody></table>

#### Response Examples

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

```json
[
    {
        "id": "1",
        "name": "School Fees"
    },
    {
        "id": "6",
        "name": "Hostel Fees"
    },
    {
        "id": "7",
        "name": "Aftercare"
    }
]
```

{% endtab %}

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

```json
{
    "error": "Not Found",
    "error_description": "The transaction category does not exist"
}
```

{% 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 Finance+ API for this client before making this request"
}
```

{% endtab %}
{% endtabs %}

## Code Samples

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

```php
<?php

const BASE_URL = 'https://integrate.d6plus.co.za/api/v1/finplus/debtmanagement/transactioncategories';
const SCHOOL_LOGIN_ID = '1000';
const PARAMS = [
    'category_id' => 2
];
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/finplus/debtmanagement/debtornotes/notetypes/1000?note_type_id=2' \
--header 'HTTP-X-USERNAME: your_username' \
--header 'HTTP-X-PASSWORD: your_password'
```

{% endtab %}
{% endtabs %}


# Getting Started

Hi and welcome!

d6 Integrate provides a RESTful API to interact with the d6+ School Administration and Management System (SAMS).

This API documentation will provide you with everything you need in order to take advantage of the capabilities that d6 Integrate offers.

Please read the entire Getting Started section before diving into the Reference section, as it provides the necessary context and detail you will need to implement an effective integration.

{% hint style="warning" %}
You might not have access to all the endpoints and/or fields listed in this documentation. Your access is determined by your API subscription level.
{% endhint %}

We are always looking to improve, so please email any suggestions to <apidocs@d6.co.za>


# Authorisation & Activation

Each school that makes use of the d6+ SAMS is able the manage the list of integrations they would like to make use of.&#x20;

Before you (our d6 Integrate partner) can interact with a school's data via the d6 Integrate API, the school must first authorise your integration in their d6+ SAMS instance.&#x20;

During your d6 Integrate partner onboarding process, you will receive introductory training on how schools manage their integrations on the d6+ SAMS. This will ensure that you are equipped to assist your new clients to authorise your integration.

This authorisation should ideally only be done once the school has entered into an agreement with you as a service provider, since the school is authorising the sharing of their information with you.

In order to keep you updated about which schools are choosing to make use of your service, each time a school authorises or de-authorises your integration, you will receive a notification email. This will be sent to the technical contact email address specified on your d6 Integrate License Agreement.&#x20;

In order to avoid being billed for schools that are not (yet) your client, you have the ability to activate the integration once it has been authorised by the school. This ensures that you retain control over who your active, legitimate clients are. You will need to activate an integration before you are able to interact with the school's data (see "[Settings/Clients/Change Client Integration State](https://apidocs.d6plus.co.za/v2/reference/settings/clients/change-client-integration-state)").&#x20;

Billing of a school will only commence after you activate the integration for the first time. Once an integration has been activated, billing will continue for the duration of your license agreement and active subscription, regardless of whether you subsequently de-activate the integration. However, should a school choose to de-authorise your integration, you will no longer be billed for that school.

Please see the [Settings](/v2/reference/settings) section in the Reference area for the relevant API endpoints to view and manage your authorised integrations.

Once a school has authorised your integration and you have activated it, you are free to interact with their data via the d6 integration API's that are included in your subscription. If you de-activate the integration, or the school de-authorises it, the d6 integration API will not allow access to that school's data.


# API v2 URL

The base URL for all v2 endpoints in this API collection is shown below.

<pre class="language-url"><code class="lang-url">https://integrate.d6plus.co.za/api/<a data-footnote-ref href="#user-content-fn-1">v2</a>/
</code></pre>

[^1]: This documentation relates to v2 of the API


# Versioning

d6 Integrate utilises versioning in order to:

* Ensure backward compatibility
* Facilitate feature enhancements and testing
* Manage the deprecation of outdated endpoints
* Ultimately provide a more reliable and consistent user experience for developers

The version number is independent per endpoint.

The version is specified by a number with a ‘v’ prefix (eg: v1, v2) - for example:&#x20;

`https://integrate.d6plus.co.za/api/`**`v1`**`/adminplus/learners`

`https://integrate.d6plus.co.za/api/`**`v3`**`/adminplus/parents`

`https://integrate.d6plus.co.za/api/`**`v2`**`/currplus/learnersubjects`


# Authentication

d6 Integrate requires authentication via username and password credentials which are provided to you by d6 after successful completion of a data sharing license agreement.

The credentials must be passed in the request header using the following parameters:

> HTTP-X-USERNAME
>
> HTTP-X-PASSWORD

{% hint style="warning" %}
All API requests must be made over HTTPS. Requests made over plain HTTP will fail and may risk exposing your key. Your credentials must never be shared. Do not use your credentials in client side code as you may risk exposing it to third parties.
{% endhint %}


# Additional Headers

### School ID

For API calls that are specific to **one** school, the **School ID** needs to be provided in the request headers. See the [Get Client Integrations](/v2/reference/settings/client-integrations/get-client-integrations) call for a list of your available School IDs.

Specify the school ID using:

> HTTP-X-SCHOOLID

#### Sample Code

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

```php
<?php

// API Credentials
$api_username = 'your_username';
$api_password = 'your_password';
$school_id = 'the_school_id';

// Base API endpoint
define('BASE_URL', 'https://integrate.d6plus.co.za/api/v2/learners');

// Optional: Set an ID to fetch a specific learner (or leave empty for all)
$id = '';

$url = BASE_URL;
if (!empty($id)) {
    $url .= '/' . $id;
}

// Initialize cURL
$curl = curl_init();

// Set cURL options
curl_setopt_array($curl, [
    CURLOPT_URL            => $url,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_TIMEOUT        => 30,  // Set timeout to prevent hanging requests
    CURLOPT_FOLLOWLOCATION => true,
    CURLOPT_HTTP_VERSION   => CURL_HTTP_VERSION_1_1,
    CURLOPT_CUSTOMREQUEST  => 'GET',
    CURLOPT_HTTPHEADER     => [
        "HTTP-X-USERNAME: $api_username",
        "HTTP-X-PASSWORD: $api_password",
        "HTTP-X-SCHOOLID: $school_id"
    ],
]);

// Execute request
$response = curl_exec($curl);

// Check for errors
$error = curl_error($curl);
if ($error) {
    curl_close($curl);
    throw new Exception("cURL Error: $error");
}

// Close cURL and output response
curl_close($curl);
echo $response;
```

{% endtab %}

{% tab title="cURL" %}

```bash
rl --request GET 'https://integrate.d6plus.co.za/api/v2/learners/123' \
     --header 'HTTP-X-USERNAME: your_username' \
     --header 'HTTP-X-PASSWORD: your_password' \
     --header 'HTTP-X-SCHOOLID: the_school_id'
```

{% endtab %}
{% endtabs %}


# Response Status Codes

d6 Integrate uses status codes that adhere to the HTTP/1.1 standard (RFC 7231):

| Code | Name                  | Description                                                                                               |
| ---- | --------------------- | --------------------------------------------------------------------------------------------------------- |
| 200  | OK                    | The request was successful.                                                                               |
| 400  | Bad Request           | The request was invalid. Normally due to missing or malformed parameters.                                 |
| 401  | Unauthorized          | The server understood the request, but is refusing it.                                                    |
| 403  | Forbidden             | The server understood the request, but access is not allowed.                                             |
| 404  | Not Found             | The resource was not found.                                                                               |
| 429  | Too Many Requests     | Rate limits have been reached, please slow down your requests.                                            |
| 500  | Internal Server Error | Internal server error which has been logged and being attended to. Please try again later.                |
| 501  | Not Implemented       | The server does not support the functionality required to fulfill the request.                            |
| 503  | Service Unavailable   | The server is currently unable to handle the request due to a temporary overload or scheduled maintenance |


# Rate Limiting

Please be aware that should you exceed these limits you will receive a 429 (Too Many Requests).

The current rate limits are:

* 60 requests per 60 seconds per unique IP address


# Errors and Bad Requests

Errors or bad requests caught by the API will always return an appropriate HTTP status code in the response headers (as described in the [Response Status Codes](/v2/getting-started/response-status-codes) section), as well as a body containing details about the error occurred:

* `success` (bool) - Either `true` or `false`. In the event of an error, this will be `false`.
* `message` (string) - A description of the actual problem encountered

In the event of a user input validation failure, the following will be included in the response body:

* `validation_errors` (object) - A list of fields and the validation error message

Example error response body:

```json
{
    "success": false,
    "message": "Validation Failed",
    "validation_errors": {
        "accountable_person_id": "The accountable_person_id is invalid",
        "date": "The Date is not valid date format. Expected format is 'Y-m-d'."
    }
}
```


# Pagination

Some API endpoints return large datasets. To ensure efficient and manageable responses, these endpoints support **cursor-based pagination**. This allows clients to retrieve results in chunks and navigate through pages as needed. The response data includes a `meta` object that contains **pagination-specific metadata**.

### Pagination Parameters

Below is a list of **optional** request parameters to control pagination of the response data.

<table><thead><tr><th width="167.7427978515625">Parameter</th><th width="130.17144775390625">Type</th><th>Description</th></tr></thead><tbody><tr><td><code>cursor</code></td><td>string</td><td>If the <code>meta</code> object contains a <code>next_cursor</code> field, it indicates that more records are available. To fetch the next set of records, include the <code>cursor</code> parameter in your request with the value of <code>next_cursor</code>. If the <code>next_cursor</code> field is not present, it means there are no more records to retrieve.</td></tr><tr><td><code>limit</code></td><td>integer</td><td>This parameter allows you to override the default limit of records returned, up to the <code>max_allowed_limit</code> specified in the response's <code>meta</code> object.</td></tr><tr><td><code>reverse_order</code></td><td>boolean</td><td>This parameter can be used to reverse the order in which the data is returned, useful for fetching the latest records first.</td></tr></tbody></table>

### Response Example

```json
{
    "data": [
        ...
    ],
    "meta": {
        "limit": 10,
        "max_allowed_limit": 50,
        "next_cursor": "eyJpZCI6MTA4MDMsIl9iYWNrd2FyZCI6ZmFsc2V9"
    }
}
```

* `limit` - The **default** number of records returned.
* `max_allowed_limit` - The **maximum** allowed limit of records per page.
* `next_cursor` - The token to use for retrieving the **next set** of records (see cursor request parameter).

{% hint style="info" %}
The `next_cursor` field will indicate **if there are more records** to return. If not, the field will not be included in the response metadata.
{% endhint %}

### Example Request

<mark style="color:blue;">`GET`</mark> `/v2/finplus/debtmanagement/financialtransactions?reverse_order=1&limit=100`

#### **Fetching the Next Page**

<mark style="color:blue;">`GET`</mark> `/v2/finplus/debtmanagement/financialtransactions?reverse_order=1&cursor=abc123&limit=100`


# Upgrading to v2

This page highlights the key changes introduced in API v2 and serves as a reference for upgrading from v1.

## 1. Adoption of Collections vs. Resources

In **v2**, our API follows RESTful principles more strictly by differentiating between **Collections** and **Resources.** A **Collection** represents a group of items whereas a **Resource** represents a specific item.

In **v1**, the API structure included the **School ID** as the last segment of the URL, and when retrieving a specific item. The **ID** was passed either as a **query parameter** or was included in the **request body**.

In **v2**, the API structure follows a more RESTful approach:

* **Resources** now have their **ID passed in the URL** (e.g., `/learners/{learner_id}`).
* **Collections** exclude the ID and are retrieved using a general endpoint (e.g., `/learners`).

#### **Request Example:**

<table><thead><tr><th width="180.9842529296875">Operation</th><th width="257.958740234375">v1 Endpoint</th><th>v2 Endpoint </th></tr></thead><tbody><tr><td>Get all learners</td><td><code>/learners/{{SCHOOL_ID}}</code></td><td><code>/learners</code></td></tr><tr><td>Get a specific learner</td><td><code>/learners/{{SCHOOL_ID}}?learner_id=123</code></td><td><code>/learners/123</code></td></tr></tbody></table>

This change also impacts the response payload structure:

* In **v1**, all responses that contained data were returned as an array, even when fetching a single item.
* In **v2**, the response format aligns with RESTful design:
  * A **Resource** request returns a single object.
  * A **Collection** request returns an array, wrapped inside a `data` object to support additional metadata (see introduction of Pagination below).&#x20;

#### Response Example:

{% tabs %}
{% tab title="Resource" %} <mark style="color:green;">`GET`</mark> `/learners/1` <- *Notice the Resource ID is now part of the URL*

```json
{
    "learner_id": 1,
    "first_name": "John",
    "last_name": "Smith",
    "gender": "M",
    "grade": "7",
    "debtor_code": "1001",
    "parent1_id": 40,
    "parent2_id": 41,
    "accountable_person_id": 40
}
```

{% endtab %}

{% tab title="Collection" %} <mark style="color:green;">`GET`</mark> `/learners`

```json
[
    "data": [
        {
            "learner_id": 1,
            "first_name": "John",
            "last_name": "Smith",
            "gender": "M",
            "grade": "7",
            "debtor_code": "1001",
            "parent1_id": 40,
            "parent2_id": 41,
            "accountable_person_id": 40
        },
        {
            "learner_id": 2,
            "first_name": "Jane",
            "last_name": "Doe",
            "gender": "F",
            "grade": "5",
            "debtor_code": "1001",
            "parent1_id": 40,
            "parent2_id": 41,
            "accountable_person_id": 40
        }
    ],
    "meta": {
        ...
    }
]
```

{% endtab %}
{% endtabs %}

## 2. School ID Moved to Request Headers

In light of the above changes to the API, the **School ID** moved to the **request headers**. This is to accommodate the changes for the adoption of a collection versus a resource design (see above).

**In example:**

```bash
curl 'https://integrate.d6plus.co.za/api/v2/learners/1' \
     --header 'HTTP-X-USERNAME: yourusername' \
     --header 'HTTP-X-PASSWORD: yourpassword' \
     --header 'HTTP-X-SCHOOLID: 1234'
```

## 3. Pagination Introduced

Version 2 of the Integrate API adopted pagination to help improve server performance and reduce response times. We've adopted the **cursor-based pagination** strategy, which uses an opaque string to mark the starting point for the next set of items.

The following **query parameters** allows you to control pagination:

<table><thead><tr><th width="155.7427978515625">Name</th><th width="92.05712890625">Type</th><th>Description</th></tr></thead><tbody><tr><td><code>cursor</code></td><td>String</td><td>To retrieve the next group of items</td></tr><tr><td><code>limit</code></td><td>Integer</td><td>To override the default limit of records returned (up to the <code>max_allowed_limit</code> provided in the response metadata).</td></tr><tr><td><code>reverse_order</code></td><td>Boolean</td><td>To sort the results in descending order (useful for fetching the latest records first).</td></tr></tbody></table>

The **response payload** now includes a `meta` object containing pagination-related data.

* `next_cursor`  – The cursor to use for retrieving the next set of items. If no further data is available, this field is omitted.
* `limit`  – The number of records returned
* `max_allowed_limit`  – The maximum number of records that can be requested per page

#### Response Example:

```json
{
    "data": [
        ...
    ],
    "meta": {
        "limit": 10,
        "max_allowed_limit": 50,
        "next_cursor": "eyJpZCI6MTA4MDMsIl9iYWNrd2FyZCI6ZmFsc2V9"
    }
}
```

## 4. Correct Type-Casting in Response Body

In **v1**, all response fields were returned as **strings**, regardless of their actual data type. This required clients to manually parse numbers, booleans, and other data types.

In **v2**, all fields in the response body are now **properly type-casted** to their correct data types, reducing processing overhead and improving API consistency.

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

```json
{
  "data": [    
    {
      "school_id": 1234,
      "name": "Greenwood High",
      "students_count": 450,
      "email_address": "admin@greenwoodhigh.co.za",
      "has_after_school_center": "Yes"
    },
    {
      "school_id": 1340,
      "name": "Riverside Academy",
      "students_count": 520,
      "email_address": null,
      "has_after_school_center": "No"
    }
  ]
}
```

{% endtab %}

{% tab title="v1" %}

```json
[
  {
    "school_id": "1234",
    "name": "Greenwood High",
    "students_count": "450",
    "email_address": "admin@greenwoodhigh.co.za",
    "has_after_school_center": "Yes"
  },
  {
    "school_id": "1340",
    "name": "Riverside Academy",
    "students_count": "520",
    "email_address": "",
    "has_after_school_center": "No"
  }
]
```

{% endtab %}
{% endtabs %}

## 5. Success Responses Updated

The **success** **response** format has been updated to a more standardized format.

The response fields are as follows:

* **`success`** – Indicates whether the request was successful.
* **`message`** – A success confirmation message.
* **`data`** – An object that contains the ID of the item that has been created. Additional fields of the created item may be included in the data object if necessary.

#### Create Request Example:

{% tabs %}
{% tab title="v2 Create Response" %} <mark style="color:orange;">`POST`</mark> `/v1/notes`

**Status Code:** <mark style="color:green;background-color:green;">`201 Created`</mark>

**Response Body:**

```json
{
    "success": true,
    "message": "Note created successfully",
    "data": {
        "note_id": 2543
    }
}
```

{% endtab %}

{% tab title="v1 Create Response" %} <mark style="color:orange;">`POST`</mark> `/v1/notes/{{SCHOOL_ID}}`

**Status Code:** <mark style="color:green;background-color:green;">`200 OK`</mark>

**Response Body:**

```json
{
    "note_id": "2545"
}
```

{% endtab %}
{% endtabs %}

#### Delete Request Example:

{% tabs %}
{% tab title="v2 Delete Response" %} <mark style="color:red;">`DELETE`</mark> `/v1/notes/2545`

**Status Code:** <mark style="color:green;background-color:green;">`200 OK`</mark>

**Response Body:**

```json
{
    "success": true,
    "message": "Note deleted successfully"
}
```

{% endtab %}

{% tab title="v1 Delete Response" %} <mark style="color:red;">`DELETE`</mark> `/v1/notes/{{SCHOOL_ID}}?note_id=2545`

**Status Code:** <mark style="color:green;background-color:green;">`200 OK`</mark>

**Response Body:**

```json
{
    "status": "Deleted"
}
```

{% endtab %}
{% endtabs %}

## 6. Error responses updated

Similar to the success responses, the **error response** format has also been updated to provide a more consistent format across the API.

The response fields are as follows:

* `success` – Indicates whether the request was successful.
* `message` – A success confirmation message.

In the event of a user input validation failure, the following will be included in the response body:

* `validation_errors` – A list of fields and the validation error message

Not Found Error Example:

{% tabs %}
{% tab title="v2 Not Found Error" %}
**Status Code:** <mark style="color:red;background-color:green;">`404 Not Found`</mark>

**Response Body:**

```json
{
    "success": false,
    "message": "The note does not exist."
}
```

{% endtab %}

{% tab title="v1 Not Found Error" %}
**Status Code:** <mark style="color:red;background-color:green;">`404 Not Found`</mark>

**Response Body:**

```json
{
    "error": "Not Found",
    "error_description": "The note does not exist."
}
```

{% endtab %}
{% endtabs %}

#### Validation Error Response Example:

{% tabs %}
{% tab title="v2 Validation Error" %}
**Status Code:** <mark style="color:red;background-color:green;">`400 Bad Request`</mark>

**Response Body:**

```json
{
    "success": false,
    "message": "Validation Failed",
    "validation_errors": {
        "note_id": "The note_id is invalid",
        "date": "The Date is not valid date format. Expected format is 'Y-m-d'."
    }
}
```

{% endtab %}

{% tab title="v1 Validation Error" %}
**Status Code:** <mark style="color:red;background-color:green;">`400 Bad Request`</mark>

**Response Body:**

```json
{
    "error": "Validation failed",
    "error_description": {
        "note_id": "The note_id is invalid",
        "date": "The Date is not valid date format. Expected format is 'Y-m-d'."
    }
}
```

{% endtab %}
{% endtabs %}

{% hint style="warning" %}
To ensure backward compatibility, some existing errors that were previously returned in v1 may still use the old response format. However, all newly introduced errors follow the updated structure, making it easier to handle and interpret responses moving forward.
{% endhint %}

## 7. Changes to Individual API Calls

In addition to the changes mentioned above, this section outlines specific updates to API endpoints and fields introduced in v2. These updates align the API more closely with RESTful principles.

<details>

<summary>Settings</summary>

## 1. Get Client Integrations

The API call named **Settings/Clients** has been renamed to **Settings/ClientIntegrations,** additionally the school ID does not form part of the URL anymore but moved to a **query parameter**.

### **Endpoint:**

**Old:**

```http
GET /v1/settings/clients(/{school_id})
```

**New:**

```http
GET /v2/settings/clientintegrations(?school_id={school_id},...)
```

### **Response Body:**

`school_login_id` changed to `school_id`

```json
[
    {
        "school_id": 1000, // school_login_id -> school_id
        "school_name": "d6+ Primary School",
        "admin_email_address": "support@d6plus.co.za",
        ...
    },
    ...
]
```

## 2. Update Client Integration

Similar to the "Get" call, the "Update" call was renamed from **Settings/Clients** to **Settings/ClientIntegrations**. The school ID does not form part of the URL anymore but moved to the **request body**. The request method also changed from PATCH to **POST**.

### **Endpoint:**

**Old:**

```http
PATCH /v1/settings/clients/{school_id}
```

**New:**

```
POST /v2/settings/clientintegrations
```

### **Request Body:**

**Old:**

```json
{
    "api_type_id": 8,
    "state": 1
}
```

**New:**

```json
{
    "school_id": 1219, // <- now part of the request body
    "api_type_id": 8,
    "state": 1
}
```

</details>

<details>

<summary>Finance+</summary>

## 1. Get Learner Parent Info

The API call to get **Learner Parent Info** has been renamed to **Learners**.

### **Endpoint:**&#x20;

**Old:**

<pre class="language-http"><code class="lang-http"><strong>GET /v1/finplus/debtmanagement/learnerparentinfo/{school_id}(?learner_id=123)
</strong></code></pre>

**New:**

```http
GET /v2/finplus/debtmanagement/learners(/{learner_id})
```

## 2. Get School Debtors

The API call to get **School Debtors** has been renamed to **Accountable Persons**.

### Endpoint:

**Old:**

```
GET /v1/finplus/debtmanagement/schooldebtors/{school_id}
(?accountable_person_id=123)
```

**New:**

```
GET /v2/finplus/debtmanagement/accountablepersons(/{accountable_person_id})
```

</details>


# Settings

This section details the REST endpoints to interact with the d6 Integrate settings on your account as well as for clients who have authorised your integration.

## Endpoint

The base URL for all endpoints in this module is shown below.

`https://integrate.d6plus.co.za/api/v2/`**`settings`**`/`


# Client Integrations


# Get Client Integrations

<mark style="color:blue;">`GET`</mark> `/v2/settings/clientintegrations`

This endpoint retrieves a list of **client integrations**, representing schools that have authorized your integration in their d6+ SAMS instance.

Each record in the response corresponds to a unique **client/API type combination**, meaning a single school may appear multiple times if it has authorized multiple integrations.

### Pagination

The response data includes a `meta` object that contains **pagination-specific metadata**. You can use the following query parameters to **control pagination**:

* **limit**: This parameter allows you to override the default limit of records returned, up to the `max_allowed_limit` specified in the response's `meta` object.
* **cursor**: If the `meta` object contains a `next_cursor` field, it indicates that more records are available. To fetch the next set of records, include the `cursor` parameter in your request with the value of `next_cursor`. If the `next_cursor` field is not present, it means there are no more records to retrieve.
* **reverse\_order**: This parameter can be used to reverse the order in which the data is returned, useful for fetching the latest records first.

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

### Query Parameters

<table><thead><tr><th width="187.142822265625">Name</th><th width="135.62860107421875">Type</th><th>Description</th></tr></thead><tbody><tr><td><code>school_id</code></td><td>Integer</td><td>Optional ID of the school to retrieve data from</td></tr><tr><td><code>api_type_id</code></td><td>Integer</td><td>For filtering on a specific API Type</td></tr><tr><td><code>cursor</code></td><td>Boolean</td><td>To retrieve the next group of items (if any)</td></tr><tr><td><code>limit</code></td><td>Integer</td><td>To override the default limit of records returned (up to the <code>max_allowed_limit</code> provided in the response metadata).</td></tr><tr><td><code>reverse_order</code></td><td>Boolean</td><td>To reverse the order the data is returned in</td></tr></tbody></table>

### Response Examples

{% tabs %}
{% tab title="Success (200 OK)" %}
**Status:** <mark style="color:green;">`200 OK`</mark>

```json
[
    "data": [
        {
            "school_id": 1000,
            "school_name": "d6+ Primary School",
            "admin_email_address": "support@d6plus.co.za",
            "telephone_calling_code": "27",
            "telephone_number": "0123334444",
            "api_type_id": 8,
            "api_type": "Admin+ API",
            "activated_by_integrator": "No"
        },
        {
            "school_id": 1000,
            "school_name": "d6+ Primary School",
            "admin_email_address": "support@d6plus.co.za",
            "telephone_calling_code": "27",
            "telephone_number": "0123334444",
            "api_type_id": 9,
            "api_type": "Curriculum+ API",
            "activated_by_integrator": "Yes"
        },
        {
            "school_id": 1001,
            "school_name": "d6+ Secondary School",
            "admin_email_address": "support@d6plus.co.za",
            "telephone_calling_code": "27",
            "telephone_number": "0123334444",
            "api_type_id": 8,
            "api_type": "Debt manager",
            "activated_by_integrator": "Yes"
        }
    ],
    "meta": {
        "limit": 10,
        "max_allowed_limit": 50,
        "next_cursor": "eyJpZCI6MjU0NiwiX2JhY2t3YXJkIjpmYWxzZX0"
    }
]
```

{% endtab %}

{% tab title="Validation Error (400 Bad Request)" %}
**Description:** When validation failed for one or more fields

**Status:** <mark style="color:red;">`400 Bad Request`</mark>

```json
{
    "success": false,
    "message": "Validation Failed",
    "validation_errors": {
        "school_id": "The School id must be integer",
        "api_type_id": "The Api type id must be integer",
        "limit": "The Limit maximum is 50"
    }
}
```

{% endtab %}
{% endtabs %}

### Code Samples

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

```php
<?php

// API Credentials
$api_username = 'your_username';
$api_password = 'your_password';

// Base API endpoint
define('BASE_URL', 'https://integrate.d6plus.co.za/api/v2/settings/clientintegrations');

// Query parameters (optional)
$query_params = [
    'school_id'   => 1000,
    'api_type_id' => 8,
    'limit'       => 50,
    'cursor'      => 'eyJpZCI6MTY5NCwiX2JhY2t3YXJkIjpmYWxzZX0',
];

$url = BASE_URL;
if (!empty($query_params)) {
    $url .= '?' . http_build_query($query_params);
}

// Initialize cURL
$curl = curl_init();

// Set cURL options
curl_setopt_array($curl, [
    CURLOPT_URL            => $url,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_TIMEOUT        => 30,  // Set timeout to prevent hanging requests
    CURLOPT_FOLLOWLOCATION => true,
    CURLOPT_HTTP_VERSION   => CURL_HTTP_VERSION_1_1,
    CURLOPT_CUSTOMREQUEST  => 'GET',
    CURLOPT_HTTPHEADER     => [
        "HTTP-X-USERNAME: $api_username",
        "HTTP-X-PASSWORD: $api_password"
    ],
]);

// Execute request
$response = curl_exec($curl);

// Check for errors
$error = curl_error($curl);
if ($error) {
    curl_close($curl);
    throw new Exception("cURL Error: $error");
}

// Close cURL and output response
curl_close($curl);
echo $response;

```

{% endtab %}

{% tab title="cURL" %}

```bash
curl --request GET "https://integrate.d6plus.co.za/api/v2/settings/clientintegrations?school_id=1000&api_type_id=8&limit=50" \
     --header "HTTP-X-USERNAME: your_username" \
     --header "HTTP-X-PASSWORD: your_password"
```

{% endtab %}
{% endtabs %}


# Change Client Integration State

<mark style="color:orange;">`POST`</mark> `/v2/settings/clientintegrations`

Use this endpoint to change the state of the integration for a client who has authorised your integration in their d6+ SAMS instance. This state indicates whether you are actively servicing the client or not.

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

### Request Body

<table><thead><tr><th width="191.94281005859375">Name</th><th width="128.314453125">Type</th><th>Description</th></tr></thead><tbody><tr><td><code>school_id</code><mark style="color:red;">*</mark></td><td>Integer</td><td>The ID of the school to update</td></tr><tr><td><code>api_type_id</code><mark style="color:red;">*</mark></td><td>Integer</td><td>The api_type_id returned by the Get Clients endpoint</td></tr><tr><td><code>state</code><mark style="color:red;">*</mark></td><td>Boolean</td><td>The state you would like to set the integration to</td></tr></tbody></table>

### Response Examples

{% tabs %}
{% tab title="Success (200 OK)" %}
**Status:** <mark style="color:green;">`200 OK`</mark>

```json
{
    "success": true,
    "message": "Integration successfully activated",
    "data": {
        "school_id": 1000,
        "school_name": "d6+ Primary School",
        "admin_email_address": "support@d6plus.co.za",
        "telephone_calling_code": "27",
        "telephone_number": "0123334444",
        "api_type_id": 8,
        "api_type": "Admin+ API",
        "activated_by_integrator": "Yes" // <-
    }
}
```

{% endtab %}

{% tab title="Update Error (400 Bad Request)" %}
**Description:** When activating/deactivating the integration when it is already in that state

**Status:** <mark style="color:red;">`400 Bad Request`</mark>

```json
{
    "success": false,
    "message": "Integration already activated",
    "data": {
        "school_id": 1000,
        "school_name": "d6+ Primary School",
        "admin_email_address": "support@d6plus.co.za",
        "telephone_calling_code": "27",
        "telephone_number": "0123334444",
        "api_type_id": 8,
        "api_type": "Admin+ API",
        "activated_by_integrator": "Yes" // <-
    }
}
```

{% endtab %}

{% tab title="Unauthorized Error (401 Unauthorized)" %}
**Description:** This error occurs when attempting to activate an integration for a school that has not authorized your integration. Schools must first authorize the integration before it can be activated by the integrator.

**Status:** <mark style="color:red;">`401 Unauthorized`</mark>

```json5
{
    "success": false,
    "message": "Client has not authorised access"
}
```

{% endtab %}

{% tab title="Validation Error (400 Bad Request)" %}
**Description:** When validation failed for one or more fields

**Status:** <mark style="color:red;">`400 Bad Request`</mark>

```json
{
    "success": false,
    "message": "Validation Failed",
    "validation_errors": {
        "api_type_id": "The api_type_id is invalid",
        "state": "The State must be a boolean"
    }
}
```

{% endtab %}
{% endtabs %}

### Code Samples

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

```php
<?php

// API Endpoint
const BASE_URL = 'https://integrate.d6plus.co.za/api/v2/settings/clientintegrations';

// API Credentials
const API_USERNAME = 'your_username';
const API_PASSWORD = 'your_password';

// Request payload
$data = [
    "school_id"   => 1000,
    "api_type_id" => 8,
    "state"       => 1
];

// Initialize cURL
$curl = curl_init();

// Set cURL options
curl_setopt_array($curl, [
    CURLOPT_URL            => BASE_URL,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_TIMEOUT        => 30,  // Set timeout to prevent hanging requests
    CURLOPT_FOLLOWLOCATION => true,
    CURLOPT_HTTP_VERSION   => CURL_HTTP_VERSION_1_1,
    CURLOPT_CUSTOMREQUEST  => 'POST',
    CURLOPT_POSTFIELDS     => json_encode($data), // Encode array as JSON
    CURLOPT_HTTPHEADER     => [
        "Content-Type: application/json",
        "HTTP-X-USERNAME: " . API_USERNAME,
        "HTTP-X-PASSWORD: " . API_PASSWORD
    ],
]);

// Execute request
$response = curl_exec($curl);

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

// Close cURL session
curl_close($curl);

// Output response
echo $response;

```

{% endtab %}

{% tab title="cURL" %}

```bash
curl --request POST "https://integrate.d6plus.co.za/api/v2/settings/clientintegrations" \
     --header "Content-Type: application/json" \
     --header "HTTP-X-USERNAME: your_username" \
     --header "HTTP-X-PASSWORD: your_password" \
     --data '{
         "school_id": 1000,
         "api_type_id": 8,
         "state": 1
     }'
```

{% endtab %}
{% endtabs %}


# Administration+

This section details the REST endpoints to interact with the Administration+ module.

## Endpoint

The base URL for all endpoints in this module is shown below. The version number is independent per endpoint.

`https://integrate.d6plus.co.za/api/v1/`**`adminplus`**`/`


# Lookups

A number of the API endpoints return values for attributes which are list items in d6+, for example a language or grade, which can be selected from a dropdown in d6+. In order to manage and facilitate these attributes more effectively, there are a number of endpoints available to lookup one or all of the available values in the list.

Some of these lists are generic across all schools, but some can be customised per school, in which case it will be necessary to specify the desired school's Login ID in the request URL, as illustrated in the relevant endpoint documentation.


# Ethnic Group(s)

## Get the list of available ethnic groups

<mark style="color:blue;">`GET`</mark> `https://integrate.d6plus.co.za/api/v1/adminplus/lookup/ethnicgroup/{ethnic_group_id}`

Use this endpoint to retrieve the list of available ethnic groups within the d6+ SAMS. The list is generic across all d6+ SAMS clients. By default all available ethnic groups are returned.&#x20;

It is possible to retrieve the information for a single ethnic group by providing the optional `ethnic_group_id` query parameter.

#### Path Parameters

| Name              | Type    | Description                            |
| ----------------- | ------- | -------------------------------------- |
| ethnic\_group\_id | Integer | The ID of the ethnic group to retrieve |

#### 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
[
    {
        "id": "1",
        "name": "African/Black"
    },
    {
        "id": "2",
        "name": "Coloured"
    },
    {
        "id": "3",
        "name": "Indian"
    },
    {
        "id": "4",
        "name": "White"
    },
    {
        "id": "5",
        "name": "Other"
    },
    {
        "id": "6",
        "name": "Asian"
    }
]
```

{% endtab %}

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

```json
{
    "error": "Not found",
    "error_description": "No ethnic group(s) found"
}
```

{% endtab %}

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

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

{% endtab %}
{% endtabs %}

## Examples

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

```php
<?php

const BASE_URL = 'https://integrate.d6plus.co.za/api/v1/adminplus/lookup/ethnicgroup';
const ETHNIC_GROUP_ID = '1';

const API_USERNAME = getenv('API_USERNAME'); // Assuming you have these environment variables set
const API_PASSWORD = getenv('API_PASSWORD');

$curl = curl_init();

$options = [
    CURLOPT_URL => BASE_URL . '/' . ETHNIC_GROUP_ID,
    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/adminplus/lookup/ethnicgroup/1' \
--header 'HTTP-X-USERNAME: your_username' \
--header 'HTTP-X-PASSWORD: your_password'
```

{% endtab %}
{% endtabs %}


# Genders

## Get the list of available genders

<mark style="color:blue;">`GET`</mark> `https://integrate.d6plus.co.za/api/v1/adminplus/lookup/genders`

Use this endpoint to retrieve the list of available genders within the d6+ SAMS. The list is generic across all d6+ SAMS clients. All available genders are returned.&#x20;

#### 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
[
    {
        "id": "M",
        "name": "Male"
    },
    {
        "id": "F",
        "name": "Female"
    }
]
```

{% endtab %}

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

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

{% endtab %}
{% endtabs %}

## Examples

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

```php
<?php

const BASE_URL = 'https://integrate.d6plus.co.za/api/v1/adminplus/lookup/genders';

const API_USERNAME = getenv('API_USERNAME'); // Assuming you have these environment variables set
const API_PASSWORD = getenv('API_PASSWORD');

$curl = curl_init();

$options = [
    CURLOPT_URL => BASE_URL,
    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/adminplus/lookup/genders' \
--header 'HTTP-X-USERNAME: your_username' \
--header 'HTTP-X-PASSWORD: your_password'
```

{% endtab %}
{% endtabs %}


# Grade(s)

## Get the list of available grades

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

Use this endpoint to retrieve the list of available grades within the d6+ SAMS.&#x20;

The list is not generic across all d6+ SAMS clients, and could be customised per school. This endpoint allows you to specify a school Login ID in order to retrieve the list of grades offered by the school, along with their potentially customised names.&#x20;

By default all available grades are returned.&#x20;

It is also possible to retrieve the information for a single grade by providing the optional `grade_id` query 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                |
| --------- | ------ | -------------------------- |
| grade\_id | String | The ID of a specific grade |

#### 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
[
    {
        "id": "1",
        "name": "Grade RR"
    },
    {
        "id": "2",
        "name": "Grade R"
    },
    {
        "id": "3",
        "name": "Grade 1"
    },
    {
        "id": "4",
        "name": "Grade 2"
    },
    {
        "id": "5",
        "name": "Grade 3"
    },
    {
        "id": "6",
        "name": "Grade 4"
    },
    {
        "id": "7",
        "name": "Grade 5"
    },
    {
        "id": "8",
        "name": "Grade 6"
    }
]
```

{% endtab %}

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

```json
{
    "error": "Not found",
    "error_description": "No grade(s) found"
}
```

{% endtab %}

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

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

{% endtab %}
{% endtabs %}

## Examples

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

```php
<?php

const BASE_URL = 'https://integrate.d6plus.co.za/api/v1/adminplus/lookup/grade';
const SCHOOL_LOGIN_ID = '1000';
const PARAMS = [
    'grade_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/adminplus/lookup/grade/1000?grade_id=1' \
--header 'HTTP-X-USERNAME: your_username' \
--header 'HTTP-X-PASSWORD: your_password'
```

{% endtab %}
{% endtabs %}


# Language(s)

## Get the list of available languages

<mark style="color:blue;">`GET`</mark> `https://integrate.d6plus.co.za/api/v1/adminplus/lookup/language/{language_id}`

Use this endpoint to retrieve the list of available languages within the d6+ SAMS. The list is generic across all d6+ SAMS clients. By default all available languages are returned.&#x20;

It is possible to retrieve the information for a single languages by providing the optional `language_id` query parameter.

#### Path Parameters

| Name         | Type    | Description                        |
| ------------ | ------- | ---------------------------------- |
| language\_id | Integer | The ID of the language to retrieve |

#### 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
[
    {
        "id": "1",
        "name": "Afrikaans"
    },
    {
        "id": "2",
        "name": "English"
    },
    {
        "id": "3",
        "name": "Ndebele"
    },
    {
        "id": "4",
        "name": "Swazi"
    },
    {
        "id": "5",
        "name": "Xhosa"
    }
]
```

{% endtab %}

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

```json
{
    "error": "Not found",
    "error_description": "No language(s) found"
}
```

{% endtab %}

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

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

{% endtab %}
{% endtabs %}

## Examples

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

```php
<?php

const BASE_URL = 'https://integrate.d6plus.co.za/api/v1/adminplus/lookup/language';
const LANGUAGE_ID = '1';

const API_USERNAME = getenv('API_USERNAME'); // Assuming you have these environment variables set
const API_PASSWORD = getenv('API_PASSWORD');

$curl = curl_init();

$options = [
    CURLOPT_URL => BASE_URL . '/' . LANGUAGE_ID,
    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/adminplus/lookup/language/1' \
--header 'HTTP-X-USERNAME: your_username' \
--header 'HTTP-X-PASSWORD: your_password'
```

{% endtab %}
{% endtabs %}


# Marital Status(')

## Get the list of available marital status'

<mark style="color:blue;">`GET`</mark> `https://integrate.d6plus.co.za/api/v1/adminplus/lookup/maritalstatus/{marital_status_id}`

Use this endpoint to retrieve the list of available marital status' within the d6+ SAMS. The list is generic across all d6+ SAMS clients. By default all available marital status' are returned.&#x20;

It is possible to retrieve the information for a single marital status by providing the optional `marital_status_id` query parameter.

#### Path Parameters

| Name                | Type    | Description                              |
| ------------------- | ------- | ---------------------------------------- |
| marital\_status\_id | Integer | The ID of the marital status to retrieve |

#### 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
[
    {
        "id": "1",
        "name": "Divorced"
    },
    {
        "id": "2",
        "name": "Married"
    },
    {
        "id": "3",
        "name": "Single"
    },
    {
        "id": "4",
        "name": "Widowed"
    },
    {
        "id": "6",
        "name": "Separated"
    },
    {
        "id": "7",
        "name": "Common law marriage"
    }
]
```

{% endtab %}

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

```json
{
    "error": "Not found",
    "error_description": "No marital status' found"
}
```

{% endtab %}

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

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

{% endtab %}
{% endtabs %}

## Examples

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

```php
<?php

const BASE_URL = 'https://integrate.d6plus.co.za/api/v1/adminplus/lookup/maritalstatus';
const MARITAL_STATUS_ID = '1';

const API_USERNAME = getenv('API_USERNAME'); // Assuming you have these environment variables set
const API_PASSWORD = getenv('API_PASSWORD');

$curl = curl_init();

$options = [
    CURLOPT_URL => BASE_URL . '/' . MARITAL_STATUS_ID,
    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/adminplus/lookup/maritalstatus/1' \
--header 'HTTP-X-USERNAME: your_username' \
--header 'HTTP-X-PASSWORD: your_password'
```

{% endtab %}
{% endtabs %}


# School


# Get School Info

## Get the school information

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

Use this endpoint to fetch the information for the specified school.

#### Path Parameters

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

#### 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
{
    "school_name": "d6+ Primary School",
    "admin_email_address": "support@d6plus.co.za",
    "telephone_calling_code": "27",
    "telephone_number": "0123334444",
    "website": "https://d6.co.za/",
    "physical_address": "Pegasus Building 1, 3rd Floor\r\nMercy Avenue\r\nWaterkloof Glen Ext 2
\r\nPretoria",
    "quantile": "4",
    "medium": "Dual medium",
    "emis_number": "999999999",
    "country": "South Africa",
    "province": "Gauteng",
    "tuition_languages": [
        "Afrikaans",
        "English"
    ]
}
```

{% endtab %}

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

```json
{
    "error": "Not found",
    "error_description": "No school record found"
}
```

{% endtab %}

{% tab title="401: Unauthorized The server understood the request, but 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 Admin+ API for this client before making this request"
}
```

{% endtab %}
{% endtabs %}

## Examples

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

```php
<?php

const BASE_URL = 'https://integrate.d6plus.co.za/api/v1/adminplus/school';
const SCHOOL_LOGIN_ID = '1000';

const API_USERNAME = getenv('API_USERNAME'); // Assuming you have these environment variables set
const API_PASSWORD = getenv('API_PASSWORD');

$curl = curl_init();

$options = [
    CURLOPT_URL => BASE_URL . '/' . SCHOOL_LOGIN_ID,
    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/adminplus/school/1000' \
--header 'HTTP-X-USERNAME: your_username' \
--header 'HTTP-X-PASSWORD: your_password'
```

{% endtab %}
{% endtabs %}


# Learner


# Get Learner(s)

## Get one or more learner records

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

Use this endpoint to fetch one or more learner records for the specified school.  By default, all current enrolled learners will be returned.&#x20;

It is possible to retrieve non-current learners by providing the optional `status` query parameter. &#x20;

When retrieving left learners, additional optional `since` and `until` query parameters will allow you to specify a date range, and only learners who have left in this date range will be returned. By default, learners who have left in the last month will be returned. The `since` - `until` range may not be more than 1 year.

It is possible to retrieve a single learner by providing the optional `learner_id` query parameter.&#x20;

It is possible to retrieve the learners for a specific grade or grades, by providing the optional `grade_id` query parameter. This can be a single grade ID or a comma-separated list of grade ID's. The list of available grade ID's for a school can be obtained by making use of the [Grade(s) Lookup](/v2/reference/administration+/lookups/grade-s) endpoint.&#x20;

If your subscription includes the Parent API, it is possible to include the parent/guardian data directly in the learner response payload by providing the optional `include_parents` query parameter. The parent/guardian data will be included in a sub-array per learner, with  parent/guardian 1 followed by parent/guardian 2.

#### 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                                                                                                                                                                                 |
| ---------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| status           | String  | <p>The status of the learners to return. Acceptable values are:<br>\* current (default)<br>\* left<br>\* waitlist</p>                                                                       |
| since            | String  | The date to which left learner transfer dates should be limited, when using the `status` parameter. Defaults to 1 month ago. May not be more than 1 year before `until`. Format: YYYY-MM-DD |
| until            | String  | The date until which left learner transfer dates should be limited, when using the `status` parameter. Defaults to today. May not be more than 1 year after `since`. Format: YYYY-MM-DD     |
| learner\_id      | Integer | The ID of a specific learner                                                                                                                                                                |
| grade\_id        | Integer | A comma-separated list of grade ID's to filter by                                                                                                                                           |
| include\_parents | String  | Whether to include the parent data in the response                                                                                                                                          |

#### 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
[
    {
        "id": "1",
        "first_name": "John",
        "last_name": "Smith",
        "mobile_calling_code": "27",
        "mobile_number": "0823456789",
        "email_address": "jsmith@example.com",
        "date_of_birth": "2018-01-01",
        "gender": "M",
        "ethnic_group_id": "4",
        "ethnic_group": "White",        
        "home_language_id": "1",
        "home_language": "Afrikaans",
        "tuition_language_id": "1",        
        "tuition_language": "Afrikaans",
        "nationality": "South Africa",
        "admission_number": "12345",
        "family_code": "1001",
        "id_number": "1801015005084",
        "passport_number": "",
        "grade_id": "9",
        "grade": "7",
        "register_class_name": "5A",
        "register_class_teacher_id": "4",
        "country": "South Africa",
        "province": "Gauteng",        
        "education_stream": "Mainstream",
        "photo_url": "",
        "parent1_id": "40",
        "parent2_id": "41",
        "parents": [
            {
                "id": "40",
                "title": "Mr",
                "first_name": "John James",
                "last_name": "Smith",
                "mobile_calling_code": "27",
                "mobile_number": "0823456789",
                "email_address": "jjsmith@example.com",
                "date_of_birth": "1967-02-14",
                "gender": "M",
                "ethnic_group_id": "4",
                "ethnic_group": "White",
                "residential_address": "Plot 101\r\nDaffodil Street\r\nPretoria",
                "postal_address": "PO Box 12\r\nMenlyn\r\nPretoria",
                "home_language_id": "2",                
                "home_language": "English",
                "nationality": "South Africa",
                "family_code": "1001",
                "id_number": "6702145076084",
                "passport_number": "A0176543",
                "marital_status_id": "2",
                "marital_status": "Married",                
                "occupation_status": "Full Time Employed",
                "occupation": "Salesman",
                "employment_sector": "Selling",
                "gross_annual_income": "120000.00"            
            },
            {
                "id": "41",
                "title": "Mrs",
                "first_name": "Jane Jenny",
                "last_name": "Smith",
                "mobile_calling_code": "27",
                "mobile_number": "0798765432",
                "email_address": "smith.jj@example.org",
                "date_of_birth": "1955-06-17",
                "gender": "F",
                "ethnic_group_id": "1",                
                "ethnic_group": "African/Black",
                "residential_address": "Plot 101\r\nDaffodil Street\r\nPretoria",
                "postal_address": "PO Box 12\r\nMenlyn\r\nPretoria",
                "home_language_id": "2",                
                "home_language": "English",
                "nationality": "South Africa",
                "family_code": "1001",
                "id_number": "5506170079082",
                "passport_number": "",
                "marital_status_id": "2",
                "marital_status": "Married",                
                "occupation_status": "Unemployed",
                "occupation": "",
                "employment_sector": "Other",
                "gross_annual_income": "0.00"            
            }
        ]
    },
    {
        "id": "2",
        "first_name": "Jane",
        "last_name": "Doe",
        "mobile_calling_code": "27",
        "mobile_number": "0798765432",
        "email_address": "jane@example.org",
        "date_of_birth": "2018-06-13",
        "gender": "F",
        "ethnic_group_id": "1",
        "ethnic_group": "African/Black",
        "home_language_id": "1",        
        "home_language": "Afrikaans",
        "tuition_language_id": "1",        
        "tuition_language": "Afrikaans",
        "nationality": "South Africa",
        "admission_number": "12346",
        "family_code": "1001",
        "id_number": "1806130110087",
        "passport_number": "",
        "grade_id": "7",        
        "grade": "5",
        "register_class_name": "4C",
        "register_class_teacher_id": "13"
        "country": "South Africa",
        "province": "Gauteng",        
        "education_stream": "Mainstream",
        "photo_url": "",
        "parent1_id": "40",
        "parent2_id": "41",
        "parents": [
            {
                "id": "40",
                "title": "Mr",
                "first_name": "John James",
                "last_name": "Smith",
                "mobile_calling_code": "27",
                "mobile_number": "0823456789",
                "email_address": "jjsmith@example.com",
                "date_of_birth": "1967-02-14",
                "gender": "M",
                "ethnic_group_id": "4",                
                "ethnic_group": "White",
                "residential_address": "Plot 101\r\nDaffodil Street\r\nPretoria",
                "postal_address": "PO Box 12\r\nMenlyn\r\nPretoria",
                "home_language_id": "2",                
                "home_language": "English",
                "nationality": "South Africa",
                "family_code": "1001",
                "id_number": "6702145076084",
                "passport_number": "A0176543",
                "marital_status_id": "2",
                "marital_status": "Married",
                "occupation_status": "Full Time Employed",
                "occupation": "Salesman",
                "employment_sector": "Selling",
                "gross_annual_income": "120000.00"            
            },
            {
                "id": "41",
                "title": "Mrs",
                "first_name": "Jane Jenny",
                "last_name": "Smith",
                "mobile_calling_code": "27",
                "mobile_number": "0798765432",
                "email_address": "smith.jj@example.org",
                "date_of_birth": "1955-06-17",
                "gender": "F",
                "ethnic_group_id": "1",                
                "ethnic_group": "African/Black",
                "residential_address": "Plot 101\r\nDaffodil Street\r\nPretoria",
                "postal_address": "PO Box 12\r\nMenlyn\r\nPretoria",
                "home_language_id": "2",                
                "home_language": "English",
                "nationality": "South Africa",
                "family_code": "1001",
                "id_number": "5506170079082",
                "passport_number": "",
                "marital_status_id": "2",
                "marital_status": "Married",
                "occupation_status": "Unemployed",
                "occupation": "",
                "employment_sector": "Other",
                "gross_annual_income": "0.00"            
            }
        ]
    }
]
```

{% endtab %}

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

```json
{
    "error": "Not found",
    "error_description": "No learner 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 Admin+ API for this client before making this request"
}
```

{% endtab %}
{% endtabs %}

## Examples

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

```php
<?php

const BASE_URL = 'https://integrate.d6plus.co.za/api/v1/adminplus/learners';
const SCHOOL_LOGIN_ID = '1000';
const PARAMS = [
    'learner_id' => 1, 
    'include_parents' => 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/adminplus/learners/1000?learner_id=1&include_parents=1' \
--header 'HTTP-X-USERNAME: your_username' \
--header 'HTTP-X-PASSWORD: your_password'
```

{% endtab %}
{% endtabs %}


# Get Learner Absentees

## Get learner absentee records

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

Use this endpoint to fetch absentee records for one or more learners for the specified school.  By default, all absentee records for the last month will be returned, regardless of the associated learners current status.

It is possible to retrieve absentee records for a single learner by providing the optional `learner_id` query parameter.

It is possible to specify a different date range by providing the optional `from_date` and `to_date` query parameters. \
The following validation applies:\
\- The `to_date` may not be before the `from_date`. \
\- The date range may not span more than 31 days.

#### 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                           |
| ----------- | ------- | ------------------------------------- |
| learner\_id | Integer | The ID of a specific learner          |
| to\_date    | String  | Range end date in format YYYY-MM-DD   |
| from\_date  | String  | Range start date in format YYYY-MM-DD |

#### 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
[
    {
        "id": "399910",
        "learner_id": "6273",
        "absent_date": "2023-06-01",
        "absent_reason": "Illness"
    },
    {
        "id": "399912",
        "learner_id": "6273",
        "absent_date": "2023-06-02",
        "absent_reason": "Illness"
    }
]
```

{% endtab %}

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

```json
{
    "error": "Not found",
    "error_description": "No learner absentee 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="400: Bad Request The request was invalid. Normally due to missing or malformed parameters." %}

```json
{
    "error": "Bad Request",
    "error_description": "The specified date range may not be more than 31 days"
}
```

{% 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 Admin+ API for this client before making this request"
}
```

{% endtab %}
{% endtabs %}

## Examples

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

```php
<?php

const BASE_URL = 'https://integrate.d6plus.co.za/api/v1/adminplus/learnerabsentees';
const SCHOOL_LOGIN_ID = '1000';
const PARAMS = [
    'learner_id' => 1,
    'from_date' => '2023-06-01',
    'to_date' => '2023-06-14'
];
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/adminplus/learnerabsentees/1000?learner_id=1&from_date=2023-06-01&to_date=2023-06-14' \
--header 'HTTP-X-USERNAME: your_username' \
--header 'HTTP-X-PASSWORD: your_password'
```

{% endtab %}
{% endtabs %}


# Get Learner Discipline

## Get learner discipline records

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

Use this endpoint to fetch discipline records for one or more learners for the specified school.  By default, all discipline records for the last month will be returned, regardless of the associated learners current status.&#x20;

It is possible to retrieve discipline records for a single learner by providing the optional `learner_id` query parameter.

It is possible to specify a different date range by providing the optional `from_date` and `to_date` query parameters. \
The following validation applies:\
\- The `to_date` may not be before the `from_date`. \
\- The date range may not span more than 31 days.

#### 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                           |
| ----------- | ------- | ------------------------------------- |
| learner\_id | Integer | The ID of a specific learner          |
| to\_date    | String  | Range end date in format YYYY-MM-DD   |
| from\_date  | String  | Range start date in format YYYY-MM-DD |

#### 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
[
    {
        "id": "1",
        "learner_id": "2",
        "discipline_date": "2023-06-30",
        "discipline_category": "Level 1",
        "discipline_reason": "Appearance : Hair / Nails",
        "discipline_points": "-1",
        "discipline_remarks": "",
        "staff_member_id": "3"
    },
    {
        "id": "2",
        "learner_id": "1",
        "discipline_date": "2023-07-03",
        "discipline_category": "General",
        "discipline_reason": "Handed in lost goods/money",
        "discipline_points": "3",
        "discipline_remarks": "",
        "staff_member_id": "4"
    }
]
```

{% endtab %}

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

```json
{
    "error": "Not found",
    "error_description": "No learner discipline 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="400: Bad Request The request was invalid. Normally due to missing or malformed parameters." %}

```json
{
    "error": "Bad Request",
    "error_description": "The specified date range may not be more than 31 days"
}
```

{% 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 Admin+ API for this client before making this request"
}
```

{% endtab %}
{% endtabs %}

## Examples

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

```php
<?php

const BASE_URL = 'https://integrate.d6plus.co.za/api/v1/adminplus/learnerdiscipline';
const SCHOOL_LOGIN_ID = '1000';
const PARAMS = [
    'learner_id' => 1,
    'from_date' => '2023-06-01',
    'to_date' => '2023-06-14'
];
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/adminplus/learnerdiscipline/1000?learner_id=1&from_date=2023-06-01&to_date=2023-06-14' \
--header 'HTTP-X-USERNAME: your_username' \
--header 'HTTP-X-PASSWORD: your_password'
```

{% endtab %}
{% endtabs %}


# Parent


# Get Parent(s)

## Get one or more parent records

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

Use this endpoint to fetch one or more parent records for the specified school.  By default, parents of all current active learners will be returned.&#x20;

It is possible to retrieve a single parent by providing the optional `parent_id` query 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                 |
| ---------- | ------- | --------------------------- |
| parent\_id | Integer | The ID of a specific parent |

#### 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
[
    {
        "id": "40",
        "title": "Mr",
        "first_name": "John James",
        "last_name": "Smith",
        "mobile_calling_code": "27",
        "mobile_number": "0823456789",
        "email_address": "jjsmith@example.com",
        "date_of_birth": "1967-02-14",
        "gender": "M",
        "ethnic_group_id": "4",
        "ethnic_group": "White",
        "residential_address": "Plot 101\r\nDaffodil Street\r\nPretoria",
        "postal_address": "PO Box 12\r\nMenlyn\r\nPretoria",
        "home_language_id": "2",
        "home_language": "English",
        "nationality": "South Africa",
        "family_code": "1001",
        "id_number": "6702145076084",
        "passport_number": "A0176543",
        "marital_status_id": "2",
        "marital_status": "Married",
        "occupation_status": "Full Time Employed",
        "occupation": "Salesman",
        "employment_sector": "Selling",
        "gross_annual_income": "120000.00"
    },
    {
        "id": "41",
        "title": "Mrs",
        "first_name": "Jane Jenny",
        "last_name": "Smith",
        "mobile_calling_code": "27",
        "mobile_number": "0798765432",
        "email_address": "smith.jj@example.org",
        "date_of_birth": "1955-06-17",
        "gender": "F",
        "ethnic_group_id": "1",
        "ethnic_group": "African/Black",
        "residential_address": "Plot 101\r\nDaffodil Street\r\nPretoria",
        "postal_address": "PO Box 12\r\nMenlyn\r\nPretoria",
        "home_language_id": "2",
        "home_language": "English",
        "nationality": "South Africa",
        "family_code": "1001",
        "id_number": "5506170079082",
        "passport_number": "",
        "marital_status_id": "2",
        "marital_status": "Married",
        "occupation_status": "Unemployed",
        "occupation": "",
        "employment_sector": "Other",
        "gross_annual_income": "0.00"
    }
]
```

{% endtab %}

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

```json
{
    "error": "Not found",
    "error_description": "No parent 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 Admin+ API for this client before making this request"
}
```

{% endtab %}
{% endtabs %}

## Examples

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

```php
<?php

const BASE_URL = 'https://integrate.d6plus.co.za/api/v1/adminplus/parents';
const SCHOOL_LOGIN_ID = '1000';
const PARAMS = ['parent_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/adminplus/parents/1000?parent_id=1' \
--header 'HTTP-X-USERNAME: your_username' \
--header 'HTTP-X-PASSWORD: your_password'
```

{% endtab %}
{% endtabs %}


# Staff Member


# Get Staff Member(s)

## Get one or more staff member records

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

Use this endpoint to fetch one or more staff member records for the specified school.  By default all current active staff members will be returned.&#x20;

It is possible to retrieve a single staff member by providing the optional `staff_member_id` query 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                       |
| ----------------- | ------- | --------------------------------- |
| staff\_member\_id | Integer | The ID of a specific staff member |

#### 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
[
    {
        "id": "1",
        "title": "Mr",
        "first_name": "John",
        "last_name": "Smith",
        "mobile_calling_code": "27",
        "mobile_number": "0823456789",
        "email_address": "jjsmith@example.com",
        "date_of_birth": "1967-02-14",
        "gender": "M",
        "ethnic_group": "White",
        "residential_address": "Plot 101\r\nDaffodil Street\r\nPretoria",
        "postal_address": "PO Box 12\r\nMenlyn\r\nPretoria",
        "home_language": "English",
        "nationality": "South Africa",
        "id_number": "6702145076084",
        "passport_number": "A0176543",
        "marital_status_id": "Married",
        "employment_category": "Finance",
        "is_educator": "Yes",
        "appointment_type": "Temporary",
        "paid_by": "Department of Education",
        "sace_number": "123456",
        "register_classes": "2A"
    },
    {
        "id": "2",
        "title": "Mrs",
        "first_name": "Jane",
        "last_name": "Smith",
        "mobile_calling_code": "27",
        "mobile_number": "0798765432",
        "email_address": "smith.jj@example.org",
        "date_of_birth": "1955-06-17",
        "gender": "F",
        "ethnic_group": "African/Black",
        "residential_address": "Plot 101\r\nDaffodil Street\r\nPretoria",
        "postal_address": "PO Box 12\r\nMenlyn\r\nPretoria",
        "home_language": "English",
        "nationality": "South Africa",
        "id_number": "5506170079082",
        "passport_number": "",
        "marital_status_id": "Married",
        "employment_category": "Head Of Department",
        "is_educator": "No",
        "appointment_type": "Permanent",
        "paid_by": "Governing Body",
        "sace_number": "234567",
        "register_classes": "1A,2B,5A"
    }
]
```

{% endtab %}

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

```json
{
    "error": "Not found",
    "error_description": "No staff member 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 Admin+ API for this client before making this request"
}
```

{% endtab %}
{% endtabs %}

## Examples

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

```php
<?php

const BASE_URL = 'https://integrate.d6plus.co.za/api/v1/adminplus/staffmembers';
const SCHOOL_LOGIN_ID = '1000';
const PARAMS = ['staff_member_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/adminplus/staffmembers/1000?staff_member_id=1' \
--header 'HTTP-X-USERNAME: your_username' \
--header 'HTTP-X-PASSWORD: your_password'
```

{% endtab %}
{% endtabs %}


# Curriculum+

This section details the REST endpoints to interact with the Curriculum+ module.

## Endpoint

The base URL for all endpoints in this module is shown below. The version number is independent per endpoint.

`https://integrate.d6plus.co.za/api/v1/`**`currplus`**`/`


# Learner


# Get Learner Subjects

## Get the subject records for one or more learners

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

Use this endpoint to fetch the list of subjects for the current year for one or more learner for the specified school.  By default, the subjects for all current active learners will be returned.&#x20;

It is possible to retrieve the subjects for a single learner by providing the optional `learner_id` query 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                  |
| ----------- | ------- | ---------------------------- |
| learner\_id | Integer | The ID of a specific learner |

#### 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
[
    {
        "learner_id": "1",
        "first_name": "Janey",
        "last_name": "Smith",
        "subject_id": 101,
        "subject_name": "Afrikaans Home Language (Gr 05)"
    },
    {
        "learner_id": "1",
        "first_name": "Janey",
        "last_name": "Smith",
        "subject_id": 105,        
        "subject_name": "English First Additional Language (Gr 05)"
    },
    {
        "learner_id": "1",
        "first_name": "Janey",
        "last_name": "Smith",
        "subject_id": 201,        
        "subject_name": "Life Skills (Gr 05)"
    },
    {
        "learner_id": "1",
        "first_name": "Janey",
        "last_name": "Smith",
        "subject_id": 135,        
        "subject_name": "Mathematics (Gr 05)"
    },
    {
        "learner_id": "1",
        "first_name": "Janey",
        "last_name": "Smith",
        "subject_id": 322,
        "subject_name": "Natural Sciences and Technology (Gr 05)"
    },
    {
        "learner_id": "1",
        "first_name": "Janey",
        "last_name": "Smith",
        "subject_id": 49,        
        "subject_name": "Social Sciences (Gr 05)"
    }
]
```

{% endtab %}

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

```json
{
    "error": "Not found",
    "error_description": "No learner subject 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 %}
{% endtabs %}

## Examples

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

```php
<?php

const BASE_URL = 'https://integrate.d6plus.co.za/api/v1/currplus/learnersubjects';
const SCHOOL_LOGIN_ID = '1000';
const PARAMS = ['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/learnersubjects/1000?learner_id=1' \
--header 'HTTP-X-USERNAME: your_username' \
--header 'HTTP-X-PASSWORD: your_password'
```

{% endtab %}
{% endtabs %}


# Get Learner Subjects Per Term

## Get the subject records for a learner per term

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

Use this endpoint to fetch the subjects per term for the specified learner, for the specified school.  \
All subjects for all terms will be return, for the current d6+ administrative year. \
The results are grouped per term, per subject, for the current administrative year.&#x20;

#### 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                  |
| --------------------------------------------- | ------- | ---------------------------- |
| learner\_id<mark style="color:red;">\*</mark> | Integer | The ID of a specific learner |

#### 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
[
    {
        "year": "2025",
        "subject_id": "10",
        "subject_name": "Afrikaans First Additional Language (Gr 07)",
        "super_subject_id": "1",
        "super_subject_name": "Afrikaans First Additional Language",
        "grade_id": "9",
        "grade": "7",
        "terms": [
            {
                "term_id": 98,
                "term": "1",
                "subject_group_id": "118",
                "subject_group_name": "Afrikaans Group 1",
                "classroom_id": "1",
                "classroom_name": "1",
                "subject_group_teacher_id": "13"
            },
            {
                "term_id": 99,
                "term": "2",
                "subject_group_id": "118",
                "subject_group_name": "Afrikaans Group 1",
                "classroom_id": "1",
                "classroom_name": "1",
                "subject_group_teacher_id": "13"
            },
            {
                "term_id": 100,
                "term": "3",
                "subject_group_id": "270",
                "subject_group_name": "Afrikaans Group 2",
                "classroom_id": "4",
                "classroom_name": "3A",
                "subject_group_teacher_id": "17"
            },
            {
                "term_id": 101,
                "term": "4",
                "subject_group_id": "270",
                "subject_group_name": "Afrikaans Group 2",
                "classroom_id": "4",
                "classroom_name": "3A",
                "subject_group_teacher_id": "17"
            }
        ]
    },
    {
        "year": "2025",
        "subject_id": "3418",
        "subject_name": "Coding and Robotics (Gr 07)",
        "super_subject_id": "2334",
        "super_subject_name": "Coding and Robotics",
        "grade_id": "9",
        "grade": "7",
        "terms": [
            {
                "term_id": 98,
                "term": "1",
                "subject_group_id": "119",
                "subject_group_name": "Coding 1A",
                "classroom_id": "2",
                "classroom_name": "2",
                "subject_group_teacher_id": "4"
            },
            {
                "term_id": 99,
                "term": "2",
                "subject_group_id": "119",
                "subject_group_name": "Coding 1A",
                "classroom_id": "2",
                "classroom_name": "2",
                "subject_group_teacher_id": "4"
            },
            {
                "term_id": 100,
                "term": "3",
                "subject_group_id": "322",
                "subject_group_name": "Coding 1B",
                "classroom_id": "9",
                "classroom_name": "K4",
                "subject_group_teacher_id": "17"
            },
            {
                "term_id": 101,
                "term": "4",
                "subject_group_id": "322",
                "subject_group_name": "Coding 1B",
                "classroom_id": "9",
                "classroom_name": "K4",
                "subject_group_teacher_id": "17"
            }
        ]
    }
]
```

{% endtab %}

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

```json
{
    "error": "Not found",
    "error_description": "No learner subject 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 learner_id request parameter."
}
```

{% endtab %}
{% endtabs %}

## Examples

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

```php
<?php

const BASE_URL = 'https://integrate.d6plus.co.za/api/v1/currplus/learnersubjectsperterm';
const SCHOOL_LOGIN_ID = '1000';
const PARAMS = ['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/learnersubjectsperterm/1000?learner_id=1' \
--header 'HTTP-X-USERNAME: your_username' \
--header 'HTTP-X-PASSWORD: your_password'
```

{% endtab %}
{% endtabs %}


# Get Learner Subject Marks

## Get the subject marks records for a learner

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

Use this endpoint to fetch the marks for the specified learner, for the specified school.  \
All marks for all terms will be return, for the current d6+ administrative year. \
The results are grouped per term, per subject, for the current administrative year.&#x20;

#### 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                  |
| --------------------------------------------- | ------- | ---------------------------- |
| learner\_id<mark style="color:red;">\*</mark> | Integer | The ID of a specific learner |

#### 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
[
    {
        "year": "2023",
        "subject_id": "21",
        "subject_name": "Afrikaans Home Language (Gr 05)",
        "grade_id": "7",
        "grade": "5",
        "terms": [
            {
                "term": "1",
                "mark": "80.00"
            },
            {
                "term": "2",
                "mark": "72.86"
            }
        ]
    },
    {
        "year": "2023",
        "subject_id": "105",
        "subject_name": "English First Additional Language (Gr 05)",
        "grade_id": "7",
        "grade": "5",
        "terms": [
            {
                "term": "1",
                "mark": "70.00"
            },
            {
                "term": "2",
                "mark": "77.14"
            }
        ]
    },
    {
        "year": "2023",
        "subject_id": "314",
        "subject_name": "Life Skills (Gr 05)",
        "grade_id": "7",
        "grade": "5",
        "terms": [
            {
                "term": "1",
                "mark": "60.00"
            },
            {
                "term": "2",
                "mark": "96.00"
            }
        ]
    },
    {
        "year": "2023",
        "subject_id": "327",
        "subject_name": "Mathematics (Gr 05)",
        "grade_id": "7",
        "grade": "5",
        "terms": [
            {
                "term": "1",
                "mark": "75.00"
            },
            {
                "term": "2",
                "mark": "96.00"
            }
        ]
    },
    {
        "year": "2023",
        "subject_id": "355",
        "subject_name": "Natural Sciences and Technology (Gr 05)",
        "grade_id": "7",
        "grade": "5",
        "terms": [
            {
                "term": "1",
                "mark": "65.00"
            },
            {
                "term": "2",
                "mark": "88.33"
            }
        ]
    },
    {
        "year": "2023",
        "subject_id": "533",
        "subject_name": "Social Sciences (Gr 05)",
        "grade_id": "7",
        "grade": "5",
        "terms": [
            {
                "term": "1",
                "mark": "85.00"
            },
            {
                "term": "2",
                "mark": "90.00"
            }
        ]
    }
]
```

{% 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 learner_id request parameter."
}
```

{% endtab %}
{% endtabs %}

## Examples

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

```php
<?php

const BASE_URL = 'https://integrate.d6plus.co.za/api/v1/currplus/learnersubjectmarks';
const SCHOOL_LOGIN_ID = '1000';
const PARAMS = ['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/learnersubjectmarks/1000?learner_id=1' \
--header 'HTTP-X-USERNAME: your_username' \
--header 'HTTP-X-PASSWORD: your_password'
```

{% endtab %}
{% endtabs %}


# Finance+

This section details the v2 REST endpoints to interact with the Finance+ module.

## Endpoint

The base URL for all endpoints in this module is shown below.

<pre class="language-url"><code class="lang-url">https://integrate.d6plus.co.za/api/<a data-footnote-ref href="#user-content-fn-1">v2</a>/finplus/
</code></pre>

[^1]: This documentation relates to v2 of the API


# Debt Management

All debt management related API calls are grouped under the Debt Management section. The base URL is as follows:

<pre class="language-url"><code class="lang-url">https://integrate.d6plus.co.za/api/<a data-footnote-ref href="#user-content-fn-1">v2</a>/finplus/debtmanagement/
</code></pre>

[^1]: This documentation relates to v2 of the API


# Debtor Notes

## Overview

The **Debtor Notes API** allows you to **create, update, or delete** debtor notes. This includes different types of notes, such as **Internal Notes, Text Notes,** and **Promise to Pay arrangements** (see the [Get Note Types](/v2/reference/finance+/debt-management/debtor-notes/get-note-type-s) page for more information).

* **Create / Update a Debtor Note:**\
  Use the Debtor Notes API to add or modify a note. This applies to all note types, including **Promise to Pay arrangements**.
* **Delete a Debtor Note:**\
  Standard debtor notes can be deleted using the Debtor Notes API.
* **Updating and Deleting Promise to Pay Arrangements:**
  * Promise to Pay arrangements are **created** as part of a debtor note.
  * To **update an individual Promise to Pay arrangement** you can either send it in the `promise_to_pays` array of an Update Note call, or use the **separate Update Promise to Pay API call** to change just that one record.
  * To **delete individual Promise to Pay arrangements** from a note, you must use the **separate Delete Promise to Pay API call**.

### Debtor Notes API Calls

[Get Communication Type(s)](/v2/reference/finance+/debt-management/debtor-notes/get-communication-type-s)

[Get Note Type(s)](/v2/reference/finance+/debt-management/debtor-notes/get-note-type-s)

[Get Note](/v2/reference/finance+/debt-management/debtor-notes/get-note-s)

[Update Note](/v2/reference/finance+/debt-management/debtor-notes/update-note)

[Delete Note](/v2/reference/finance+/debt-management/debtor-notes/delete-note)

[Get Promise to Pay(s)](/v2/reference/finance+/debt-management/debtor-notes/get-promise-to-pay-record-s)

[Update Promise to Pay](/v2/reference/finance+/debt-management/debtor-notes/update-promise-to-pay)

[Delete Promise to Pay](/v2/reference/finance+/debt-management/debtor-notes/delete-promise-to-pay)


# Get Communication Type(s)

<mark style="color:blue;">`GET`</mark> `/v2/finplus/debtmanagement/debtornotes/communicationtypes` `(/{id})`

This endpoint retrieves a list of available debtor note communication types, such as **SMS, Email, Telephonic,** and others. These types define the method used to communicate with debtors regarding their accounts.

{% hint style="info" %}
By default, this endpoint returns a **collection of records**, wrapped in a `data` array. To retrieve a **single record**, provide its **ID in the URL**, which will return a **single object** instead of a collection.
{% endhint %}

### Path Parameters

<table><thead><tr><th width="143.6859130859375">Name</th><th width="102">Type</th><th>Description</th></tr></thead><tbody><tr><td><code>{id}</code></td><td>Integer</td><td>Optionally provide the <strong>Communication Type ID</strong> for retrieving a single record.</td></tr></tbody></table>

### Request Headers

<table><thead><tr><th width="260.3714599609375">Name</th><th width="94.4857177734375">Type</th><th>Description</th></tr></thead><tbody><tr><td><code>HTTP-X-USERNAME</code><mark style="color:red;">*</mark></td><td>String</td><td>As provided by d6</td></tr><tr><td><code>HTTP-X-PASSWORD</code><mark style="color:red;">*</mark></td><td>String</td><td>As provided by d6</td></tr><tr><td><code>HTTP-X-SCHOOLID</code><mark style="color:red;">*</mark></td><td>Integer</td><td>The unique identifier of the school for which the data is being queried.</td></tr></tbody></table>

### Response Examples

{% tabs %}
{% tab title="Success - Collection (200 OK)" %}
**Status:** <mark style="color:green;">`200 OK`</mark>

```json
{
    "data": [
        {
            "id": 1,
            "name": "SMS"
        },
        {
            "id": 2,
            "name": "E-mail"
        },
        {
            "id": 3,
            "name": "Telephonic"
        },
        ...
    ]
}
```

{% endtab %}

{% tab title="Success - Resource (200 OK)" %}
**Description:** When querying a specific communication type ID

**Status:** <mark style="color:green;">`200 OK`</mark>

```json
{
    "id": 2,
    "name": "E-mail"
}
```

{% endtab %}

{% tab title="ID Not Found Error (404 Not Found)" %}
**Description:** The requested ID does not exist in the system.

**Status:** <mark style="color:red;">`404 Not Found`</mark>

```json
{
    "success": false,
    "message": "The note type does not exist"
}
```

{% endtab %}
{% endtabs %}

### Code Samples

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

```php
<?php

// API Credentials
$api_username = 'your_username';
$api_password = 'your_password';
$school_id = 'the_school_id';

// Base API endpoint
define('BASE_URL', 'https://integrate.d6plus.co.za/api/v2/finplus/debtmanagement/debtornotes/communicationtypes');

// Optional: Set an ID to fetch a specific communication type (or leave empty for all)
$id = '';

$url = BASE_URL;
if (!empty($id)) {
    $url .= '/' . $id;
}

// Initialize cURL
$curl = curl_init();

// Set cURL options
curl_setopt_array($curl, [
    CURLOPT_URL            => $url,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_TIMEOUT        => 30,  // Set timeout to prevent hanging requests
    CURLOPT_FOLLOWLOCATION => true,
    CURLOPT_HTTP_VERSION   => CURL_HTTP_VERSION_1_1,
    CURLOPT_CUSTOMREQUEST  => 'GET',
    CURLOPT_HTTPHEADER     => [
        "HTTP-X-USERNAME: $api_username",
        "HTTP-X-PASSWORD: $api_password",
        "HTTP-X-SCHOOLID: $school_id"
    ],
]);

// Execute request
$response = curl_exec($curl);

// Check for errors
$error = curl_error($curl);
if ($error) {
    curl_close($curl);
    throw new Exception("cURL Error: $error");
}

// Close cURL and output response
curl_close($curl);
echo $response;

```

{% endtab %}

{% tab title="cURL" %}

<pre class="language-bash"><code class="lang-bash">curl --location --request GET 'https://integrate.d6plus.co.za/api/v2/finplus/debtmanagement/debtornotes/communicationtypes' \
<strong>     --header 'HTTP-X-USERNAME: your_username' \
</strong>     --header 'HTTP-X-PASSWORD: your_password' \
     --header 'HTTP-X-SCHOOLID: the_school_id'
</code></pre>

{% endtab %}
{% endtabs %}


# Get Note Type(s)

<mark style="color:blue;">`GET`</mark> `/v2/finplus/debtmanagement/debtornotes/notetypes` `(/{id})`

This endpoint retrieves a list of available debtor note types.

Debtor Notes consist of three types: **Internal Note, Text Note,** and **Promise to Pay Arrangement**.

1. **Internal Note**: As the name suggests, this is an internal record for the school. It allows staff to document conversations and interactions with debtors for reference.
2. **Text Note**: Similar to an internal note, but with the distinction that it is typically **printed on the debtor’s statement**.
3. **Promise to Pay Arrangement**: This represents a commitment from the debtor to make specific payments on agreed-upon dates. The system records these arrangements and provides reminders to the school for follow-ups.

{% hint style="info" %}
By default, this endpoint returns a **collection of records**, wrapped in a `data` array. To retrieve a **single record**, provide its **ID in the URL**, which will return a **single object** instead of a collection.
{% endhint %}

### Path Parameters

<table><thead><tr><th width="138.20001220703125">Name</th><th width="102">Type</th><th>Description</th></tr></thead><tbody><tr><td><code>{id}</code></td><td>Integer</td><td>Optionally provide the <strong>Note Type ID</strong> for retrieving a single record.</td></tr></tbody></table>

### Request Headers

<table><thead><tr><th width="260.37152099609375">Name</th><th width="94.4857177734375">Type</th><th>Description</th></tr></thead><tbody><tr><td><code>HTTP-X-USERNAME</code><mark style="color:red;">*</mark></td><td>String</td><td>As provided by d6</td></tr><tr><td><code>HTTP-X-PASSWORD</code><mark style="color:red;">*</mark></td><td>String</td><td>As provided by d6</td></tr><tr><td><code>HTTP-X-SCHOOLID</code><mark style="color:red;">*</mark></td><td>Integer</td><td>The unique identifier of the school for which the data is being queried.</td></tr></tbody></table>

### Response Examples

{% tabs %}
{% tab title="Success - Collection (200 OK)" %}
**Status:** <mark style="color:green;">`200 OK`</mark>&#x20;

```json
{
    "data": [
        {
            "id": 1,
            "name": "Text note"
        },
        {
            "id": 2,
            "name": "Promise to pay"
        },
        {
            "id": 3,
            "name": "Internal note"
        }
    ]
}
```

{% endtab %}

{% tab title="Success - Resource (200 OK)" %}
**Description:** When querying a specific note type ID

**Status:** <mark style="color:green;">`200 OK`</mark>

```json
{
    "id": 2,
    "name": "Promise to pay"
}
```

{% endtab %}

{% tab title="ID Not Found Error (404 Not Found)" %}
**Description:** The requested ID does not exist in the system.

**Status:** <mark style="color:red;">`404 Not Found`</mark>

```json
{
    "success": false,
    "message": "The note type does not exist"
}
```

{% endtab %}
{% endtabs %}

### Code Samples

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

```php
<?php

// API Credentials
$api_username = 'your_username';
$api_password = 'your_password';
$school_id = 'the_school_id';

// Base API endpoint
define('BASE_URL', 'https://integrate.d6plus.co.za/api/v2/finplus/debtmanagement/debtornotes/notetypes');

// Optional: Set an ID to fetch a specific note type (or leave empty for all)
$id = '';

$url = BASE_URL;
if (!empty($id)) {
    $url .= '/' . $id;
}

// Initialize cURL
$curl = curl_init();

// Set cURL options
curl_setopt_array($curl, [
    CURLOPT_URL            => $url,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_TIMEOUT        => 30,  // Set timeout to prevent hanging requests
    CURLOPT_FOLLOWLOCATION => true,
    CURLOPT_HTTP_VERSION   => CURL_HTTP_VERSION_1_1,
    CURLOPT_CUSTOMREQUEST  => 'GET',
    CURLOPT_HTTPHEADER     => [
        "HTTP-X-USERNAME: $api_username",
        "HTTP-X-PASSWORD: $api_password",
        "HTTP-X-SCHOOLID: $school_id"
    ],
]);

// Execute request
$response = curl_exec($curl);

// Check for errors
$error = curl_error($curl);
if ($error) {
    curl_close($curl);
    throw new Exception("cURL Error: $error");
}

// Close cURL and output response
curl_close($curl);
echo $response;

```

{% endtab %}

{% tab title="cURL" %}

```bash
curl --request GET 'https://integrate.d6plus.co.za/api/v2/finplus/debtmanagement/debtornotes/notetypes' \
     --header 'HTTP-X-USERNAME: your_username' \
     --header 'HTTP-X-PASSWORD: your_password' \
     --header 'HTTP-X-SCHOOLID: the_school_id'
```

{% endtab %}
{% endtabs %}


# Get Note(s)

<mark style="color:blue;">`GET`</mark> `/v2/finplus/debtmanagement/debtornotes/notes/` `(/{id})`

Use this endpoint to **fetch one or more debtor note records** for the specified school.

**Deleted** debtor notes are excluded by default but **can be included** by setting the optional `include_deleted` query parameter.

Additionally, you can **search for debtor notes** using the **`debtor_code`**, **`accountable_person_id`**, and/or **`note_type_id`** query parameters. To return notes for **a specific year**, use the **`year`** query parameter.s

To **include "Promise to Pay" records** directly in the response, set the **`include_promise_to_pays`** query parameter. The payment arrangement data will be included in a **sub-array within each note**.

{% hint style="info" %}
By default, this endpoint returns a **collection of records**, wrapped in a `data` array. To retrieve a **single record**, provide its **ID in the URL**, which will return a **single object** instead of a collection.
{% endhint %}

### Pagination

The response data includes a `meta` object that contains **pagination-specific metadata**. You can use the following query parameters to **control pagination**:

* **limit**: This parameter allows you to override the default limit of records returned, up to the `max_allowed_limit` specified in the response's `meta` object.
* **cursor**: If the `meta` object contains a `next_cursor` field, it indicates that more records are available. To fetch the next set of records, include the `cursor` parameter in your request with the value of `next_cursor`. If the `next_cursor` field is not present, it means there are no more records to retrieve.
* **reverse\_order**: This parameter can be used to reverse the order in which the data is returned, useful for fetching the latest records first.

### Path Parameters

<table><thead><tr><th width="184.5712890625">Name</th><th width="120.68572998046875">Type</th><th>Description</th></tr></thead><tbody><tr><td><code>{id}</code></td><td>Integer</td><td>Optionally provide the <strong>Note ID</strong> for retrieving a single record.</td></tr></tbody></table>

### Request Headers

<table><thead><tr><th width="226.60003662109375">Name</th><th width="117.0286865234375">Type</th><th>Description</th></tr></thead><tbody><tr><td><code>HTTP-X-USERNAME</code><mark style="color:red;">*</mark></td><td>String</td><td>As provided by d6</td></tr><tr><td><code>HTTP-X-PASSWORD</code><mark style="color:red;">*</mark></td><td>String</td><td>As provided by d6</td></tr><tr><td><code>HTTP-X-SCHOOLID</code><mark style="color:red;">*</mark></td><td>Integer</td><td>The unique identifier of the school for which the data is being queried.</td></tr></tbody></table>

### Query Parameters

<table><thead><tr><th width="234.05712890625">Name</th><th width="116.60003662109375">Type</th><th>Description</th></tr></thead><tbody><tr><td><code>note_type_id</code></td><td>Integer</td><td>To only return notes of a given note type</td></tr><tr><td><code>communication_type_id</code></td><td>Integer</td><td>To only return notes of a given communication type</td></tr><tr><td><code>accountable_person_id</code></td><td>Integer</td><td>To only return a specific accountable person's notes</td></tr><tr><td><code>debtor_code</code></td><td>Integer</td><td>To only return a given debtor code's notes</td></tr><tr><td><code>year</code></td><td>Integer</td><td>To filter on a specific year</td></tr><tr><td><code>include_deleted</code></td><td>Boolean</td><td>Whether to include notes that have been deleted already</td></tr><tr><td><code>include_promise_to_pays</code></td><td>Boolean</td><td>Whether to include promise-to-pay data in the response</td></tr><tr><td><code>cursor</code></td><td>String</td><td>To retrieve the next group of items (if any)</td></tr><tr><td><code>limit</code></td><td>Integer</td><td>To override the default limit of records returned (up to the <code>max_allowed_limit</code> provided in the response metadata).</td></tr><tr><td><code>reverse_order</code></td><td>Boolean</td><td>To reverse the order the data is returned in</td></tr></tbody></table>

### Response Examples

{% tabs %}
{% tab title="Success - Collection (200 OK)" %}
**Status:** <mark style="color:green;">`200 OK`</mark>

```json
{
    "data": [
        {
            "note_id": 6,
            "accountable_person_id": 40,
            "accountable_person": "Mr James, John",
            "debtor_code": "1001",
            "debtor_reference": "James",
            "date": "2024-03-03",
            "note_type_id": 2,
            "note_type": "Promise to Pay",
            "communication_type_id": 2,
            "communication_type": "E-mail",
            "note": "Payment arrangement of R1000 to be paid off on outstanding school fees",
            "status": "Created"
        },
        {
            "note_id": 7
            "accountable_person_id": 3,
            "accountable_person": "Mr Webster, Nic",
            "debtor_code": "1002",
            "debtor_reference": "Webster",
            "date": "2024-04-15",
            "note_type_id": 3
            "note_type": "Internal",
            "communication_type_id": 7,
            "communication_type": "Internal",
            "note": "Mr Webster asked to be phoned back tomorrow at 2pm",
            "status": "Created"
        }
    ],
    "meta": {
        "limit": 10,
        "max_allowed_limit": 50,
        "next_cursor": "eyJpZCI6MjU0NiwiX2JhY2t3YXJkIjpmYWxzZX0"
    }
}
```

{% endtab %}

{% tab title="Success Including Promise to Pays (200 OK)" %}
**Status:** <mark style="color:green;">`200 OK`</mark>

```json
{
    "data": [
        {
            "note_id": 6,
            "accountable_person_id": 40,
            "accountable_person": "Mr James, John",
            "debtor_code": "1001",
            "debtor_reference": "James",
            "date": "2024-03-03",
            "note_type_id": 2,
            "note_type": "Promise to Pay",
            "communication_type_id": 2,
            "communication_type": "E-mail",
            "note": "Payment arrangement of R1000 to be paid off on outstanding school fees",
            "status": "Created",
            "promise_to_pays": [
                {
                    "promise_to_pay_id": 8,
                    "date_promised": "2024-03-31",
                    "amount_promised": "1000.00",
                    "amount_paid": "1000.00",
                    "promise_completed": "Yes"
                },
                {
                    "promise_to_pay_id": 10,
                    "date_promised": "2024-04-30",
                    "amount_promised": "1000.00",
                    "amount_paid": "750.00",
                    "promise_completed": "Partial"
                },
                {
                    "promise_to_pay_id": 12,
                    "date_promised": "2020-05-31",
                    "amount_promised": "1000.00",
                    "amount_paid": "",
                    "promise_completed": "No"
                }
            ]
        }
    ],
    "meta": {
        "limit": 10,
        "max_allowed_limit": 50,
        "next_cursor": "eyJpZCI6MjU0NiwiX2JhY2t3YXJkIjpmYWxzZX0"
    }
}
```

{% endtab %}

{% tab title="Success - Resource (200 OK)" %}
**Description:** When querying a specific note ID

**Status:** <mark style="color:green;">`200 OK`</mark>

<pre class="language-json"><code class="lang-json"><strong>{
</strong>    "note_id": 6,
    "accountable_person_id": 40,
    "accountable_person": "Mr James, John",
    "debtor_code": "1001",
    "debtor_reference": "James",
    "date": "2024-03-03",
    "note_type_id": 2,
    "note_type": "Promise to Pay",
    "communication_type_id": 2,
    "communication_type": "E-mail",
    "note": "Payment arrangement of R1000 to be paid off on outstanding school fees",
    "status": "Created"
}
</code></pre>

{% endtab %}

{% tab title="ID Not Found Error (404 Not Found)" %}
**Description:** The requested ID does not exist in the system.

**Status:** <mark style="color:red;">`404 Not Found`</mark>

```json
{
    "success": false,
    "message": "The note does not exist"
}
```

{% endtab %}

{% tab title="Validation Error (400 Bad Request)" %}
**Description:** When validation failed for one or more fields

**Status:** <mark style="color:red;">`400 Bad Request`</mark>

```json
{
    "success": false,
    "message": "Validation Failed",
    "validation_errors": {
        "note_type_id": "The Note type id only allows '1', '2', or '3'",
        "year": "The Year must be integer"
    }
}
```

{% endtab %}
{% endtabs %}

### Code Samples

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

```php
<?php

// API Credentials
$api_username = 'your_username';
$api_password = 'your_password';
$school_id = 'the_school_id';

// Base API endpoint
define('BASE_URL', 'https://integrate.d6plus.co.za/api/v2/finplus/debtmanagement/debtornotes/notes');

// Optional: Set an ID to fetch a specific note (or leave empty for all)
$id = '';

$url = BASE_URL;
if (!empty($id)) {
    $url .= '/' . $id;
}

// Query parameters (optional)
$query_params = [
    'year' => 2023,
    'debtor_code' => 1000,
    'accountable_person_id' => 1,
    'include_deleted' => 1,
    'include_promise_to_pays' => 1,
    'note_type_id' => 1,
    'reverse_order' => 1,
    'limit' => 10,
    'cursor' => 'eyJpZCI6MjU0NiwiX2JhY2t3YXJkIjpmYWxzZX0',
];

if (!empty($query_params)) {
    $url .= '?' . http_build_query($query_params);
}

// Initialize cURL
$curl = curl_init();

// Set cURL options
curl_setopt_array($curl, [
    CURLOPT_URL            => $url,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_TIMEOUT        => 30,  // Set timeout to prevent hanging requests
    CURLOPT_FOLLOWLOCATION => true,
    CURLOPT_HTTP_VERSION   => CURL_HTTP_VERSION_1_1,
    CURLOPT_CUSTOMREQUEST  => 'GET',
    CURLOPT_HTTPHEADER     => [
        "HTTP-X-USERNAME: $api_username",
        "HTTP-X-PASSWORD: $api_password",
        "HTTP-X-SCHOOLID: $school_id"
    ],
]);

// Execute request
$response = curl_exec($curl);

// Check for errors
$error = curl_error($curl);
if ($error) {
    curl_close($curl);
    throw new Exception("cURL Error: $error");
}

// Close cURL and output response
curl_close($curl);
echo $response;

```

{% endtab %}

{% tab title="cURL" %}

```bash
curl --location 'https://integrate.d6plus.co.za/api/v2/finplus/debtmanagement/debtornotes/notes?year=2023&debtor_code=1000&accountable_person_id=1&include_deleted=1&include_promise_to_pays=1&note_type_id=1&reverse_order=1&limit=10' \
     --header 'HTTP-X-USERNAME: your_username' \
     --header 'HTTP-X-PASSWORD: your_password' \
     --header 'HTTP-X-SCHOOLID: the_school_id'
```

{% endtab %}
{% endtabs %}


# Create Note

<mark style="color:orange;">`POST`</mark> `/v2/finplus/debtmanagement/debtornotes/notes`&#x20;

Use this endpoint to **create a new debtor note** for a specified school.

* **Accountable Person**: The note must be linked to an accountable person, requiring an `accountable_person_id`. This ID can be retrieved using either the [**Get Accountable Person(s)**](/v2/reference/finance+/debt-management/get-accountable-person-s) or [**Get Learner(s)**](/v2/reference/finance+/debt-management/get-learner-s) calls.
* **Note Date**: The `date` of the note must be in **"YYYY-MM-DD"** format and must fall between the **start of last year** and the **end of next year**.
* **Note Type**: The `note_type_id` is required and can be retrieved using the [**Get Note Type(s)**](/v2/reference/finance+/debt-management/debtor-notes/get-note-type-s) call.
* **Communication Type**: The `communication_type_id` is required for all note types **except** Internal Notes. This ID can be obtained using the [**Get Communication Type(s)**](/v2/reference/finance+/debt-management/debtor-notes/get-communication-type-s) call.
* **Note Content**: The actual text of the note should be provided in the `note` field.
* **Promise to Pay Notes**:
  * If creating a **Promise to Pay** note (`note_type_id: 2`), payment arrangement details must be included under the `promise_to_pays` array.
  * A **Promise to Pay** requires:
    * `date_promised`: A date between the **start of this year** and the **end of next year**.
    * `amount_promised`: A numeric value without a currency symbol (e.g., `"100.00"`).

{% hint style="warning" %}
The `amount_paid` value and the `promise_completed` flag may only be set by the school.
{% endhint %}

### Request Headers

<table><thead><tr><th width="226.3143310546875">Name</th><th width="106.05718994140625">Type</th><th>Description</th></tr></thead><tbody><tr><td><code>HTTP-X-USERNAME</code><mark style="color:red;">*</mark></td><td>String</td><td>As provided by d6</td></tr><tr><td><code>HTTP-X-PASSWORD</code><mark style="color:red;">*</mark></td><td>String</td><td>As provided by d6</td></tr><tr><td><code>HTTP-X-SCHOOLID</code><mark style="color:red;">*</mark></td><td>Integer</td><td>The unique identifier of the school for which the data is being queried.</td></tr></tbody></table>

### Request Body

<table><thead><tr><th width="261">Name</th><th width="98">Type</th><th>Description</th></tr></thead><tbody><tr><td><code>accountable_person_id</code><mark style="color:red;">*</mark></td><td>Integer</td><td>The id of the accountable person who the note belongs to.</td></tr><tr><td><code>date</code><mark style="color:red;">*</mark></td><td>String</td><td>The date of the note in "yyyy-mm-dd" format.</td></tr><tr><td><code>note_type_id</code><mark style="color:red;">*</mark></td><td>Integer</td><td>The id of the note type.</td></tr><tr><td><code>communication_type_id</code></td><td>Integer</td><td>The id of the communication type (not required for internal notes).</td></tr><tr><td><code>note</code></td><td>String</td><td>The note text</td></tr><tr><td><code>promise_to_pays</code></td><td>Array</td><td>An array of payment arrangement data for promise-to-pay notes</td></tr></tbody></table>

### Request Examples

{% tabs %}
{% tab title="Promise-to-Pay Note" %}

```json
{
    "accountable_person_id": 40,
    "date": "2024-03-03",
    "note_type_id": 2,
    "communication_type_id": 2,
    "note": "Payment arrangement of R1000 to be paid off on outstanding school fees",
    "promise_to_pays": [
        {
            "date_promised": "2024-03-31",
            "amount_promised": "1000.00"
        },
        {
            "date_promised": "2024-04-30",
            "amount_promised": "1000.00"
        },
        {
            "date_promised": "2020-05-31",
            "amount_promised": "1000.00"
        }
    ]
}
```

{% endtab %}

{% tab title="Internal Note" %}

```json
{
    "accountable_person_id": 3,
    "date": "2024-04-15",
    "note_type_id": 3,
    "note": "Mr Webster asked to be phoned back tomorrow at 2pm"
}
```

{% endtab %}
{% endtabs %}

### Response Examples

{% tabs %}
{% tab title="Success (201 Created)" %}
**Status:** <mark style="color:green;">`201 Created`</mark>

```json
{
    "success": true,
    "message": "Note created successfully",
    "data": {
        "note_id": 6
    }
}
```

{% endtab %}

{% tab title="Success - Including Promise to Pays (201 Created)" %}
**Status:** <mark style="color:green;">`201 Created`</mark>

```json
{
    "success": true,
    "message": "Note created successfully",
    "data": {
        "note_id": 7,
        "promise_to_pays": [
            {
                "promise_to_pay_id": 11,
                "date_promised": "2024-03-31",
                "amount_promised": "1000.00"
            },
            {
                "promise_to_pay_id": 12,
                "date_promised": "2024-04-30",
                "amount_promised": "1000.00"
            },
            {
                "promise_to_pay_id": 13,
                "date_promised": "2020-05-31",
                "amount_promised": "1000.00"
            }
        ]
    }
}
```

{% endtab %}

{% tab title="Validation Error (400 Bad Request)" %}
**Description:** When validation failed for one or more fields

**Status:** <mark style="color:red;">`400 Bad Request`</mark>

```json
{
    "success": false,
    "message": "Validation Failed",
    "validation_errors": {
        "accountable_person_id": "The accountable_person_id is invalid",
        "date": "The Date is not valid date format. Expected format is 'Y-m-d'.",
        "note": "The Note is required"
    }
}
```

{% endtab %}
{% endtabs %}

### Code Samples

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

```php
<?php

// API Credentials
$api_username = 'your_username';
$api_password = 'your_password';
$school_id = 'the_school_id';

// Base API endpoint
define('BASE_URL', 'https://integrate.d6plus.co.za/api/v2/finplus/debtmanagement/debtornotes/notes');

// Request payload
$request_data = [
    "accountable_person_id" => 1234,  // Replace with actual accountable person ID
    "date" => "2025-04-01",           // Note date (YYYY-MM-DD)
    "note_type_id" => 2,              // Replace with actual note type ID
    "communication_type_id" => 1,      // Required unless it's an Internal Note
    "note" => "This is a test debtor note.",
    "promise_to_pays" => [             // Only required if creating a "Promise to Pay" note
        [
            "date_promised" => "2025-05-01",
            "amount_promised" => "1500.00"
        ]
    ]
];

// Initialize cURL
$curl = curl_init();

// Set cURL options
curl_setopt_array($curl, [
    CURLOPT_URL            => BASE_URL,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_TIMEOUT        => 30,
    CURLOPT_FOLLOWLOCATION => true,
    CURLOPT_HTTP_VERSION   => CURL_HTTP_VERSION_1_1,
    CURLOPT_CUSTOMREQUEST  => 'POST',
    CURLOPT_POSTFIELDS     => json_encode($request_data),
    CURLOPT_HTTPHEADER     => [
        "HTTP-X-USERNAME: $api_username",
        "HTTP-X-PASSWORD: $api_password",
        "HTTP-X-SCHOOLID: $school_id",
        "Content-Type: application/json"
    ],
]);

// Execute request
$response = curl_exec($curl);

// Check for errors
$error = curl_error($curl);
if ($error) {
    curl_close($curl);
    throw new Exception("cURL Error: $error");
}

// Close cURL and output response
curl_close($curl);
echo $response;

```

{% endtab %}

{% tab title="cURL" %}

```bash
curl --location --request POST 'https://integrate.d6plus.co.za/api/v2/finplus/debtmanagement/debtornotes/notes' \
     --header 'HTTP-X-USERNAME: your_username' \
     --header 'HTTP-X-PASSWORD: your_password' \
     --header 'HTTP-X-SCHOOLID: the_school_id' \
     --header 'Content-Type: application/json' \
     --data-raw '{
         "accountable_person_id": 1234,
         "date": "2025-04-01",
         "note_type_id": 2,
         "communication_type_id": 1,
         "note": "This is a test debtor note.",
         "promise_to_pays": [
             {
                 "date_promised": "2025-05-01",
                 "amount_promised": "1500.00"
             }
         ]
     }'
```

{% endtab %}
{% endtabs %}


# Update Note

<mark style="color:purple;">`PATCH`</mark> `/v2/finplus/debtmanagement/debtornotes/notes/{id}`

Use this endpoint to **update an existing debtor note** for a specified school.

* The **note ID** must be passed in the URL and can be retrieved using the [**Get Note(s)**](/v2/reference/finance+/debt-management/debtor-notes/get-note-s) call.
* If you need to update the **payment arrangements** attached to a promise-to-pay note, include the updated data in the `promise_to_pays` array (see details below).
* To update an **existing** promise-to-pay entry, provide its `promise_to_pay_id`. This ID can be retrieved using either the [**Get Note(s)**](/v2/reference/finance+/debt-management/debtor-notes/get-note-s) or [**Get Promise To Pay(s)**](/v2/reference/finance+/debt-management/debtor-notes/get-promise-to-pay-record-s) call.
* If a `promise_to_pay_id` is **not included**, a **new** promise-to-pay entry will be created.
* The API will **not** allow a duplicate promise-to-pay entry to be added if both `date_promised` and `amount_promised` match an existing record.
* To **restore** a previously deleted note, provide the `note_id` and set the `status` field to `"Created"`.
* For a detailed explanation of individual fields, refer to the [**Create Note**](/v2/reference/finance+/debt-management/debtor-notes/create-note) documentation.

### Path Parameters

<table><thead><tr><th width="226.31427001953125">Name</th><th width="106.05712890625">Type</th><th>Description</th></tr></thead><tbody><tr><td><code>{id}</code><mark style="color:red;">*</mark></td><td>Integer</td><td>The <strong>Note ID</strong> of the note to be updated</td></tr></tbody></table>

### Request Headers

<table><thead><tr><th width="228.5714111328125">Name</th><th width="96">Type</th><th>Description</th></tr></thead><tbody><tr><td><code>HTTP-X-USERNAME</code><mark style="color:red;">*</mark></td><td>String</td><td>As provided by d6</td></tr><tr><td><code>HTTP-X-PASSWORD</code><mark style="color:red;">*</mark></td><td>String</td><td>As provided by d6</td></tr><tr><td><code>HTTP-X-SCHOOLID</code><mark style="color:red;">*</mark></td><td>Integer</td><td>The unique identifier of the school for which the data is being queried.</td></tr></tbody></table>

### Request Body

<table><thead><tr><th width="219.85711669921875">Name</th><th width="98">Type</th><th>Description</th></tr></thead><tbody><tr><td><code>accountable_person_id</code></td><td>Integer</td><td>The id of the accountable person who the note belongs to.</td></tr><tr><td><code>date</code></td><td>String</td><td>The date of the note in "yyyy-mm-dd" format.</td></tr><tr><td><code>note_type_id</code></td><td>Integer</td><td>The id of the note type.</td></tr><tr><td><code>communication_type_id</code></td><td>Integer</td><td>The id of the communication type (not required for internal notes).</td></tr><tr><td><code>note</code></td><td>String</td><td>The note text</td></tr><tr><td><code>status</code></td><td>String</td><td>The status of the note (either "Created" or "Deleted")</td></tr><tr><td><code>promise_to_pays</code></td><td>Array</td><td>An array of payment arrangement data for promise-to-pay notes</td></tr></tbody></table>

### Request Examples

{% tabs %}
{% tab title="Update a note" %}

```json
{
    "note_id": 7,
    "date": "2024-04-16",
    "note": "Mr Webster asked to be phoned back tomorrow at 10am"
}
```

{% endtab %}

{% tab title="Update / Add Promise-to-Pay" %}

```json
{
    "note_id": 6,
    "promise_to_pays": [
        {
            // Updating an existing promise to pay
            "promise_to_pay_id": 12, // <- promise to pay ID included
            "date_promised": "2020-05-31",
            "amount_promised": "1500.00"
        },
        {
            // Create a new promise to pay
            "date_promised": "2020-06-30",
            "amount_promised": "500.00"
        }
    ]
}
```

{% endtab %}

{% tab title="Restore a deleted note" %}

```json
{
    "note_id": 6
    "status": "Created"
}
```

{% endtab %}
{% endtabs %}

### Response Examples

{% tabs %}
{% tab title="Success (200 OK)" %}
**Status:** <mark style="color:green;">`200 OK`</mark>

```json
{
    "success": true,
    "message": "Note updated successfully",
    "data": {
        "note_id": 7,
        "accountable_person_id": 3,
        "accountable_person": "Mr Webster, Nic",
        "debtor_code": "1002",
        "debtor_reference": "Webster",
        "date": "2024-04-15",
        "note_type_id": 3,
        "note_type": "Internal",
        "communication_type_id": 7,
        "communication_type": "Internal",
        "note": "Mr Webster asked to be phoned back tomorrow at 10am",
        "status": "Created"
    }
}
```

{% endtab %}

{% tab title="Success - Including Promise to Pays (200 OK)" %}
**Status:** <mark style="color:green;">`200 OK`</mark>

```json
{
    "success": true,
    "message": "Note updated successfully",
    "data": {
        "note_id": 6,
        "accountable_person_id": 40,
        "accountable_person": "Mr James, John",
        "debtor_code": "1001",
        "debtor_reference": "James",
        "date": "2024-03-03",
        "note_type_id": 2,
        "note_type": "Promise to Pay",
        "communication_type_id": 2,
        "communication_type": "E-mail",
        "note": "Payment arrangement of R1000 to be paid off on outstanding school fees",
        "status": "Created",
        "promise_to_pays": [
            {
                "promise_to_pay_id": 8,
                "date_promised": "2024-03-31",
                "amount_promised": "1000.00",
                "amount_paid": "1000.00",
                "promise_completed": "Yes"
            },
            {
                "promise_to_pay_id": 10,
                "date_promised": "2024-04-30",
                "amount_promised": "1000.00",
                "amount_paid": "750.00",
                "promise_completed": "Partial"
            },
            {
                "promise_to_pay_id": 12,
                "date_promised": "2020-05-31",
                "amount_promised": "1500.00",
                "amount_paid": "",
                "promise_completed": "No"
            },
            {
                "promise_to_pay_id": 13,
                "date_promised": "2020-06-30",
                "amount_promised": "500.00",
                "amount_paid": "",
                "promise_completed": "No"
            }
        ]
    }
}
```

{% endtab %}

{% tab title="ID Missing Error (400 Bad Request)" %}
**Description:** When the note ID was not included in the URL.

**Status:** <mark style="color:red;">`400 Bad Request`</mark>

```json
{
    "success": false,
    "message": "The Note ID is required"
}
```

{% endtab %}

{% tab title="ID Not Found Error (404 Not Found)" %}
**Description:** When the note ID provided does not exist.

**Status:** <mark style="color:red;">`404 Not Found`</mark>

```json
{
    "success": false,
    "message": "The note does not exist."
}
```

{% endtab %}

{% tab title="Validation Error (400 Bad Request)" %}
**Description:** When validation failed for one or more fields

**Status:** <mark style="color:red;">`400 Bad Request`</mark>

```json
{
    "success": false,
    "message": "Validation Failed",
    "validation_errors": {
        "accountable_person_id": "The accountable_person_id is invalid",
        "date": "The Date is not valid date format. Expected format is 'Y-m-d'."
    }
}
```

{% endtab %}
{% endtabs %}

### Code Samples

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

```php
<?php

// API Credentials
$api_username = 'your_username';
$api_password = 'your_password';
$school_id    = 'the_school_id';

// Note ID to update (retrieved from Get Note(s) or Get Promise To Pay(s) calls)
$note_id = '1234';

// Base API endpoint with note_id appended
define('BASE_URL', 'https://integrate.d6plus.co.za/api/v2/finplus/debtmanagement/debtornotes/notes');
$url = BASE_URL . '/' . $note_id;

// Request payload data
$request_data = [
    "accountable_person_id" => 1234,             // Replace with actual accountable person ID
    "date"                  => "2025-04-01",       // Date of the note in "YYYY-MM-DD" format
    "note_type_id"          => 2,                  // Replace with actual note type ID
    "communication_type_id" => 1,                  // Required for all note types except Internal Notes
    "note"                  => "Updated debtor note text.",
    "status"                => "Created",          // Use "Created" to restore a deleted note
    "promise_to_pays"       => [                   // Optional: Promise-to-pay details
        [
            "promise_to_pay_id" => 5678,           // To update an existing promise-to-pay, include its ID. Omit to create a new one.
            "date_promised"     => "2025-05-15",
            "amount_promised"   => "2000.00"
        ]
    ]
];

// Initialize cURL
$curl = curl_init();

// Set cURL options
curl_setopt_array($curl, [
    CURLOPT_URL            => $url,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_TIMEOUT        => 30,  // Set timeout to prevent hanging requests
    CURLOPT_FOLLOWLOCATION => true,
    CURLOPT_HTTP_VERSION   => CURL_HTTP_VERSION_1_1,
    CURLOPT_CUSTOMREQUEST  => 'PATCH',
    CURLOPT_POSTFIELDS     => json_encode($request_data),
    CURLOPT_HTTPHEADER     => [
        "HTTP-X-USERNAME: $api_username",
        "HTTP-X-PASSWORD: $api_password",
        "HTTP-X-SCHOOLID: $school_id",
        "Content-Type: application/json"
    ],
]);

// Execute the request
$response = curl_exec($curl);

// Check for errors
$error = curl_error($curl);
if ($error) {
    curl_close($curl);
    throw new Exception("cURL Error: $error");
}

// Close cURL session and output the response
curl_close($curl);
echo $response;

```

{% endtab %}

{% tab title="cURL" %}

```bash
curl --location --request PATCH 'https://integrate.d6plus.co.za/api/v2/finplus/debtmanagement/debtornotes/notes/{note_id}' \
     --header 'HTTP-X-USERNAME: your_username' \
     --header 'HTTP-X-PASSWORD: your_password' \
     --header 'HTTP-X-SCHOOLID: the_school_id' \
     --header 'Content-Type: application/json' \
     --data-raw '{
         "accountable_person_id": 1234,
         "date": "2025-04-01",
         "note_type_id": 2,
         "communication_type_id": 1,
         "note": "Updated debtor note text.",
         "status": "Created",
         "promise_to_pays": [
             {
                 "promise_to_pay_id": 5678,
                 "date_promised": "2025-05-15",
                 "amount_promised": "2000.00"
             }
         ]
     }'
```

{% endtab %}
{% endtabs %}


# Delete Note

<mark style="color:red;">`DELETE`</mark> `/v2/finplus/debtmanagement/debtornotes/notes/{id}`

Use this endpoint to **delete a debtor note** for a specified school.

The **note ID** must be included in the URL and can be found using the [Get Note(s)](/v2/reference/finance+/debt-management/debtor-notes/get-note-s) call.

To restore a deleted debtor not, refer to the [Update Note](/v2/reference/finance+/debt-management/debtor-notes/update-note) page.

### Path Parameters

<table><thead><tr><th width="189.257080078125">Name</th><th width="162.57147216796875">Type</th><th>Description</th></tr></thead><tbody><tr><td><code>{id}</code><mark style="color:red;">*</mark></td><td>Integer</td><td>The <strong>Note ID</strong> of the debtor note to delete</td></tr></tbody></table>

### Request Headers

<table><thead><tr><th width="204.7713623046875">Name</th><th width="117.028564453125">Type</th><th>Description</th></tr></thead><tbody><tr><td><code>HTTP-X-USERNAME</code><mark style="color:red;">*</mark></td><td>String</td><td>As provided by d6</td></tr><tr><td><code>HTTP-X-PASSWORD</code><mark style="color:red;">*</mark></td><td>String</td><td>As provided by d6</td></tr><tr><td><code>HTTP-X-SCHOOLID</code><mark style="color:red;">*</mark></td><td>Integer</td><td>The unique identifier of the school for which the data is being queried.</td></tr></tbody></table>

### Response Examples

{% tabs %}
{% tab title="Success (200 OK)" %}
**Status:** <mark style="color:green;">`200 OK`</mark>

```json
{
    "success": true,
    "message": "Note deleted successfully",
    "data": {
        "status": "Deleted"
    }
}
```

{% endtab %}

{% tab title="ID Missing Error (400 Bad Request)" %}
**Description:** When the note ID was not included in the URL.

**Status:** <mark style="color:red;">`400 Bad Request`</mark>

```json
{
    "success": false,
    "message": "The Note ID is required"
}
```

{% endtab %}

{% tab title="ID Not Found Error (404 Not Found)" %}
**Description:** When the note ID provided does not exist or has already been deleted.

**Status:** <mark style="color:red;">`404 Not Found`</mark>

```json
{
    "success": false,
    "message": "The note does not exist or has already been deleted."
}
```

{% endtab %}
{% endtabs %}

### Code Samples

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

```php
<?php

// API Credentials
$api_username = 'your_username';
$api_password = 'your_password';
$school_id = 'the_school_id';

// Note ID to be deleted (required)
$note_id = '12345'; // Replace with the actual note ID

// API Endpoint
define('BASE_URL', 'https://integrate.d6plus.co.za/api/v2/finplus/debtmanagement/debtornotes/notes');

$url = BASE_URL . '/' . $note_id;

// Initialize cURL
$curl = curl_init();

// Set cURL options
curl_setopt_array($curl, [
    CURLOPT_URL            => $url,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_TIMEOUT        => 30,
    CURLOPT_FOLLOWLOCATION => true,
    CURLOPT_HTTP_VERSION   => CURL_HTTP_VERSION_1_1,
    CURLOPT_CUSTOMREQUEST  => 'DELETE',
    CURLOPT_HTTPHEADER     => [
        "HTTP-X-USERNAME: $api_username",
        "HTTP-X-PASSWORD: $api_password",
        "HTTP-X-SCHOOLID: $school_id"
    ],
]);

// Execute request
$response = curl_exec($curl);

// Check for errors
$error = curl_error($curl);
if ($error) {
    curl_close($curl);
    throw new Exception("cURL Error: $error");
}

// Close cURL and output response
curl_close($curl);
echo $response;

```

{% endtab %}

{% tab title="cURL" %}

```bash
curl --request DELETE 'https://integrate.d6plus.co.za/api/v2/finplus/debtmanagement/debtornotes/notes/{note_id}' \
     --header 'HTTP-X-USERNAME: your_username' \
     --header 'HTTP-X-PASSWORD: your_password' \
     --header 'HTTP-X-SCHOOLID: the_school_id'
```

{% endtab %}
{% endtabs %}




---

[Next Page](https://apidocs.d6plus.co.za/llms-full.txt/1)