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, your organisation's IT team, and the API service switched on by the helpdesk team.
For your IT team: the developer documentation covers getting started, authentication, concepts and identifiers, responses and errors, and the full API reference (OpenAPI v3).
View the Form User API documentation
Contents
- Overview of the setup process
- Enable the API and generate an API key
- Integrate the API with your application
- Create organisation units and groups
- Create auto-enrolments and workflows
- Create user fields
- Invite users
- Maintain data: reading and updating
- Disable the API
Overview of the setup process
Setup is shared between you, working in Form, and your IT team, working in your application:
| Where | Step |
|---|---|
| Form LMS | Turn on the API and generate an API key |
| Your application | Integrate the API |
| Your application | Create organisation units and groups |
| Form LMS | Create auto-enrolment rules, workflows and user fields (if required) |
| Your application | Invite users |
See the following sections for detailed setup steps.
⚠️ Important
- We strongly recommend setting up the API on a new workspace with no existing users, groups or organisation units. This prevents data inconsistencies.
- While the API is on, you cannot manage users, organisation units or groups manually in Form. Your application owns that data.
- Identify users by email address in API requests. Form also accepts user IDs, but email addresses are easier to keep consistent with your application.
- Turning the API off later lets you edit that data in Form again, which can conflict with your application. See Disable the API.
Enable the API and generate an API key
To get started with the API, turn it on and create an API key:
- Go to Setup → Site settings → API integration.
- Select the API toggle to turn the API on.
- Click Generate key to create an API key.
You need the Site admin role to do this.
💡 Helpful tips
- If you do not see the API integration tab, contact the helpdesk team to have the API service enabled for your account.
- 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.
See the API in action. This 4-minute walkthrough uses Postman to create organisation units and groups, set up auto-enrolment rules and workflows, and send invitations. It is aimed at your IT team.
ℹ️ 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.
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.
Your application creates them through the API:
| Action | Endpoint |
|---|---|
| Create an organisation unit | POST /api/organisation-units |
| Create a group | POST /api/groups |
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 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.
Your IT team can read the field names and types with GET /api/settings/custom-fields, and set values when inviting or updating a user.
Invite users
Users join Form through an invitation. This is how it works:
- Your application calls
POST /api/users/invite. Form creates the user profile with the status Invited and emails the invitation to the user. - While the invitation is open, your application can resend it as a reminder or cancel it. It can also update the invited user's name, email address, expiry date, custom fields, organisation unit, groups and roles.
- The user clicks the link in the email. If the invitation was cancelled, they see an error and nothing changes.
- Otherwise the profile becomes Active. If the organisation unit or groups on the invitation have auto-enrolment rules, Form enrols the user onto those courses at this point.
| Action | Endpoint |
|---|---|
| Create an invitation | POST /api/users/invite |
| Resend an invitation | PATCH /api/user/{userId}/invite-resend |
| Cancel an invitation | DELETE /api/user/{userId}/invite-cancel |
| Update name or expiry date | PATCH /api/invitation/{userId}/data |
| Change email address | PUT /api/invitation/{userId}/email-address |
| Update custom fields | PATCH /api/invitation/{userId}/custom-fields |
| Change organisation unit | PATCH /api/invitation/{userId}/organisation-unit |
| Change groups | PATCH /api/invitation/{userId}/groups |
| Change roles or managed organisation units | PATCH /api/invitation/{userId}/roles |
ℹ️ Note: Changing an invited user's email address resends the invitation to the new address automatically. You do not need a separate resend request.
For request and response details, see the Invitation section of Concepts and identifiers in the developer documentation.
Maintain data: reading and updating
Once your data is loaded, your application can read and update it at any time.
Use the GET endpoints to list users, organisation units and groups, or to read a single record. Use the PATCH endpoints to update user details, organisation units and groups.
For full details, refer to the API reference. If you run into any problems, the helpdesk team is ready to help.
Disable the API
To turn the API off, go to Setup → Site settings → API integration, switch the API toggle off and confirm.
While the API is off, you can manage users, organisation units and groups manually in Form. Your existing organisation units and groups are kept, and turning the API back on does not delete them.
⚠️ Important
Your application does not know about changes you make in Form while the API is off. When you turn the API back on, those changes may conflict with the data your application sends. Only turn the API off when the integration is no longer needed, or agree any changes with your IT team first.