Menu
shell

Introduction

Welcome to the Lessonly API documentation! First you will need to get an API key by signing into your account, navigating to the company settings page and clicking “API & Webhook”.

Currently we only have language bindings for shell, however we are open to providing libraries in other languages. Contact us at info@lessonly.com to let us know what libraries you would like to see.

Authentication

The following pattern authorizes an API request:

# With shell, you can just pass the correct header with each request
curl -u "SUBDOMAIN:API_KEY" "api_endpoint_here"

Make sure to replace SUBDOMAIN with your Lessonly subdomain and API_KEY with your personal API key.

Lessonly uses API keys and basic HTTP authorization to allow access to the API. All API requests must be sent over HTTPS. You can register a new Lessonly API key by signing into Lessonly and navigating to the settings page. If you do not see the API key link, you may need to request for the feature to be activated: here.

Users

List Users

curl https://api.lessonly.com/api/v1/users \
-u "SUBDOMAIN:API_KEY"

The above command returns JSON structured like this:

{
    "type": "users",
    "total_users": 300,
    "total_pages": 150,
    "page": 1,
    "per_page": 2,
    "users": [
        {
            "id": 78,
            "resource_type": "user",
            "ext_uid": "1234567899",
            "email": "joe@lessonly.com",
            "name": "Joe Ubuntu",
            "role": "admin",
            "role_id": 42,
            "archived_at": null,
            "archived_by_user_id": null,
            "job_title": "",
            "business_unit": "",
            "department": "",
            "location": "",
            "locale": "en",
            "hire_date": null,
            "manager_name": ""
        },
        {
            "id": 1694,
            "resource_type": "user",
            "ext_uid": null,
            "email": "alexie@lessonly.com",
            "name": "James alexie",
            "role": "admin",
            "role_id": 42,
            "archived_at": "2019-02-01T02:51:40.436-05:00",
            "archived_by_user_id": 1640090,
            "job_title": null,
            "business_unit": null,
            "department": null,
            "location": null,
            "locale": "en",
            "hire_date": null,
            "manager_name": null
        }
    ]
}

This endpoint retrieves all users.

HTTP Request

GET https://api.lessonly.com/api/v1/users?filter[email]=email@example.com

Query Parameters

Parameter Required Type Description
page no Positive Integer Which page in the pagination to fetch. Default = 1
per_page no Positive Integer How many results to return in each page. Default = 50; Maximum = 1000. Numbers > 1000 are ignored and 1000 will be returned.
filter no String Specified user filter for users list. Supported filters are email, ext_uid, sso_id, and custom_user_field. The SSO ID is the provider ID that we store from a successful SSO request. The format for custom_user_field is filter[custom_user_field][FIELD_ID]=FIELD_VALUE.

List Users (v1.1)

curl https://api.lessonly.com/api/v1.1/users \
-u "SUBDOMAIN:API_KEY"

The above command returns JSON structured like this:

{
    "type": "users",
    "total_users": 300,
    "total_pages": 150,
    "page": 1,
    "per_page": 2,
    "users": [
        {
            "id": 78,
            "resource_type": "user",
            "ext_uid": "1234567899",
            "email": "max@lessonly.com",
            "name": "Max Yoder",
            "role": "admin",
            "role_id": 42,
            "archived_at": null,
            "archived_by_user_id": null,
            "job_title": "",
            "business_unit": "",
            "department": "",
            "location": "",
            "locale": "en",
            "hire_date": null,
            "manager_name": "",
            "mobile_phone_number": null,
            "custom_user_field_data": [
                {
                    "id": 1823576,
                    "custom_user_field_id": 2096,
                    "value": "3171234567",
                    "name": "SMS Reminder Phone Number"
                },
            ],
            "groups": {
                "member": [
                    {
                        "id": 38780,
                        "name": "Test Group"
                    },
                    {
                        "id": 15251,
                        "name": "Leadership: Execs, Directors & Managers"
                    }
                ],
                "manager": [
                    {
                        "id": 46421,
                        "name": "Org - AE - West"
                    },
                    {
                        "id": 46407,
                        "name": "Org - Customer Support"
                    },
                ]
            }
        }
    ]
}

This endpoint retrieves all users.

HTTP Request

GET https://api.lessonly.com/api/v1.1/users?filter[email]=email@example.com

Query Parameters

Parameter Required Type Description
page no Positive Integer Which page in the pagination to fetch. Default = 1
per_page no Positive Integer How many results to return in each page. Default = 50; Maximum = 1000. Numbers > 1000 are ignored and 1000 will be returned.
filter no String Specified user filter for users list. Supported filters are email, ext_uid, sso_id, custom_user_field, created_since and active_only. The SSO ID is the provider ID that we store from a successful SSO request. created_since takes a date format of “YYYY-MM-DD”. active_only returns only active users if the value “true” is passed. Anything else will result in all users being returned. The format for custom_user_field is filter[custom_user_field][FIELD_ID]=FIELD_VALUE.

Show User Details

curl https://api.lessonly.com/api/v1/users/:user_id \
-u "SUBDOMAIN:API_KEY"

The above command returns JSON structured like this:

{
  "type": "user",
  "resource_type": "user",
  "id": 1,
  "name": "Test User",
  "email": "test@test.com",
  "role": "learner",
  "role_id": 42,
  "ext_uid": "ABC123",
  "job_title": "Account Executive",
  "business_unit": "Global",
  "department": "Sales",
  "location": "Illinois",
  "locale": "en",
  "hire_date": "2014-12-25",
  "manager_name": "Mary Doe",
  "custom_user_field_data": [
    {
      "id": 1,
      "custom_user_field_id": 1,
      "name": "Custom Field Name 1",
      "value": "Custom Value 1"
    }
  ],
  "archived_at": null,
  "archived_by_user_id": null
}

This endpoint retrieves all the user’s details including their custom field data. To see the users groups see the user group endpoint.

HTTP Request

GET https://api.lessonly.com/api/v1/users/:user_id

Query Parameters

Parameter Required Type Description
user_id yes Positive Integer The user to access. The company must have access to the user.

Show User Learning Library Statistics

curl https://api.lessonly.com/api/v1/users/:user_id/learning_library_statistics \
-u "SUBDOMAIN:API_KEY"

The above command returns JSON structured like this:

{
  "type": "user_learning_library_statistics",
  "learning_library_statistics": {
     "total_completed": 3,
     "total_views": 50,
     "unique_lesson_and_path_views": 10
  }
}

This endpoint retrieves all the user’s learning library statistics. Note: this endpoint is available only to customers whose plan includes the Learning Library

HTTP Request

GET https://api.lessonly.com/api/v1/users/:user_id/learning_library_statistics

Query Parameters

Paramter Required Type Description
user_id yes Positive Integer The user to access. The company must have access to the user.

Create User

curl -X POST https://api.lessonly.com/api/v1/users \
-H "Content-Type: application/json" \
-u "SUBDOMAIN:API_KEY" \
-d '{
  "name": "User Name",
  "email": "email@example.com",
  "role_id": 32,
  "ext_uid": "ABC123",
  "job_title": "Account Executive",
  "business_unit": "Global",
  "department": "Sales",
  "location": "Illinois",
  "locale": "en",
  "hire_date": "2014-12-25",
  "manager_name": "Mary Doe",
  "custom_user_fields": [
    {
      "custom_user_field_id": 1,
      "value": "Custom Value 1"
    },
    {
      "name": "Custom Field Name 2",
      "value": "Custom Value 2"
    }
  ]
}'

A successful post returns JSON consisting of the show user detail response

 {
  "type": "create_user",
  "resource_type": "user",
  "id": 1,
  "name": "User Name",
  "email": "email@example.com",
  "role": "learner",
  "role_id": 32,
  "ext_uid": "ABC123",
  "job_title": "Account Executive",
  "business_unit": "Global",
  "department": "Sales",
  "location": "Illinois",
  "locale": "en",
  "hire_date": "2014-12-25",
  "manager_name": "Mary Doe",
  "custom_user_field_data":
    [
      {
        "id": 1,
        "custom_user_field_id": 1,
        "name": "Custom Field Name 1",
        "value": "Custom Value 1"
      },
      {
        "id": 2,
        "custom_user_field_id": 2,
        "name": "Custom Field Name 2",
        "value": "Custom Value 2"
      }
    ]
}

This endpoint allows you to create a user in the api.

HTTP Request

POST https://api.lessonly.com/api/v1/users/ -d params

Query Parameters

Parameter Required Type Description
name yes String User full name. Cannot begin with a space and the following characters are restricted: `!@#\$%^&*+=()|[];
email yes String User Email
role role or role_id String User role to change user to. Options: admin, manager, creator, learner. You must use either role or role_id
role_id role or role_id Integer The ID of the role to associate with the user. This is the prefered way to set a role. You must use either role or role_id
ext_uid no String The user’s ID in another system, useful for linking data.
job_title no String User job title
business_unit no String User business unit
department no String User department
location no String User location
locale no String User locale code to control the interface language. Options: ar, de, en, es, fr, it, ja, nl, pt, ru, sv, zh-CN. Defaults to ‘en’.
hire_date no String User hire date. Must be an ISO8601 formatted date (YYYY-MM-DD).
manager_name no String User manager name
notify no String Whether or not to notify the user. Passing ‘false’ will not send an email notification to the user that their account has been created. Defaults to ‘true’ for admin, manager, creator and custom roles. Defaults to ‘false’ for learner role.
custom_user_fields no Array Custom user fields for the user. Hashes must contain a “value” and either a “customer_user_field_id” or “name”. If an unknown custom user field “name” is provided, a new custom user field will be created with that name.

Update User

curl -X PUT https://api.lessonly.com/api/v1/users/:user_id \
-H "Content-Type: application/json" \
-u "SUBDOMAIN:API_KEY" \
-d '{
  "name": "User Name",
  "email": "email@example.com",
  "role_id": 32,
  "ext_uid": "ABC123",
  "job_title": "Account Executive",
  "business_unit": "Global",
  "department": "Sales",
  "location": "Illinois",
  "locale": "en",
  "hire_date": "2014-12-25",
  "manager_name": "Mary Doe",
  "custom_user_fields": [
    {
      "custom_user_field_id": 1,
      "value": "Custom Value 1"
    },
    {
      "name": "Custom Field Name 2",
      "value": "Custom Value 2"
    }
  ]
}'

A successful update returns JSON consisting of the show user detail response

 {
  "type": "update_user",
  "resource_type": "user",
  "id": 1,
  "name": "User Name",
  "email": "email@example.com",
  "role": "learner",
  "role_id": 32,
  "ext_uid": "ABC123",
  "job_title": "Account Executive",
  "business_unit": "Global",
  "department": "Sales",
  "location": "Illinois",
  "locale": "en",
  "hire_date": "2014-12-25",
  "manager_name": "Mary Doe",
  "custom_user_field_data":
    [
      {
        "id": 1,
        "custom_user_field_id": 1,
        "name": "Custom Field Name 1",
        "value": "Custom Value 1"
      },
      {
        "id": 2,
        "custom_user_field_id": 2,
        "name": "Custom Field Name 2",
        "value": "Custom Value 2"
      }
    ]
}

This endpoint allows you to update a user in the api.

HTTP Request

PUT https://api.lessonly.com/api/v1/users/:user_id -d params

Query Parameters

Parameter Required Type Description
user_id yes Positive Integer The user to access. The company must have access to the user.
name no String User name to change user to
email no String User Email to change user to
role no String User role to change user to. Options: admin, manager, creator, learner. You must use either role or role_id.
role_id no Integer The ID of the role to associate with the user. This is the prefered way to set a role. You must use either role or role_id.
ext_uid no String The user’s ID in another system, useful for linking data.
job_title no String User job title
business_unit no String User business unit
department no String User department
location no String User location
locale no String User locale code to control the interface language. Options: ar, de, en, es, fr, it, ja, nl, pt, ru, sv, zh-CN. Defaults to ‘en’.
hire_date no String User hire date. Must be an ISO8601 formatted date (YYYY-MM-DD).
manager_name no String User manager name
custom_user_fields no Array Custom user fields for the user. Hashes must contain a “value” and either a “customer_user_field_id” or “name”. If an unknown custom user field “name” is provided, a new custom user field will be created with that name. If the user does not have a value for the specified customer user field it will be added, otherwise it will be updated to the specified “value”.

Archive User

curl -X PUT https://api.lessonly.com/api/v1/users/:user_id/archive \
-u "SUBDOMAIN:API_KEY"

The above command returns JSON structured like this:

{
    "archived_at": "2016-10-13T09:34:24.151-04:00",
    "archived_by_user_id": null,
    "custom_user_field_data": [],
    "email": "learner@example.com",
    "ext_uid": null,
    "job_title": "Account Executive",
    "business_unit": "Global",
    "department": "Sales",
    "location": "Illinois",
    "locale": "en",
    "hire_date": "2014-12-25",
    "manager_name": "Mary Doe",
    "id": 739413,
    "name": "Beta Learner",
    "resource_type": "user",
    "role": "learner",
    "role_id": 32,
    "type": "user"
}

This endpoint allows the archiving of a single user.

HTTP Request

PUT https://api.lessonly.com/api/v1/users/:user_id/archive

Query Parameters

Parameter Required Type Description
user_id yes Positive Integer The user to archive. The company must have access to the user.

Restore User

curl -X PUT https://api.lessonly.com/api/v1/users/:user_id/restore \
-u "SUBDOMAIN:API_KEY"

The above command returns JSON structured like this:

{
    "archived_at": null,
    "archived_by_user_id": null,
    "custom_user_field_data": [],
    "email": "learner@example.com",
    "ext_uid": null,
    "job_title": "Account Executive",
    "business_unit": "Global",
    "department": "Sales",
    "location": "Illinois",
    "locale": "en",
    "hire_date": "2014-12-25",
    "manager_name": "Mary Doe",
    "id": 739413,
    "name": "Beta Learner",
    "resource_type": "user",
    "role": "learner",
    "role_id": 32,
    "type": "user"
}

This endpoint allows the restoring of a single archived user.

HTTP Request

PUT https://api.lessonly.com/api/v1/users/:user_id/restore

Query Parameters

Parameter Required Type Description
user_id yes Positive Integer The user to restore. The company must have access to the user.

Delete User

curl -X DELETE https://api.lessonly.com/api/v1/users/:user_id \
-u "SUBDOMAIN:API_KEY"

A successful update returns JSON consisting of the id of the deleted user

{
  "type": "delete_user",
  "id": "3"
}

This endpoint allows you to delete a user in the API.

HTTP Request

DELETE https://api.lessonly.com/api/v1/users/:user_id

Query Parameters

Parameter Required Type Description
user_id yes Positive Integer The user to delete. The company must have access to the user.

User Groups

curl https://api.lessonly.com/api/v1/users/:user_id/groups \
-u "SUBDOMAIN:API_KEY"

The above command returns JSON structured like this:

{
  "type": "user_groups",
  "memberships": [
    {
      "id": 1,
      "name": "Test Group"
    },
    {
      "id": 3,
      "name": "Test Group 3"
    }
  ],
  "managing": [
    {
      "id": 1,
      "name": "Test Group5"
    }
  ]
}

This endpoint allows you to list out a user’s group memberships and groups they are managing.

HTTP Request

GET https://api.lessonly.com/api/v1/users/:user_id/groups

Query Parameters

Parameter Required Type Description
user_id yes Positive Integer The user to access. The company must have access to the user.

Update User Groups

curl -X PUT https://api.lessonly.com/api/v1/users/:user_id/groups \
-H "Content-Type: application/json" \
-u "SUBDOMAIN:API_KEY" \
-d '{
  "memberships": [
    {
      "id": 1
    },
    {
      "id": 2,
      "remove": "true"
    }
  ],
  "managing": [
    {
      "id": 3,
      "remove": "true"
    },
    {
      "id": 4
    }
  ]
}'

A successful update will return JSON consisting of the user group repsonse:

{
  "type": "update_user_groups",
  "memberships": [
    {
      "id": 1,
      "name": "Test Group"
    },
    {
      "id": 3,
      "name": "Test Group 3"
    }
  ],
  "managing": [
    {
      "id": 1,
      "name": "Test Group5"
    }
  ]
}

This endpoint allows you to update a user’s involvement in various groups.

HTTP Request

PUT https://api.lessonly.com/api/v1/users/:user_id/groups

Query Parameters

Parameter Required Type Description
user_id yes Positive Integer The user to access. The company must have access to the user.
memberships no Array The groups in which the user is a member. Passing “remove”: “true” will remove this association.
managing no Array The groups in which the user is managing. Passing “remove”: “true” will remove this association.

User Assignments

curl https://api.lessonly.com/api/v1/users/:user_id/assignments \
-u "SUBDOMAIN:API_KEY"

The above command returns JSON structured like this:

{
  "type": "user_assignments",
  "assignments": [
    {
      "type": "Assignment",
      "resource_type": "assignment",
      "id": 1,
      "assignee_id": 1,
      "ext_uid": "ABC123",
      "assignable_id": 1,
      "assignable_type": "Lesson",
      "due_by": "2020-09-30T00:00:00Z",
      "reassigned_at": "2020-09-30T00:00:00Z",
      "completed_at": "2020-09-30T00:00:00Z",
      "updated_at": "2020-09-30T00:00:00Z",
      "status": "Completed",
      "score": 20
    },
    {
      "type": "Assignment",
      "resource_type": "assigment",
      "id": 2,
      "assignee_id": 1,
      "ext_uid": "DEF456",
      "assignable_id": 2,
      "assignable_type": "LearningPaths::Path",
      "due_by": "2020-09-30T00:00:00Z",
      "reassigned_at": "2020-09-30T00:00:00Z",
      "completed_at": null,
      "updated_at": "2020-09-30T00:00:00Z",
      "status": "Incomplete",
      "score": null
    }
  ]
}

This endpoint returns a list of assignments for a given user.

HTTP Request

GET https://api.lessonly.com/api/v1/users/:user_id/assignments

Query Parameters

Parameter Required Type Description
user_id yes Positive Integer The user to access. The company must have access to the user.

Create User Assignments

curl -X POST https://api.lessonly.com/api/v1/users/:user_id/assignments \
-H "Content-Type: application/json" \
-u "SUBDOMAIN:API_KEY" \
-d '{
  "assignments": [
    {
      "assignable_id": 1,
      "assignable_type": "Lesson",
      "due_by": "2020-09-30",
      "notify": false
    },
    {
      "assignable_id": 3,
      "assignable_type": "LearningPaths::Path",
      "due_by": "2020-09-30",
      "notify": false
    }
  ]
}'

A successful update will return JSON consisting of the user assignment repsonse:

{
  "type": "create_user_assignments",
  "assignments": [
    {
      "type": "Assignment",
      "resource_type": "assignment",
      "id": 1,
      "assignee_id": 1,
      "ext_uid": "ABC123",
      "assignable_id": 1,
      "assignable_type": "Lesson",
      "due_by": "2020-09-30T00:00:00Z",
      "reassigned_at": "2020-09-30T00:00:00Z",
      "completed_at": null,
      "updated_at": "2020-09-30T00:00:00Z",
      "status": "Incomplete",
      "score": 20
    },
    {
      "type": "Assignment",
      "resource_type": "assignment",
      "id": 3,
      "assignee_id": 2,
      "ext_uid": "DEF456",
      "assignable_id": 2,
      "assignable_type": "LearningPaths::Path",
      "due_by": "2020-09-30T00:00:00Z",
      "reassigned_at": "2020-09-30T00:00:00Z",
      "completed_at": null,
      "updated_at": "2020-09-30T00:00:00Z",
      "status": "Incomplete",
      "score": null
    }
  ]
}

This endpoint allows you to create assignments for a user.

HTTP Request

POST https://api.lessonly.com/api/v1/users/:user_id/assignments

Query Parameters

Parameter Required Type Description
user_id yes Positive Integer The user to access. The company must have access to the user.
assignments yes Array Array of assignments to be made to the user. Each requires an assignable_id and assignable_type of “Lesson” or “LearningPaths::Path”. By default, an email will be sent to the assignee; it will come from notifications@lessonly.com. To suppress the email notification set notify to false.

Groups

List Groups

curl https://api.lessonly.com/api/v1/groups \
-u "SUBDOMAIN:API_KEY"

The above command returns JSON structured like this:

{
  "type": "groups",
  "groups": [
    {
      "id": 1,
      "name": "Group 1",
      "archived_at": null,
      "archived_by_user_id": null
    },
    {
      "id": 2,
      "name": "Group 2",
      "archived_at": null,
      "archived_by_user_id": null
    }
  ]
}

This endpoint retrieves all groups.

HTTP Request

GET https://api.lessonly.com/api/v1/groups

Show Group Details

curl https://api.lessonly.com/api/v1/groups/:group_id \
-u "SUBDOMAIN:API_KEY"

The above command returns JSON structured like this:

{
  "id": 12345,
  "type": "group",
  "resource_type": "group",
  "name": "Test Group",
  "archived_at": null,
  "archived_by_user_id": null,
  "members": [
    {
      "id": 4308512,
      "resource_type": "user",
      "ext_uid": null,
      "email": "joe.alec@lessonly.com",
      "name": "Joe Alec",
      "role": "admin",
      "role_id": 42,
      "archived_at": null,
      "archived_by_user_id": null,
      "job_title": "",
      "business_unit": "Andela",
      "department": "Product",
      "location": "",
      "locale": "en",
      "hire_date": null,
      "manager_name": "Joe Metil"
    }
  ],
  "managers": [
    {
      "id": 21494,
      "resource_type": "user",
      "ext_uid": "3175551234",
      "email": "jay@lessonly.com",
      "name": "Jay Bentley",
      "role": "manager",
      "role_id": 42,
      "archived_at": null,
      "archived_by_user_id": null,
      "job_title": "",
      "business_unit": "",
      "department": "Product",
      "location": "",
      "locale": "en",
      "hire_date": null,
      "manager_name": ""
    }
   ]
}

This endpoint retrieves a listing of a groups members and managers.

Query Parameters

Parameter Required Type Description
group_id yes Positive Integer The group to access. The company must have access to the group.

HTTP Request

GET https://api.lessonly.com/api/v1/groups/:group_id

Create Group

curl -X POST https://api.lessonly.com/api/v1/groups \
-H "Content-Type: application/json" \
-u "SUBDOMAIN:API_KEY" \
-d '{
  "name": "create_group",
  "members": [
    {
      "id": 1
    },
    {
      "id": 2
    }
  ],
  "managers": [
    {
      "id": 3
    },
    {
      "id": 4
    }
  ]
}'

A successful post will return JSON consisting of the group details response:

{
  "type": "create_group",
  "resource_type": "group",
  "id": 12345,
  "name": "New Name",
  "archived_at": null,
  "archived_by_user_id": null,
  "members": [
    {
      "id": 1,
      "resource_type": "user",
      "ext_uid": null,
      "email": "joe.alec@lessonly.com",
      "name": "Joe Alec",
      "role": "admin",
      "role_id": 42,
      "archived_at": null,
      "archived_by_user_id": null,
      "job_title": "",
      "business_unit": "Andela",
      "department": "Product",
      "location": "",
      "locale": "en",
      "hire_date": null,
      "manager_name": "Joe Metil"
    },
    {
      "id": 2,
      "resource_type": "user",
      "ext_uid": null,
      "email": "me@lessonly.com",
      "name": "Henry Alec",
      "role": "admin",
      "role_id": 42,
      "archived_at": null,
      "archived_by_user_id": null,
      "job_title": "",
      "business_unit": "Andela",
      "department": "Product",
      "location": "",
      "locale": "en",
      "hire_date": null,
      "manager_name": "Joe Metil"
    }
   ],
  "managers":  [
     {
        "id": 3,
        "resource_type": "user",
        "ext_uid": "3175551234",
        "email": "jay@lessonly.com",
        "name": "Jay Bentley",
        "role": "manager",
        "role_id": 36,
        "archived_at": null,
        "archived_by_user_id": null,
        "job_title": "",
        "business_unit": "",
        "department": "Product",
        "location": "",
        "locale": "en",
        "hire_date": null,
        "manager_name": ""
     },
     {
        "id": 4,
        "resource_type": "user",
        "ext_uid": "3175551234",
        "email": "irene@lessonly.com",
        "name": "Sandra Irene",
        "role": "manager",
        "role_id": 36,
        "archived_at": null,
        "archived_by_user_id": null,
        "job_title": "",
        "business_unit": "",
        "department": "Product",
        "location": "",
        "locale": "en",
        "hire_date": null,
        "manager_name": ""
     }
   ]
}

This endpoint allows you to create a group, its members and managers.

HTTP Request

POST https://api.lessonly.com/api/v1/groups/ -d params

Query Parameters

Parameter Required Type Description
name yes String The name of the group
members no Array The members of a group.
managers no Array The managers of a group.

Update Group

curl -X PUT https://api.lessonly.com/api/v1/groups/:group_id \
-H "Content-Type: application/json" \
-u "SUBDOMAIN:API_KEY" \
-d '{
  "name": "New Name",
  "members": [
    {
      "id": 1
    },
    {
      "id": 2,
      "remove": "true"
    }
  ],
  "managers": [
    {
      "id": 3,
      "remove": "true"
    },
    {
      "id": 4
    }
  ]
}'

A successful update will return JSON consisting of the group details response:

{
  "type": "update_group",
  "resource_type": "group",
  "id": 12345,
  "name": "New Name",
  "archived_at": null,
  "archived_by_user_id": null,
  "members": [
    {
      "id": 1,
      "resource_type": "user",
      "ext_uid": null,
      "email": "me@lessonly.com",
      "name": "Henry Alec",
      "role": "learner",
      "role_id": 32,
      "archived_at": null,
      "archived_by_user_id": null,
      "job_title": "",
      "business_unit": "Andela",
      "department": "Product",
      "location": "",
      "locale": "en",
      "hire_date": null,
      "manager_name": "Joe Metil"
    }
  ],
  "managers":  [
     {
        "id": 4,
        "resource_type": "user",
        "ext_uid": "3175551234",
        "email": "irene@lessonly.com",
        "name": "Sandra Irene",
        "role": "manager",
        "role_id": 36,
        "archived_at": null,
        "archived_by_user_id": null,
        "job_title": "",
        "business_unit": "",
        "department": "Product",
        "location": "",
        "locale": "en",
        "hire_date": null,
        "manager_name": ""
     }
   ]
}

This endpoint allows you to update a group, its members and managers.

HTTP Request

PUT https://api.lessonly.com/api/v1/groups/:group_id/ -d params

Query Parameters

Parameter Required Type Description
group_id yes Positive Integer The group to access. The company must have access to the group.
name no String The name of the group.
members no Array The members of a group. Passing “remove”: “true” will remove this association.
managers no Array The managers of a group. Passing “remove”: “true” will remove this association.

Archive Group

curl -X PUT https://api.lessonly.com/api/v1/groups/:group_id/archive \
-u "SUBDOMAIN:API_KEY"

The above command returns JSON structured like this:

{
    "id": 12631,
    "name": "Developer",
    "resource_type": "group",
    "type": "group",
    "archived_at": "2016-09-26T13:05:01.174-04:00",
    "archived_by_user_id": null,
    "members": [
      {
        "id": 1,
        "resource_type": "user",
        "ext_uid": null,
        "email": "me@lessonly.com",
        "name": "Henry Alec",
        "role": "learner",
        "role_id": 32,
        "archived_at": null,
        "archived_by_user_id": null,
        "job_title": "",
        "business_unit": "Andela",
        "department": "Product",
        "location": "",
        "locale": "en",
        "hire_date": null,
        "manager_name": "Joe Metil"
      }
    ],
    "managers": [
       {
          "id": 4,
          "resource_type": "user",
          "ext_uid": "3175551234",
          "email": "irene@lessonly.com",
          "name": "Sandra Irene",
          "role": "manager",
          "role_id": 36,
          "archived_at": null,
          "archived_by_user_id": null,
          "job_title": "",
          "business_unit": "",
          "department": "Product",
          "location": "",
          "locale": "en",
          "hire_date": null,
          "manager_name": ""
       }
    ]
}

This endpoint allows the archiving of a single group.

HTTP Request

PUT https://api.lessonly.com/api/v1/groups/:group_id/archive

Query Parameters

Parameter Required Type Description
group_id yes Positive Integer The group to archive. The company must have access to the group.

Restore Group

curl -X PUT https://api.lessonly.com/api/v1/groups/:group_id/restore \
-u "SUBDOMAIN:API_KEY"

The above command returns JSON structured like this:

{
    "id": 12631,
    "name": "Developer",
    "resource_type": "group",
    "type": "group",
    "archived_at": null,
    "archived_by_user_id": null,
    "members": [
      {
        "id": 1,
        "resource_type": "user",
        "ext_uid": null,
        "email": "me@lessonly.com",
        "name": "Henry Alec",
        "role": "learner",
        "role_id": 32,
        "archived_at": null,
        "archived_by_user_id": null,
        "job_title": "",
        "business_unit": "Andela",
        "department": "Product",
        "location": "",
        "locale": "en",
        "hire_date": null,
        "manager_name": "Joe Metil"
      }
    ],
    "managers": [
       {
          "id": 4,
          "resource_type": "user",
          "ext_uid": "3175551234",
          "email": "irene@lessonly.com",
          "name": "Sandra Irene",
          "role": "manager",
          "role_id": 36,
          "archived_at": null,
          "archived_by_user_id": null,
          "job_title": "",
          "business_unit": "",
          "department": "Product",
          "location": "",
          "locale": "en",
          "hire_date": null,
          "manager_name": ""
       }
    ]
}

This endpoint allows the restoring of a single archived group.

HTTP Request

PUT https://api.lessonly.com/api/v1/groups/:group_id/restore

Query Parameters

Parameter Required Type Description
group_id yes Positive Integer The group to restore. The company must have access to the group.

Delete Group

curl -X DELETE https://api.lessonly.com/api/v1/groups/:group_id \
-u "SUBDOMAIN:API_KEY"

A successful delete returns JSON consisting of the id of the deleted group

{
  "type": "delete_group",
  "id": "3",
  "name": "Group 3",
  "archived_at": null,
  "archived_by_user_id": null
}

This endpoint allows you to delete a group in the API.

HTTP Request

DELETE https://api.lessonly.com/api/v1/groups/:group_id

Query Parameters

Parameter Required Type Description
group_id yes Positive Integer The group to delete. The company must have access to the group.

Group Assignments

curl https://api.lessonly.com/api/v1/groups/:group_id/assignments \
-u "SUBDOMAIN:API_KEY"

The above command returns JSON structured like this:

[
  {
    "id": 1,
    "assignable_id": 10,
    "assignable_type": "Lesson",
    "group_id": 5
  },
  {
    "id": 2,
    "assignable_id": 15,
    "assignable_type": "LearningPaths::Path",
    "group_id": 5
  }
]

This endpoint returns a list of all lessons and paths that have been assigned to the given group, in no particular order. Results include both archived and unarchived learning content.

HTTP Request

GET https://api.lessonly.com/api/v1/groups/:group_id/assignments

Query Parameters

Parameter Required Type Description
group_id yes Positive Integer The group whose assignments to access

Lessons

List Lessons

curl https://api.lessonly.com/api/v1/lessons \
-u "SUBDOMAIN:API_KEY"

The above command returns JSON structured like this:

{
  "type": "lessons",
  "lessons": [
      {
        "id": 30976,
        "title": "Lesson 3",
        "archived_at": "2016-08-08T10:49:37.676-04:00",
        "archived_by_user_id": 1735
      },
      {
        "id": 94861,
        "title": "Trent - Kendra Scott",
        "archived_at": "2018-02-10T15:38:51.014-05:00",
        "archived_by_user_id": 78
      }
  ]
}

This endpoint retrieves all lessons.

HTTP Request

GET https://api.lessonly.com/api/v1/lessons

List Lessons (v1.1)

curl https://api.lessonly.com/api/v1.1/lessons \
-u "SUBDOMAIN:API_KEY"

The above command returns JSON structured like this:

{
  "type": "lessons",
  "lessons": [
    {
      "id": 1,
      "resource_type": "lesson",
      "title": "First Lesson",
      "archived_at": null,
      "archived_by_user_id": null,
      "retake_score": 80,
      "public": false,
      "created_at": "2020-09-30T00:00:00Z",
      "last_updated_at": "2020-09-30T00:00:00Z",
      "tags": [
        {
          "id": 1,
          "name": "test_tag",
          "resource_type": "tag"
        }
      ],
      "links": {
        "overview": "https://mycompany.lessonly.com/lessons/1-first-lesson"
      }
    },
    {
      "id": 2,
      "resource_type": "lesson",
      "title": "Second Lesson",
      "archived_at": null,
      "archived_by_user_id": null,
      "retake_score": 95,
      "public": true,
      "created_at": "2020-09-30T00:00:00Z",
      "last_updated_at": "2020-09-30T00:00:00Z",
      "tags": [
        {
          "id": 1,
          "name": "test_tag",
          "resource_type": "tag"
        }
      ],
      "links": {
        "overview": "https://mycompany.lessonly.com/lessons/2-second-lesson",
        "shareable": "https://mycompany.lessonly.com/lesson/2-second-lesson"
      }
    }
  ]
}

This endpoint retrieves all lessons.

HTTP Request

GET https://api.lessonly.com/api/v1.1/lessons

Show Lesson Details

curl https://api.lessonly.com/api/v1/lessons/:lesson_id \
-u "SUBDOMAIN:API_KEY"

The above command returns JSON structured like this:

{
  "id": 1,
  "type": "lesson",
  "resource_type": "lesson",
  "title": "Lesson 1",
  "assignees_count": 10,
  "completed_count": 5,
  "retake_score": 80,
  "description": "just another lesson",
  "public": false,
  "created_at": "2020-09-30T00:00:00Z",
  "last_updated_at": "2020-09-30T00:00:00Z",
  "tags": [
    {
      "id": 1,
      "name": "test_tag",
      "resource_type": "tag"
    }
  ],
  "links": {
    "overview": "https://mycompany.lessonly.com/lessons/1-lesson-1",
    "shareable": "https://mycompany.lessonly.com/lesson/1-lesson-1"
  },
  "archived_at": null,
  "archived_by_user_id": null
}

This endpoint retrieves all the lesson details including statistics about the completion of the lesson.

HTTP Request

GET https://api.lessonly.com/api/v1/lessons/:lesson_id

Show Lesson Details (v1.1)

curl https://api.lessonly.com/api/v1.1/lessons/:lesson_id \
-u "SUBDOMAIN:API_KEY"

The above command returns JSON structured like this:

{
  "id": 1,
  "type": "lesson",
  "resource_type": "lesson",
  "title": "Lesson 1",
  "retake_score": 80,
  "description": "just another lesson",
  "public": false,
  "created_at": "2020-09-30T00:00:00Z",
  "last_updated_at": "2020-09-30T00:00:00Z",
  "tags": [
    {
      "id": 1,
      "resource_type": "tag",
      "name": "test_tag"
    }
  ],
  "links": {
    "shareable": "https://lesson-link",
    "overview": "https://lesson-link"
  },
  "archived_at": "2016-08-12T08:54:52.982-04:00",
  "archived_by_user_id": 78
}

This endpoint retrieves the lesson’s information. For a count of completed assignments, please see Lesson Completed Assignments.

HTTP Request

GET https://api.lessonly.com/api/v1.1/lessons/:lesson_id

Update Lesson

curl -X PUT https://api.lessonly.com/api/v1/lessons/:lesson_id \
-H "Content-Type: application/json" \
-u "SUBDOMAIN:API_KEY" \
-d '{
  "title": "Untitled Lesson",
  "retake_score": "80",
  "public": true
}'

The above command returns JSON structured like this:

{
  "type": "update_lesson",
  "resource_type": "lesson",
  "id": 1,
  "title": "Untitled Lesson",
  "description": "just another lesson",
  "assignees_count": 10,
  "completed_count": 5,
  "retake_score": 80,
  "public": true,
  "created_at": "2020-09-30T00:00:00Z",
  "last_updated_at": "2020-09-30T00:00:00Z",
  "archived_at": null,
  "archived_by_user_id": null,
  "tags": [
    {
      "id": 1,
      "name": "test_tag"
    }
  ],
  "links": {
    "overview": "https://mycompany.lessonly.com/lessons/1-lesson-1",
    "shareable": "https://mycompany.lessonly.com/lesson/1-lesson-1"
  }
}

This endpoint allows the updating of a single lesson and its attributes.

HTTP Request

PUT https://api.lessonly.com/api/v1/lessons/:lesson_id -d params

Query Parameters

Parameter Required Type Description
lesson_id yes Positive Integer The lesson to access. The company must have access to the lesson.
title no String The title of the lesson.
retake_score no Positive Integer The retake score of the lesson.
public no Boolean Whether or not the lesson is public

Archive Lesson

curl -X PUT https://api.lessonly.com/api/v1/lessons/:lesson_id/archive \
-u "SUBDOMAIN:API_KEY"

The above command returns JSON structured like this:

{
    "id": 43530,
    "title": "Untitled Lesson",
    "type": "lesson",
    "archived_at": "2016-10-12T16:12:09.850-04:00",
    "archived_by_user_id": null,
    "assignees_count": 0,
    "completed_count": 0,
    "created_at": "2016-10-06T16:09:41Z",
    "description": null,
    "last_updated_at": "2016-10-06T16:18:01Z",
    "links": {
      "overview": "https://mycompany.lessonly.com/lessons/43530-untitled-lesson",
      "shareable": "https://mycompany.lessonly.com/lesson/43530-untitled-lesson"
    },
    "public": false,
    "resource_type": "lesson",
    "retake_score": 90,
    "tags": [
      {
        "id": 1,
        "name": "test_tag",
        "resource_type": "tag"
      }
    ]
}

This endpoint allows the archiving of a single lesson.

HTTP Request

PUT https://api.lessonly.com/api/v1/lessons/:lesson_id/archive

Query Parameters

Parameter Required Type Description
lesson_id yes Positive Integer The lesson to archive. The company must have access to the lesson.

Restore Lesson

curl -X PUT https://api.lessonly.com/api/v1/lessons/:lesson_id/restore \
-u "SUBDOMAIN:API_KEY"

The above command returns JSON structured like this:

{
    "id": 43530,
    "title": "Untitled Lesson",
    "type": "lesson",
    "archived_at": null,
    "archived_by_user_id": null,
    "assignees_count": 0,
    "completed_count": 0,
    "created_at": "2016-10-06T16:09:41Z",
    "description": null,
    "last_updated_at": "2016-10-06T16:18:01Z",
    "links": {
      "overview": "https://mycompany.lessonly.com/lessons/43530-untitled-lesson",
      "shareable": "https://mycompany.lessonly.com/lesson/43530-untitled-lesson"
    },
    "public": false,
    "resource_type": "lesson",
    "retake_score": 90,
    "tags": [
      {
        "id": 1,
        "name": "test_tag",
        "resource_type": "tag"
      }
    ]
}

This endpoint allows the restoring of a single archived lesson.

HTTP Request

PUT https://api.lessonly.com/api/v1/lessons/:lesson_id/restore

Query Parameters

Parameter Required Type Description
lesson_id yes Positive Integer The lesson to restore. The company must have access to the lesson.

Lesson Assignments

curl https://api.lessonly.com/api/v1/lessons/:lesson_id/assignments \
-u "SUBDOMAIN:API_KEY"

The above command returns JSON structured like this:

{
  "type": "lesson_assignments",
  "total_assignments": 2000,
  "page": 1,
  "per_page": 2,
  "total_pages": 1000,
  "assignments":[
    {
      "id": 1,
      "resource_type": "assignment",
      "assignee_id": 1,
      "assignable_type": "Lesson",
      "assignable_id": 12,
      "ext_uid": "ABC123",
      "due_by": "2020-09-30T00:00:00Z",
      "assigned_at": "2020-03-20T00:00:00Z",
      "reassigned_at": "2020-09-30T00:00:00Z",
      "started_at": "2018-04-19T14:00:41Z",
      "completed_at": "2020-09-30T00:00:00Z",
      "updated_at": "2020-09-30T00:00:00Z",
      "status": "Completed",
      "score": 20
    },
    {
      "id": 2,
      "resource_type": "assignment",
      "assignee_id": 2,
      "assignable_type": "Lesson",
      "assignable_id": 15,
      "ext_uid": "DEF456",
      "due_by": "2020-09-30T00:00:00Z",
      "reassigned_at": "2020-09-30T00:00:00Z",
      "started_at": "2018-04-19T14:00:41Z",
      "completed_at": null,
      "updated_at": "2020-09-30T00:00:00Z",
      "status": "Incomplete",
      "score": null
    }
  ]
}

This endpoint retrieves all the assignments for a particular lesson.

HTTP Request

GET https://api.lessonly.com/api/v1/lessons/:lesson_id/assignments

Query Parameters

Parameter Required Type Description
lesson_id yes Positive Integer The lesson to access. The company must have access to the lesson.
page no Positive Integer Which page in the pagination to fetch. Default = 1
per_page no Positive Integer How many results to return in each page. Default = 50; Maximum = 1000. Numbers > 1000 are ignored and 1000 will be returned.

Lesson Completed Assignments (v1.1)

curl https://api.lessonly.com/api/v1.1/lessons/:lesson_id/assignments/completed \
-u "SUBDOMAIN:API_KEY"

The above command returns JSON structured like this:

{
  "type": "lesson_assignments_completed",
  "completed_count": 13
}

This endpoint retrieves the number of completed assignments for a given lesson.

HTTP Request

GET https://api.lessonly.com/api/v1.1/lessons/:lesson_id/assignments/completed

Lesson Total Completions (v1)

curl https://api.lessonly.com/api/v1/lessons/:lesson_id/total_completions \
-u "SUBDOMAIN:API_KEY"

The above command returns JSON structured like this:

{
  "type": "lesson_total_completion_count",
  "completion_count": 92
}

This endpoint retrieves the number of completions for a given lesson.

HTTP Request

GET https://api.lessonly.com/api/v1/lessons/:lesson_id/total_completions

Lesson Completion Breakdown (v1)

curl https://api.lessonly.com/api/v1/lessons/:lesson_id/completion_breakdown \
-u "SUBDOMAIN:API_KEY"

The above command returns JSON structured like this:

{
  "type": "lesson_completion_breakdown",
  "total": 92,
  "via_assignment": 45,
  "via_other": 47
}

This endpoint retrieves the completion breakdown for a given lesson.

HTTP Request

GET https://api.lessonly.com/api/v1/lessons/:lesson_id/completion_breakdown

Assign Lesson

curl -X PUT https://api.lessonly.com/api/v1/lessons/:lesson_id/assignments \
-H "Content-Type: application/json" \
-u "SUBDOMAIN:API_KEY" \
-d '{
  "assignments": [
    {
      "assignee_id": 1,
      "due_by": "2020-09-30T00:00:00Z",
      "notify": false
    }
  ]
}'

A successful update returns JSON formatted version of the assignments made

{
  "type": "update_lesson_assignments",
  "assignments": [
    {
      "id": 1,
      "resource_type": "assignment",
      "assignee_id": 1,
      "assignable_type": "Lesson",
      "assignable_id": 3,
      "ext_uid": "ABC123",
      "due_by": "2020-09-30T00:00:00Z",
      "reassigned_at": "2020-09-30T00:00:00Z",
      "completed_at": "2020-09-30T00:00:00Z",
      "updated_at": "2020-09-30T00:00:00Z",
      "status": "Incomplete",
      "score": null
    }
  ]
}

This endpoint allows you to make assignments to a particular lesson in the API.

HTTP Request

PUT https://api.lessonly.com/api/v1/lessons/:lesson_id/assignments -d params

Query Parameters

Parameter Required Type Description
lesson_id yes Positive Integer The lesson to access. The company must have access to the user.
assignments no Hash A hash of assignments to be made to the lesson. If the assignment for a particular user already exists, the user will be reassigned the lesson (only completed assignments will be reassigned). By default, an email will be sent to the assignee; it will come from notifications@lessonly.com. To suppress the email notification set notify to false.

Paths

List Paths

curl https://api.lessonly.com/api/v1/paths \
-u "SUBDOMAIN:API_KEY"

The above command returns JSON structured like this:

{
  "type": "paths",
  "paths": [
    {
      "id": 271,
      "title": "Sales Onboarding",
      "archived_at": "2018-02-28T08:53:40.614-05:00",
      "archived_by_user_id": 78,
      "is_certification": true
    },
    {
      "id": 33,
      "title": "Moderation Team Onboarding - August",
      "archived_at": "2017-08-18T15:26:12.786-04:00",
      "archived_by_user_id": 13018,
      "is_certification": false
    }
  ]
}

This endpoint retrieves all paths.

HTTP Request

GET https://api.lessonly.com/api/v1/paths

List Paths (v1.1)

curl https://api.lessonly.com/api/v1.1/paths \
-u "SUBDOMAIN:API_KEY"

The above command returns JSON structured like this:

{
  "type": "paths",
  "paths": [
    {
      "resource_type": "path",
      "id": 31,
      "title": "Competition",
      "archived_at": null,
      "archived_by_user_id": null,
      "public": true,
      "created_at": "2017-08-17T13:09:35Z",
      "last_updated_at": "2018-02-02T12:52:53Z",
      "published_at": "2017-08-17T18:54:22.870-04:00",
      "publisher_id": 668968,
      "tags": [
          {
              "id": 3,
              "resource_type": "tag",
              "name": "Sales"
          }
      ],
      "links": {
          "shareable": "https://dev.lessonly.com/path/31-competition",
          "overview": "https://dev.lessonly.com/paths/31-competition"
      },
      "is_certification": false
    }
  ]
}

This endpoint retrieves all paths

HTTP Request

GET https://api.lessonly.com/api/v1.1/paths

Show Path Details

curl https://api.lessonly.com/api/v1/paths/:path_id \
-u "SUBDOMAIN:API_KEY"

The above command returns JSON structured like this:

{
  "type": "path",
  "id": 1,
  "resource_type": "path",
  "title": "Developer Onboarding",
  "description": "All you need to know to get up-and-running.",
  "enforced_order": true,
  "public": false,
  "created_at": "2017-07-24T10:47:23Z",
  "last_updated_at": "2017-07-24T10:49:10Z",
  "published_at": null,
  "publisher_id": null,
  "tags": [
    {
      "id": 1,
      "resource_type": "tag",
      "name": "Engineering"
    }
  ],
  "links": {
    "shareable": "https://mycompany.lessonly.com/path/1-developer-onboarding",
    "overview": "https://mycompany.lessonly.com/paths/1-developer-onboarding"
  },
  "archived_at": null,
  "archived_by_user_id": null,
  "contents": [
    {
      "id": 10,
      "resource_type": "lesson",
      "title": "Setting up a development environment",
      "archived_at": null,
      "archived_by_user_id": null
    },
    {
      "id": 2,
      "resource_type": "wait_step",
      "effect": "locked",
      "condition": "prev_step_finished",
      "unit": "days",
      "amount": 3
    },
    {
      "id": 20,
      "resource_type": "path",
      "title": "Know Your Tools",
      "archived_at": null,
      "archived_by_user_id": null,
      "contents": [
        {
          "id": 4,
          "type": "lesson",
          "title": "Clubhouse 101",
          "archived_at": null,
          "archived_by_user_id": null
        },
        {
          "id": 5,
          "resource_type": "placeholder",
          "description": "Add a lesson about Github"
        }
      ]
    }
  ],
  "is_certification": false
}

This endpoint retrieves all the path’s details including their steps.

The "resource_type" of Paths’ "contents" will be one of "lesson", "wait_step", "path", or "placeholder".

Paths’ "contents" may be nested.

HTTP Request

GET https://api.lessonly.com/api/v1/paths/:path_id

Query Parameters

Parameter Required Type Description
path_id yes Positive Integer The path to access. The company must have access to the path.

Path Total Completions (v1)

curl https://api.lessonly.com/api/v1/paths/:path_id/total_completions \
-u "SUBDOMAIN:API_KEY"

The above command returns JSON structured like this:

{
  "type": "path_total_completion_count",
  "completion_count": 44
}

This endpoint retrieves the number of completions for a given path.

HTTP Request

GET https://api.lessonly.com/api/v1/paths/:path/total_completions

Archive Path

curl -X PUT https://api.lessonly.com/api/v1/paths/:path_id/archive \
-u "SUBDOMAIN:API_KEY"

The above command returns JSON structured like this:

{
  "type": "path",
  "id": 1,
  "resource_type": "path",
  "title": "Developer Onboarding",
  "description": "All you need to know to get up-and-running.",
  "enforced_order": true,
  "public": false,
  "created_at": "2017-07-24T10:47:23Z",
  "last_updated_at": "2017-07-24T10:49:10Z",
  "published_at": null,
  "publisher_id": null,
  "tags": [
    {
      "id": 1,
      "resource_type": "tag",
      "name": "Engineering"
    }
  ],
  "links": {
    "shareable": "https://mycompany.lessonly.com/path/1-developer-onboarding",
    "overview": "https://mycompany.lessonly.com/paths/1-developer-onboarding"
  },
  "archived_at": "2016-10-13T09:51:13.549-04:00",
  "archived_by_user_id": 1,
  "contents": [
    {
      "id": 10,
      "resource_type": "lesson",
      "title": "Setting up a development environment",
      "archived_at": null,
      "archived_by_user_id": null
    },
    {
      "id": 2,
      "resource_type": "wait_step",
      "effect": "locked",
      "condition": "prev_step_finished",
      "unit": "days",
      "amount": 3
    },
    {
      "id": 20,
      "resource_type": "path",
      "title": "Know Your Tools",
      "archived_at": null,
      "archived_by_user_id": null,
      "contents": [
        {
          "id": 4,
          "type": "lesson",
          "title": "Clubhouse 101",
          "archived_at": null,
          "archived_by_user_id": null
        },
        {
          "id": 5,
          "resource_type": "placeholder",
          "description": "Add a lesson about Github"
        }
      ]
    }
  ]
}

This endpoint allows the archiving of a single path.

HTTP Request

PUT https://api.lessonly.com/api/v1/paths/:path_id/archive

Query Parameters

Parameter Required Type Description
path_id yes Positive Integer The path to archive. The company must have access to the path.

Restore Path

curl -X PUT https://api.lessonly.com/api/v1/paths/:path_id/restore \
-u "SUBDOMAIN:API_KEY"

The above command returns JSON structured like this:

{
  "type": "path",
  "id": 1,
  "resource_type": "path",
  "title": "Developer Onboarding",
  "description": "All you need to know to get up-and-running.",
  "enforced_order": true,
  "public": false,
  "created_at": "2017-07-24T10:47:23Z",
  "last_updated_at": "2017-07-24T10:49:10Z",
  "published_at": null,
  "publisher_id": null,
  "tags": [
    {
      "id": 1,
      "resource_type": "tag",
      "name": "Engineering"
    }
  ],
  "links": {
    "shareable": "https://mycompany.lessonly.com/path/1-developer-onboarding",
    "overview": "https://mycompany.lessonly.com/paths/1-developer-onboarding"
  },
  "archived_at": null,
  "archived_by_user_id": null,
  "contents": [
    {
      "id": 10,
      "resource_type": "lesson",
      "title": "Setting up a development environment",
      "archived_at": null,
      "archived_by_user_id": null
    },
    {
      "id": 2,
      "resource_type": "wait_step",
      "effect": "locked",
      "condition": "prev_step_finished",
      "unit": "days",
      "amount": 3
    },
    {
      "id": 20,
      "resource_type": "path",
      "title": "Know Your Tools",
      "archived_at": null,
      "archived_by_user_id": null,
      "contents": [
        {
          "id": 4,
          "type": "lesson",
          "title": "Clubhouse 101",
          "archived_at": null,
          "archived_by_user_id": null
        },
        {
          "id": 5,
          "resource_type": "placeholder",
          "description": "Add a lesson about Github"
        }
      ]
    }
  ]
}

This endpoint allows the restoring of a single archived path.

HTTP Request

PUT https://api.lessonly.com/api/v1/paths/:path_id/restore

Query Parameters

Parameter Required Type Description
path_id yes Positive Integer The path to restore. The company must have access to the path.

Assigning a Path

curl -X PUT https://api.lessonly.com/api/v1/paths/:path_id/assignments \
-H "Content-Type: application/json" \
-u "SUBDOMAIN:API_KEY" \
-d '{
  "assignments": [
    {
      "assignee_id": 1,
      "due_by": "2020-09-30T00:00:00Z",
      "notify": false
    }
  ]
}'

A successful update returns a JSON formatted version of the assignments made:

{
  "type": "update_path_assignments",
  "assignments": [
    {
      "id": 1,
      "resource_type": "assignment",
      "assignee_id": 1,
      "assignable_type": "LearningPaths::Path",
      "assignable_id": 1,
      "ext_uid": "ABC123",
      "due_by": "2020-09-30T00:00:00Z",
      "reassigned_at": "2020-09-30T00:00:00Z",
      "completed_at": "2020-09-30T00:00:00Z",
      "status": "Incomplete",
      "score": null
    }
  ]
}

This endpoint allows you to make assignments to a particular path in the API.

HTTP Request

PUT https://api.lessonly.com/api/v1/paths/:path_id/assignments -d params

Query Parameters

Parameter Required Type Description
path_id yes Positive Integer The path to access. The company must have access to the path.
assignments no Hash A hash of assignments to be made to the path. If the assignment for a particular user already exists, the user will be reassigned the path (only completed assignments will be reassigned). By default, an email will be sent to the assignee; it will come from notifications@lessonly.com. To suppress the email notification set notify to false.

List Path Assignments

curl https://api.lessonly.com/api/v1/paths/:path_id/assignments \
-u "SUBDOMAIN:API_KEY"

The above command returns JSON structured like this:

{
  "type": "path_assignments",
  "total_assignments": 2,
  "page": 1,
  "per_page": 10,
  "total_pages": 1,
  "assignments":[
    {
      "id": 1,
      "resource_type": "assignment",
      "assignee_id": 2,
      "assignable_type": "LearningPaths::Path",
      "assignable_id": 1,
      "score": 80,
      "ext_uid": "ABC123",
      "due_by": "2020-09-30T00:00:00Z",
      "assigned_at": "2020-03-20T00:00:00Z",
      "reassigned_at": "2020-09-30T00:00:00Z",
      "status": "Completed",
      "started_at": "2016-03-28T14:15:17Z",
      "completed_at": "2016-03-28T18:20:06Z",
      "updated_at": "2016-03-28T18:20:06Z"
    },
    {
      "id": 2,
      "resource_type": "assignment",
      "assignee_id": 3,
      "assignable_type": "LearningPaths::Path",
      "assignable_id": 1,
      "score": null,
      "ext_uid": "DEF456",
      "due_by": "2020-09-30T00:00:00Z",
      "reassigned_at": "2020-09-30T00:00:00Z",
      "status": "Incomplete",
      "started_at": "2016-03-28T14:15:17Z",
      "completed_at": null,
      "updated_at": "2016-03-28T18:20:06Z"
    }
  ]
}

This endpoint retrieves all the assignments for a particular path.

HTTP Request

GET https://api.lessonly.com/api/v1/paths/:path_id/assignments

Query Parameters

Parameter Required Type Description
path_id yes Positive Integer The path to access. The company must have access to the path.
page no Positive Integer Which page in the pagination to fetch. Default = 1
per_page no Positive Integer How many results to return in each page. Default = 50; Maximum = 1000. Numbers > 1000 are ignored and 1000 will be returned.

Path Assignments Completed

curl https://api.lessonly.com/api/v1/paths/:path_id/assignments/completed \
-u "SUBDOMAIN:API_KEY"

The above command returns JSON structured like this:

{
  "type": "path_assignments_completed",
  "completed_count": 11
}

This endpoint retrieves the count of completed assignments for a particular path.

HTTP Request

GET https://api.lessonly.com/api/v1/paths/:path_id/assignments/completed

Query Parameters

Parameter Required Type Description
path_id yes Positive Integer The path to access. The company must have access to the path.

Tags

List Tags

curl https://api.lessonly.com/api/v1/tags \
-u "SUBDOMAIN:API_KEY"

The above command returns JSON structured like this:

{
  "type": "tags",
  "tags": [
    {
      "id": 1,
      "resource_type": "tag",
      "name": "Marketing"
    },
    {
      "id": 2,
      "resource_type": "tag",
      "name": "Development"
    }
  ]
}

This endpoint retrieves all tags.

HTTP Request

GET https://api.lessonly.com/api/v1/tags

Show Tag Details

curl https://api.lessonly.com/api/v1/tags/:tag_id \
-u "SUBDOMAIN:API_KEY"

The above command returns JSON structured like this:

{
  "type": "tag",
  "resource_type": "tag",
  "id": 1,
  "name": "Marketing"
}

This endpoint retrieves all the tag details.

HTTP Request

GET https://api.lessonly.com/api/v1/tags/:tag_id

Query Parameters

Parameter Required Type Description
tag_id yes Positive Integer The tag to access. The company must have access to the tag.

Tag Lessons

curl https://api.lessonly.com/api/v1/tags/:tag_id/lessons \
-u "SUBDOMAIN:API_KEY"

The above command returns JSON structured like this:

{
  "type": "tag_lessons",
  "lessons": [
    {
      "id": 19458,
      "resource_type": "lesson",
      "title": "Industry Update 10/16/15",
      "assignees_count": 1,
      "completed_count": 0,
      "retake_score": 80,
      "description": "A quick overview about how we do marketing.",
      "public": true,
      "created_at": "2015-10-15T23:22:31Z",
      "last_updated_at": null,
      "archived_at": "2016-09-07T12:19:55.453-04:00",
      "archived_by_user_id": 651540,
      "tags": [
        {
            "id": 18448,
            "resource_type": "tag",
            "name": "Archive"
        }
      ],
      "links": {
        "shareable": "https://adidas.lessonly.com/lesson/19458-industry-update-10-16-15",
        "overview": "https://adidas.lessonly.com/lessons/19458-industry-update-10-16-15"
      }
    }
  ]
}

This endpoint retrieves all the lessons tagged with a particular tag.

HTTP Request

GET https://api.lessonly.com/api/v1/tags/:tag_id/lessons

Query Parameters

Parameter Required Type Description
tag_id yes Positive Integer The tag to access. The company must have access to the tag.

Tag Paths

curl https://api.lessonly.com/api/v1/tags/:tag_id/paths \
-u "SUBDOMAIN:API_KEY"

The above command returns JSON structured like this:

{
  "type": "tag_paths",
  "paths": [
    {
      "id": 123,
      "resource_type": "path",
      "title": "Onboarding Path",
      "description": "This Path will get you up to speed in our company.",
      "enforced_order": true,
      "public": false,
      "created_at": "2017-11-16T14:57:41Z",
      "last_updated_at": null,
      "published_at": "2017-11-16T14:57:42.351-05:00",
      "publisher_id": 1,
      "tags": [
        {
          "id": 1,
          "resource_type": "tag",
          "name": "First Tag"
        },
        {
          "id": 2,
          "resource_type": "tag",
          "name": "Second tag"
        }
      ],
      "links": {
        "shareable": "http://dev123.lessonly.dev/path/9999-onboarding-test",
        "overview": "http://dev123.lessonly.dev/paths/9999-onboarding-test"
      },
      "archived_at": null,
      "archived_by_user_id": null,
      "contents": [
        {
          "id": 1339,
          "resource_type": "lesson",
          "title": "Your first day",
          "archived_at": null,
          "archived_by_user_id": null
        },
        {
          "id": 8,
          "resource_type": "wait_step",
          "effect": "locked",
          "condition": "prev_step_finished",
          "unit": "days",
          "amount": 1
        },
        {
          "id": 1339,
          "resource_type": "lesson",
          "title": "Getting started",
          "archived_at": null,
          "archived_by_user_id": null
        }
      ]
    }
  ]
}

This endpoint retrieves all the paths tagged with a particular tag.

HTTP Request

GET https://api.lessonly.com/api/v1/tags/:tag_id/paths

Query Parameters

Parameter Required Type Description
tag_id yes Positive Integer The tag to access. The company must have access to the tag.

Assignments

List Assignments

curl https://api.lessonly.com/api/v1/assignments \
-u "SUBDOMAIN:API_KEY"

The above command returns JSON structured like this:

{
  "type": "assignments",
  "total_assignments": 2000,
  "page": 1,
  "per_page": 2,
  "total_pages": 1000,
  "assignments":[
    {
      "id": 1,
      "resource_type": "assignment",
      "assignee_id": 1,
      "score": 90,
      "assignable_type": "Lesson",
      "assignable_id": 1,
      "ext_uid": "ABC123",
      "due_by": "2020-09-30T00:00:00Z",
      "assigned_at": "2020-03-20T00:00:00Z",
      "reassigned_at": "2020-09-30T00:00:00Z",
      "status": "Completed",
      "started_at": "2016-03-28T14:15:17Z",
      "completed_at": "2016-03-28T18:20:06Z",
      "updated_at": "2016-03-28T18:20:06Z"
    },
    {
      "id": 2,
      "resource_type": "assignment",
      "assignee_id": 2,
      "score": null,
      "assignable_type": "LearningPaths::Path",
      "assignable_id": 1,
      "ext_uid": "DEF456",
      "assigned_at": "2016-02-22T17:35:17Z",
      "due_by": "2020-09-30T00:00:00Z",
      "reassigned_at": "2020-09-30T00:00:00Z",
      "status": "Incomplete",
      "started_at": "2016-03-28T14:15:17Z",
      "completed_at": null,
      "updated_at": "2016-03-28T18:20:06Z"
    },
    {
      "id": 3,
      "resource_type": "assignment",
      "assignee_id": 3,
      "score": null,
      "assignable_type": "LearningPaths::Path",
      "assignable_id": 1,
      "ext_uid": "DEF456",
      "assigned_at": "2016-02-22T17:35:17Z",
      "due_by": "2016-03-27T14:15:17Z",
      "reassigned_at": "2020-09-30T00:00:00Z",
      "status": "Overdue",
      "started_at": "2016-03-28T14:15:17Z",
      "completed_at": null,
      "updated_at": "2016-03-28T18:20:06Z"
    },
    {
      "id": 4,
      "resource_type": "assignment",
      "assignee_id": 4,
      "score": null,
      "assignable_type": "LearningPaths::Path",
      "assignable_id": 1,
      "ext_uid": "DEF456",
      "assigned_at": "2016-02-22T17:35:17Z",
      "due_by": "2020-09-30T00:00:00Z",
      "reassigned_at": "2020-09-30T00:00:00Z",
      "status": "Grade Pending",
      "started_at": "2016-03-28T14:15:17Z",
      "completed_at": null,
      "updated_at": "2016-03-28T18:20:06Z"
    }
  ]
}

This endpoint returns paginated assignments in no particular order across all of your users, lessons, and paths. Optionally, you can filter by assignments with activity after a given ISO8601 timestamp by passing gt[updated_at]=TIMESTAMP in the query string.

To view assignments for a particular user, lesson, or path please use those dedicated endpoints.

HTTP Request

GET https://api.lessonly.com/api/v1/assignments

Query Parameters

Parameter Required Type Description
page no Positive Integer Which page in the pagination to fetch. Default = 1
per_page no Positive Integer How many results to return in each page. Default = 50; Maximum = 1000. Numbers > 1000 are ignored and 1000 will be returned.
gt no String Specified greater than filter for assignments list. Supported filters are (updated_at). Please follow ISO8601 date format.

List Assignments (v1.1)

curl https://api.lessonly.com/api/v1.1/assignments \
-u "SUBDOMAIN:API_KEY"

The above command returns JSON structured like this:

{
  "type": "assignments",
  "total_assignments": 2000,
  "page": 1,
  "per_page": 2,
  "total_pages": 1000,
  "assignments":[
    {
      "id": 1,
      "resource_type": "assignment",
      "assignee_id": 1,
      "assignable_type": "Lesson",
      "assignable_id": 1,
      "ext_uid": "ABC123",
      "assigned_at": "2016-02-22T17:35:17Z",
      "due_by": "2020-09-30T00:00:00Z",
      "reassigned_at": "2016-03-22T17:35:17Z",
      "status": "Completed",
      "started_at": "2016-03-28T14:15:17Z",
      "completed_at": "2016-03-28T18:20:06Z",
      "score": 100
      "updated_at": "2016-03-28T18:20:06Z"
    },
    {
      "id": 2,
      "resource_type": "assignment",
      "assignee_id": 2,
      "assignable_type": "LearningPaths::Path",
      "assignable_id": 1,
      "ext_uid": "DEF456",
      "assigned_at": "2016-02-22T17:35:17Z",
      "due_by": "2020-09-30T00:00:00Z",
      "reassigned_at": "2016-03-28T10:25:17Z",
      "status": "Incomplete",
      "started_at": "2016-03-28T14:15:17Z",
      "completed_at": null,
      "score" : 50,
      "updated_at": "2016-03-28T18:20:06Z",
      "contents": [
        {
          "id": 2,
          "resource_type": "lesson",
          "started_at": null,
          "completed_at": null,
          "score": 100,
          "status": "Incomplete"
        },
        {
          "id": 4,
          "resource_type": "path",
          "contents": [
            {
              "id": 3,
              "resource_type": "lesson",
              "started_at": "2019-01-18T09:48:10Z",
              "completed_at": "2019-01-18T14:43:33Z",
              "score": 0,
              "status": "Completed"
            },
            {
              "id": 5,
              "resource_type": "path",
              "contents": [
                {
                  "id": 4,
                  "resource_type": "lesson",
                  "started_at": "2019-01-18T09:48:10Z",
                  "completed_at": "2019-01-18T14:43:33Z",
                  "score": null,
                  "status": "Completed"
                }
              ]
            }
          ]
        }
      ],
      "is_certification": false
    },
    {
      "id": 3,
      "resource_type": "assignment",
      "assignee_id": 3,
      "assignable_type": "LearningPaths::Path",
      "assignable_id": 1,
      "ext_uid": "DEF456",
      "assigned_at": "2016-02-22T17:35:17Z",
      "due_by": "2016-03-27T14:15:17Z",
      "reassigned_at": "2016-03-20T14:15:17Z",
      "status": "Completed",
      "started_at": "2016-03-28T14:15:17Z",
      "completed_at": "2016-03-30T18:20:06Z",
      "updated_at": "2016-03-28T18:20:06Z",
      "contents": [
        {
          "id": 2,
          "resource_type": "lesson",
          "started_at": "2016-03-28T14:15:17Z",
          "completed_at": "2016-03-30T18:20:06Z",
          "status": "Completed"
        },
      ],
      "is_certification": true,
    },
    {
      "id": 4,
      "resource_type": "assignment",
      "assignee_id": 3,
      "assignable_type": "Lesson",
      "assignable_id": 1,
      "ext_uid": "DEF456",
      "assigned_at": "2016-02-22T17:35:17Z",
      "due_by": "2016-03-27T14:15:17Z",
      "reassigned_at": null,
      "status": "Overdue",
      "started_at": "2016-03-28T14:15:17Z",
      "completed_at": null,
      "updated_at": "2016-03-28T18:20:06Z"
    },
    {
      "id": 5,
      "resource_type": "assignment",
      "assignee_id": 4,
      "assignable_type": "LearningPaths::Path",
      "assignable_id": 1,
      "ext_uid": "DEF456",
      "assigned_at": "2016-02-22T17:35:17Z",
      "due_by": "2016-03-27T14:15:17Z",
      "reassigned_at": "2016-03-23T16:43:17Z",
      "status": "Grade Pending",
      "started_at": "2016-03-28T14:15:17Z",
      "completed_at": "2016-03-30T18:20:06Z",
      "updated_at": "2016-03-28T18:20:06Z",
      "contents": [
        {
          "id": 2,
          "resource_type": "lesson",
          "started_at": "2016-03-28T14:15:17Z",
          "completed_at": null,
          "status": "Incomplete"
        },
      ],
      "is_certification": false,
    }
  ]
}

This endpoint returns paginated assignments in no particular order across all of your users, lessons, and paths. Optionally, you can filter by assignments with activity after a given ISO8601 timestamp by passing gt[updated_at]=TIMESTAMP in the query string.

Path assignments show completion status (Completed/Incomplete) for lessons in the path.

To view assignments for a particular user, lesson, or path please use those dedicated endpoints.

HTTP Request

GET https://api.lessonly.com/api/v1.1/assignments

Query Parameters

Parameter Required Type Description
page no Positive Integer Which page in the pagination to fetch. Default = 1
per_page no Positive Integer How many results to return in each page. Default = 50; Maximum = 1000. Numbers > 1000 are ignored and 1000 will be returned.
gt no String Specified greater than filter for assignments list. Supported filters are (updated_at). Please follow ISO8601 date format.
filter no String Specified assignment filter for assignments list. Supported filters are (group_id) which filters the list of assignments to only assignments for users who are currently members of the specified group.

Show Assignments by Status

curl https://api.lessonly.com/api/v1/assignments/:status \
-u "SUBDOMAIN:API_KEY"

The above command returns JSON structured like this:

{
  "type": "assignments",
  "total_assignments": 2000,
  "page": 1,
  "per_page": 2,
  "total_pages": 1000,
  "assignments": [
    {
      "id": 5566,
      "resource_type": "assignment",
      "assignee_id": 1735,
      "assignable_type": "Lesson",
      "assignable_id": 855,
      "ext_uid": "3175551234",
      "assigned_at": "2014-01-20T20:07:07Z",
      "due_by": "2014-05-13T04:00:00Z",
      "reassigned_at": "2014-05-07T18:33:46Z",
      "status": "Completed",
      "updated_at": "2015-10-08T19:58:28Z",
      "score": 100,
      "started_at": "2014-08-04T14:31:42Z",
      "completed_at": "2014-08-04T14:36:16Z"
    },
    {
      "id": 6876654,
      "resource_type": "assignment",
      "assignee_id": 3120575,
      "assignable_type": "LearningPaths::Path",
      "assignable_id": 19433,
      "ext_uid": null,
      "assigned_at": "2018-12-12T13:02:21Z",
      "due_by": null,
      "reassigned_at": null,
      "status": "Incomplete",
      "updated_at": "2018-12-13T18:35:40Z",
      "score": null,
      "started_at": "2018-12-13T18:35:40Z",
      "completed_at": null
    }
  ]
}

This endpoint retrieves all assignments by their status.

HTTP Request

GET https://api.lessonly.com/api/v1/assignments/:status

Query Parameters

Parameter Required Type Description
status yes String An assignment status. Supported statues are: incomplete, completed, overdue, or grade_pending
page no Positive Integer Which page in the pagination to fetch. Default = 1
per_page no Positive Integer How many results to return in each page. Default = 50; Maximum = 1000. Numbers > 1000 are ignored and 1000 will be returned.

Company Settings

Update Webhook URL

curl -X PUT https://api.lessonly.com/api/v1/company_settings \
-H "Content-Type: application/json" \
-u "SUBDOMAIN:API_KEY" \
-d '{
  "lesson_completed_callback_url": "https://webhook.mycompany.com",
  "lesson_completed_callback_authorization": "Tm93IGlzIHRo"
}'

A successful update returns a JSON representation of the updated webhook configuration:

{
  "lesson_completed_callback_url": "https://webhook.mycompany.com",
  "lesson_completed_callback_authorization": "Tm93IGlzIHRo"
}

This endpoint allows you to update the recipient URL for webhooks sent upon Lesson completion. See the docs for more information on webhooks.

HTTP Request

PUT https://api.lessonly.com/api/v1/company_settings

Query Parameters

Parameter Required Type Description
lesson_completed_callback_url no String the URL to which webhooks should be sent
lesson_completed_callback_authorization no String the optional value of an Authorization: VALUE header to be sent with webhooks

Rate Limiting

Lessonly currently limits the rate of requests made to the API. At the limit of 500 requests per minute the API will return “403 Forbidden (Rate Limit Exceeded)”. To avoid hitting this rate limit, you can adjust your scripts and workflows to add pauses in between subsequent API requests.

Errors

The Lessonly API uses the following error codes:

Error Code Meaning
400 Malformed Request – Verify that the parameters required are being passed in and all parameters have the format specified in the documentation.
401 Unauthorized – Verify that you have passed your company’s subdomain and API key correctly.
403 Forbidden – The endpoint that you have tried to access you do not have privileges to.
404 Not Found – The resource in the endpoint could not be found. Verify the resource id.
405 Method Not Allowed – You tried to access an endpoint with an invalid method
406 Not Acceptable – You requested a format that isn’t json
500 Internal Server Error – We had a problem with our server. Try again later.
503 Service Unavailable – We’re temporarially offline for maintanance. Please try again later.
shell