Skip to main content

LMS Integration - Automation via API

  • Updated

This article explains how to automate, via API, the two operations required by the LMS Integration: linking SMARTFENSE users to their LMS user, and retrieving the SCORM package for a campaign.

What can be automated

Setting up the integration involves two operations, and each one can be done from the platform or via API. Both paths coexist: the API is an additional channel, not a replacement.

  • User linking: from the platform, a CSV file is uploaded; via API, users are sent with their LMS ID.
  • SCORM package: from the platform, it is downloaded with the button in the Calendar; via API, it is requested and the platform returns a download link.

Automating these operations is useful when the organization onboards users frequently, or manages several pieces of content and does not want to manually download and upload each package.

If you are looking for the manual steps, see LMS Integration - User Linking and LMS Integration - Campaign Configuration.

Before you start

Both operations require your organization to have the LMS Integration component contracted, and the instance to be active and in good standing.

You also need an application registered under Settings > Integrations > API. The full registration procedure is in API Integration in SMARTFENSE.

When registering the application, select only the scopes you are going to use:

  • Link users with an external LMS, for linking.
  • Download LMS integration SCORM package, for the package.

These scopes are separated on purpose: an integration that only uploads users does not need to be able to download content, and one that only downloads packages does not need to be able to modify the user roster.

Linking users with the LMS

Sets or updates the ID each user has in the external LMS, identifying the user by their email address in SMARTFENSE.

 
POST /api/v1/users/lms-id

The request body carries the list of users to link:

 
json
{
  "users": [
    { "email": "ana.perez@ejemplo.com", "lms_id": "aperez" },
    { "email": "juan.gomez@ejemplo.com", "lms_id": "jgomez" }
  ]
}

Request rules

  • Up to 200 users per request are accepted.
  • The LMS ID allows up to 250 characters. Sending it empty unlinks the user.
  • The LMS ID cannot start with the characters =, +, @, comma, semicolon or hyphen, nor contain < or >. The platform rejects those values instead of altering them, because altering them would break the correspondence with the LMS.
  • If the same request repeats an email or an LMS ID, all repeated occurrences are rejected, not just the second one.

Response

Users are processed independently: one that fails does not roll back the ones already applied, just like in the CSV import. The response separates the two groups:

 
json
{
  "processed": [
    { "email": "ana.perez@ejemplo.com", "lms_id": "aperez" }
  ],
  "errors": [
    { "email": "no.existe@ejemplo.com", "error_code": "...", "error": "..." }
  ],
  "details": { "total_processed": 1, "total_errors": 1 }
}

Each item in errors states the reason: either the email does not match any user in the organization, or the email or ID was repeated in the request.

The operation is logged in the administration audit trail, with the total number of users updated and the per-user detail.

Retrieving the SCORM package for a campaign

Returns the same package produced by the download button in the Calendar, so it can be loaded into the LMS without manual steps.

 
GET /api/v1/campaigns/{tipo_de_campaña}/{id_de_campaña}/scorm-package

The valid campaign types are training (Interactive Modules), video, videogame and exam.

The campaign must be configured with the Integrar esta campaña con un LMS option. If it is not, the response is the same as if the campaign did not exist.

Response

 
json
{
  "file_url": "https://...",
  "file_name": "lms-integration-....zip",
  "expires_in": 14400
}

The download link is temporary: expires_in reports, in seconds, how long it remains valid. Download the file within that window; once it expires, you need to request the package again.

💡 Best practices

  • Verify that users exist on both platforms before linking them: the API resolves the user by their email and returns an error if it cannot find one.
  • Send users in batches of up to 200 and review the errors block of each response before considering the upload complete.
  • Use the identifier your LMS requires. In Moodle, for example, this corresponds to the user's username field.
  • Request the SCORM package at the time you are going to load it into the LMS, not in advance, since the link expires.
  • Register one application per integration, with the minimum scopes that integration needs.

Related articles