Authorization occurs using the OAUTH v2 protocol with the client_credentials grant. For authorization, you will need:
To begin using our API:
{
'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.
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:
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 |
---|---|---|---|---|
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 |
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 |
This returns an array of certificates received by learners, or an empty array.
Input:
Field name | Type | Example | Required | Description |
---|---|---|---|---|
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 |
This returns a learner’s progress in all active courses/groups.
Input:
Field name | Type | Example | Required | Description |
---|---|---|---|---|
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 |
lessons_amount | int | 10 | Amount of lessons in course |
progress_amount | int | 5 | Amount of passed lessons |
progress | int | 50 | Progress in % |
content_progress[][name] | string | My First Lesson | Content name |
content_progress[][is_passed] | bool | true | Has learner passed this content |
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 |
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 |
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 |
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 |
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 |
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 |
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 |
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 |
string | test@test.com | Learner email | |
company | string | https://academyocean.com | Link to learner company or null |
This creates an invitation to a private Academy
Input:
Field name | Type | Example | Required | Description |
---|---|---|---|---|
learners[][email] | string | test@test.com | required | Email of invited learner |
learners[][name] | string | John Smith | required | Name of invited learner |
learners[][type] | string | learner | required | Type of learner from following values 'learner', 'manager' |
Output:
Returns the number of created invitations
Field 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.
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 |
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 |
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 |
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 |
All errors are sent in the following format:
Field name | Type | Example | Description |
---|---|---|---|
error[message] | string | Email is required | Error message |
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 |
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',
],
]);
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) |
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.
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',
]
],
]);
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) |
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.
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',
],
]
],
]
],
]);