> For the complete documentation index, see [llms.txt](https://apidocs.d6plus.co.za/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://apidocs.d6plus.co.za/v2/reference/finance+/debt-management/get-schools.md).

# Get Schools

<mark style="color:blue;">`GET`</mark> `/v2/finplus/debtmanagement/schools` `(/{id})`

Use this endpoint to fetch one or more **school records**.

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

### Request Headers

<table><thead><tr><th width="194.7427978515625">Name</th><th width="122.5714111328125">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></tbody></table>

### Query Parameters

<table><thead><tr><th width="149.028564453125">Name</th><th width="114.7142333984375">Type</th><th>Description</th></tr></thead><tbody><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>

<pre class="language-json"><code class="lang-json">{
    "data": [
<strong>        {
</strong>            "school_id": "1000",
            "school_name": "d6+ Primary School",
            "school_short_name": "primary",
            "ownership_type": "Public",
            "country": "South Africa",
            "province": "Gauteng",
            "town": "Pretoria",
            "suburb": "Waterkloof Glen",
            "district": "METRO EAST",
            "district_code": "D1",
            "circuit": "Circuit 2",
            "quantile": "4",
            "emis_number": "600000001",
            "telephone_number": "0123334444",
            "lowest_grade": "Grade R",
            "highest_grade": "Grade 7",
            "admin_email_address": "info@d6.co.za",
            "debtors_email_address": "accounts@d6.co.za",
            "finance_email_address": "accounts@d6.co.za",
            "physical_address": "Spaces Building, Floor 3,/r/n210 Amarand Ave,/r/nWaterkloof Glen,/r/nPretoria,/r/n0010",
            "postal_address": "Spaces Building, Floor 3,/r/n210 Amarand Ave,/r/nWaterkloof Glen,/r/nPretoria,/r/n0010",
            "has_after_school_center": "Yes",
            "has_hostel": "No",
            "uses_debit_orders": "No",
            "uses_cashless": "Yes"
        },
        {
            "school_id": "1001",
            "school_name": "d6+ Secondary School",
            "school_short_name": "secondary",
            "ownership_type": "Public",
            "country": "South Africa",
            "province": "Western Cape",
            "town": "Stellenbosch",
            "suburb": "Techno Park",
            "district": "CAPE WINELANDS",
            "district_code": "D1",
            "circuit": "Circuit 10",
            "quantile": "5",
            "emis_number": "600000002",
            "telephone_number": "0213337654",
            "lowest_grade": "Grade 8",
            "highest_grade": "Grade 12",
            "admin_email_address": "info@d6.co.za",
            "debtors_email_address": "accounts@d6.co.za",
            "finance_email_address": "accounts@d6.co.za",
            "physical_address": "Octo Place, Block B\r\nElektron Road\r\nTechno Park\r\nStellenbosch\r\n7600",
            "postal_address": "Octo Place, Block B\r\nElektron Road\r\nTechno Park\r\nStellenbosch\r\n7600",
            "has_after_school_center": "No",
            "has_hostel": "Yes",
            "uses_debit_orders": "Yes",
            "uses_cashless": "No"
        }
    ],
    "meta": {
        "limit": 10,
        "max_allowed_limit": 50,
        "cursor": "eyJpZCI6MjU0NiwiX2JhY2t3YXJkIjpmYWxzZX0"
    }
]
</code></pre>

{% endtab %}

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

```json
{
    "school_id": "1000",
    "school_name": "d6+ Primary School",
    "school_short_name": "primary",
    "ownership_type": "Public",
    "country": "South Africa",
    "province": "Gauteng",
    "town": "Pretoria",
    "suburb": "Waterkloof Glen",
    "district": "METRO EAST",
    "district_code": "D1",
    "circuit": "Circuit 2",
    "quantile": "4",
    "emis_number": "600000001",
    "telephone_number": "0123334444",
    "lowest_grade": "Grade R",
    "highest_grade": "Grade 7",
    "admin_email_address": "info@d6.co.za",
    "debtors_email_address": "accounts@d6.co.za",
    "finance_email_address": "accounts@d6.co.za",
    "physical_address": "Spaces Building, Floor 3,/r/n210 Amarand Ave,/r/nWaterkloof Glen,/r/nPretoria,/r/n0010",
    "postal_address": "Spaces Building, Floor 3,/r/n210 Amarand Ave,/r/nWaterkloof Glen,/r/nPretoria,/r/n0010",
    "has_after_school_center": "Yes",
    "has_hostel": "No",
    "uses_debit_orders": "No",
    "uses_cashless": "Yes"
}
```

{% 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 school 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_bank_accounts": "The Limit must be integer"
    }
}
```

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

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

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

// Query parameters (optional)
$query_params = [
    '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;

```

{% endtab %}

{% tab title="cURL" %}

```bash
curl --request GET 'https://integrate.d6plus.co.za/api/v2/finplus/debtmanagement/schools' \
     --header 'HTTP-X-USERNAME: your_username' \
     --header 'HTTP-X-PASSWORD: your_password'
```

{% endtab %}
{% endtabs %}