# Get Learner(s)

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

{% 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 <a href="#pagination" id="pagination"></a>

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="177.54296875">Name</th><th width="134">Type</th><th>Description</th></tr></thead><tbody><tr><td><code>{id}</code></td><td>Integer</td><td>Optionally provide the <strong>Learner ID</strong> for retrieving a single record.</td></tr></tbody></table>

### Request Headers

<table><thead><tr><th width="198.2572021484375">Name</th><th width="121">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="258">Name</th><th width="96.51434326171875">Type</th><th>Description</th></tr></thead><tbody><tr><td><code>debtor_code</code></td><td>Integer</td><td>To filter on a specific <strong>Debtor Code</strong></td></tr><tr><td><code>accountable_person_id</code></td><td>Integer</td><td>To filter on a specific <strong>Accountable Person ID</strong></td></tr><tr><td><code>parent_id</code></td><td>Integer</td><td>To filter on a specific <strong>Parent ID</strong></td></tr><tr><td><code>all_accounts</code></td><td>Boolean</td><td>Whether to <strong>include all accounts</strong></td></tr><tr><td><code>include_parents</code></td><td>Boolean</td><td>Whether to <strong>include the parent data</strong> in the response</td></tr><tr><td><code>include_accountable_person</code></td><td>Boolean</td><td>Whether to <strong>include the accountable person's data</strong> in the response</td></tr><tr><td><code>cursor</code></td><td>String</td><td>To <strong>retrieve</strong> the <strong>next group</strong> of items (if any)</td></tr><tr><td><code>limit</code></td><td>Integer</td><td>To <strong>override</strong> the <strong>default limit</strong> 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 <strong>reverse</strong> the <strong>order</strong> 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": [
        {
            "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"
    }
}
```

{% endtab %}

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

```json
{
    "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",
                    "correspondence_language": "English",
                    "communication_method": "E-Mail",
                    "include_in_debtor_comms": "No",
                    "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",
                    "correspondence_language": "English",
                    "communication_method": "SMS",
                    "include_in_debtor_comms": "Yes",
                    "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"
    }
}
```

{% endtab %}

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

```json
{
    "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",
                "correspondence_language": "English",
                "communication_method": "E-Mail",
                "include_in_debtor_comms": "Yes",
                "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",
                "correspondence_language": "English",
                "communication_method": "SMS",
                "include_in_debtor_comms": "Yes",
                "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"
    }
}
```

{% endtab %}

{% tab title="ID Not Found Error (404 Not Found)" %}
**Description:** The requested ID does not exist in the system.

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

```json
{
    "success": false,
    "message": "The learner 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": {
        "parent_id": "The Parent id must be integer",
        "include_parents": "The Include parents must be a boolean"
    }
}
```

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

```

{% endtab %}

{% tab title="cURL" %}

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

{% endtab %}
{% endtabs %}