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
  • Pagination
  • Path Parameters
  • Request Headers
  • Query Parameters
  • Response Examples
  • Code Samples
  1. Reference
  2. Finance+
  3. Debt Management

Get Learner(s)

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

Use this endpoint to fetch a school's learners and optionally include the parent info and the accountable person's details.

By default, only learners with active accounts (current learners or accounts with an outstanding balance) will be returned. You can use the all_accounts query parameter to include learners for all accounts (includes left learners and zero-balance accounts).

To include parent information in the response, set the include_parents query parameter. For including the accountable person's details, set the include_accountable_person query parameter.

Optionally it is possible to filter on a specific learner_id, debtor_code or accountable_person_id.

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

debtor_code

Integer

To filter on a specific Debtor Code

accountable_person_id

Integer

To filter on a specific Accountable Person ID

parent_id

Integer

To filter on a specific Parent ID

all_accounts

Boolean

Whether to include all accounts

include_parents

Boolean

Whether to include the parent data in the response

include_accountable_person

Boolean

Whether to include the accountable person's 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": [
        {
            "learner_id": "1",
            "first_name": "John",
            "last_name": "Smith",
            "gender": "M",
            "grade": "7",
            "debtor_code": "1001",
            "parent1_id": "40",
            "parent2_id": "41",
            "accountable_person_id": "40"
        },
        {
            "learner_id": "2",
            "first_name": "Jane",
            "last_name": "Doe",
            "gender": "F",
            "grade": "5",
            "debtor_code": "1001",
            "parent1_id": "40",
            "parent2_id": "41",
            "accountable_person_id": "40"
        }
    ],
    "meta": {
        "limit": 10,
        "max_allowed_limit": 50,
        "cursor": "eyJpZCI6MjU0NiwiX2JhY2t3YXJkIjpmYWxzZX0"
    }
}

Status: 200 OK

{
    "data": [
        {
            "learner_id": "1",
            "first_name": "John",
            "last_name": "Smith",
            "gender": "M",
            "grade": "7",
            "debtor_code": "1001",
            "parent1_id": "40",
            "parent2_id": "41",
            "accountable_person_id": "40",
            "parents": [
                {
                    "parent_id": "40",
                    "title": "Mr",
                    "first_name": "John",
                    "full_names": "John James",
                    "last_name": "Smith",
                    "mobile_calling_code": "27",
                    "mobile_number": "0823456789",
                    "work_tel_number": "0860010012",
                    "home_tel_number": "0123456789",
                    "email_address": "jjsmith@example.com",
                    "date_of_birth": "1967-02-14",
                    "gender": "M",
                    "residential_address": "Plot 101\r\nDaffodil Street\r\nPretoria",
                    "postal_address": "PO Box 12\r\nMenlyn\r\nPretoria",
                    "home_language": "English",
                    "nationality": "South Africa",
                    "debtor_code": "1001",
                    "id_number": "6702145076084",
                    "passport_number": "A0176543",
                    "employer": "Smith Attorneys",
                    "employer_address": "Suite 101\r\nSmith Street\r\nSouth Africa"
                },
                {
                    "parent_id": "41",
                    "title": "Mrs",
                    "first_name": "Jane",
                    "full_names": "Jane Jenny",
                    "last_name": "Smith",
                    "mobile_calling_code": "27",
                    "mobile_number": "0798765432",
                    "work_tel_number": "0860010012",
                    "home_tel_number": "0123456789",
                    "email_address": "smith.jj@example.org",
                    "date_of_birth": "1955-06-17",
                    "gender": "F",
                    "residential_address": "Plot 101\r\nDaffodil Street\r\nPretoria",
                    "postal_address": "PO Box 12\r\nMenlyn\r\nPretoria",
                    "home_language": "English",
                    "nationality": "South Africa",
                    "debtor_code": "1001",
                    "id_number": "5506170079082",
                    "passport_number": "",
                    "employer": "Smith Attorneys",
                    "employer_address": "Suite 101\r\nSmith Street\r\nSouth Africa"
                }
            ]
        },
        {
            "learner_id": "2",
            "first_name": "Jane",
            "last_name": "Doe",
            "gender": "F",
            "grade": "5",
            "debtor_code": "1002",
            "parent1_id": "55",
            "parent2_id": "56",
            "accountable_person_id": "40",
            "parents": [
                {
                    "parent_id": "55",
                    "title": "Mr",
                    "first_name": "Jonathan",
                    "full_names": "Jonathan Andrew",
                    "last_name": "Doe",
                    "mobile_calling_code": "27",
                    "mobile_number": "0813456789",
                    "work_tel_number": "0860010012",
                    "home_tel_number": "0123456789",
                    "email_address": "jd@example.com",
                    "date_of_birth": "1969-03-11",
                    "gender": "M",
                    "residential_address": "91 Monument Street\r\nMonument Park\r\nPretoria",
                    "postal_address": "PO Box 12\r\nMonument Park\r\nPretoria",
                    "home_language": "English",
                    "nationality": "South Africa",
                    "debtor_code": "1002",
                    "id_number": "6903115013085",
                    "passport_number": "",
                    "employer": "Happy Car Hire",
                    "employer_address": "10 Happy Street\r\nJohannesburg\r\nSouth Africa"
                },
                {
                    "parent_id": "56",
                    "title": "Mrs",
                    "first_name": "Janine",
                    "full_names": "Janine",
                    "last_name": "Doe",
                    "mobile_calling_code": "27",
                    "mobile_number": "0798124678",
                    "work_tel_number": "0860010012",
                    "home_tel_number": "0123456789",
                    "email_address": "jd2@example.org",
                    "date_of_birth": "1984-10-07",
                    "gender": "F",
                    "residential_address": "91 Monument Street\r\nMonument Park\r\nPretoria",
                    "postal_address": "PO Box 12\r\nMonument Park\r\nPretoria",
                    "home_language": "English",
                    "nationality": "South Africa",
                    "debtor_code": "1002",
                    "id_number": "8410070079082",
                    "passport_number": "",
                    "employer": "Happy Car Hire",
                    "employer_address": "10 Happy Street\r\nJohannesburg\r\nSouth Africa"
                }
            ]
        }
    ],
    "meta": {
        "limit": 10,
        "max_allowed_limit": 50,
        "cursor": "eyJpZCI6MjU0NiwiX2JhY2t3YXJkIjpmYWxzZX0"
    }
}

Status: 200 OK

{
    "data": [
        {
            "learner_id": "1",
            "first_name": "John",
            "last_name": "Smith",
            "gender": "M",
            "grade": "7",
            "debtor_code": "1001",
            "parent1_id": "40",
            "parent2_id": "41",
            "accountable_person_id": "40",
            "accountable_person": {
                "accountable_person_id": "40",
                "title": "Mr",
                "full_names": "John James",
                "first_name": "John",
                "last_name": "Smith",
                "mobile_calling_code": "27",
                "mobile_number": "0823456789",
                "work_tel_number": "0860010012",
                "home_tel_number": "0123456789",
                "email_address": "jjsmith@example.com",
                "date_of_birth": "1967-02-14",
                "gender": "M",
                "residential_address": "Plot 101\r\nDaffodil Street\r\nPretoria",
                "postal_address": "PO Box 12\r\nMenlyn\r\nPretoria",
                "home_language": "English",
                "nationality": "South Africa",
                "debtor_code": "1001",
                "id_number": "6702145076084",
                "passport_number": "A0176543",
                "employer": "Smith Attorneys",
                "employer_address": "Suite 101\r\nSmith Street\r\nSouth Africa"
            }
        },
        {
            "learner_id": "2",
            "first_name": "Jane",
            "last_name": "Doe",
            "gender": "F",
            "grade": "5",
            "debtor_code": "1002",
            "parent1_id": "55",
            "parent2_id": "56",
            "accountable_person_id": "55",
            "accountable_person": {
                "accountable_person_id": "55",
                "title": "Mr",
                "full_names": "Jonathan Andrew",
                "first_name": "Jonathan",
                "last_name": "Doe",
                "mobile_calling_code": "27",
                "mobile_number": "0813456789",
                "work_tel_number": "0860010012",
                "home_tel_number": "0123456789",
                "email_address": "jd@example.com",
                "date_of_birth": "1969-03-11",
                "gender": "M",
                "residential_address": "91 Monument Street\r\nMonument Park\r\nPretoria",
                "postal_address": "PO Box 12\r\nMonument Park\r\nPretoria",
                "home_language": "English",
                "nationality": "South Africa",
                "debtor_code": "1002",
                "id_number": "6903115013085",
                "passport_number": "",
                "employer": "Happy Car Hire",
                "employer_address": "10 Happy Street\r\nJohannesburg\r\nSouth Africa"
            }
        }
    ],
    "meta": {
        "limit": 10,
        "max_allowed_limit": 50,
        "cursor": "eyJpZCI6MjU0NiwiX2JhY2t3YXJkIjpmYWxzZX0"
    }
}

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

Status: 404 Not Found

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

Description: When validation failed for one or more fields

Status: 400 Bad Request

{
    "success": false,
    "message": "Validation Failed",
    "validation_errors": {
        "parent_id": "The Parent id must be integer",
        "include_parents": "The Include parents must be a boolean"
    }
}

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

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

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

// Query parameters (optional)
$query_params = [
    'debtor_code' => '1002',
    'accountable_person_id' => 14,
    'parent_id' => 4,
    'all_accounts' => 1,
    'include_parents' => 12,
    'include_accountable_person' => 1,
    'reverse_order' => 1,
    'limit' => 10,
    'cursor' => 'eyJpZCI6NjksIl9iYWNrd2FyZCI6ZmFsc2V9',
];

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 --request GET 'https://integrate.d6plus.co.za/api/v2/finplus/debtmanagement/learners?all_accounts=1' \
     --header 'HTTP-X-USERNAME: your_username' \
     --header 'HTTP-X-PASSWORD: your_password' \
     --header 'HTTP-X-SCHOOLID: the_school_id'
PreviousGet Accountable Person(s)NextGet Transaction Type(s)

Last updated 1 day ago