> 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/reference/administration+/learner/get-learner-s.md). # 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](/reference/administration+/lookups/grade-s.md) 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 | {% tabs %} {% tab title="200 The request was successful." %} ```json [ { "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" } ] } ] ``` {% endtab %} {% tab title="404: Not Found The resource was not found." %} ```json { "error": "Not found", "error_description": "No learner records found" } ``` {% endtab %} {% tab title="401: Unauthorized The server understood the request, but is refusing it or access is not allowed." %} ```json { "error": "Unauthorized", "error_description": "Client access not authorised" } ``` {% endtab %} {% tab title="403: Forbidden The server understood the request, but the requested action is not allowed." %} ```json { "error": "Integration not activated", "error_description": "Please activate the Admin+ API for this client before making this request" } ``` {% endtab %} {% endtabs %} ## Examples {% tabs %} {% tab title="PHP" %} ```php 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; ``` {% endtab %} {% tab title="cURL" %} ```bash 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' ``` {% endtab %} {% endtabs %}