Lessonly User Management API Guide

Auth method: API Key (HTTP Basic Auth: subdomain as username, API key as password, Base64-encoded)

Setup steps

1. Log in to Lessonly as an admin and navigate to Settings > Integrations > API.
2. Copy your company subdomain and generate or retrieve your API key.
3. Encode 'subdomain:api_key' in Base64.
4. Pass the encoded value in the Authorization header: 'Authorization: Basic '.

List Users

• Method: GET
• URL: https://api.lessonly.com/api/v1/users
• Watch out for: Returns up to 50 users per page. Iterate 'page' param until response returns fewer than 50 records.

Request example

GET /api/v1/users?page=1
Authorization: Basic <base64>

Response example

{
  "type": "users",
  "users": [
    {"id": 101, "name": "Jane Doe", "email": "jane@example.com", "role": "learner"}
  ]
}

Show User

• Method: GET
• URL: https://api.lessonly.com/api/v1/users/{user_id}
• Watch out for: Use the integer Lessonly user ID, not email.

Request example

GET /api/v1/users/101
Authorization: Basic <base64>

Response example

{
  "type": "user",
  "id": 101,
  "name": "Jane Doe",
  "email": "jane@example.com",
  "role": "learner",
  "group_ids": [5, 12]
}

Create User

• Method: POST
• URL: https://api.lessonly.com/api/v1/users
• Watch out for: Email must be unique. Duplicate email returns an error, not a silent upsert.

Request example

POST /api/v1/users
Content-Type: application/json
{
  "name": "John Smith",
  "email": "john@example.com",
  "role": "learner"
}

Response example

{
  "type": "user",
  "id": 202,
  "name": "John Smith",
  "email": "john@example.com",
  "role": "learner"
}

Update User

• Method: PUT
• URL: https://api.lessonly.com/api/v1/users/{user_id}
• Watch out for: Sending 'group_ids' replaces all existing group memberships; omit the field to leave groups unchanged.

Request example

PUT /api/v1/users/202
Content-Type: application/json
{
  "role": "manager",
  "group_ids": [5]
}

Response example

{
  "type": "user",
  "id": 202,
  "role": "manager",
  "group_ids": [5]
}

Archive User

• Method: PUT
• URL: https://api.lessonly.com/api/v1/users/{user_id}/archive
• Watch out for: Archiving is not the same as deletion. Archived users retain historical completion data but cannot log in.

Request example

PUT /api/v1/users/202/archive
Authorization: Basic <base64>

Response example

{
  "type": "user",
  "id": 202,
  "archived_at": "2024-06-01T12:00:00Z"
}

Restore User

• Method: PUT
• URL: https://api.lessonly.com/api/v1/users/{user_id}/restore
• Watch out for: Restoring a user reactivates their account but does not re-enroll them in previously assigned content.

Request example

PUT /api/v1/users/202/restore
Authorization: Basic <base64>

Response example

{
  "type": "user",
  "id": 202,
  "archived_at": null
}

List Groups

• Method: GET
• URL: https://api.lessonly.com/api/v1/groups
• Watch out for: Group IDs are required when assigning users to groups via the user create/update endpoints.

Request example

GET /api/v1/groups
Authorization: Basic <base64>

Response example

{
  "type": "groups",
  "groups": [
    {"id": 5, "name": "Sales Team"}
  ]
}

Show User Assignments

• Method: GET
• URL: https://api.lessonly.com/api/v1/users/{user_id}/assignments
• Watch out for: Returns all assignments regardless of status; filter client-side by 'status' field.

Request example

GET /api/v1/users/101/assignments
Authorization: Basic <base64>

Response example

{
  "type": "assignments",
  "assignments": [
    {"id": 9, "assignable_type": "Lesson", "status": "completed"}
  ]
}

• Rate limits: Lessonly's public API documentation does not publish explicit rate limit numbers. Practical guidance from the developer docs suggests avoiding burst requests.

• Rate-limit headers: Unknown

• Retry-After header: Unknown

• Rate-limit notes: No officially documented rate limit tiers or headers found. Treat as unknown; implement exponential backoff on 429 responses.

• Pagination method: offset

• Default page size: 50

• Max page size: 50

• Pagination pointer: page

• Webhooks available: No

• Webhook notes: No webhook functionality is documented in Lessonly's official API or help center documentation as of the research date.

• Alternative event strategy: Poll the REST API (e.g., GET /users, GET /users/{id}/assignments) on a scheduled basis to detect changes.

• SCIM available: Yes

• SCIM version: 2.0

• Plan required: Enterprise

• Endpoint: https://{subdomain}.lessonly.com/scim/v2

• Supported operations: Create User (POST /Users), Update User (PUT /Users/{id}), Deactivate User (PATCH /Users/{id} with active=false), List Users (GET /Users), Get User (GET /Users/{id})

Limitations:

• SSO (SAML) must be configured before SCIM provisioning can be enabled.
• Azure AD / Microsoft Entra SCIM is not officially supported; only Okta and OneLogin are documented.
• Group push support varies by IdP configuration; verify in IdP integration settings.
• SCIM is gated to the Enterprise plan only.

For provisioning into an identity graph, the recommended flow is: resolve the target group ID via GET /api/v1/groups, then POST /api/v1/users with name, email, role, and group_ids.

Store the returned integer id - all subsequent operations (update, archive, assignment lookup) require this Lessonly-native ID, not email. Email must be unique; a duplicate email returns an error, not a silent upsert, so pre-check with GET /api/v1/users and filter client-side before creating.

For offboarding, PUT /api/v1/users/{user_id}/archive is the correct action - there is no DELETE endpoint. Archiving sets archived_at and blocks login but preserves all completion history. When updating group membership, group_ids in a PUT /api/v1/users/{user_id} call is a full replacement: omit the field entirely if group membership should remain unchanged, or you will silently remove existing memberships.

For SCIM-based provisioning via Okta, SAML SSO must be fully configured in Lessonly before SCIM can be enabled - the dependency is hard. The SCIM base URL is https://{subdomain}.lessonly.com/scim/v2. Azure AD / Microsoft Entra SCIM is not officially supported; provisioning failures in that configuration are outside Lessonly support scope.

Provision a new employee and assign to a group

1. GET /api/v1/groups to retrieve the target group ID.
2. POST /api/v1/users with 'name', 'email', 'role', and 'group_ids' containing the retrieved group ID.
3. Store the returned 'id' in your system for future updates.

Watch out for: If the email already exists, the API returns an error. Check for existing users with GET /api/v1/users and filter by email before creating.

Offboard a departing employee

1. Identify the user's Lessonly ID via GET /api/v1/users (filter by email client-side).
2. PUT /api/v1/users/{user_id}/archive to deactivate the account.
3. Optionally verify the 'archived_at' field is populated in the response.

Watch out for: Archiving preserves completion history. There is no hard-delete endpoint; archived users remain in the system.

Automated SCIM provisioning via Okta

1. Confirm the Lessonly account is on the Enterprise plan.
2. Configure SAML SSO in Lessonly Settings > Integrations > SSO before enabling SCIM.
3. In Okta, add the Lessonly application from the OIN and enable SCIM provisioning.
4. Enter the SCIM base URL (https://{subdomain}.lessonly.com/scim/v2) and the SCIM API token from Lessonly admin settings.
5. Map Okta profile attributes to Lessonly SCIM attributes and enable Create, Update, and Deactivate operations.
6. Test with a single user assignment before enabling group push.

Watch out for: Azure AD SCIM is not officially supported. Attempting to configure it may result in provisioning failures not covered by Lessonly support.

The most common integration trap is treating group_ids as an additive patch - it is not. A PUT to update any user field while including group_ids will replace all existing group memberships with exactly the array provided.

Pipelines that update user attributes without explicitly carrying forward current group state will silently strip group assignments, breaking content delivery without any error signal.

The second trap is the SCIM/manual deactivation conflict: archiving a user via the API or admin UI while the IdP still marks them active will result in re-provisioning on the next SCIM sync cycle.

Any offboarding automation must disable the user in the IdP first, then allow SCIM to propagate the deactivation - not the reverse.

Custom user fields are a third failure point: fields must be created in the Lessonly admin UI before they can be written via custom_user_field_data in the API; attempting to set an undeclared field does not return a validation error in all documented cases.