Skip to main content

Setting up the Form User API

  • Updated

The Form LMS User API is a REST API that lets an external application manage users, organisation units and groups. This saves time and resources compared to manual updates.

✅ Before you start: You need the Site admin role, plus your organisation's IT team.

Watch this short demo of the API:

ℹ️ Note: CSV files are used in the video for demonstration purposes. In practice, each row of data is delivered to Form via a bespoke integration developed by your IT team.

View the API endpoint documentation (OpenAPI v3 standard):
View the API specification documentation

Contents

Overview of the setup process

Setting up the API requires these steps:

Where Step
Form LMS Turn on the API and generate an API key
Your application Integrate the API
Your application Create organisation units, groups and user fields (via API)
Form LMS Create auto-enrolment rules, workflows and user fields (if required)
Your application Invite users (via API)

Initial setup diagram

See the following sections for detailed setup steps.

⚠️ Important

  • Before any setup, the API service must be switched on for your account by the helpdesk team.
  • We strongly recommend setting up the API on newly created workspaces without existing users, groups or organisation units. This prevents data inconsistencies.
  • When the API is turned on, manual operations on users, organisation units and groups are disabled.
  • We recommend using email addresses in API requests, as users can be identified by both their IDs and email addresses.
  • If the API is turned off after being enabled, any existing organisation units or groups will be deleted from the workspace. This is irreversible.

Enable the API and generate an API key

To get started with the API, turn it on and create an API key:

  1. Go to Setup → Site settings → API integration.
  2. Select the API toggle to turn the API on.
  3. Click Generate key to create an API key.

You need the Site admin role to do this.

💡 Helpful tips

  • If you do not have access to the API Integration tab, contact support to have the API service enabled on your site.
  • An API key is required for all API requests.
  • The API key grants access to sensitive data. Store it securely.
  • If your API key may have been compromised, generate a new one. The previous key is automatically deactivated.
  • You can have up to two active API keys at the same time. This lets you replace keys without interrupting requests.

Integrate the API with your application

Your IT team is responsible for integrating the API into your application. They call the API when certain actions happen. For example, when a new user is added, they make an API call to invite the user to Form.

We suggest setting up a test workspace for your IT team. This lets them test the API before implementing it in the live environment.

Create organisation units and groups

Form supports two ways of grouping user profiles within a workspace: organisation units and groups.

Groups are open containers without a fixed structure. Organisation units reflect your departmental structure as a tree. All organisation units branch from the workspace itself, with as many child units as needed.

Use the API to create your groups and organisation units.

Create auto-enrolments and workflows

Both organisation units and groups can trigger automatic enrolments and workflow automation rules. However, you must set these up within Form as an administrator. The API does not manage these rules directly.

If a user is invited to a group or organisation unit with existing auto-enrolment rules, they are enrolled in the defined courses automatically. If a user is moved between organisation units or groups, they receive enrolments as defined by the target's rules.

If a user completes a course included in a workflow rule, they are enrolled in the next course in that workflow.

ℹ️ Note: Automated enrolments may fail if no course licence is available or if the user is already enrolled and has not yet completed the course.

To create auto-enrolments in Form, go to People → Auto-enrolments.

To create workflows in Form, go to People → Workflows.

Create user fields

Each workspace in Form can have up to 10 custom fields. These are useful for associating custom information with a user, such as job title or payroll number.

To create user fields in Form, go to Setup → Site settings → User fields.

Invite users

A simplified overview of the user invitation process is shown below.

inviteUser.png

There are three endpoints for managing invitations:

  1. https://euma.api.melearning.co.uk/api/users/invite (POST) - create new invitations
  2. https://euma.api.melearning.co.uk/api/users/{userId}/invite-resend (PATCH) - resend an invitation as a reminder
  3. https://euma.api.melearning.co.uk/api/users/{userId}/invite-cancel (DELETE) - cancel a sent invitation

⚠️ Important

When inviting users through the API, you must:

  • Use the user's email address as their unique user ID.
  • Allocate the user to a group or organisation unit at the time of invitation, not afterwards. This makes sure auto-enrolments are triggered correctly.

 

Maintain data: reading and updating

Once you have uploaded your data for the first time, you can change it at any time.

Use the GET method to see a list of everything in the API and look through the details. This is helpful when you have a large amount of data to manage.

Use PATCH to update user details, and manage your organisation units and groups.

For full details, refer to the OpenAPI 3.0 documentation. If you run into any problems, the helpdesk team is ready to help.

Disable the API

⚠️ Disabling the API

Disabling the API enables manual management of organisation units and groups, which may cause data inconsistency. Do not turn off the API unless it is no longer required for the workspace.

 

Related articles