# Get Promise To Pay Record(s)

<mark style="color:blue;">`GET`</mark> `/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.

{% hint style="info" %}
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.
{% endhint %}

### 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

<table><thead><tr><th width="145.3714599609375">Name</th><th width="137.7427978515625">Type</th><th>Description</th></tr></thead><tbody><tr><td><code>{id}</code></td><td>Integer</td><td>Optional ID of the promise-to-pay item to retrieve a single record</td></tr></tbody></table>

### Request Headers

<table><thead><tr><th width="203.8856201171875">Name</th><th width="119.71429443359375">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>

### Query Parameters

<table><thead><tr><th width="231.7142333984375">Name</th><th width="107.88580322265625">Type</th><th>Description</th></tr></thead><tbody><tr><td><code>accountable_person_id</code></td><td>Integer</td><td>To only return a specific accountable person's promise to pays</td></tr><tr><td><code>debtor_code</code></td><td>Integer</td><td>To only return a specific debtor code's promise to pays</td></tr><tr><td><code>promise_completed</code></td><td>String</td><td>To filter on the status of the promise to pay</td></tr><tr><td><code>year_promised</code></td><td>Integer</td><td>To filter on a specific year</td></tr><tr><td><code>include_debtor_note</code></td><td>Boolean</td><td>Whether to include debtor note data in the response</td></tr><tr><td><code>cursor</code></td><td>String</td><td>To retrieve the next group of items (if any)</td></tr><tr><td><code>limit</code></td><td>Integer</td><td>To override the default limit of records returned (up to the <code>max_allowed_limit</code> provided in the response metadata).</td></tr><tr><td><code>reverse_order</code></td><td>Boolean</td><td>To reverse the order the data is returned in</td></tr></tbody></table>

### Response Examples

{% tabs %}
{% tab title="Success - Collection (200 OK)" %}
**Status:** <mark style="color:green;">`200 OK`</mark>

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

{% endtab %}

{% tab title="Success- Including Debtor Note (200 OK)" %}
**Description:** When including the associated debtor notes (`include_debtor_note`)

**Status:** <mark style="color:green;">`200 OK`</mark>

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

{% endtab %}

{% tab title="Success - Resource (200 OK)" %}
**Description:** When querying a specific promise-to-pay ID

**Status:** <mark style="color:green;">`200 OK`</mark>

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

{% endtab %}

{% tab title="ID Not Found Error (404 Not Found)" %}
**Description:** When the promise-to-pay ID provided does not exist

**Status:** <mark style="color:red;">`404 Not Found`</mark>

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

{% 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": {
        "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"
    }
}
```

{% 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/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;
```

{% endtab %}

{% tab title="cURL" %}

```bash
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'
```

{% endtab %}
{% endtabs %}