Get Accountable Person(s)

GET /v2/finplus/debtmanagement/accountablepersons (/{id})

This endpoint retrieves one or all accountable persons for the specified school.

• By default, only accountable persons with active debtor accounts (current learners or accounts with an outstanding balance) are returned.

• The all_accounts query parameter can be used to fetch all accountable persons, including those with left learners and zero-balance accounts.

• The include_learners query parameter allows learners' data to be included in the response.

• You can filter results using the debtor_code or accountable_person_id query parameters.

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	Optionally provide the Accountable Person ID for retrieving 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
all_accounts	Boolean	Whether to include all accounts
include_learners	Boolean	Whether to include the learner data in the response
debtor_code	Integer	To filter on a specific Debtor Code
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

Success - Collection (200 OK)

Status: 200 OK

{
    "data": [
        {
            "accountable_person_id": "40",
            "title": "Mr",
            "first_name": "John",
            "full_names": "John James",
            "last_name": "Smith",
            "debtor_code": "1001",
            "mobile_calling_code": "27",
            "mobile_number": "0821237654",
            "work_tel_number": "0124567890",
            "home_tel_number": "0123214567",
            "email_address": "[e-mail]",
            "residential_address": "Moneytow Street\r\nNow Village\r\n0123\r\nSouth Africa",
            "postal_address": "Moneytow Street\r\nNow Village\r\n0123\r\nSouth Africa",
            "home_language": "English",
            "nationality": "South Africa",
            "id_number": "8104050240082",
            "passport_number": "A456732243",
            "employer": "Greenholt Group",
            "employer_address": "3 School Lane\r\nBig City\r\nSouth Africa",
            "account_closing_date": "0000-00-00",
            "account_start_date": "2023-01-01"
        },
        {
            "accountable_person_id": "3",
            "title": "Mr",
            "first_name": "Nic",
            "full_names": "Nicholas Nigel",
            "last_name": "Webster",
            "debtor_code": "1002",
            "mobile_calling_code": "27",
            "mobile_number": "0678901234",
            "work_tel_number": "",
            "home_tel_number": "",
            "email_address": "[e-mail]",
            "residential_address": "7th Street\r\nSmall Town\r\n0123\r\nSouth Africa",
            "postal_address": "7th Street\r\nSmall Town\r\n0123\r\nSouth Africa",
            "home_language": "English",
            "nationality": "South Africa",
            "id_number": "",
            "passport_number": "",
            "employer": "",
            "employer_address": "",
            "account_closing_date": "0000-00-00",
            "account_start_date": "2023-01-01"
        }
    ],
    "meta": {
        "limit": 10,
        "max_allowed_limit": 50,
        "cursor": "eyJpZCI6MjU0NiwiX2JhY2t3YXJkIjpmYWxzZX0"
    }
}

Success - Including Learners (200 OK)

Status: 200 OK

{
    "data": [
        {
            "accountable_person_id": "40",
            "title": "Mr",
            "first_name": "John",
            "full_names": "John James",
            "last_name": "Smith",
            "debtor_code": "1001",
            "mobile_calling_code": "27",
            "mobile_number": "0821237654",
            "work_tel_number": "0124567890",
            "home_tel_number": "0123214567",
            "email_address": "[e-mail]",
            "residential_address": "Moneytow Street\r\nNow Village\r\n0123\r\nSouth Africa",
            "postal_address": "Moneytow Street\r\nNow Village\r\n0123\r\nSouth Africa",
            "home_language": "English",
            "nationality": "South Africa",
            "id_number": "8104050240082",
            "passport_number": "A456732243",
            "employer": "Greenholt Group",
            "employer_address": "3 School Lane\r\nBig City\r\nSouth Africa",
            "account_closing_date": "0000-00-00",
            "account_start_date": "2023-01-01",
            "learners": [
                {
                    "learner_id": "1",
                    "first_name": "John",
                    "last_name": "Smith",
                    "gender": "M",
                    "grade": "7"
                }
            ]
        },
        {
            "accountable_person_id": "3",
            "title": "Mr",
            "first_name": "Nic",
            "full_names": "Nicholas Nigel",
            "last_name": "Webster",
            "debtor_code": "1002",
            "mobile_calling_code": "27",
            "mobile_number": "0678901234",
            "work_tel_number": "",
            "home_tel_number": "",
            "email_address": "[e-mail]",
            "residential_address": "7th Street\r\nSmall Town\r\n0123\r\nSouth Africa",
            "postal_address": "7th Street\r\nSmall Town\r\n0123\r\nSouth Africa",
            "home_language": "English",
            "nationality": "South Africa",
            "id_number": "",
            "passport_number": "",
            "employer": "",
            "employer_address": "",
            "account_closing_date": "0000-00-00",
            "account_start_date": "2023-01-01",
            "learners": [
                {
                    "learner_id": "51",
                    "first_name": "Michelle",
                    "last_name": "Webster",
                    "gender": "F",
                    "grade": "3"
                }
            ]
        }
    ],
    "meta": {
        "limit": 10,
        "max_allowed_limit": 50,
        "cursor": "eyJpZCI6MjU0NiwiX2JhY2t3YXJkIjpmYWxzZX0"
    }
}

Success - Resource (200 OK)

Status: 200 OK

{
    "accountable_person_id": "40",
    "title": "Mr",
    "first_name": "John",
    "full_names": "John James",
    "last_name": "Smith",
    "debtor_code": "1001",
    "mobile_calling_code": "27",
    "mobile_number": "0821237654",
    "work_tel_number": "0124567890",
    "home_tel_number": "0123214567",
    "email_address": "[e-mail]",
    "residential_address": "Moneytow Street\r\nNow Village\r\n0123\r\nSouth Africa",
    "postal_address": "Moneytow Street\r\nNow Village\r\n0123\r\nSouth Africa",
    "home_language": "English",
    "nationality": "South Africa",
    "id_number": "8104050240082",
    "passport_number": "A456732243",
    "employer": "Greenholt Group",
    "employer_address": "3 School Lane\r\nBig City\r\nSouth Africa",
    "account_closing_date": "0000-00-00",
    "account_start_date": "2023-01-01"
}

ID Not Found Error (404 Not Found)

Description: The requested ID does not exist in the system.

Status: 404 Not Found

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

Validation Error (400 Bad Request)

Description: When validation failed for one or more fields

Status: 400 Bad Request

{
    "success": false,
    "message": "Validation Failed",
    "validation_errors": {
        "include_learners": "The Include learners must be a boolean"
    }
}

Code Samples

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

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

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

// Query parameters (optional)
$query_params = [
    'all_accounts' => 1,
    'include_learners' => 1,
    'debtor_code' => '1002',
    'reverse_order' => 1,
    'limit' => 10,
    'cursor' => 'eyJpZCI6MjU0NiwiX2JhY2t3YXJkIjpmYWxzZX0',
];

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

curl --request GET 'https://integrate.d6plus.co.za/api/v2/finplus/debtmanagement/accountablepersons?all_accounts=1' \
     --header 'HTTP-X-USERNAME: your_username' \
     --header 'HTTP-X-PASSWORD: your_password' \
     --header 'HTTP-X-SCHOOLID: the_school_id'