API for the LLN Robot System
Purpose
These APIs are also used by the LLN-Robot Zapier application and APIs must be enabled for your deployment before using the Zapier integration.
Getting Started
Configure API Access
To be able to use the API for your deployment, you first need to go to Manage System Settings and switch Enable API to on. Once enabled, your API Authentication Key will be made visible. This key is validated on all calls to API endpoints.
Authentication
When sending any request to the API we require the api key be passed in a header parameter with key Authorization
Key: Authorization
Value: ROBOT-V1-KEY apikey=”[API Authentication Key]”
Example of header key as shown in a Postman request;
URL Structure
APIs endpoints are access via a standard URL structure;
http://api.lln.training/api/[deployment]/v1/[resource]
where the variables inside [ ] need to be replaced for the correct response.
| deployment | the deployment name that is assigned to the client to access the LLN Robot |
| resource | the kind of resource information that you want to access from the system, in this case it is 'learners' since we are accessing all the learners information. |
Some endpoints may have required / option query string parameters. These are mentioned under each endpoint.
Data Formats
The response from all APIs is a JSON document. At this time, JSON is the only format that we support, therefore you will need to take it into consideration when displaying the data.
Standard Response Codes
| Response Code | Definition |
| 200 | No Errors. Data should be fetched. |
| 400 | Bad Request. There is a mistake in the URL that you entered. Please check and make sure the version and the resource are spelt and placed correctly. |
| 401 | Unauthorized - wrong API Key or Deployment name. |
| 404 | Not Found. There is no deployment with that name. |
API Endpoints
Learners
/api/[deployment]/v1/learners
| HTTP Method | Use |
| GET | Fetching a list of records. |
| POST | Create / invite a learner |
GET Learners
Retrieves the list of learners in your deployment.
Optional Parameters can be added to this the URL to filter the results;
| Name | Type | Use |
| since | Date | a UTC date in JSON format. Will only retrieve learner records updated since this time. |
| string | Will only return learner record(s) that have this email address | |
| complete | Int | If parameter is included, will only return learner which have been completed the quiz. |
Examples:
https://api.lln.training/api/testing/v1/learners?since=2019-01-01T00:00:00Z
https://api.lln.training/api/testing/v1/learners?completed=1&email=test@testing.com
Results format
An array of JSON objects will be returned with the following properties;
| Property Name | Type | Use |
| inviteCode | UUID | Uniquely identifies the quiz results. |
| learnerId | string | The learnerId from your deployment (if entered). Please Note: the same learnerId may be on several results if learner has redone the quiz or completed multiple testLevels. |
| name | Object | The learners name { first: string, last } |
| string | The email address of the learner | |
| results | Object | ACSF Test: The results object contains 5 key-value pairs which display their ACSF scores for each section. VSL Test: The results object contains 2 key-value pairs which display a 1 if they passed the section or a 0 if they failed. |
| complete | boolean | Is true if the learner has completed the quiz. |
| details | Array<Object> | The details object includes all custom fields that the administrators of the deployment want learners to fill out. |
| testLevel | String | Displays test they were invited for. |
| updatedAt | Date | JSON formatted UTC date/time this record was last updated |
Example object;
{
"email": "danthompson@example.com",
"inviteCode": "e6d064ee-3e2c-4136-8112-5cda96f86928",
"completeTime": "2019-07-04T04:51:31.820Z",
"updatedAt": "2019-09-07T03:22:34.750Z",
"learnerId": "448-726-085-021",
"results": {
"learning": 1,
"reading": 2,
"writing": 0,
"oralcommunication": 2,
"numeracy": 3
},
"details": [],
"name": {
"first": "Daniel",
"last": "Thompson"
},
"id": "e6d064ee-3e2c-4136-8112-5cda96f86928",
"quiz": "ACSF_4",
"complete": true
}
POST Learner
This method can be used to create new learners in the LLN robot system. The learner record will be created and an email will be sent to the leaner inviting them to complete the quiz.
The details of the new learner must be passed as a JSON object in the request body having the following properties
| Property Name | Type | Use |
| nameFirst | String | Learners first name |
| nameLast | String | Learners surname |
| String | Email address of the learner | |
| testLevel | String | The test level to create for them. Value in this field must be one of; |
| details | Array<Object> | The details object includes all custom fields that the administrators of the deployment want learners to fill out. |
| testLevel | String | Displays test they were invited for. |
| updatedAt | Date | JSON formatted UTC date/time this record was last updated |
COURSES
/api/[deployment]/v1/COURSES
The courses endpoint can be used to retrieve the list of courses defined in your deployment. The results from this API could then be used in calling the Learner Report endpoint.
GET
Retrieves the list of courses set up your deployment.
Result format
An array of JSON objects will be returned with the following properties;
| Property Name | Type | Use |
| title | String | Title of the course |
| level | Number | Qualification level |
| profile | Object | The ACSF result profile for this course and level |
| Units | Array<string> | Array of the units for the course |
| Id | String | Internal LLN-Robot id for the course |
Example object;
{
"title": "Business Administration",
"level": 4,
"profile": {
"numeracy": 3,
"oralcommunication": 3,
"writing": 4,
"reading": 4,
"learning": 4
},
"units": [
"BSBWRT401",
"BSBSUS401",
"BSBRSK401",
"BSBADM301"
],
"id": "57cf74e12e3d91ef586e1b75"
}
LEARNER SUMMARY REPORT
/api/[deployment]/v1/learnersummary
This endpoint can be used to generate the learner results summary report for a specific learner. The report is generated and a URL link to the report is returned.
GET
The learnerId parameter is required on this request.
| Name | Type | Use |
| learnerId | UUID | The unique identifier of the record IMPORTANT NOTE: this is the inviteCode field returned from the GET Learners endpoint |
Examples:
Result format
The response is an array but will only include a single entry. The object returned simply has one property “file” which is the URL of the document that can be downloaded from AWS.
Example object;
{
"file": "https://s3-ap-southeast-2.amazonaws.com/static.lln.training/zapier/testing/9875687a-8417-49c6-8da3-5d3c8479a71a_summary"
}
LEARNER REPORT
/api/[deployment]/v1/learnerreport
This endpoint can be used to generate the LLN report for the learner results and any supplements required based on a corresponding course.
GET
The learnerId and courseName parameters are both required on this request.
| Name | Type | Use |
| learnerId | UUID | The unique identifier of the record IMPORTANT NOTE: this is the inviteCode field returned from the GET Learners endpoint |
| courseName | String | Course Name – must match a course name that exists in your deployment, eg. as returned from the Courses endpoint. |
Examples:
Result format
The response is an array but will only include a JSON object which includes a link to the report document and supplements (if applicable).
Example object;
{
"file": "https://s3-ap-southeast-2.amazonaws.com/static.lln.training/zapier/testing/9875687a-8417-49c6-8da3-5d3c8479a71a_Warehousing Operations",
"supplementLink": "https://api.lln.training/testing/supplement/d243a0db-4875-46dd-bfee-a5df214f3975"
}