Overview
The EnrolHQ to Compass integration syncs student enrolment data — including student details, parent/guardian information, medical records, emergency contacts, and school history — from EnrolHQ into Compass. Data flows one way: EnrolHQ → Compass. Document sync is not currently supported.
The integration uses the Compass Enrolments API (/Enrolments/V1/import) and authenticates via an API key sent in request headers.
Requirements
To set up the Compass integration, you need the following from the school's Compass administrator:
Instructions for Compass Administrator at SCHOOL NAME
Please set up an API user in Compass and send credentials using Bitwarden or similar. The 4 required items are:
| Item | Example | Notes |
|---|---|---|
| URL | https://xxxxxxx-state.compass.education/API |
Must end in /API |
| Username | EHQAPI |
API user account |
| Password | (provided securely) | API user password |
| API Secret | xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx |
UUID format — this is the key used for authentication |
After receiving credentials, EnrolHQ will conduct a proof-of-connection test and organise a meeting to demonstrate syncing from EnrolHQ to Compass.
Standard mapping list: enrolhq.com.au/product/sis-integrations/compass/
Core Campus Lookup - not required for single Campus School
- If they have multiple campuses then contact the School IT and ask for a data dump of their campuses in Compass, it should include name and campus code.
- Match the EnrolHQ and Compass campuses by name and fill in the fields as follows:
- School: the school
- Provider: Compass
- Campus code from provider: Compass campus code
- Description: campus name (if there is variation between EnrolHQ and Compass than use the EnrolHQ name)
- Corresponding value in EnrolHQ: EnrolHQ campus ID
Core Year Level Lookup
- Ask the School IT for a data dump of their year levels in Compass, it should include name and year level code.
- Match the EnrolHQ and Compass year levels by name and fill in the fields as follows:
- School: the school
- Provider: Compass
- Year level code from provider: Compass year level code
- Description: year level name (if there is variation between EnrolHQ and Compass than use the EnrolHQ name)
- Value: EnrolHQ year level code ID
Field Mapping Reference
Student Fields
| EnrolHQ Field | Compass Field | Notes |
|---|---|---|
| First name | firstName | Required |
| Last name | lastName | Required |
| Preferred name | preferredFirstName | |
| Middle name | middleName | |
| Date of birth | dateOfBirth | Defaults to 1971-01-01 if missing |
| Gender | gender | Male → 1, Female → 2, Other → 0 |
| External ID | externalCode | Auto-generated if not present |
| Entry grade | yearLevelCode | Via Year Level Lookup |
| Title | title | Master / Miss / Unspecified |
| Aboriginal status | indigenousType | None → 1, Aboriginal → 2, Torres Strait → 3, Both → 4, Not Stated → 5 |
| Birth country | birthCountry | |
| Visa expiry date | visaExpiryDate | Format: YYYY-MM-DD |
| Home language | languages | Language list |
| ESL status | languageBackgroundOtherThanEnglish | Boolean |
| Disabilities | disability | Boolean |
| Religion | religion | |
| Visa subclass | visaSubclass | Must be numeric |
| Residency status | residentialStatus | PR → 1, Temp Resident → 2, Citizen → 3 |
| Mobile phone | phoneMobile | |
| Home phone | phoneHome | |
| Nationality | nationality | First nationality |
| Commencement date | commencementDate | Resolved via priority logic (see below) |
| Address | addresses | Residential address |
| Student resides with | livingAmount | Always / Sometimes / Rarely / Never |
| Campus | campusStatuses | Via Campus Lookup |
| House | groupC | House/form group name |
| Attendance type | studentDetailsBoarderTypeString | Day Student / Boarder / Full Time / Weekday |
| Medical conditions | userMedicals | Conditions and medications |
| Doctor details | personDoctors | Doctor name, phone, address |
| Emergency contacts | emergencyContacts | With relationship and notes |
| Photo permissions | publishPhotoToMedia/Internal | From “Photo and Video permission” custom form |
| Siblings | siblingHints | Sibling information |
| Current school | schoolHistory | Previous school |
| EnrolHQ UUID | govtCode1 | Configurable via provider_meta |
Parent/Guardian Fields
| EnrolHQ Field | Compass Field | Notes |
|---|---|---|
| First name | firstName | Required |
| Last name | lastName | Required |
| Middle name | middleName | |
| External ID | externalCode | Auto-generated if not present |
| Title | title | Mr / Mrs / Miss etc. |
| Gender | gender | Derived from relationship and title |
| Relationship | adultToStudentRelationship | Mother → 0, Father → 1, Guardian → 2, Stepmother → 4, Stepfather → 5, Grandmother → 6, Grandfather → 7, Aunt → 8, Uncle → 9, Sponsor → 10 |
| Date of birth | dateOfBirth | Configurable; defaults to 1971-01-01 |
| Address | addresses | Residential address |
emailAddress | Optionally used as username | |
| Mobile phone | phoneMobile | |
| Home phone | phoneHome | |
| Occupation | occupation | |
| Employer | employer | |
| Occupational group | parentDetailsOccupationalStatus | Mapped to Compass codes 1–6 |
| Highest school year | parentDetailsSchoolEducationBackground | Integer |
| Degree | parentDetailsNonSchoolEducationBackground | Bachelor → 1, Diploma → 2, Cert IV → 3, None → 4 |
| Birth country | birthCountry | |
| Nationality | nationality | |
| Religion | religion |
Commencement Date Resolution
The commencement date is resolved in priority order:
- Student's commencement_date field — if explicitly set on the student profile
- Commencement date settings — matched by entry year and entry grade from the EnrolHQ school settings
- Term-based defaults — Term 1 → 1 Jan, Term 2 → 1 Apr, Term 3 → 1 Jul, Term 4 → 1 Oct of the entry year
- Fallback — 1 Jan of the entry year
Running a Sync
Proof of Connection Test
After confirming with the EnrolHQ team that the data/sync team has configured the SIS Settings and received API credentials:
- Select a test student in SentralEnrolHQ
- Trigger a single sync to Compass
- Verify the student appears in Compass with correct field mappings
- Check the API Log in admin for the request/response details
Single Student Sync
Individual students are synced when triggered via the EnrolHQ "Sync Compass" button. Each sync sends one student with their parent(s) in a single API call.
Bulk Sync
Bulk sync processes multiple students sequentially with a 10-second delay between each sync to prevent API rate limiting or job invalidation in Compass. Do not attempt to parallelise bulk syncs.
What Gets Sent
Each sync call sends an enrolment payload containing:
- One student record with all mapped fields
- One or two parent/guardian records (each with their own external code)
- Medical records, emergency contacts, and school history as nested data
Troubleshooting
API Connection Issues
- 401 Unauthorised: Check the API Secret in SIS Settings is correct and the API user is active in Compass
- Timeout errors: Default timeout is 40 seconds. Can be increased via the
COMPASS_REQUEST_TIMEOUTenvironment variable - SSL errors: Ensure
verify_sslis enabled on the Business record (recommended). Only disable for testing if required
Data Issues
- Missing year level mapping: Check Year Level Lookups are configured for the correct school and provider (
compass) - Missing campus mapping: For multi-campus schools, ensure Campus Lookups exist. Single-campus schools default to campus code
1 - External code conflicts: If using sequential codes, check the
CompassCodeCounterin admin to verify the current counter value doesn't conflict with existing Compass records - Missing commencement date: Verify the student has an entry year set, and check that commencement date settings are configured in EnrolHQ if using the settings-based resolution
Checking Logs
- API Logs: Navigate to the API Log in admin to view request/response payloads for each sync attempt
- Application Logs: Compass requests are logged under the
compass/requestslogger — check server logs for detailed request/response debugging
EnrolHQ Internal Setup Checklist
- Receive Compass API credentials (URL, username, password, API secret) via Bitwarden or similar
- Create/update the Business record with
system_type = compass - Create the SIS Settings record with Compass credentials
- Configure Provider Meta settings (if non-default behaviour is needed)
- Set up Year Level Lookups (match EnrolHQ grades to Compass year level codes)
- Set up Campus Lookups (multi-campus schools only)
- Set up Medication Permission Lookups (if the school uses medical permission forms)
- Run a proof-of-connection test with a single student
- Verify mapped fields in Compass
- Review API logs for any errors or warnings
- Schedule onboarding meeting with the school to demonstrate the sync
- Run bulk sync for existing pipeline students (if required)