API Documentation.
Version: 3.0.15

By using the ValeLearning API Platform, you can access and integrate records into your third-party application.

Last Updated: August 15th, 2024 at 8:00 AM

Getting Started.

To get started using the ValeLearning API, please review the following sections:

Before You Start Register With L&D

Before You Start

You will need:

ValeLearning API Credentials which consist of client ID and client Access Token.
A browser to run your query which will export JSON data; or
A command-line tool such as Terminal or an app like Postman that can perform requests and handle JSON data.

Register With L&D

Before your ValeLearning API Credentials are issued, we need to verify the legitimacy of your third-party application. Please fill out the following form to request a developer account. Developer accounts contain your unique ValeLearning API Credentials.

API Structure.

There are two (2) main components to the ValeLearning API:

Request Structure Response Structure Basic Request Example

API Request Structure

ValeLearning API requests require the following URL parameters:


                    client_id={CLIENT_ID}

Your ValeLearning API Client ID. Please review the Before You Start section for more information.


                    client_secret={CLIENT_SECRET}

Your ValeLearning API Client Secret. Please review the Before You Start section for more information.


                    scope={SCOPE}

The ValeLearning API Scope determines the type of request. Avialable public scopes are:

validate_token
get_datasheet
get_serials
get_profiles
user_profile
course_export
region_export


                    value={VALUE}

The default value parameter for the ValeLearning API. The {VALUE} parameter is used to target a specific response from the ValeLearning API.


                    start={START_START}

Some ValeLearning API Scopes require a date object to be passed over the URL parameters. The {START_START} parameter requires a date string in ISO 8601 format (YYYY-MM-DD). Please note that no time data is required.


                    end={END_DATE}

The {END_DATE} parameter requires the same format as the {START_START} parameter.


                    response_type={TYPE}

ValeLearning API responses will always default to JSON format. There is limited support for exporting data as a downloadable CSV file. The response option is declared in the {TYPE} parameter.

json (JSON format)
csv (downloadable CSV format)

Please note that these responses requested as CSV will still output JSON data, but a downloadable link to the generated file will be included in the response. CSV support is available for all public scopes, except for:

validate_token


                    callback={CALL}

If your application requires a callback function, you can request a unique {CALL} by including a numerical callback parameter in your API request.

API Response Structure

There are three (3) types of responses for public ValeLearning API requests:

Error Response

        
            {

            "error":"The contractor ID does not exist in the ValeLearning contractor database.",

            "response":[],

            "target_value":"1234567",

            "scope":"user_profile",

            "client": "{CLIENT_ID}",

            "secret": "{ACCESS_TOKEN}",

            "origin": "https://api.valelearning.ca/auth?client_id={CLIENT_ID}&client_secret={ACCESS_TOKEN}&scope=user_profile&value=1234567&response_type=json"

            "Error":"DEPRECIATED KEY: See error data for details."

            }

Error responses contain the following JSON objects:

error: The error key contains a description of the error.
response: The response key will either contain the result from the ValeLearning database or an error response. In the example above, the result was empty, which is why the error was thrown.
target_value: The value key is the data you're passing onto the ValeLearning database, in the example above it's the target for a contractor search.
scope: The selected scope for the request.
client: Your ValeLearning API Client ID.
secret: Your ValeLearning API Client Secret.
origin: The request origin URL.

Success Response

        
            {

            "success":"Your requested CSV export has been successfully generated. Your download should start shortly.",

            "response":"https://api.valelearning.ca/profile-export.csv",

            "target_value":"OTA3307",

            "scope":"user_profile",

            "client": "{CLIENT_ID}",

            "secret": "{ACCESS_TOKEN}",

            "origin": "https://api.valelearning.ca/auth?client_id={CLIENT_ID}&client_secret={ACCESS_TOKEN}&scope=user_profile&value=OTA3307&response_type=csv"

            }

Success responses contain a similar structure as error responses, except for these JSON objects:

success: The success key contains a description of the success.
response: The response contains a successful response from the ValeLearning server. In the example above, the result is the destination of a CSV file.

Successful Data Output Response

        
            {

            "id": 1234,

            "FirstName": "Brad",

            "LastName": "Danks",

            "ValeID": "OTA3307",

            "DateOfBirth": "1994-06-12",

            "ContractorPhone": "7051234567",

            "ContractorEmail": "test@vale.com",

            "ContractorOccupation": "Other",

            "ContractorLocation": "Sudbury, ON",

            "CompanyName": "VALE CANADA",

            "CompanyPhone": "7051234567",

            "EmergencyName": "Kelly Danks",

            "EmergencyPhone": "7051234567",

            "Type": "N",

            "RecordUpdated": "2024-08-15",

            ...

            }

Successful data output responses vary between request scopes, however the data is structured in JSON. The example above is for a contractor profile export (user_profile) requested in JSON format.

Basic Request Example

Below is an example of validating your ValeLearning API Credentials. Notice the request scope we're using is referenced in the list above.

        
            https://api.valelearning.ca/auth?

            client_id={CLIENT_ID}

            &client_secret={ACCESS_TOKEN}

            &scope=validate_token

            &response_type=json

If your ValeLearning API Credentials are valid, you will receive the following successful JSON response.

        
            {

            "success": "Account Validated. Your CLIENT_ID and ACCESS_TOKEN are valid.",

            "scope": "validate_token",

            "client": "{CLIENT_ID}",

            "secret": "{ACCESS_TOKEN}",

            "origin": "https://api.valelearning.ca/auth?client_id={CLIENT_ID}&client_secret={ACCESS_TOKEN}&scope=validate_token&value=check&response_type=json"

            }

Supported Public API Scopes.

The following sections outline each available scope:

Validate Token Get Datasheet Get Serials Get Profiles User Profile Course Export Region Export

Validate Token

Scope: validate_token

        
            https://api.valelearning.ca/auth?

            client_id={CLIENT_ID}

            &client_secret={ACCESS_TOKEN}

            &scope=validate_token

            &response_type=json

The above scope is used to verify your ValeLearning API credentials.

Get Datasheet

Scope: get_datasheet

        
            https://api.valelearning.ca/auth?

            client_id={CLIENT_ID}

            &client_secret={ACCESS_TOKEN}

            &scope=get_datasheet

            &value={SHEET}

            &response_type=json

The above scope exports ValeLearning datasheets.

Datasheets contain various information ranging from the module library to valid Vale Operations. Available {SHEET} types are as follows:

modules: ValeLearning Module Library
locations: Available Vale Operations
occupations: Supported Occupation Types
vendors_ontario: Vale Certified Ontario Vendor List
vendors_manitoba: Vale Certified Manitoba Vendor List
vendors_newfoundland: Vale Certified Newfoundland Vendor List
vendors_unitedkingdom: Vale Certified United Kingdom Vendor List

Get Serials

Scope: get_serials

        
            https://api.valelearning.ca/auth?

            client_id={CLIENT_ID}

            &client_secret={ACCESS_TOKEN}

            &scope=get_serials

            &value=all

            &response_type=json

The above scope exports all generated Vale Contractor Pass Numbers (C100000 Series) from ValeLearning.ca. The Number Generator was migrated to ValeLearning in June of 2022.

Get Profiles

Scope: get_profiles

        
            https://api.valelearning.ca/auth?

            client_id={CLIENT_ID}

            &client_secret={ACCESS_TOKEN}

            &scope=get_profiles

            &value=all

            &start={START_DATE}

            &end={END_DATE}

            &response_type=json

The above scope exports contractor profiles that have been updated within a targeted date range. This is the only scope that supports {START_DATE} and {END_DATE} parameters that target when the profile was last updated or created. If you wish to export all contractors, then set both parameters to "all".

User Profile

Scope: user_profile

        
            https://api.valelearning.ca/auth?

            client_id={CLIENT_ID}

            &client_secret={ACCESS_TOKEN}

            &scope=user_profile

            &value={CONTRACTOR_ID}

            &response_type=json

The above scope exports a single contractor profile. Replace {CONTRACTOR_ID} with the contractor's unique Vale ID.

Course Export

Scope: course_export

        
            https://api.valelearning.ca/auth?

            client_id={CLIENT_ID}

            &client_secret={ACCESS_TOKEN}

            &scope=course_export

            &value={COURSE_ID}

            &response_type=json

The above scope exports training records for a specific ValeLearning training module. Replace {COURSE_ID} with any module ID from our Module Library. Please note that this scope is locked for 2500 results per request. If you require more results, please contact the system administrator.

Region Export

Scope: region_export

        
            https://api.valelearning.ca/auth?

            client_id={CLIENT_ID}

            &client_secret={ACCESS_TOKEN}

            &scope=region_export

            &value={REGION_ID}

            &response_type=json

The above scope exports contractors by Vale region.

Available {REGION_ID} options are as follows:

1: Port Colborne, ON
2: Sudbury, ON
3: Long Harbour, NL
4: Voiseys Bay, NL
5: Thompson, MB
6: Clydach, UK

Training Index.

The ValeLearning training index is outlined below:

Module Status Module Library

Module Status

Our module library contains all current and depreciated training modules. Since contractor training is always changing, ValeLearning keeps records even if those records are no longer considered valid or have been replaced with an updated module.

Modules may be placed under the following status:

active: The module is considered valid training.
paused: The module is considered valid training but new contractor registrations have been suspended. This is usually due to the module being replaced by updated training.
depreciated: The module has been removed from ValeLearning's course offerings. This is usually due to the module being replaced or the site/operation being closed.

Module Library ( items)

Below are the full course offerings from ValeLearning.ca. A more detailed overview can be accessed through the Data Sheets panel in your ValeLearning Management account.

Contact Us

If you have any questions or comments about this API documentation, please contact us at:

Gavin Toole, Interim Superintendent
Learning and Development, NA Operations

VALE
KMK Place, 2nd Level
18 Hebron Way
St. John's, NL, A1A 0L9
C: 1.709.728.6124

Matthew Urso, Senior Developer and ValeLearning Project Lead
OvertheAtlantic Interactive Limited (OTA)

OTA™ Creative. Candid. Insightful.
C: 1.705.521.2231
ota.studio

Questions?

Last Updated: September 5th, 2023 at 1:00 PM

API Documentation.Version: 3.0.15