API Documentation — AcademyOcean

API Documentation

Authorization:

AcademyOcean has an API and webhooks. Webhooks are particularly useful for asynchronous events, such as when a learner starts or finishes a course.

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"
  }
				 
  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
Error messages

All errors are sent in the following format:

Field name Type Example Description
error[message] string Email is required Error message

Available functions:

Webhooks:

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 name Type Example Required Description
email string test@test.com optional lets 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 name Type Example Description
name string John Smith Learner name
email string test@test.com Learner email
registered_at string 2017-07-24T10:26:23+00:00 Learner register datetime in atom string with timezone representation
score int 50 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_opened int 20 Amount of opened Academy contents
lessons_completed int 10 Amount of completed Academy contents
courses_completed int 1 Amount of courses complete
spent_time_in_academy int 234562 Spent time in Academy in seconds
certificates_amount int 1 Amount of issued certificates
company string https://academyocean.com Link to learner company or null
country string United States Learner country
country_iso_code string US Learner country ISO code
city string Los Angeles Learner City
os string OS X learner os
device string Macintosh learner device
browser string Chrome learner browser
last_login_at string 2017-09-24T10:26:23+00:00 learner 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 name Type Example Required Description
email string test@test.com required search for a user by email

Output:

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

Learner data comprises:

Field name Type Example Description
issued_date string 2017-07-24T10:26:23+00:00 Certificate issue datetime in atom string with timezone representation
course_name string My Course Course name
url_to_pdf string https://./NAME.pdf URL to pdf version
url_to_image string https://./NAME.jpg URL to image version
learnersProgressByCourse

This returns a learner’s progress in specified courses

Input:

Field name Type Example Required Description
course_id string byY3dwq2exrmWvLpoanMQ required Course ID, you can get from course settings, from field “API, Course ID”
course_slug string course_slug required Course slug, you can get from course settings, from field ‘course URL’
page int 1 optional Number of page in API response
amount int 10 optional Number of courses shown on page
show_not_started_learners bool true optional Option of displaying learners who did not start the course

Output:

When the request is executed, an array of learner’s information is returned

The data output example:

			

 	[
    {
    "learners": [
        {
        "email": "john.smith@gmail.com",
        "full_name": "John Smith",
        "first_name": "John",
        "last_name": "Smith"
         "startDate": "01/01/2022", //Date when the learner started the course
        "startTime": "7:41 AM", // Time when the learner started the course
        "completionDate": "01/01/2022", // Date when the learner completed the course
        "completionTime": "7:51 AM", // Time when the learner completed the course
        "status": "Completed", // Whether or not the learner completed the course
        "duration": "00:10:50", //Estimated time the learner need to finish the course, formatted as hh:mm:ss
        "viewTime": "00:10:55", // Time the learner spent in the course, formatted as hh:mm:ss
        "totalAmount": 5, // Amount of content in course
        "passedAmount": "5", // Amount of content passed by learner
        "courseScore": 100, // Score for the course got by Learner
        "teams": [		// Array of teams in which the course is available
                "No Team"
                 ]
        }
       ]
     }
   ]

			
		
courseProgress

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

You can also specify the parameter that returns the courses: all (as now) / only published / only published

Input:

Field name Type Example Required Description
email string test@test.com required search 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 name Type Example Description
course_name string My Course Course/Group name
course_description string My Course Description Text Course description
course_open_url string https://create.academyocean.com/course/how-to-manage-your-academy/start Course URL
start_date string null or date string in ISO-8601 format Course start date
finish_date string null or date string in ISO-8601 format Course completion date
course_id string NVpz0PmrkjrkOQW9d1Kx Course ID
course_img string https://app.academyocean.com/img/upload_img.png Course cover image
course_type string all / published / unpublished Search for published or unpublished courses
lessons_amount int 10 Amount of lessons in course
progress_amount int 5 Amount of passed lessons
progress int 50 Progress in %
content_progress[][id] string NVpz0werkjrkOQW9d1Kx Content id
content_progress[][name] string My First Lesson Content name
content_progress[][is_passed] bool true Has learner passed this content
content_progress[][type] string ‘lesson’ or ‘quiz’ Content-type: lesson or quiz
content_progress[][started_at] string null or date string in ISO-8601 format Content first opening date
content_progress[][passed_at] string null or date string in ISO-8601 format Content been passed date
content_progress[][pass_time_sec] int 120 Total time taken to pass in seconds

Unique parameters only if the type is quiz

Field name Type Example Description
content_progress[][score] int 60 Total score learner got for quiz
content_progress[][passing_score] int 50 Score to pass the quiz
content_progress[][is_need_manual_approve] bool false Manual check for the quiz is set
content_progress[][is_timer_on] bool true The timer for quiz is set
content_progress[][timer_minutes] int 5 Time given to finish the quiz in minutes
content_progress[][is_timer_expired] bool false Learner managed to finish quiz in time

The data output example:

			

 	[
     [
       "course_id" => "NVpz0PmrkjNJOQW9d1K",
       "course_name" => "Test group",
       "course_description" => "",
       "course_img" => "http://app.academyocean.test/img/upload_img.png",
       "course_open_url" => "http://test.academyocean.test/group/gR9eYq5oE6wm3NAPmwxG/open",
       "start_date" => "2021-12-08",
       "finish_date" => "2021-12-08",
       "lessons_amount" => 4,
       "progress_amount" => 3,
       "progress" => 75.0,
       "content_progress" => [
         [
           "id" => "9GKDJlMkpMREXyz2Awp",
           "type" => "lesson",
           "name" => "lesson 1",
           "is_passed" => true,
           "started_at" => "2021-12-08T14:41:20+00:00",
           "passed_at" => "2021-12-08T14:41:23+00:00",
           "pass_time_sec" => 0,
         ],
         [
           "id" => "NnO5GBYv4o53baMJo6p",
           "type" => "quiz",
           "name" => "quiz 1",
           "is_passed" => true,
           "started_at" => "2021-12-08T14:41:23+00:00",
           "passed_at" => "2021-12-08T14:42:10+00:00",
           "pass_time_sec" => 25,
           "score" => "5",
           "passing_score" => 0,
           "is_need_manual_approve" => true,
           "is_time_on" => null,
           "is_timer_expired" => false,
           "timer_minutes" => 5,
         ],
         [
           "id" => "2DAjr0BkWwykbypL86d",
           "type" => "lesson",
           "name" => "lesson 2",
           "is_passed" => false,
           "started_at" => "2021-12-08T14:42:19+00:00",
           "passed_at" => null,
           "pass_time_sec" => null,
         ],
         [
           "id" => "Brq7Zbe3Oe1vyRPm6Yg",
           "type" => "lesson",
           "name" => "lesson 1",
           "is_passed" => true,
           "started_at" => "2021-12-08T14:42:17+00:00",
           "passed_at" => "2021-12-08T14:42:19+00:00",
           "pass_time_sec" => 0,
         ],
       ],
     ],
     [
       "course_id" => "0yZM9XkmLy3A7lpJYg",
       "course_name" => "cert course for webhooks tests",
       "course_description" => "",
       "course_img" => "http://app.academyocean.test/img/upload_img.png",
       "course_open_url" => "http://test.academyocean.test/course/cert-course-for-webhooks-tests/open",
       "start_date" => "2021-12-09T15:23:19+00:00",
       "finish_date" => "2021-12-09T15:23:30+00:00",
       "lessons_amount" => 6,
       "progress_amount" => 6,
       "progress" => 100.0,
       "content_progress" => [
         [
           "id" => "KAV6q743G7Y13MbJN1Or",
           "type" => "lesson",
           "name" => "Lesson 1",
           "is_passed" => true,
           "started_at" => "2021-12-09T15:23:19+00:00",
           "passed_at" => "2021-12-09T15:23:28+00:00",
           "pass_time_sec" => 0,
         ],
         [
           "id" => "Lw1ro0GvP9OwEW2VzqBm",
           "type" => "lesson",
           "name" => "Lesson 2",
           "is_passed" => true,
           "started_at" => "2021-12-09T15:23:28+00:00",
           "passed_at" => "2021-12-09T15:23:30+00:00",
           "pass_time_sec" => 0,
         ],
         [
           "id" => "LqA0N1ZELnqwkro8aDyb",
           "type" => "lesson",
           "name" => "Lesson 3",
           "is_passed" => true,
           "started_at" => "2021-12-09T15:45:31+00:00",
           "passed_at" => "2021-12-09T15:45:35+00:00",
           "pass_time_sec" => 0,
         ],
         [
           "id" => "VAjml0RkQeJWk2e6bgqn",
           "type" => "quiz",
           "name" => "Quiz 1",
           "is_passed" => true,
           "started_at" => "2021-12-09T15:45:35+00:00",
           "passed_at" => "2021-12-09T16:02:55+00:00",
           "pass_time_sec" => 2,
           "score" => "1",
           "passing_score" => 0,
           "is_need_manual_approve" => false,
           "is_time_on" => null,
           "is_timer_expired" => false,
           "timer_minutes" => 5,
         ],
         [
           "id" => "GJ0n8jwEZBvRy1LrQ7",
           "type" => "lesson",
           "name" => "Lesson 4",
           "is_passed" => true,
           "started_at" => "2021-12-09T16:02:55+00:00",
           "passed_at" => "2021-12-09T16:02:58+00:00",
           "pass_time_sec" => 0,
         ],
         [
           "id" => "R5VD9yZ3wq3240axmz",
           "type" => "quiz",
           "name" => "Quiz",
           "is_passed" => true,
           "started_at" => "2021-12-09T16:02:58+00:00",
           "passed_at" => "2021-12-09T16:14:51+00:00",
           "pass_time_sec" => 5,
           "score" => "3",
           "passing_score" => 2,
           "is_need_manual_approve" => false,
           "is_time_on" => null,
           "is_timer_expired" => false,
           "timer_minutes" => 6,
         ],
       ],
     ],
     [
       "course_id" => "j4zx6GrZ0zky2wR18J",
       "course_name" => "WebhookGroup",
       "course_description" => "",
       "course_img" => "http://app.academyocean.test/img/upload_img.png",
       "course_open_url" => "http://test.academyocean.test/group/1AbDljeg3z6y3qB6rKZ9/open",
       "start_date" => "2021-12-09”,
       "finish_date" => "2021-12-09”,
       "lessons_amount" => 3,
       "progress_amount" => 3,
       "progress" => 100.0,
       "content_progress" => [
         [
           "id" => "5DG1ByVn4kZ6YMQdJ",
           "type" => "lesson",
           "name" => "group lesson",
           "is_passed" => true,
           "started_at" => "2021-12-09T16:58:33+00:00",
           "passed_at" => "2021-12-09T16:59:02+00:00",
           "pass_time_sec" => 0,
         ],
         [
           "id" => "rqzxKO0kyyaLkl5g4d1n",
           "type" => "lesson",
           "name" => "Group lesson 2",
           "is_passed" => true,
           "started_at" => "2021-12-09T16:59:04+00:00",
           "passed_at" => "2021-12-09T16:59:07+00:00",
           "pass_time_sec" => 0,
         ],
         [
           "id" => "qXxZ4p93KKz631WboGVB",
           "type" => "lesson",
           "name" => "Group lesson 3",
           "is_passed" => true,
           "started_at" => "2021-12-09T16:59:08+00:00",
           "passed_at" => "2021-12-09T16:59:11+00:00",
           "pass_time_sec" => 0,
         ],
       ],
     ],
   ]

			
		
learnersAmountFromCountries

This returns a breakdown of learners by country.

Input:

Field name Type Example Required Description
country_iso_code string US optional Country 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 name Type Example Description
country_iso_code string US Country ISO code
country string United States Country full name
amount int 20 Amount of learners
learnersFromCountry

This returns a list of learners from the chosen country

Input:

Field name Type Example Required Description
country_iso_code string US required Country iso code

Output:

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

Field name Type Example Description
country_iso_code string US Country ISO code
country string United States Country full name
amount int 20 Amount of learners
learners[][name] string John Smith Learner name
learners[][email] string test@test.com Learner email
learners[][registered_at] string 2017-07-24T10:26:23+00:00 Learner register datetime in atom string with timezone representation
learners[][score] int 50 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)
learners[][lessons_opened] int 20 Amount of opened Academy contents
learners[][lessons_completed] int 10 Amount of completed Academy contents
learners[][courses_completed] int 1 Amount of courses complete
learners[][spent_time_in_academy] int 234562 Spent time in Academy in seconds
learners[][certificates_amount] int 1 Amount of issued certificates
learners[][company] string https://academyocean.com Link to learner company or null
learners[][country] string United States Learner country
learners[][country_iso_code] string US Learner country ISO code
learners[][city] string Los Angeles Learner City
learners[][os] string OS X learner os
learners[][device] string Macintosh learner device
learners[][browser] string Chrome learner browser
learners[][last_login_at] string 2017-09-24T10:26:23+00:00 learner last login datetime in atom string with timezone representation
learnersWithScore

This returns a list of learners filtered by their score

Input:

Field name Type Example Required Description
score int 40 required Filter score the ratio of completed content to available content, across all courses/groups
operator string => optional One 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 name Type Example Description
name string John Smith Learner name
email string test@test.com Learner email
registered_at string 2017-07-24T10:26:23+00:00 Learner register datetime in atom string with timezone representation
score int 50 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_opened int 20 Amount of opened Academy contents
lessons_completed int 10 Amount of completed Academy contents
courses_completed int 1 Amount of courses complete
spent_time_in_academy int 234562 Spent time in Academy in seconds
certificates_amount int 1 Amount of issued certificates
company string https://academyocean.com Link to learner company or null
country string United States Learner country
country_iso_code string US Learner country ISO code
city string Los Angeles Learner City
os string OS X learner os
device string Macintosh learner device
browser string Chrome learner browser
last_login_at string 2017-09-24T10:26:23+00:00 learner 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 name Type Example Required Description
date string 2017-09-24 required Date string for filter
operator string => optional One of the following comparison operators '=', '>', '<', '>=', '<=', '<>'

or

Input:

Field name Type Example Required Description
dates array [2017-09-24 00:00:00, 2017-09-27 23:59:59] required Array 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 name Type Example Description
name string John Smith Learner name
email string test@test.com Learner email
registered_at string 2017-07-24T10:26:23+00:00 Learner register datetime in atom string with timezone representation
score int 50 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_opened int 20 Amount of opened Academy contents
lessons_completed int 10 Amount of completed Academy contents
courses_completed int 1 Amount of completed courses
spent_time_in_academy int 234562 Spent time in Academy in seconds
certificates_amount int 1 Amount of issued certificates
company string https://academyocean.com Link to learner company or null
country string United States Learner country
country_iso_code string US Learner country ISO code
city string Los Angeles Learner City
os string OS X learner os
device string Macintosh learner device
browser string Chrome learner browser
last_login_at string 2017-09-24T10:26:23+00:00 learner last login datetime in atom string with timezone representation
learnersCourseComplete

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

Input:

Field name Type Example Required Description
course_id string my-course required Course 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 name Type Example Description
date_of_passing string 2017-09-24T10:26:23+00:00 Course pass datetime in atom string with timezone representation
name string John Smith Learner name name
score int 20 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)
courses_completed int 1 Amount of completed courses
spent_time_in_academy int 412321 Second spent in Academy content
certificates_amount int 1 Amount of issued certificates
company string http://company.com URL 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 name Type Example Description
registered_at string 2017-09-24T10:26:23+00:00 Date of registration
name string John Smith Learner name name
email string test@test.com Learner email
company string https://academyocean.com Link to learner company or null
inviteLearners

This creates an invitation to a private Academy

You can also specify a parameter for the function that, when filled, will send an email invitation letter to the entire array of learners.

Input:

Field name Type Example Required Description
learners[][email] string test@test.com required Email of invited learner
is_send_email string True/False optional Was an email sent to a 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'
learners[][teams] array [‘testTeamsID2’, ‘testTeamsID1’] optional Teams ID to which learner(s) will be invited

Output:

Returns the number of created invitations

Field name Type Example Description
invited int 2 Amount 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.

checkLearnerInvite

Allows you to check if there is an invitation for a specific student. And it shows the date if the invitation is already activated.

Search for an invitation is made by email.

Input:

Field name Type Example Required Description
emails array [‘learner1@test.com’, ‘learner2@test.com’, ‘learner42@test.com’] required List of emails you want to check the status of invitation for

Example of the request for getting information about the invitation

			
				$client->post('https://app.academyocean.com/api/v1/', [
				   'headers' => [
					   'Authorization' => $apiToken,
				   ],
				   'form_params' => [
					   'action' => 'checkLearnerInvite',
					   'options' => [
						   'emails' => [
							   'invite@test.com',
							   'invite2@test.com',
							   'invite3@test.com'
						   ]
					   ],
				   ],
				]);
			
		

Output example:

			
			[
				 "invite@test.com" => [ // The email is the key to required array
				   "is_found" => true, // Is the invitation with needed email found
				   "is_used" => true, // Is the invitation used/ activated
				   "used_at" => "2021-12-09T18:57:44+00:00", // When the invitation was used/activated
				 ],
				 "invite2@test.com" => [
				   "is_found" => true,
				   "is_used" => false,
				   "used_at" => null,
				 ],
				 "invite3@test.com" => [
				   "is_found" => false,
				   "is_used" => null,
				   "used_at" => null,
				 ],
			]

			
		
learnersChurnAtContent

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

Input:

Field name Type Example Required Description
course_id string my-course required Course id, you can get it from edit course, from field ‘course URL’
content_id string first-lesson required content 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 name Type Example Description
churn_date string 2017-09-24T10:26:23+00:00 Churn datetime in atom string with timezone representation
email string test@test.com Learner email
name string John Smith Learner name
spent_time_in_academy int 12312 Learner spent time in Academy
spent_time_in_content int 123 Learner spent time in content
registered_at string 2017-09-24T10:26:23+00:00 Learner 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 name Type Example Description
name string John Smith Learner name
email string test@test.com Learner email
registered_at string 2017-07-24T10:26:23+00:00 Learner register datetime in atom string with timezone representation
score int 50 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_opened int 20 Amount of opened Academy contents
lessons_completed int 10 Amount of completed Academy contents
courses_completed int 1 Amount of courses complete
spent_time_in_academy int 234562 Spent time in Academy in seconds
certificates_amount int 1 Amount of issued certificates
company string https://academyocean.com Link to learner company or null
country string United States Learner country
country_iso_code string US Learner country ISO code
city string Los Angeles Learner City
os string OS X learner os
device string Macintosh learner device
browser string Chrome learner browser
last_login_at string 2017-09-24T10:26:23+00:00 learner last login datetime in atom string with timezone representation
log_ins_amount int 4 amount of logins amount
Academies

Get the list of all academies. It returns the list of all academies in account with a description of them. Here are the fields that are returning:

Field name Description
id Academy ID, you will need it for using the new function
name Academy name
slug Academy subdomain on our domain
is_cname_enabled Flag that shows whether the academy publishing function on a different domain is on
cname_domain Domain name, where the academy is published
is_private Shows whether private mode for the academy is on
is_published Shows whether the academy is published
learners_amount Number of learners in the academy
created_at Date and time when the academy was created
content_amount Number of courses and groups in the academy
access_request_amount Number of user access requests that haven't been approved

Sample code for getting a list of academies (Language:PHP, Library: GuzzleHTTP used)

			
	$response = $client->post('http://app.academyocean.com/api/v1/', [
		'headers' => [
			'Authorization' => $auth->token_type . ' ' . $auth->access_token,
		],
		'form_params' => [
			'action'  => 'academies',
		],
	]);
			
		
Create Login Token

Creates a one-off URL for authorization/registration in an academy. This creates a one-time link. For the next login, a new link is required.

Data we receive:

Field name Type Required Description
academy_id string required Academy ID in which we create a link (it is taken from the previous request)
email string required Learner’s email for whom we create a link
course string optional course slug (where we should redirect after login, taken from the course settings page, the field ‘Course URL’ ). This parameter is optional
lesson string optional Lesson slug (the lesson to which learner will be redirected after login, you should specify the course for this parameter. You can take it from the lesson edit pop-up, from the field ‘Lesson URL’). This parameter is optional
quiz string optional Quiz slug (the quiz to which learner will be redirected after login, you should specify the course for this parameter. You can take it from the quiz edit pop-up from field ‘Quiz URL’) This parameter is optional
ignore_academy_privacy_mode boolean optional Ignore or not the academy privacy mode, by default true(ignoring privacy mode), boolean value. This parameter is optional
course_id string optional Course id (where we should redirect after login, taken from the course settings page, the field ‘Api Id’ ). This parameter is optional
content_id string optional Content id (at which lesson/quiz we should redirect after login, this parameter requires course_id parameter. It is taken from the lesson/quiz edit pop-up from the field ‘Api Id’) This parameter is optional

If you don’t specify any of these fields (course, lesson, quiz, course_id, content_id), learners will be redirected to courses page.

If you specify only course/course_id parameters, learners will be redirected to a specific course.

If you specify course and lesson/quiz parameters, the learner will be redirected to the exact lesson or quiz inside of the course.

Parameter course_id works only with content_id and vice versa. You can’t use course parameter and lesson/quiz parameter.

Please, if you specify lesson and quiz parameters, make sure that your course has a non-linear passing mode.

Data that we will be sent:

Field name Type Example Description
link string https://academy.academyocean.com/auth/token/{TOKEN} URL for redirecting a user to the academy
Note: You can use one link only one time. If you try use it again it'll not work.

Sample code for creating an authorization URL (Language:PHP, Library: GuzzleHTTP used)

			
    $response = $client->post('http://app.academyocean.com/api/v1/', [
        'headers' => [
            'Authorization' => $auth->token_type . ' ' . $auth->access_token,
        ],
        'form_params' => [
            'action'  => 'createLoginToken',
            'options' => [
                'academy_id' => 'zyK0bxgWEY9E4XA6JedG',
                'email' => 'learner@link.test',
            ]
        ],
    ]);

			
		
Set/Create Lesson Variables

Input:

Field name Type Required Description
academy_id string required Academy ID in which we'll insert variables
records array required Learner’s email for whom we create a link
is_invite_learner_if_not_found boolean optional Invite or not a learner if we couldn't find such email at specified academy
records[email@example.com][][key] string required Key of variable.It must be in a snake case
records[email@example.com][][value] string required Value that you want to set
records[email@example.com][][type] integer optional Type of variable if you want to create one (0 — String, 1 — Paragraph, 2 — Number, 3 — HTML, 4 — Markdown String)
records[email@example.com][][default_value] string optional Default value of variable (by default will be null)

You can use Markdown formatting in paragraphs to stylize the text.

If we can't find a variable by this key, then we create it and set the value to the learner to whom it was indicated.

If the parameter "is_invite_learner_if_not_found" is turned on and we didn't find the learner by the email you specified, then we will create an invite for this email and set these variables to it.

After the learner activates this invite, all set variables will be automatically set to his profile.

Sample code for creating an authorization URL (Language: PHP, Library: GuzzleHTTP used)

			
    $response = $client->post('http://app.academyocean.com/api/v1/', [
        'headers' => [
            'Authorization' => $auth->token_type . ' ' . $auth->access_token,
        ],
        'form_params' => [
            'action'  => 'setLessonVariables',
            'options' => [
                'academy_id' => 'zyK0bxgWEY9E4XA6JedG',
                'records' => [
		'email@example.com' => [
				[
				'key' => 'some_lesson_variable',
				'value' => 'Example',
				'type' => 0,
				'default_value' => 'Some Default Value For Variable',
				],
			]
		],
            ]
        ],
    ]);
			
		
getLearnerVariable

What it does:

Returns the current values of the specified variables for one or more learners

What to pass:

An array of values where the keys are learner email addresses and the value is an array of the names of the variables for which you would like the values

Field name Type Required Description
records[email@example.com][] array required Names of the variables you would like to see the values of

What we return:

An array with learners' email keys and an internal array with variables found and their values

Sample:

			
	[
		'i6dge8kn6cvmzjzq@api.com' => [
			'var_name_1' => 1,
			'var_name_4' => ‘abcd’,
		],
		'9ldqwqsufrurqlxm@api.com' => [
			'var_name_2' => 2,
			'var_name_10' => 10,
		],
	]
			
		

Sample code:

			
	$response = $client->post('https://app.academyocean.com/api/v1/', [
		'headers' => [
			'Authorization' => $apiToken,
		],
		'form_params' => [
			'action' => 'getLearnerVariable',
			'options' => [
				'records' => [
					'i6dge8kn6cvmzjzq@api.com' => ['var_name_1', 'var_name_4'],
					'9ldqwqsufrurqlxm@api.com' => ['var_name_2', 'var_name_10'],
				]
			]
		],
	]);

			
		
getTeams

Returns a list of all teams in the academy. No parameters.

Returns an array of teams with the following fields:

  • ID — Team ID
  • Name — Team name

Sample code:

			
	 $response = $client->post('https://academyocean.com/api/v1/', [
		'headers' => [
			'Authorization' => $apiToken,
		],
		'form_params' => [
			'action' => 'getTeams',
			'options' => [
			]
		],
	]);
				
		
addLearnersToTeams

Add learner(s) to an existing team or teams. This lets you simultaneously add any number of learners to any teams.

Input:

Field name Type Example Required Description
teams array [‘testTeamID1’, ‘testTeamID2’] required Teams ID to which learner(s) will be invited
learners array [‘learner1@test.com’, ‘learner2@test.com’] required Email address(es) of learner(s) being added to the specified teams

Sample code:

			
	$response = $client->post('https://academyocean.com/api/v1/', [
		'headers' => [
			'Authorization' => $apiToken,
		],
		'form_params' => [
			'action' => 'addLearnersToTeams',
			'options' => [
				'teams' => ['teamID_1', 'teamID_42'],
				'learners' => ['learner42@test.com', 'learner69@test.com', 'learner78@test.com']
			]
		],
	]);
			
		
removeLearnersFromTeams

Remove learner(s) from a team or teams. This function allows you to remove any number of learners from any team(s) at one time

Input:

Field name Type Example Required Description
learners[][email] string learner42@test.com required Email address(es) of learner(s) being removed from the specified teams
learners[][teams] array ['teamID_1', 'teamID_42'], required Array of Team IDs of teams from which the learner(s) or learner invite(s) should be removed

Sample code:

			
	$response = $client->post('https://academyocean.com/api/v1/', [
		'headers' => [
			'Authorization' => $apiToken,
		],
		'form_params' => [
			'action' => 'removeLearnersFromTeams',
			'options' => [
				'learners' => [
					[
						'email' => 'learner42@test.com',
						'teams' => ['teamID_42', 'teamID_99']
					],
				]
			]
		],
	]);
			
		
revokeLearnersAccess

Revoke a learner or learners' access to the current Academy. The progress of the learner or learners will be saved.

Input:

Field name Type Example Required Description
learners array [‘learner1@test.com’, ‘learner2@test.com’, ‘learner42@test.com’] required Array of email addresses of the learner(s) whose access should be revoked

Sample code:

			
	$response = $client->post('https://academyocean.com/api/v1/', [
		'headers' => [
			'Authorization' => $apiToken,
		],
		'form_params' => [
			'action' => 'revokeLearnersAccess',
			'options' => [
				'learners' => ['learner42@test.com', 'learner69@test.com', 'learner78@test.com']
			]
		],
	]);
			
		
returnLearnersAccess

Give back access to academy for the BLOCKED learners. Use this action to return access for learners that were previously blocked (their access was previously revoked)

Input:

Field name Type Example Required Description
learners array [‘learner1@test.com’, ‘learner2@test.com’, ‘learner42@test.com’] required An array of learners' emails, who need to return access to the Academy

Sample code:

			
	$response = $client->post('https://academyocean.com/api/v1/', [
		'headers' => [
			'Authorization' => $apiToken,
		],
		'form_params' => [
			'action' => 'returnLearnersAccess',
			'options' => [
				'learners' => ['learner42@test.com', 'learner69@test.com', 'learner78@test.com']
			]
		],
	]);
			
		
getLearnersQuizStatistic

What it does:

Returns statistics about the specified quiz for the specified learner(s).

What to pass:

An array where the keys are learner email addresses and the value is an array of the quiz IDs for which you would like to return data.

The quiz ID can be found in the quiz settings.

records array required Container
records[email@example.com][] array required ID of the quiz you want to see statistics for

What's returned:

An array with the learner or learners' email addresses and an internal array with variables found and their values.

Sample response:

			
	[
		'i6dge8kn6cvmzjzq@api.com' => [
			'Lzq0weBKvR72E72olW4X' => [
				'name' => 'Quiz Name 1', // Quiz name
				'score' => 4, // How many points the learner earned
				'passing_score' => 4, // Passing score for the quiz
				'is_passed' => true, // Whether or not the learner passed the quiz (if score >= passing_score)
				'spent_time' => '00:01:30', // Time the learner spent on the quiz, formatted as hh:mm:ss
				'spent_time_seconds' => 90, // Time the learner spent on the quiz, in seconds
				'pass_date' => '01/24/2021', // Date when the learner passed the quiz
				'pass_time' => '07:40 AM', // Time when the learner passed the quiz
				'is_timer_on' => false, // Whether or not the timer was enabled when the quiz was taken
				'is_expired' => false, // Whether or not the learner finished the quiz in time, if the timer was on
				'is_manual_approve_on' => false, // Whether or not manual grading was enabled when the quiz was taken
				'globalComment' => null, // If manual grading was enabled, this will display any comments about the results left by the person who graded
				'pass_percent' => 100, // Quiz pass percentage
				'questions' => [ // Array with questions and their detailed statuses
					[
						'id' => 'yJAg4qNO', // question ID
						'name' => 'First Question', // Question text
						'number' => 1, // Index
						'type' => 'checkbox', // Type of question
						'isHasImage' => false, // Whether or not the question had an image when the quiz was taken
						'imageUrl' => '', // If there was an image, there will be a link to it here
						'is_passed' => true, // Whether or not the learner answered the question correctly
						'isExpired' => false, // If the timer ran out, you can see here which question it ran out on
						'checkerComment' => '', // If manual grading was enabled, you can see here any comments left on specific questions by the person who graded
						'time_spent' => '00:00:05', // How much time was spent on this question, formatted as hh:mm:ss
						'answers' => [ // Array with detailed information about the answers chosen
							'selected' => [ //Answers that the learner selected/wrote/uploaded
								[
									'answer' => 'asdasdasdas', // Answer text
									'is_right' => true, // Whether or not the answer was correct
									'isHasImage' => false, // Whether or not the answer had an image
									'imageUrl' => '' // If there was an image, there will be a link to it here
								],
											…
							],
							'missed' => [], // Missed answers
						]
					],
							…
				]
			]
		],
	]
			
		

Sample API call:

			
	$response = $client->post('https://app.academyocean.com/api/v1/', [
		'headers' => [
			'Authorization' => $apiToken,
		],
		'form_params' => [
			'action' => 'getLearnersQuizStatistic',
			'options' => [
				'records' => [
					'i6dge8kn6cvmzjzq@api.com' => ['eK61OzXl38z5vogrmP0y', 'Lzq0weBKvR72E72olW4X'],
					'9ldqwqsufrurqlxm@api.com' => ['eK61OzXl38z5vogrmP0y', 'Lzq0weBKvR72E72olW4X'],
				]
			]
		],
	]);
			
		

Webhooks

Catches the events on your AcademyOcean account so your integration can automatically trigger reactions. Available by request add-ons to a PRO or Premium plan

course.started

The event is triggered when the learner starts the course

Example of data being sent:

			
	{
	   "id":"EVENT_ID",
	   "event":"course.started",
	   "academy":{
		  "id":"ACADEMY_ID",
		  "name":"ACADEMY_NAME"
	   },
	   "course":{
		  "id":"COURSE_ID",
		  "name":"COURSE_NAME"
	   },
	   "learner":{
		  "email":"LEARNER_EMAIL",
		  "full_name":"LEARNER_FULL_NAME",
		  "first_name":"LEARNER_FIRST_NAME",
		  "last_name":"LEARNER_LAST_NAME"
	   }
	}
			
		
course.finished

The event is triggered when the learner has finished the course

Example of data being sent:

			
	{
	   "id":"ba3d236-dab8-458a-8fe8-bf942bb0fe94",
	   "event":"lesson.finished",
	   "academy":{
		  "id":"j1Q5GN35RYmk9gmMqp7",
		  "name":"Academy"
	   },
	   "course":{
		  "id":"dPoNKgv7Jo0kayxqL0O",
		  "name":"Course"
	   },
	   "lesson":{
		  "id":"apeRywEMgWd6k0lPQ1g",
		  "name":"Lesson",
		  "start_date":"2021-12-10T14:03:04+00:00",
		  "finish_date":"2021-12-10T14:12:00+00:00",


	   },
	   "learner":{
		  "email":"john.smith@gmail.com",
		  "full_name":"John",
		  "first_name":"Smith",
		  "last_name":"Smith"
	   }
	}
			
		
course_group.started

The event is triggered when the learner starts the group of courses

Example of data being sent:

			
	{
	   "id":"4a33202-2281-4793-9e34-454969897a8d",
	   "event":"course_group.started",
	   "academy":{
		  "id":"j1Q5GN35RYmk9gmMqp7",
		  "name":"Academy"
	   },
	   "group":{
		  "id":"PAg7azkDr1KE4eYyqw2",
		  "name":"Group"
	   },
	   "learner":{
		  "email":"john.smith@gmail.com",
		  "full_name":"John Smith",
		  "first_name":"John",
		  "last_name":"Smith"
	   }
	}

			
		
course_group.finished

The event is triggered when the learner finishes a group of courses

Example of data being sent:

			
	{
	   "id":"769fde4-59b6-44ee-9241-ccfe81a02867",
	   "event":"course_group.finished",
	   "academy":{
		  "id":"j1Q5Gb35RYmk9gmMqp7",
		  "name":"Academy"
	   },
	   "group":{
		  "id":"PAg6azkDr1KE4eYyqw2",
		  "name":"Group"
	   },
	   "learner":{
		  "email":"john.smith@gmail.com",
		  "full_name":"John Smith",
		  "first_name":"John",
		  "last_name":"Smith"
	   }
	}

			
		
learner.course_certificate.issued

Triggered when a learner receives a certificate and it is generated

Example of data being sent:

			
	{
	   "id":"2cba9c09-be-4623-9e7b-d56fe982169f",
	   "event":"learner.course_certificate.issued",
	   "academy":{
		  "id":"j1Q5GbNRYmgmMqp7",
		  "name":"Academy"
	   },
	   "course":{
		  "id":"dPboNKgvJo0kayxqL0O",
		  "name":"Course"
	   },
	   "certificate":{
		  "link_to_pdf":"https://app.academyocean.com/public/certificates/kTxmlf1lGhSLb0.pdf",
		  "link_to_img":"https://app.academyocean.com/public/certificates/kTxm0SLb0.png",
		  "verify_link":"https://app.academyocean.com/verify/kTxmlf0SLb0",
		  "issue_date":"2021-12-10T14:12:58+00:00"
	   },
	   "learner":{
		  "email":"john.smith@gmail.com",
		  "full_name":"John Smith",
		  "first_name":"John",
		  "last_name":"Smith"
	   }
	}
			
		
lesson.started

The event is triggered when the learner starts the lesson

Example of data being sent:

			
	{
	   "id":"bf85e9a0-0-4363-abd8-a4fa9f6201bc",
	   "event":"lesson.started",
	   "academy":{
		  "id":"j1Q5GbNYmk9gmMqp7",
		  "name":"Academy"
	   },
	   "course":{
		  "id":"dPboNKgo0kayxqL0O",
		  "name":"Course"
	   },
	   "lesson":{
		  "id":"NnO5GBYnBo3baMJo6",
		  "name":"Test",
		  "start_date":"2021-12-10T14:12:01+00:00"
	   },
	   "learner":{
		  "email":"john.smith@gmail.com",
		  "full_name":"John Smith",
		  "first_name":"John",
		  "last_name":"Smith"
	   }
	}
			
		
lesson.finished

The event is triggered when the learner finishes the lesson

Example of data being sent:

			
	{
	   "id":"7babd-077b-4eef-bbc4-861f0b91eaba",
	   "event":"lesson.finished",
	   "academy":{
		  "id":"j1Q5G35RYmk9gmMqp7",
		  "name":"Academy"
	   },
	   "course":{
		  "id":"dPbov7Jo0kayxqL0O",
		  "name":"Course"
	   },
	   "lesson":{
		  "id":"NnO5GNXnBo3baMJo6",
		  "name":"Test",
		  "start_date":"2021-12-10T14:12:01+00:00",
		  "finish_date":"2021-12-10T14:12:43+00:00"

	   },
	   "learner":{
		  "email":"john.smith@gmail.com",
		  "full_name":"John Smith",
		  "first_name":"John",
		  "last_name":"Smith"
	   }
	}

			
		
quiz.started

The event is triggered when the learner starts the quiz

Example of data being sent:

			
	{
	   "id":"2adde-568d-45a1-ba8d-62d94b1f414e",
	   "event":"quiz.started",
	   "academy":{
		  "id":"j1bN35RYmk9gmMqp7",
		  "name":"Academy"
	   },
	   "course":{
		  "id":"dPbv7Jo0kayxqL0O",
		  "name":"Course"
	   },
	   "quiz":{
		  "id":"Lw1rP0WB5vW2VzqB",
		  "name":"Test",
		  "start_date":"2021-12-10T14:12:52+00:00"
	   },
	   "learner":{
		  "email":"john.smith@gmail.com",
		  "full_name":"John Smith",
		  "first_name":"John",
		  "last_name":"Smith"
	   }
	}


			
		
quiz.finished

The event is triggered when the learner finishes the quiz

Example of data being sent:

			
	{
	   "id":"66ede-ba03-4d95-b144-061dd53b4b56",
	   "event":"quiz.finished",
	   "academy":{
		  "id":"j1QbN35RYmk9gmMqp7",
		  "name":"Academy"
	   },
	   "course":{
		  "id":"dPbov7Jo0kayxqL0O",
		  "name":"Course"
	   },
	   "quiz":{
		  "id":"Lw1vP0WB5vW2VzqB",
		  "name":"Test",
		  "start_date":"2021-12-10T14:12:52+00:00",
		  "finish_date":"2021-12-10T14:12:58+00:00",
		  "spent_time_sec":46,
		  "score":"1",
		  "passing_score":0,
		  "is_need_manual_approve":false,
		  "is_timer_on":false,
		  "timer_minutes":5,
		  "is_timer_expired":false,
		  "is_passed":true
	   },
	   "learner":{
		  "email":"john.smith@gmail.com",
		  "full_name":"John Smith",
		  "first_name":"John",
		  "last_name":"Smith"
	   }
	}


			
		
academy.learner.sing_up

The event is triggered when a new learner registered in Academy

Example of data being sent:

			
	{
		id:"9e3de92f-5603-42ef-8948-c67b5544f7a2"
		event:"academy.learner.sign_up"
		academy:{
			id:"az5Mnwegw1P3qN1qYwefk7wBjkl9rm"
			name:"Academy"
 		}
		learner:{
		 email: "john.smith@gmail.com"
		 "full_name": "John Smith",
		 "first_name": "John",
		 "last_name":  "Smith"
		}
	}
			
		
learner.course.available

The event is triggered when a learner gets access to a new course. Course needs to be published. Access to the course can be given through teams

Example of data being sent:

			
	{
	  "id": "7924a8ac-48c2-4580-b829-7e179440a921",
	  "event": "learner.course.available",
	  "academy": {
		"id": "VXWP82xvd0lQvmMdOan5",
		"name": "Academy"
	  },
	  "teams": [
		{
		  "id": "yK0bxgWEY9xOljE4XA6Jed",
		  "name": "Team"
		}
	  ],
	  "learners": [
		{
		"email": "john.smith@gmail.com",
		"full_name": "John Smith",
		"first_name": "John",
		"last_name": "Smith"
		}
	  ],
	  "courses": [
		{
		  "id": "Vpz0PmrkjdKPEOQW9d1K",
		  "name": "Course"
		}
	  ],
	  "course_groups": []
	}

			
		
team.new.learners

The event is triggered: 1. When learner to a team 2. When a learner enters the No Team

Example of data being sent:

			
	{
	  "id": "788ff1fb-dc1d-4bd0-8f47-08df9a5f525c",
	  "event": "team.new_learners",
	  "academy": {
		"id": "VXWP82xvd0lQvmMdOan5",
		"name": "Academy"
	  },
	  "team": [
		{
		  "id": "pKboQM5EAkmLM22vJWnLYq",
		  "name": "Team"
		}
	  ],
	  "learners": [
		{
		"email": "john.smith@gmail.com",
		"full_name": "John Smith",
		"first_name": "John",
		"last_name": "Smith"
		}
	  ],
	  "courses": [
		{
		  "id": "Vpz0PmrkjdKPEOQW9d1K",
		  "name": "Course"
		}
	  ],
	  "course_groups": []
	}