Get Promise To Pay Record(s)

GET /v2/finplus/debtmanagement/debtornotes/promisetopays (/{id})

This call provides a convenient way to retrieve all promise-to-pay records, regardless of the debtor notes they are associated with.

To fetch a specific promise-to-pay record, include the ID of the promise-to-pay record in the URL.
To find records associated with a particular person, use the debtor_code or accountable_person_id query parameters.
You can filter records based on their completion status using the promise_completed query parameter. Possible values are "Yes", "No", and "Partial".
To retrieve records for a specific year, use the year_promised query parameter.
To include details of the debtor note associated with the promise-to-pay record in the response, provide the include_debtor_note query parameter.

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

Optional ID of the promise-to-pay item to retrieve 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

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

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

Status: 200 OK

{
    "data": [
        {
            "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"
        }
    ],
    "meta": {
        "limit": 10,
        "max_allowed_limit": 50,
        "cursor": "eyJpZCI6MjU0NiwiX2JhY2t3YXJkIjpmYWxzZX0"
    }
}

Description: When including the associated debtor notes (include_debtor_note)

Status: 200 OK

{
    "data": [
        {
            "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"
            }
        }
    ],
    "meta": {
        "limit": 10,
        "max_allowed_limit": 50,
        "cursor": "eyJpZCI6MjU0NiwiX2JhY2t3YXJkIjpmYWxzZX0"
    }
}

Description: When querying a specific promise-to-pay ID

Status: 200 OK

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

Description: When the promise-to-pay ID provided does not exist

Status: 404 Not Found

{
    "success": false,
    "message": "Promise To Pay does not exist"
}

Description: When validation failed for one or more fields

Status: 400 Bad Request

{
    "success": false,
    "message": "Validation Failed",
    "validation_errors": {
        "include_debtor_note": "The Include debtor note must be a boolean",
        "promise_completed": "The Promise completed only allows 'Yes', 'No', or 'Partial'",
        "limit": "The Limit maximum is 50"
    }
}

Code Samples

<?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/promisetopays');

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

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

// Query parameters (optional)
$query_params = [
    'accountable_person_id' => 380,
    'debtor_code' => '1270',
    'promise_completed' => 'No',
    'year_promised' => 2024,
    'include_debtor_note' => 1,
    'reverse_order' => 1,
    'limit' => 50,
    'cursor' => 'eyJpZCI6NTMsIl9iYWNrd2FyZCI6ZmFsc2V9',
];

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 --location 'https://integrate.d6plus.co.za/api/v2/finplus/debtmanagement/debtornotes/promisetopays?accountable_person_id=380&debtor_code=1270&promise_completed=No&year_promised=2024&include_debtor_note=1&reverse_order=1&limit=50' \
     --header 'HTTP-X-USERNAME: your_username' \
     --header 'HTTP-X-PASSWORD: your_password' \
     --header 'HTTP-X-SCHOOLID: the_school_id'

PreviousDelete Note NextDelete Promise To Pay

{ "data": [ { "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" } } ], "meta": { "limit": 10, "max_allowed_limit": 50, "cursor": "eyJpZCI6MjU0NiwiX2JhY2t3YXJkIjpmYWxzZX0" } }

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

{ "success": false, "message": "Validation Failed", "validation_errors": { "include_debtor_note": "The Include debtor note must be a boolean", "promise_completed": "The Promise completed only allows 'Yes', 'No', or 'Partial'", "limit": "The Limit maximum is 50" } }

<?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/promisetopays'); // Optional: Set an ID to fetch a specific note type (or leave empty for all) $id = ''; $url = BASE_URL; if (!empty($id)) { $url .= '/' . $id; } // Query parameters (optional) $query_params = [ 'accountable_person_id' => 380, 'debtor_code' => '1270', 'promise_completed' => 'No', 'year_promised' => 2024, 'include_debtor_note' => 1, 'reverse_order' => 1, 'limit' => 50, 'cursor' => 'eyJpZCI6NTMsIl9iYWNrd2FyZCI6ZmFsc2V9', ]; 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 --location 'https://integrate.d6plus.co.za/api/v2/finplus/debtmanagement/debtornotes/promisetopays?accountable_person_id=380&debtor_code=1270&promise_completed=No&year_promised=2024&include_debtor_note=1&reverse_order=1&limit=50' \ --header 'HTTP-X-USERNAME: your_username' \ --header 'HTTP-X-PASSWORD: your_password' \ --header 'HTTP-X-SCHOOLID: the_school_id'