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:

• Link for authorization requests: https://app.academyocean.com/oauth/token
• URL for accessing the API: https://app.academyocean.com/api/v1/

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

5. 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:

Available functions:

• learners
• courses
• certificates
• learnersProgressByCourse
• courseProgress
• learnersAmountFromCountries
• learnersFromCountry
• learnersWithScore
• learnersRegisteredAt
• learnersCourseComplete
• passiveLearners
• inviteLearners
• checkLearnerInvite
• learnersChurnAtContent
• learnersRepeatedLogIns
• academies
• createLoginToken
• setLessonVariables
• getLearnerVariable
• getTeams POST
• addLearnersToTeams
• removeLearnersFromTeams
• revokeLearnersAccess
• returnLearnersAccess
• getLearnersQuizStatistic
• deleteLearnerInvite
• deleteLearners
• courseCertificateVariables
• updateCourseCertificateVariables

Webhooks:

• course.started
• course.finished
• course.deadline_reminder.three_days
• course.deadline_reminder.seven_days
• course_group.started
• course_group.finished
• learner.course_certificate.issued
• lesson.started
• lesson.finished
• quiz.started
• quiz.finished
• academy.learner.sign_up
• learner.course.available
• learner.end_quiz_attempts
• team.new.learners

Description of Available Functions

learners

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

Also there are optional parameters that return Academy ID and Team ID

Input:

Output:

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

Learner data comprises:

courses

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

Output:

Returns an array of teams with the following fields:

Sample code:

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

The data output example:

1. Without optional parameter

			
			[
				{
					"id": "zyK0bxgWEY9E4XA6JedG",
					"slug": "incidunt-course",
					"name": "incidunt course",
					"description": "Description.",
					"img": "https://app.academyocean.com/img/upload_img.png",
					"course_open_url": "https://academy.academyocean.com/course/incidunt-course/open",
					"is_in_group": false,
					"is_scorm": false,
					"is_ribbon_enabled": true,
					"ribbon_text": "Ribbon text"
				},
				{...},
			]
			
		

certificates

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

Input:

Output:

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

Learner data comprises:

learnersProgressByCourse

This returns a learner’s progress in specified courses

Input:

Output:

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

The data output example:

			

 	[
    {
    "learners": [
        {
        "email": "[email protected]",
        "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 available for Learner courses. Also, there are optional parameters which return Academy ID and Team ID

Input:

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”

Unique parameters only if the type is quiz

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:

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.

learnersFromCountry

This returns a list of learners from the chosen country

Input:

Output:

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

learnersWithScore

This returns a list of learners filtered by their score

Input:

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:

learnersRegisteredAt

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

Input:

or

Input:

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:

learnersCourseComplete

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

Input:

Output:

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

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.

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:

Output:

Returns the number of created invitations

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:

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' => [
							   '[email protected]',
							   '[email protected]',
							   '[email protected]'
						   ]
					   ],
				   ],
				]);
			
		

Output example:

			
			[
				 "[email protected]" => [ // 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
				 ],
				 "[email protected]" => [
				   "is_found" => true,
				   "is_used" => false,
				   "used_at" => null,
				 ],
				 "[email protected]" => [
				   "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:

Output:

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

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:

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:

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',
		],
	]);
			
		

createLoginToken

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:

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:

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' => '[email protected]',
            ]
        ],
    ]);

			
		

set/createLessonVariables

Input:

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 protected]' => [
				[
				'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

What we return:

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

Sample:

			
	[
		'[email protected]' => [
			'var_name_1' => 1,
			'var_name_4' => ‘abcd’,
		],
		'[email protected]' => [
			'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' => [
					'[email protected]' => ['var_name_1', 'var_name_4'],
					'[email protected]' => ['var_name_2', 'var_name_10'],
				]
			]
		],
	]);

			
		

getTeams

Returns a list of all teams in the academy. You can also add a parameter to return courses available for each team.

Input:

Output:

Returns an array of teams with the following fields:

Sample code:

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

The data output example

1. Without optional parameter

			
				[
					{
						"id": "1AbDljeg3zyEqB6rKZ92",
						"name": "test 5"
					},
					{...},
				]
			
		

2. With optional parameter

			
				[
					{
						"id": "NVpz0PmrkjrkOQW9d1Kx",
						"name": "test 2",
						"courses": [
							{
								"id": 2,
								"name": "2"
							}
						]
					},
					{...}
				]
			
		

addLearnersToTeams

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

Also, you can add a parameter that checks if learners are registered in the academy and, if not, sends invitations

Input:

Sample code:

			
	$response = $client->post('https://app.academyocean.com/api/v1/', [
		'headers' => [
			'Authorization' => $apiToken,
		],
		'form_params' => [
			'action' => 'addLearnersToTeams',
			'options' => [
				'teams' => ['teamID_1', 'teamID_42'],
				'learners' => ['[email protected]', '[email protected]', '[email protected]']
			]
		],
	]);
			
		

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:

Sample code:

			
	$response = $client->post('https://app.academyocean.com/api/v1/', [
		'headers' => [
			'Authorization' => $apiToken,
		],
		'form_params' => [
			'action' => 'removeLearnersFromTeams',
			'options' => [
				'learners' => [
					[
						'email' => '[email protected]',
						'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:

Sample code:

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

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:

Sample code:

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

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.

What's returned:

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

Sample response:

			
	[
		'[email protected]' => [
			'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' => [
					'[email protected]' => ['eK61OzXl38z5vogrmP0y', 'Lzq0weBKvR72E72olW4X'],
					'[email protected]' => ['eK61OzXl38z5vogrmP0y', 'Lzq0weBKvR72E72olW4X'],
				]
			]
		],
	]);
			
		

addLearnerQuizAttempts

Adds one attempt to a specified quiz for a specific Learner

Input:

deleteLearnerInvite

Allows you to remove invites that have not yet been accepted.

You can also use the optional parameter to remove learners

Example of request for deleting the invitations:

			
			$client->post('https://app.academyocean.com/api/v1/', [
        'headers' => [
          'Authorization' => $apiToken,
        ],
        'form_params' => [
        'action' => ‘deleteLearnerInvite’,
        'options' => [
					'emails' => [
						'[email protected]',
						'[email protected]',
						'[email protected]'
						]
					],
				],
			]);
			
		

Output example:

			
			[
   			"done"
			]
			
		

deleteLearners

This method allows you to delete learners

Input:

Output:

The data comprises:

Sample code:

			
				$response = $client->post('http://app.academyocean.com/api/v1/', [
					'headers' => [
						'Authorization' => $auth->token_type . ' ' . $auth->access_token,
					],
					'form_params' => [
						'action'  => 'deleteLearners',
						'options' => [
							'is_permanently_delete' => true,
							'emails' => [‘[email protected]’, ‘[email protected]’],
							'ids' => [‘learner1_ID’, ‘learner2_ID’]
						]
					],
				]);
			
		

The data output example:

			
				[
					'deleted' => 1
				]
			
		

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

To maintain data integrity in webhook requests, a secret key and signature header are employed. Each webhook request includes a Signature field in its header. This signature is created using the HMAC (Hash-based Message Authentication Code) algorithm in combination with the SHA-256 hashing function.

Here’s how the signing process works:

• Secret Key: A unique secret key is generated and associated with your webhook. This key is known only to your system and can be accessed in the webhook settings.
• Payload: When a webhook event occurs, the payload (the data being sent) is used to generate the signature.
• Signature Generation: The HMAC algorithm takes the payload and the secret key as inputs. It then applies the SHA-256 hashing function to produce a hash value. This hash value is the signature.
• Signature Header: The resulting signature is included in the request header as the `Signature` field.
• Verification: On the receiving end, the signature can be verified by recalculating it using the same secret key and payload. If the recalculated signature matches the one sent in the header, the request is confirmed to be authentic and untampered.

This process ensures that the data received via the webhook has not been altered and that it originates from a trusted source.

courseCertificateVariables

What it does:

Returns the certificate variables for requested course id

What to pass:

Hashed course id

What we return:

Current certificate template id and list of certificate variables

Sample code:

			
				{
					'template_id': 144,
					'certificate_variables': [
						{
							'code': 'variable_1',
							'name': 'Variable 1 \/ Background (Recommendation: 1650x1080 px)',
							'type': 'image_url',
							'value': '\/img\/certificates\/master_certificate\/master_certificate_template_test-bg.png'
						},
						{
							'code': 'variable_2',
							'name': 'Variable 2 \/ Logotype',
							'type': 'image_url',
							'value': '\/img\/certificates\/master_certificate\/master_certificate_template_variable2.png'
						},
						{
							'code': 'variable_3',
							'name': 'Variable 3 \/ Course Skill 1',
							'type': 'text',
							'value': 'REAL Variable 3 \/ Course Skill 1'
						}
					]
				}
			
		

Sample code:

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

updateCourseCertificateVariables

Input:

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'  => 'updateCourseCertificateVariables',
						'options' => [
							'course_id' => '1AbDljeg3zyEqB6rKZ92',
							'certificate_variables' => [
								[
									'code'  => 'variable_1',
									'name'  => 'Example 1',
									'type'  => 'image_url',
									'value' => 'test.com/master_certificate_template_test-bg.png',
								],
								[
									'code'  => 'variable_2',
									'name'  => 'Example 2',
									'type'  => 'text',
									'value' => null,
								],
							],
						],
					],
				]);
			
		

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",
		  "is_in_folder":true,
		  "folder_name":"Folder",
		  "folder_id":"j4zx6GrZk4Avy2wR18JD",
		  "folder_category":"Category (recommended)",
	   },
	   "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",
		  "is_in_folder":false,
		  "folder_name":"",
		  "folder_id":"",
		  "folder_category":"",
	   },
	   "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":"[email protected]",
		  "full_name":"John",
		  "first_name":"Smith",
		  "last_name":"Smith"
	   }
	}
			
		

course.deadline_reminder.three_days

This event is triggered when there are 3 days left until the deadline

Example of data being sent:

			
			[
				"id":"EVENT_ID",
			  "event":"course.deadline_reminder.three_days",
				"first_name": "Jane",
				"last_name": "Smith",
				"learner_email": "[email protected]",
				"course_name": "new_course",
				"event_date": "02/11/2025 14:33:29"
			]
			
		

course.deadline_reminder.seven_days

This event is triggered when there are 7 days left until the deadline

Example of data being sent:

			
			[
				"id":"EVENT_ID",
			  "event":"course.deadline_reminder.seven_days",
				"first_name": "Jane",
				"last_name": "Smith",
				"learner_email": "[email protected]",
				"course_name": "new_course",
				"event_date": "02/11/2025 14:33:29"
			]
			
		

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",
		  "is_in_folder":true,
		  "folder_name":"Folder",
		  "folder_id":"j4zx6GrZk4Avy2wR18JD",
		  "folder_category":"Category (recommended)",
	   },
	   "learner":{
		  "email":"[email protected]",
		  "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",
		  "is_in_folder":true,
		  "folder_name":"Folder",
		  "folder_id":"j4zx6GrZk4Avy2wR18JD",
		  "folder_category":"Category (recommended)",
	   },
	   "learner":{
		  "email":"[email protected]",
		  "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",
		  "is_in_folder":false,
		  "folder_name":"",
		  "folder_id":"",
		  "folder_category":"",
	   },
	   "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":"[email protected]",
		  "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":"[email protected]",
		  "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":"[email protected]",
		  "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":"[email protected]",
		  "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":"[email protected]",
		  "full_name":"John Smith",
		  "first_name":"John",
		  "last_name":"Smith"
	   }
	}


			
		

academy.learner.sign_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: "[email protected]"
		 "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": "[email protected]",
		  "full_name": "John Smith",
		  "first_name": "John",
		  "last_name": "Smith"
		}
	  ],
	  "courses": [
		{
		  "id": "Vpz0PmrkjdKPEOQW9d1K",
		  "name": "Course",
		  "is_in_folder":false,
		  "folder_name":"",
		  "folder_id":"",
		  "folder_category":"",
		}
	  ],
	  "course_groups": []
	}

			
		

learner.end_quiz_attempts

The event is triggered when the learner uses all attempts to pass the quiz

Example of data being sent:

			
	{
	  id:"e63e4a55-2654-47edef-ba89-af33a0b709b3"
	  event:"learner.end_quiz_attempts"
	  academy:{
		id:"x5KbL1AEBOQa3zMkm9gYde"
			name:"Academy"
		}
	  quiz:{
		 id:"qenV4RffG3woNsef43zPK8mZO"
		 name:"Quiz"
	  }
	  learner:{
	  email: "[email protected]"
		"full_name": "John Smith",
		"first_name": "John",
		"last_name":  "Smith"
	  }
	}


			
		

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": "[email protected]",
		  "full_name": "John Smith",
		  "first_name": "John",
		  "last_name": "Smith"
		}
	  ],
	  "courses": [
		{
		  "id": "Vpz0PmrkjdKPEOQW9d1K",
		  "name": "Course"
		}
	  ],
	  "course_groups": []
	}