Authorization:

Authorization occurs using the OAUTH v2 protocol with the client_credentials grant. For authorization, you will need:

API Requests:

To begin using our API:

  1. You must obtain an access key. To do so, go to the Settings section of your Academy and click API tab
  2. Next, you must set up access. To do this, click “Register a new OAuth application” and fill in all fields in the window that appears. You can change these fields at any time. Next, click “Register Application.”
  3. You will be redirected to a page with the newly created access keys. Here, copy the Client ID and Client Secret and transfer them to your application.
  4. To authorize using the keys you have obtained,send a POST request using the following URL: https://app.academyocean.com/oauth/token with the following parameters:
 {'client_id' => 'CLIENT_ID','client_secret' => 'CLIENT_SECRET','scope' => '',‘grant_type’ => ‘client_credentials’ }

The response will be in the following format:

 {"token_type":"Bearer","expires_in":604800,"access_token":"eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsImp0aSI6IjM5ODIwNmQyNGZjNGY1NDkxZTZiNDVkZmQyZjY2NjE4NGFmNTdiMjc0Y2FkMWQ4NjUyZThmZTNjZjk4NDYzNzI0N2ZlNDkxMzk0YzU5YWM2In0.eyJhdWQiOiI0IiwianRpIjoiMzk4MjA2ZDI0ZmM0ZjU0OTFlNmI0NWRmZDJmNjY2MTg0YWY1N2IyNzRjYWQxZDg2NTJlOGZlM2NmOTg0NjM3MjQ3ZmU0OTEzOTRjNTlhYzYiLCJpYXQiOjE1MDYwMDU4MjAsIm5iZiI6MTUwNjAwNTgyMCwiZXhwIjoxNTA2NjEwNjIwLCJzdWIiOiIiLCJzY29wZXMiOltdfQ.gdQDcsFOS6h8EoYKL-5naQVVf66X_8iVDwYlIyZ8Kd6Q0LLDdWj0bD0LEkt4XrsKPbB3BqfAOauNKInNrvw-NcbyZ50p3v29Rp_SN5zGHIGqi6P-2f6l0ssz_ARgdpzOfyEywUIj23EIY5jTTPzXTM_Ci6Q-GWCo3SnSs8o2qaBF640NUldE79UNorm-rhfMaulvqmiuQmcMRlQr-cjtObaDCKnjYqaSoUfsF_-aJGJag3-pzrszJS0ZNOkDMpXJ2Cott0eR9zU7scQs4nOo8j3qO1QXHu3GwCndCTk0tUE_DW1RF6ETdAP6gnh6Rg04fa4yAkxo6wOHt3THe_VkOoAUKG29yCCAUeW8B4Xo0bw3PuQjyyiXy69_KWpkMqF-Dt4vmHb6xdCjyv-UhBNK6BCG1FU2KTJ0m_5JgLVVqKV1OkL6VXVuhXFJOSUQTGYocV3TB_hzTIFfHKBDMNeKL17GLiwDQFH4HXBpBt9GxeNx8XDssl1xAKPRRSZhEqTBh69_291fz-4fgHmPnlDIhIu9HqiTDiW1T6sbUaXUNCdWJ5DnFm43hp22hQMy8cq6r2_C_oDNo6Gt3OCs3YOnTwivW49rou6we65Nk4uIVMEJzS-GHpNvX2BYOu8VYzd3hUw1BE6_lFyXJSfoIod3qIQT_wXeAFDwjBjAuksAXMg" }

The access_token is issued for 30 days, after which it will no longer work. After 30 days, you will need to obtain a new access_token using the same request.

  1. After receiving an access_token, you can send requests to the API: https://app.academyocean.com/api/v1/

The request body is an array that contains function name and an array of parameters. It looks like this:

 'action' => 'learners', 'options' => [ 'dates' => ['2017-07-25 00:00:00', '2017-07-25 23:59:59'] ]

In this example, we are making a request for a list of learners who were registered between 2017-07-25 00:00:00 and 2017-07-25 23:59:59.

Here is how a sample request looks using the GuzzleHttp library:

 $client = new GuzzleHttp\Client(); $response = $client->post('https://app.academyocean.com/oauth/token', [ 'form_params' => [ 'grant_type' => 'client_credentials', 'client_id' => 'gR9eYq5oE6mvNAPmwxGO', 'client_secret' => 'rJbVCKO1eZ8opQwfhNQfmQRlotSJOykg9BbdCDh7', 'scope' => '', ], ]); $auth = json_decode((string)$response->getBody()); $response = $client->post('https://app.academyocean.com/api/v1/', ['headers' => [ 'Authorization' => $auth->token_type . ' ' . $auth->access_token,], 'form_params' => [ 'action' => 'learners', 'options' => [ 'dates' => ['2017-07-25 00:00:00', '2017-07-25 23:59:59'],],], ]); $learners = json_decode((string)$response->getBody()); var_dump($learners);

Tip #1

Save the access_token so you don’t have to go through the authorization process each time you wish to use the API. If you have the access_token, you can easily insert it into the request header to send requests to the API.
'Authorization' => $auth->token_type. ' ' . $auth->access_token

Tip #2

All dates returned in the request results are in the UTC timezone

Available functions:

Description of Available Functions

learners

This returns an array of learners from the Academy, or an empty array, if there is no data.

Input:

Field nameTypeExampleRequiredDescription
emailstringtest@test.comoptionallets you search for learners by email

Output:

When this request is executed, you will receive an array with learners and their data.

Learner data comprises:

Field nameTypeExampleDescription
namestringJohn SmithLearner name
emailstringtest@test.comLearner email
registered_atstring2017-07-24T10:26:23+00:00Learner register datetime in atom string with timezone representation
scoreint50Learner’s “score” (how “educated” a learner is), which is expressed as a percentage: the ratio of completed content to available content (across all courses/groups)
lessons_openedint20Amount of opened Academy contents
lessons_completedint10Amount of completed Academy contents
courses_completedint1Amount of courses complete
spent_time_in_academyint234562Spent time in Academy in seconds
certificates_amountint1Amount of issued certificates
companystringhttps://academyocean.comLink to learner company or null
countrystringUnited StatesLearner country
country_iso_codestringUSLearner country ISO code
citystringLos AngelesLearner City
osstringOS Xlearner os
devicestringMacintoshlearner device
browserstringChromelearner browser
last_login_atstring2017-09-24T10:26:23+00:00learner last login datetime in atom string with timezone representation
certificates

This returns an array of certificates received by learners, or an empty array.

Input:

Field nameTypeExampleRequiredDescription
emailstringtest@test.comrequiredsearch for a user by email

Output:

When this request is executed, you will receive data on a learner’s certificates.

Learner data comprises:

Field nameTypeExampleDescription
issued_datestring2017-07-24T10:26:23+00:00Certificate issue datetime in atom string with timezone representation
course_namestringMy CourseCourse name
url_to_pdfstringhttps://./NAME.pdfURL to pdf version
url_to_imagestringhttps://./NAME.jpgURL to image version
courseProgress

This returns a learner’s progress in all active courses/groups.

Input:

Field nameTypeExampleRequiredDescription
emailstringtest@test.comrequiredsearch for a user by email

Output:

When the request is executed, an array of current courses and a specific learner’s general progress in them is returned. Progress in each course broken out by content is also returned, in the following form: “Content name” — “completed/did not complete”

Field nameTypeExampleDescription
course_namestringMy CourseCourse/Group name
lessons_amountint10Amount of lessons in course
progress_amountint5Amount of passed lessons
progressint50Progress in %
content_progress[][name]stringMy First LessonContent name
content_progress[][is_passed]booltrueHas learner passed this content
learnersAmountFromCountries

This returns a breakdown of learners by country.

Input:

Field nameTypeExampleRequiredDescription
country_iso_codestringUSoptionalCountry iso code

Output:

Returns an array of countries and a breakdown of learners in them. If the country_iso_code is specified, then it returns an array with one element.

Field nameTypeExampleDescription
country_iso_codestringUSCountry ISO code
countrystringUnited StatesCountry full name
amountint20Amount of learners
learnersFromCountry

This returns a list of learners from the chosen country

Input:

Field nameTypeExampleRequiredDescription
country_iso_codestringUSrequiredCountry iso code

Output:

Returns information about a country and a list of learners from it

Field nameTypeExampleDescription
country_iso_codestringUSCountry ISO code
countrystringUnited StatesCountry full name
amountint20Amount of learners
learners[][name]stringJohn SmithLearner name
learners[][email]stringtest@test.comLearner email
learners[][registered_at]string2017-07-24T10:26:23+00:00Learner register datetime in atom string with timezone representation
learners[][score]int50Learner’s “score” (how “educated” a learner is), which is expressed as a percentage: the ratio of completed content to available content (across all courses/groups)
learners[][lessons_opened]int20Amount of opened Academy contents
learners[][lessons_completed]int10Amount of completed Academy contents
learners[][courses_completed]int1Amount of courses complete
learners[][spent_time_in_academy]int234562Spent time in Academy in seconds
learners[][certificates_amount]int1Amount of issued certificates
learners[][company]stringhttps://academyocean.comLink to learner company or null
learners[][country]stringUnited StatesLearner country
learners[][country_iso_code]stringUSLearner country ISO code
learners[][city]stringLos AngelesLearner City
learners[][os]stringOS Xlearner os
learners[][device]stringMacintoshlearner device
learners[][browser]stringChromelearner browser
learners[][last_login_at]string2017-09-24T10:26:23+00:00learner last login datetime in atom string with timezone representation
learnersWithScore

This returns a list of learners filtered by their score

Input:

Field nameTypeExampleRequiredDescription
scoreint40requiredFilter score the ratio of completed content to available content, across all courses/groups
operatorstring=>optionalOne of the following comparison operators '=', '>', '<', '=>', '<=', '<>'

If no comparison operator is provided, the operator ‘=’ is automatically used.

Output:

When the request is executed, an array of learners and their data is returned.

Learner data comprises:

Field nameTypeExampleDescription
namestringJohn SmithLearner name
emailstringtest@test.comLearner email
registered_atstring2017-07-24T10:26:23+00:00Learner register datetime in atom string with timezone representation
scoreint50Learner’s “score” (how “educated” a learner is), which is expressed as a percentage: the ratio of completed content to available content (across all courses/groups)
lessons_openedint20Amount of opened Academy contents
lessons_completedint10Amount of completed Academy contents
courses_completedint1Amount of courses complete
spent_time_in_academyint234562Spent time in Academy in seconds
certificates_amountint1Amount of issued certificates
companystringhttps://academyocean.comLink to learner company or null
countrystringUnited StatesLearner country
country_iso_codestringUSLearner country ISO code
citystringLos AngelesLearner City
osstringOS Xlearner os
devicestringMacintoshlearner device
browserstringChromelearner browser
last_login_atstring2017-09-24T10:26:23+00:00learner last login datetime in atom string with timezone representation
learnersRegisteredAt

This allows you to get a list of learners who registered on a certain date or in a certain date range.

Input:

Field nameTypeExampleRequiredDescription
datestring2017-09-24requiredDate string for filter
operatorstring=>optionalOne of the following comparison operators '=', '>', '<', '=>', '<=', '<>'

or

Input:

Field nameTypeExampleRequiredDescription
datesarray[2017-09-24 00:00:00, 2017-09-27 23:59:59]requiredArray with dates for filter by interval. First element must be less than second

If both the ‘date’ and ‘dates’ options are passed, then ‘dates’ will be executed and ‘date’ will be ignored.

Output:

When the request is executed, an array of learners and their data is returned.

Learner data comprises:

Field nameTypeExampleDescription
namestringJohn SmithLearner name
emailstringtest@test.comLearner email
registered_atstring2017-07-24T10:26:23+00:00Learner register datetime in atom string with timezone representation
scoreint50Learner’s “score” (how “educated” a learner is), which is expressed as a percentage: the ratio of completed content to available content (across all courses/groups)
lessons_openedint20Amount of opened Academy contents
lessons_completedint10Amount of completed Academy contents
courses_completedint1Amount of completed courses
spent_time_in_academyint234562Spent time in Academy in seconds
certificates_amountint1Amount of issued certificates
companystringhttps://academyocean.comLink to learner company or null
countrystringUnited StatesLearner country
country_iso_codestringUSLearner country ISO code
citystringLos AngelesLearner City
osstringOS Xlearner os
devicestringMacintoshlearner device
browserstringChromelearner browser
last_login_atstring2017-09-24T10:26:23+00:00learner last login datetime in atom string with timezone representation
learnersCourseComplete

This returns a list of learners who have completed a given course.

Input:

Field nameTypeExampleRequiredDescription
course_idstringmy-courserequiredCourse id, you can get it from edit course, from field
‘course URL’

Output:

Returns an array of learners who have completed a given course and brief summary about them.

Field nameTypeExampleDescription
date_of_passingstring2017-09-24T10:26:23+00:00Course pass datetime in atom string with timezone representation
namestringJohn SmithLearner name name
scoreint20Learner’s “score” (how “educated” a learner is), which is expressed as a percentage: the ratio of completed content to available content (across all courses/groups)
courses_completedint1Amount of completed courses
spent_time_in_academyint412321Second spent in Academy content
certificates_amountint1Amount of issued certificates
companystringhttp://company.comURL to learner company if exists
passiveLearners

This returns a list of learners who registered in an Academy but took no further actions (no lessons opened)

Output:

Returns an array of learners and a brief summary about them.

Field nameTypeExampleDescription
registered_atstring2017-09-24T10:26:23+00:00Date of registration
namestringJohn SmithLearner name name
emailstringtest@test.comLearner email
companystringhttps://academyocean.comLink to learner company or null
inviteLearners

This creates an invitation to a private Academy

Input:

Field nameTypeExampleRequiredDescription
learners[][email] string test@test.com required Email of invited learner
learners[][name] string John Smith required Name of invited learner
learners[][type] string learner required Type of learner from following values 'learner', 'manager'

Output:

Returns the number of created invitations

Field nameTypeExampleDescription
invitedint2Amount of created invites

This could return fewer invited users than you sent invitations to, in the event that there was an error recording invitations or users were invited multiple times.

learnersChurnAtContent

This returns an array of learners who churned at a specific lesson in the course.

Input:

Field nameTypeExampleRequiredDescription
course_idstringmy-courserequiredCourse id, you can get it from edit course, from field
‘course URL’
content_idstringfirst-lessonrequiredcontent id, you can get it from edit content, from field
‘lesson/quiz URL’

Output:

Returns a list of learners who churned and a brief summary about them.

Field nameTypeExampleDescription
churn_datestring2017-09-24T10:26:23+00:00Churn datetime in atom string with timezone representation
emailstringtest@test.comLearner email
namestringJohn SmithLearner name
spent_time_in_academyint12312Learner spent time in Academy
spent_time_in_contentint123Learner spent time in content
registered_atstring2017-09-24T10:26:23+00:00Learner register datetime in atom string with timezone representation
learnersRepeatedLogIns

This returns an array of learners who logged in to the Academy more than one time.

Output:

When the given request is executed, you will receive an array with learners and their data.

Learner data comprises:

Field nameTypeExampleDescription
namestringJohn SmithLearner name
emailstringtest@test.comLearner email
registered_atstring2017-07-24T10:26:23+00:00Learner register datetime in atom string with timezone representation
scoreint50 Learner’s “score” (how “educated” a learner is), which is expressed as a percentage: the ratio of completed content to available content (across all courses/groups)
lessons_openedint20Amount of opened Academy contents
lessons_completedint10Amount of completed Academy contents
courses_completedint1Amount of courses complete
spent_time_in_academyint234562Spent time in Academy in seconds
certificates_amountint1Amount of issued certificates
companystringhttps://academyocean.comLink to learner company or null
countrystringUnited StatesLearner country
country_iso_codestringUSLearner country ISO code
citystringLos AngelesLearner City
osstringOS Xlearner os
devicestringMacintoshlearner device
browserstringChromelearner browser
last_login_atstring2017-09-24T10:26:23+00:00learner last login datetime in atom string with timezone representation
log_ins_amountint4amount of logins amount
Error messages

All errors are sent in the following format:

Field nameTypeExampleDescription
error[message]stringEmail is requiredError message