Sending course completions to external systems

Activate LMS can automatically send data to external systems — typically your HR system, training system, or data warehouse — when a user completes a course. This is called outbound sync. The LMS can also receive data (for example new users) from external systems via webhooks, but this article focuses on outbound sync, which is by far the most common use case.

Integrations are created and configured by an LMS administrator through the admin UI. IT's role is typically to:

• Provide the receiving endpoint (URL and authentication)
• Confirm which data and fields should be sent
• Verify that the connection works and report any payload-format issues
• Configure firewall or IP whitelisting if your system has IP restrictions

How it works

1. A user completes a course in the LMS.
2. The LMS background service runs on the configured schedule (e.g. daily at 02:00) and looks for new completions that have not yet been sent.
3. For each new completion, the LMS builds a JSON payload based on the configured field mapping.
4. The payload is sent via HTTPS POST to your endpoint, using the configured authentication.
5. Your endpoint responds with an HTTP status code. 2xx = success; 4xx/5xx = failure.
6. Failed requests are recorded in the LMS sync log and retried later using exponential backoff (typically 1 min, 5 min, 30 min — up to 3 attempts).
7. If an integration fails 10 times in a row without any success, it is automatically disabled and a notification is sent.

What IT needs to provide

For the LMS administrator to configure an outbound integration, you need to provide:

Item	Description
Endpoint URL	The full HTTPS URL the LMS should POST data to, e.g. https://hr-system.company.com/api/completions.
Authentication	How the LMS should authenticate itself. See Authentication types below.
Expected payload format	Which fields should be in the JSON, with their names, types, and which are required. See Payload and field mapping below.
Success status code	Usually 200 or 201. Other 2xx codes are also accepted as success.
IP whitelist / firewall	If your endpoint sits behind a firewall, request the current list of Activate LMS outbound IPs from support.
Test endpoint (optional)	A separate test URL so the setup can be verified without writing to production.

Authentication types

Activate LMS supports the following authentication types for outbound integrations:

API key in header

The LMS sends a static API key in a configured HTTP header. This is the simplest and most common authentication type.

• Header name: any name — typically X-API-Key, Authorization, or apikey.
• The API key: a long, random string you generate in your own system and provide to the LMS administrator.
• Security: the API key is stored encrypted in the LMS database and is never displayed in plaintext after entry.

Bearer token (static)

The LMS sends a static bearer token in the Authorization: Bearer <token> header. Typically used by systems with long-lived access tokens.

Bearer login (dynamic token)

The LMS first signs in to a login endpoint with username and password, receives a JWT access token, and then uses that token in the Authorization header on the actual sync calls. The token is cached and refreshed automatically when it expires.

• Login URL: the full URL of your login endpoint, e.g. https://api.company.com/auth/login.
• Username: the service account's username.
• Password: the service account's password (stored encrypted).
• Expected response: JSON with an access_token field — either a string, or an object such as { "token": "...", "expires_in_seconds": 600 }.

Basic authentication

The LMS sends username and password Base64-encoded in the Authorization: Basic header. Only recommended for older systems — Bearer-based auth is generally more secure.

OAuth2 client credentials

The LMS retrieves an access token from an OAuth2 token endpoint using the client-credentials grant flow and uses it on the sync calls.

• Token URL: OAuth2 token endpoint.
• Client ID: OAuth2 client ID.
• Client Secret: OAuth2 client secret (stored encrypted).
• Scope: optional — any scopes that should be requested.

Client certificate (mTLS)

The LMS presents a client certificate during the TLS handshake (mutual TLS). Used by systems with strict security requirements, e.g. Mindkey HR.

Client certificates require the certificate to be installed in the Azure App Service certificate store on the Activate LMS server. Contact Activate LMS support to have your certificate installed. You need to provide the certificate (.pfx or .cer) and any password protection.

No authentication

For test scenarios only — not for production. The endpoint is open on the public internet and accepts all requests.

Payload and field mapping

The LMS administrator can configure exactly which fields are sent to your endpoint and what they should be called. This is done in a visual Payload Mapping editor in the admin UI.

Available LMS fields

LMS field	Description	Type
user.email	The user's email address	string
user.userName	Username (login)	string
user.firstName	First name	string
user.lastName	Last name	string
user.organisation	The name of the user's organisation / department	string
user.organisationId	Numeric ID of the organisation in the LMS	number
user.learningProfiles	Comma-separated list of the user's learning profiles	string
activity.activityName	The name of the completed course	string
activity.activityId	The LMS's internal ID for the course	number
completion.completionDate	Time of completion (UTC)	datetime
completion.bestCombined	Completion status (0–100)	number
completion.bestScore	Score, if the course has scoring (0–100)	number

Transforms

Each field can be transformed before it is sent. The following transforms are available:

Transform	Description	Example
dateFormat	Convert a date to a different format	dateFormat:yyyy-MM-dd or dateFormat:epoch for a Unix timestamp
statusMap	Map a numeric status to a text value	statusMap:100=passed,0=failed
concat	Combine the value with a static prefix	concat:PREFIX-{value}
omitIfNull	Omit the field entirely if the value is null	omitIfNull
toString	Force the value to a string	toString
toInt	Force the value to an integer	toInt

Multiple transforms can be chained with the pipe character. Example: dateFormat:yyyy-MM-dd | toString.

Example payload

With a standard mapping, a typical JSON payload looks like this:

{
  "employeeId": "anne@company.com",
  "courseName": "GDPR introduction",
  "completedOn": "2026-04-11T14:32:00Z",
  "score": 95,
  "status": "passed",
  "organisation": "HR department"
}

Testing the integration

Before an integration goes to production, Activate LMS offers two test functions that can be run from the admin UI without affecting production data:

Test connection

Verifies that Activate LMS can reach your endpoint and that authentication works. Sends a single GET or OPTIONS request to the endpoint URL without any data. Use this for a quick check of URL and authentication.

Test with user

Sends one or more real completion records for specific users — but without writing to the sync log or updating status. Use this to verify that the payload format and field mapping are correct. You can specify one or more usernames and run the test as many times as you like; the same data can be sent again and again without being "consumed" by the production sync.

The test functions use the exact same code path as production sync — so if the test succeeds, production sync will succeed too. The only difference is that test does not write to the integration log.

Troubleshooting

Common errors

Symptom	Cause	Fix
HTTP 401 Unauthorized	Wrong API key, bearer token, or basic credentials	Verify that the auth values in the LMS configuration match exactly what your endpoint expects.
HTTP 403 Forbidden	Authentication is OK, but the account does not have access to the endpoint	Confirm the service account has the necessary permissions in your system.
HTTP 400 Bad Request	The payload format is not what your endpoint expects	Use "Test with user" to inspect the exact payload. Adjust the field mapping in the LMS to match.
HTTP 404 Not Found	The endpoint URL is wrong or has moved	Verify the URL and test with curl/Postman from outside the LMS.
HTTP 500 Server Error	Error in your own system — the LMS sent something that triggered a failure	Check your own logs for details. If possible, send the payload to a test environment first.
Timeout (no response)	Your endpoint is slow or blocked by a firewall	Verify that the Activate LMS outbound IPs are whitelisted. Ensure the endpoint responds within 30 seconds.
Certificate error	Client certificate missing or expired	Contact Activate LMS support to verify the certificate status in the Azure certificate store.

Logs

The LMS administrator has access to a complete sync log under Admin → Integrations → (select integration) → Synchronisation log. For each sync attempt, the log shows:

• Which user and which completion was attempted
• Timestamp of the attempt
• HTTP status code received
• The full request payload that was sent
• The full response body received
• Error message if there was an exception

If you experience integration problems, ask the LMS administrator to share the relevant log entries. It will almost always make debugging much faster.

Security recommendations

• Always use HTTPS — never plain HTTP. Activate LMS rejects HTTP endpoints in production.
• Use a dedicated service account for the integration instead of a personal user. Grant it only the permissions it needs.
• Rotate credentials regularly — ideally every six months. The LMS administrator can change the API key or password in the admin UI without downtime.
• Whitelist only Activate LMS's outbound IPs if your endpoint allows it. Contact support for the current list.
• Log all incoming requests on your side to maintain an audit trail.
• Always test in a test environment first before activating an integration against production.