# 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)**](https://apidocs.d6plus.co.za/v2/reference/finance+/debt-management/get-accountable-person-s) or [**Get Learner(s)**](https://apidocs.d6plus.co.za/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)**](https://apidocs.d6plus.co.za/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)**](https://apidocs.d6plus.co.za/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 %}