Integrate
Integrate v2
Integrate v2
  • Getting Started
    • 🤝Authorisation & Activation
    • 🔗API v2 URL
    • 🔢Versioning
    • 🔐Authentication
    • 🟰Additional Headers
    • 🆗Response Status Codes
    • 🛑Rate Limiting
    • ⁉️Errors and Bad Requests
    • 📖Pagination
    • ⏭️Upgrading to v2
  • Reference
    • Settings
      • Client Integrations
        • Get Client Integrations
        • Change Client Integration State
    • Finance+
      • Debt Management
        • Debtor Notes
          • Get Communication Type(s)
          • Get Note Type(s)
          • Get Note(s)
          • Create Note
          • Update Note
          • Delete Note
          • Get Promise To Pay Record(s)
          • Delete Promise To Pay
        • Age Analysis Report
        • Financial Transactions Report
        • Get Schools
        • Get Accountable Person(s)
        • Get Learner(s)
        • Get Transaction Type(s)
        • Get Transaction Category(s)
Powered by GitBook
On this page
  • Path Parameters
  • Request Headers
  • Request Body
  • Request Examples
  • Response Examples
  • Code Samples
  1. Reference
  2. Finance+
  3. Debt Management
  4. Debtor Notes

Update Note

PreviousCreate NoteNextDelete Note

PATCH /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 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 or 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 documentation.

Path Parameters

Name
Type
Description

{id}*

Integer

The Note ID of the note to be updated

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.

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

status

String

The status of the note (either "Created" or "Deleted")

promise_to_pays

Array

An array of payment arrangement data for promise-to-pay notes

Request Examples

{
    "note_id": 7,
    "date": "2024-04-16",
    "note": "Mr Webster asked to be phoned back tomorrow at 10am"
}
{
    "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"
        }
    ]
}
{
    "note_id": 6
    "status": "Created"
}

Response Examples

Status: 200 OK

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

Status: 200 OK

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

Description: When the note ID was not included in the URL.

Status: 400 Bad Request

{
    "success": false,
    "message": "The Note ID is required"
}

Description: When the note ID provided does not exist.

Status: 404 Not Found

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

Description: When validation failed for one or more fields

Status: 400 Bad Request

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

Code Samples

<?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;
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"
             }
         ]
     }'
Get Note(s)
Get Note(s)
Get Promise To Pay(s)
Create Note