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
  • Get one or more learner records
  • Examples
  1. Reference
  2. Administration+
  3. Learner

Get Learner(s)

Get one or more learner records

GET https://integrate.d6plus.co.za/api/v1/adminplus/learners/{school_login_id}

Use this endpoint to fetch one or more learner records for the specified school. By default, all current enrolled learners will be returned.

It is possible to retrieve non-current learners by providing the optional status query parameter.

When retrieving left learners, an additional optional since query parameter will allow you to specify a date, and only learners who have left after this date will be returned. By default, learners who have left in the last month will be returned. The since value may not be more than 1 year in the past.

It is possible to retrieve a single learner by providing the optional learner_id query parameter.

It is possible to retrieve the learners for a specific grade or grades, by providing the optional grade_id query parameter. This can be a single grade ID or a comma-separated list of grade ID's. The list of available grade ID's for a school can be obtained by making use of the endpoint.

If your subscription includes the Parent API, it is possible to include the parent/guardian data directly in the learner response payload by providing the optional include_parents query parameter. The parent/guardian data will be included in a sub-array per learner, with parent/guardian 1 followed by parent/guardian 2.

Path Parameters

Name
Type
Description

school_login_id*

Integer

The login ID of the school to retrieve data from

Query Parameters

Name
Type
Description

status

String

The status of the learners to return. Acceptable values are: * current (default) * left * waitlist

since

String

The date to which left learners should be limited, when using the status parameter. Format: YYYY-MM-DD

learner_id

Integer

The ID of a specific learner

grade_id

Integer

A comma-separated list of grade ID's to filter by

include_parents

String

Whether to include the parent data in the response

Headers

Name
Type
Description

HTTP-X-USERNAME*

String

As provided by d6

HTTP-X-PASSWORD*

String

As provided by d6

[
    {
        "id": "1",
        "first_name": "John",
        "last_name": "Smith",
        "mobile_calling_code": "27",
        "mobile_number": "0823456789",
        "email_address": "jsmith@example.com",
        "date_of_birth": "2018-01-01",
        "gender": "M",
        "ethnic_group_id": "4",
        "ethnic_group": "White",        
        "home_language_id": "1",
        "home_language": "Afrikaans",
        "tuition_language_id": "1",        
        "tuition_language": "Afrikaans",
        "nationality": "South Africa",
        "admission_number": "12345",
        "family_code": "1001",
        "id_number": "1801015005084",
        "passport_number": "",
        "grade_id": "9",
        "grade": "7",
        "register_class_name": "5A",
        "register_class_teacher_id": "4",
        "country": "South Africa",
        "province": "Gauteng",        
        "education_stream": "Mainstream",
        "photo_url": "",
        "parent1_id": "40",
        "parent2_id": "41",
        "parents": [
            {
                "id": "40",
                "title": "Mr",
                "first_name": "John James",
                "last_name": "Smith",
                "mobile_calling_code": "27",
                "mobile_number": "0823456789",
                "email_address": "jjsmith@example.com",
                "date_of_birth": "1967-02-14",
                "gender": "M",
                "ethnic_group_id": "4",
                "ethnic_group": "White",
                "residential_address": "Plot 101\r\nDaffodil Street\r\nPretoria",
                "postal_address": "PO Box 12\r\nMenlyn\r\nPretoria",
                "home_language_id": "2",                
                "home_language": "English",
                "nationality": "South Africa",
                "family_code": "1001",
                "id_number": "6702145076084",
                "passport_number": "A0176543",
                "marital_status_id": "2",
                "marital_status": "Married",                
                "occupation_status": "Full Time Employed",
                "occupation": "Salesman",
                "employment_sector": "Selling",
                "gross_annual_income": "120000.00"            
            },
            {
                "id": "41",
                "title": "Mrs",
                "first_name": "Jane Jenny",
                "last_name": "Smith",
                "mobile_calling_code": "27",
                "mobile_number": "0798765432",
                "email_address": "smith.jj@example.org",
                "date_of_birth": "1955-06-17",
                "gender": "F",
                "ethnic_group_id": "1",                
                "ethnic_group": "African/Black",
                "residential_address": "Plot 101\r\nDaffodil Street\r\nPretoria",
                "postal_address": "PO Box 12\r\nMenlyn\r\nPretoria",
                "home_language_id": "2",                
                "home_language": "English",
                "nationality": "South Africa",
                "family_code": "1001",
                "id_number": "5506170079082",
                "passport_number": "",
                "marital_status_id": "2",
                "marital_status": "Married",                
                "occupation_status": "Unemployed",
                "occupation": "",
                "employment_sector": "Other",
                "gross_annual_income": "0.00"            
            }
        ]
    },
    {
        "id": "2",
        "first_name": "Jane",
        "last_name": "Doe",
        "mobile_calling_code": "27",
        "mobile_number": "0798765432",
        "email_address": "jane@example.org",
        "date_of_birth": "2018-06-13",
        "gender": "F",
        "ethnic_group_id": "1",
        "ethnic_group": "African/Black",
        "home_language_id": "1",        
        "home_language": "Afrikaans",
        "tuition_language_id": "1",        
        "tuition_language": "Afrikaans",
        "nationality": "South Africa",
        "admission_number": "12346",
        "family_code": "1001",
        "id_number": "1806130110087",
        "passport_number": "",
        "grade_id": "7",        
        "grade": "5",
        "register_class_name": "4C",
        "register_class_teacher_id": "13"
        "country": "South Africa",
        "province": "Gauteng",        
        "education_stream": "Mainstream",
        "photo_url": "",
        "parent1_id": "40",
        "parent2_id": "41",
        "parents": [
            {
                "id": "40",
                "title": "Mr",
                "first_name": "John James",
                "last_name": "Smith",
                "mobile_calling_code": "27",
                "mobile_number": "0823456789",
                "email_address": "jjsmith@example.com",
                "date_of_birth": "1967-02-14",
                "gender": "M",
                "ethnic_group_id": "4",                
                "ethnic_group": "White",
                "residential_address": "Plot 101\r\nDaffodil Street\r\nPretoria",
                "postal_address": "PO Box 12\r\nMenlyn\r\nPretoria",
                "home_language_id": "2",                
                "home_language": "English",
                "nationality": "South Africa",
                "family_code": "1001",
                "id_number": "6702145076084",
                "passport_number": "A0176543",
                "marital_status_id": "2",
                "marital_status": "Married",
                "occupation_status": "Full Time Employed",
                "occupation": "Salesman",
                "employment_sector": "Selling",
                "gross_annual_income": "120000.00"            
            },
            {
                "id": "41",
                "title": "Mrs",
                "first_name": "Jane Jenny",
                "last_name": "Smith",
                "mobile_calling_code": "27",
                "mobile_number": "0798765432",
                "email_address": "smith.jj@example.org",
                "date_of_birth": "1955-06-17",
                "gender": "F",
                "ethnic_group_id": "1",                
                "ethnic_group": "African/Black",
                "residential_address": "Plot 101\r\nDaffodil Street\r\nPretoria",
                "postal_address": "PO Box 12\r\nMenlyn\r\nPretoria",
                "home_language_id": "2",                
                "home_language": "English",
                "nationality": "South Africa",
                "family_code": "1001",
                "id_number": "5506170079082",
                "passport_number": "",
                "marital_status_id": "2",
                "marital_status": "Married",
                "occupation_status": "Unemployed",
                "occupation": "",
                "employment_sector": "Other",
                "gross_annual_income": "0.00"            
            }
        ]
    }
]
{
    "error": "Not found",
    "error_description": "No learner records found"
}
{
    "error": "Unauthorized",
    "error_description": "Client access not authorised"
}
{
    "error": "Integration not activated",
    "error_description": "Please activate the Admin+ API for this client before making this request"
}

Examples

<?php

const BASE_URL = 'https://integrate.d6plus.co.za/api/v1/adminplus/learners';
const SCHOOL_LOGIN_ID = '1000';
const PARAMS = [
    'learner_id' => 1, 
    'include_parents' => 1
    ];
const API_USERNAME = getenv('API_USERNAME'); // Assuming you have these environment variables set
const API_PASSWORD = getenv('API_PASSWORD');

$curl = curl_init();

$query = http_build_query(PARAMS);

$options = [
    CURLOPT_URL => BASE_URL . '/' . SCHOOL_LOGIN_ID . '?' . $query,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_SSL_VERIFYPEER => true,
    CURLOPT_CUSTOMREQUEST => 'GET',
    CURLOPT_HTTPHEADER => [
        "HTTP-X-USERNAME: " . API_USERNAME,
        "HTTP-X-PASSWORD: " . API_PASSWORD
    ],
];

curl_setopt_array($curl, $options);

$response = curl_exec($curl);

if (curl_errno($curl)) {
    throw new Exception('Curl error: ' . curl_error($curl));
}

curl_close($curl);

echo $response;
curl --location 'https://integrate.d6plus.co.za/api/v1/adminplus/learners/1000?learner_id=1&include_parents=1' \
--header 'HTTP-X-USERNAME: your_username' \
--header 'HTTP-X-PASSWORD: your_password'
❗
❗
Grade(s) Lookup