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, additional optional since and until query parameters will allow you to specify a date range, and only learners who have left in this date range will be returned. By default, learners who have left in the last month will be returned. The since - until range may not be more than 1 year.

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 Grade(s) Lookup 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 learner transfer dates should be limited, when using the status parameter. Defaults to 1 month ago. May not be more than 1 year before until. Format: YYYY-MM-DD
until	String	The date until which left learner transfer dates should be limited, when using the status parameter. Defaults to today. May not be more than 1 year after since. 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
name	String	Search for a learner by their name, surname or name and surname combination
family_code	Integer	Search for a learner(s) by their family code

Headers

Name	Type	Description
HTTP-X-USERNAME*	String	As provided by d6
HTTP-X-PASSWORD*	String	As provided by d6

200 The request was successful.

[
    {
        "id": "1",
        "first_name": "John",
        "last_name": "Smith",
        "mobile_calling_code": "27",
        "mobile_number": "0823456789",
        "email_address": "[email protected]",
        "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": "[email protected]",
                "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": "[email protected]",
                "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": "[email protected]",
        "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": "[email protected]",
                "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": "[email protected]",
                "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"            
            }
        ]
    }
]

404: Not Found The resource was not found.

401: Unauthorized The server understood the request, but is refusing it or access is not allowed.

403: Forbidden The server understood the request, but the requested action is not allowed.

Examples

PHP

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