This article provides a comprehensive, step-by-step guide to help you import your iSAMS data into SchoolsBuddy. Use the index on the right-hand side to quickly navigate to the section relevant to your needs.
1. Overview
SchoolsBuddy imports your essential data—including students, contacts, and staff—directly from iSAMS using Batch API keys. The system performs an overnight data update, ensuring that your information remains accurate and up to date.
Please set up seven separate Batch API keys (the Medical key is optional) via the iSAMS Admin Control Panel > API Keys section.
Creating these keys separately allows SchoolsBuddy to pull different types of data independently, improving load handling and ensuring the data import runs smoothly and in the correct sequence.
2. How to Create a Batch API Key
To set up API Keys, follow the steps below. These may differ slightly depending on whether you use a cloud-hosted or self-hosted instance of ISAMS.
- Log in to ISAMS as an Administrator and click on the Control Panel.
-
Select the API Services Manager
-
Select Manage Batch API Keys
- Click Request Batch API Key (or Create Batch API Key if you see that instead). You'll need to request 6 or 7 new keys from ISAMS first (depending on whether you want to share medical information or not).
-
Enter the Integrator and Product name as "SchoolsBuddy" then Save and close. If you can't see the save & close button, expand the popup window - it is in the top left corner.
- The ISAMS team will create the key for you. When it is ready, it will appear under the API Key Manager. Click the Edit icon to configure the settings of the key.
- Copy the API Key Reference — you’ll need this to complete the SchoolsBuddy integration form (see reference below).
- Name the key clearly based on its purpose (e.g., SchoolsBuddy – Students; SchoolsBuddy – staff) so it’s easy to identify later.
-
Set the following key configurations:
State: Active
Mode: Production
-
Cache Expiry: 2 or 3 hours (instead of the default 24 hours)
Why adjust the Cache Expiry?
SchoolsBuddy queries iSAMS once every 24 hours, during the night, based on your time zone. Reducing the cache expiry to 2–3 hours ensures:
Data can be refreshed sooner if needed.
You can request a manual data sync from SchoolsBuddy support (e.g., if a new student is added during the day).
The system still minimises the load on your iSAMS database by caching results for a few hours.
If the cache is set to the default 24 hours, any new or updated data would not be available until the next day’s scheduled sync.
- Select the Batch Methods tab.
- Configure each key by checking the settings as shown in the table below. This is an example of the Contacts key.
- Save & Close.
3. API Keys Settings
Each API key must be configured with a specific Batch Method — these are individual calls to different iSAMS modules to retrieve the required data.
⚠️ Important:
Only select the methods listed for each key below.
Do not select any additional settings or custom fields, as this may prevent SchoolsBuddy from processing the data correctly.
Please refer to the table below for the exact configuration required for each of the seven keys.
| API Key 1 | Groups |
|
| API Key 2 | Staff |
|
 | ||
| API Key 3 | Students |
|
 | ||
| API Key 4 | Contacts |
|
 | ||
| API Key 5 | Medical |
|
 | ||
| API Key 6 | Subjects |
|
| API Key 7 | Leavers (Alumni) |
|
⚠️Important Notes:
Student: If you are only using SchoolsBuddy for certain year groups or grades (not the entire school), you can use the Student Filter to include only students from specific year levels. See this iSAMS guide for more detailed steps.
-
Contacts: There is a section on the API submission form where you can provide notes about contact filtering. Please keep in mind that any contacts imported into SchoolsBuddy will receive email notifications about the student’s activities and will be able to log in to view the student’s schedule. Therefore, please decide based on your school’s policies—who should have access.
SchoolsBuddy can filter contacts using the following options. Contacts must meet all selected criteria in order to be imported:
Contact Type: Specify which contacts should be imported (e.g., Mother, Father, or All contact types).
-
Merge type: You can choose only to import contacts with the following merge type.
All merge or Billing Merge (Default selection)
All merge or Correspondence Merge
Parental Responsibility: Only contacts who have parental responsibility.
4. Optional Attendance Integration - REST API
You only need to complete this step if you’d like SchoolsBuddy to display absent marks within activity registers based on iSAMS records. This allows an after-school activity leader to see if a student is absent from school for the day. This setup is optional and can be added at a later stage if preferred.
How Attendance Sync Works
Attendance data is synced twice daily at 9:30AM and 2:20PM
See our attendance guide MIS Absence for more information on how we use attendance information in SchoolsBuddy.
What You Need to Do
Request REST API access from iSAMS support on behalf of SchoolsBuddy.
-
Provide us with the following:
Client ID
Client Secret
-
Let us know the Register Rules you'd like us to use for AM and PM registration, respectively.
We can import multiple registration rules, but please note that each rule can only be used once per day—either in the morning or in the afternoon. A single rule cannot be applied to both time slots.
Why do we need a REST API Key for attendance - why not use a "batch" API Key?
SchoolsBuddy uses the REST API for attendance because the iSAMS Batch API relies on cached data (default: 24 hours). If data has been cached, it won’t re-query the database, which means it may not reflect real-time attendance changes.
The REST API provides real-time data, which is essential for attendance since we pull data twice daily (AM and PM). Relying on batch data could result in outdated information being shown in activity registers.
Additionally, the Batch API is subject to usage limits and throttling. By using the REST API for attendance and reserving the Batch API for the main overnight data sync, we reduce the risk of hitting those limits and ensure smooth, reliable imports.
5. Submit Batch API Keys, Access URL (& REST API key) to Us
After creating and saving the API Keys, please copy and paste them into this API submission form along with your iSAMS access URL (e.g., yourschool.isams.cloud). If you would like attendance updates, please include the REST API Client ID and Client Secret.
6. SchoolsBuddy Configuration
Once we have entered the API keys in your SchoolsBuddy account, we will begin importing your data overnight.
After the initial import, we will examine the data and confirm with you that the data has come into SchoolsBuddy successfully.
7. FAQ
Q: What if we need to update any student, parent, or staff details?
A: Please update the details directly in iSAMS as usual. These changes will imports into SchoolsBuddy each night. However, sometimes iSAMS may take a little longer to update its API feed, and you might notice that student records appear before their email addresses are fully updated. We recommend allowing up to 48 hours for all new student details to sync completely.
Q: Will students be automatically removed when they leave?
A: Yes. Students marked as leavers or alumni in iSAMS will be automatically removed.
Q: Will parents automatically be removed when their student leaves?
A: Parents’ accounts will be deactivated unless the student has a sibling currently attending the school with an active SchoolsBuddy account.
Q: Will staff be automatically removed when they leave?
A: No. Both internal and external staff will retain their SchoolsBuddy accounts until they are manually deleted. An Organisation Super Admin user must delete their accounts in SchoolsBuddy. This is due to a limitation of the iSAMS API.
Q: Can SchoolsBuddy import iSAMS ‘off-school’ attendance each day?
A: No, not currently. In the future, iSAMS may include this data in their public API, allowing SchoolsBuddy to import it.
Q: Can SchoolsBuddy import medical information?
A: Yes. If you provide us with the Medical Batch Method API key, we can import medical conditions for your students.
Q: Will teachers’ classes be imported directly into SchoolsBuddy?
A: Yes, but only set-based classes will be imported to support Parent-Teacher Conferences and communications. Form-based classes are not imported.
Q: Can boarding houses be added to SchoolsBuddy?
A: Our integration currently supports academic houses only. However, some schools have expressed interest in adding boarding houses to student records. Please visit our Product Portal to vote for this feature.
Q: Can student photos be synced to SchoolsBuddy?
A: It is not currently possible to sync student photos via the iSAMS API. However, please contact our Support Team if you are interested, as we may be able to offer an alternative workflow.
Q: We are using one iSAMS account for multiple campuses by assigning years as below. Is this a problem?
Campus 1: Years 1 – 10
Campus 2: Years 20 – 30
A: SchoolsBuddy syncs the year’s display name, so if both Year 10 and Year 20 share the same name (e.g., “Year 5”), they will be imported as one year group. We recommend adding a campus identifier to the year group names to distinguish them in SchoolsBuddy, for example, “Year 5 Campus 1” and “Year 5 Campus 2.”