Create Note

Create a new debtor note

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

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 or 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) call. The communication_type_id, which can be found using the 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*	Integer	The login ID of the school to retrieve data from

Headers

Name	Type	Description
HTTP-X-USERNAME*	String	As provided by d6
HTTP-X-PASSWORD*	String	As provided by d6

Request Body

Name	Type	Description
accountable_person_id*	Integer	The id of the accountable person who the note belongs to.
date*	String	The date of the note in "yyyy-mm-dd" format.
note_type_id*	Integer	The id of the note type.
communication_type_id	Integer	The id of the communication type (not required for internal notes).
note	String	The note text
promise_to_pays	Array	An array of payment arrangement data for promise-to-pay notes

Request Examples

Promise-to-Pay Note

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

Internal Note

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

Response Examples

200 The request was successful.

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

200 Including Promise to Pays

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

204 No Content

404: Not Found The resource was not found.

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

401: Unauthorized The server understood the request, but is refusing it or access is not allowed.

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

403: Forbidden The server understood the request, but the requested action is not allowed.

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

Code Samples

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;

cURL

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"
        }
    ]
}'