API Documentation

Authorization:

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

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

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

Available functions:

• learners
• certificates
• courseProgress
• learnersAmountFromCountries
• learnersFromCountry
• learnersWithScore
• learnersRegisteredAt
• learnersCourseComplete
• passiveLearners
• inviteLearners
• learnersChurnAtContent
• learnersRepeatedLogIns
• error_messages
• academies
• createLoginToken
• setLessonVariables
• getLearnerVariable
• getTeams
• addLearnersToTeams
• revokeLearnersAccess
• returnLearnersAccess

Description of Available Functions

learners

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

Input:

Output:

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

Learner data comprises:

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:

courseProgress

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

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”

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

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.

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:

Error messages

All errors are sent in the following format:

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:

Example of a 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:

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.

Example of a 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:

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.

Example of a 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:

It returns the current values of the specified variables for learners.

What is transmitted to us:

Records array with keys is an array that contains variable names, the values of which must be returned.

Return response:

An array with keys of learners' emails and internal array with recovered variables and their values.

Return data example:

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

Example of a 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 available teams in the academy. A function without passed parameters.

The return values are an array of teams with the following fields:

• ID — Team ID
• Name — Team name

Example of a code:

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

addLearnersToTeams

Add learner(s) into existing team(s). This action allows you to add any number of learners into any teams at one time.

Input:

Example of a 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) or invite from team(s). This action allows you to remove any number of learners from any teams at one time.

Input:

Example of a 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 access of learner(s) in current Аcademy. This action allows to revoke any learner(s) access. Learners progress is being saved.

Input:

Example of a 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:

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