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 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 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": "[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"            
            }
        ]
    }
]

{
    "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'

PreviousLearner NextGet Learner Absentees

Last updated 3 months ago