Get Note(s)

GET /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.

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.

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

Name	Type	Description
{id}	Integer	Optionally provide the Note ID for retrieving a single record.

Request Headers

Name	Type	Description
HTTP-X-USERNAME*	String	As provided by d6
HTTP-X-PASSWORD*	String	As provided by d6
HTTP-X-SCHOOLID*	Integer	The unique identifier of the school for which the data is being queried.

Query Parameters

Name	Type	Description
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
cursor	String	To retrieve the next group of items (if any)
limit	Integer	To override the default limit of records returned (up to the max_allowed_limit provided in the response metadata).
reverse_order	Boolean	To reverse the order the data is returned in

Response Examples

Success - Collection (200 OK)

Status: 200 OK

{
    "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,
        "cursor": "eyJpZCI6MjU0NiwiX2JhY2t3YXJkIjpmYWxzZX0"
    }
}

Success Including Promise to Pays (200 OK)

Status: 200 OK

{
    "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,
        "cursor": "eyJpZCI6MjU0NiwiX2JhY2t3YXJkIjpmYWxzZX0"
    }
}

Success - Resource (200 OK)

Description: When querying a specific note ID

Status: 200 OK

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

ID Not Found Error (404 Not Found)

Description: The requested ID does not exist in the system.

Status: 404 Not Found

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

Validation Error (400 Bad Request)

Description: When validation failed for one or more fields

Status: 400 Bad Request

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

Code Samples

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;

cURL

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'