How the Integration Works
PortalHQ connects to Engage through the Engage API, using API credentials the school configures in Engage. Each day, PortalHQ retrieves current students, their contacts (parents and carers), and current staff from Engage. Where a school runs more than one Engage tenant, for example one per campus, each tenant is read in turn. Newsroom by PortalHQ then refreshes its contact lists from that data, so families and staff who join or leave Engage flow through to mailing lists automatically, with no manual uploads required.
Audiences can be built from any of the fields listed below (for example, all parents of Year 7 students, or all staff in a particular staff category), and those lists remain current as Engage records change.
| Step | Frequency | What happens |
|---|---|---|
| Engage to PortalHQ | Daily, around 4:45am AEST (5:45am during daylight saving) | Current students, their parents and carers, and staff are read from Engage and updated in PortalHQ. |
| PortalHQ to Newsroom by PortalHQ contacts | Daily | Newsroom by PortalHQ contacts and dynamic mailing lists are refreshed from the synced records. Families and staff who have left are removed. |
Current Families (Parents and Carers)
Parents and carers are drawn from the contacts listed against each current student in Engage. PortalHQ reads each student’s contact list (API method getcurrentpupilinfo, with contact information included), then looks up each contact’s full details (API method getcontactinfo) using the contact ID.
Every contact linked to a current student is brought in, provided they have a primary email address in Engage. Contacts without a primary email address are skipped. Only parents linked to at least one current student are included. When a family’s last child leaves the school, that family is removed from the current-parent audience automatically.
Fields retrieved for each parent or carer
| PortalHQ field | Source in Engage | Notes |
|---|---|---|
| Title | Contact: title | |
| First name | Contact: forename | If the forename is blank, the contact’s greeting is used instead. |
| Surname | Contact: surname | |
| Email address | Contact: email addresses, the one marked as primary | Only the primary email address is used. Contacts without one are not added. |
| Mobile | Contact: telephone numbers, the number with type code 001 | |
| Relationship | Contact: the description on the primary email address | Read as Mother, Father, Step-Mother, Step-Father, Grandmother, Grandfather or Guardian when the description contains that word (for example “Mother’s email”), otherwise Other. |
| Do not contact | Contact: doNotContact | A contact marked Do Not Contact in Engage is still linked to their children in PortalHQ, but is kept unsubscribed in Newsroom by PortalHQ. |
| Engage contact ID | Contact: contactId (from the primary email address) | Used to match the same person on each sync. |
The sync does not read a deceased flag from Engage. To stop emails going to a deceased contact, remove them from the student’s contact list in Engage or mark them Do Not Contact.
Fields inherited from their children (for targeting)
| PortalHQ field | Source |
|---|---|
| Year level(s) | Each current child’s year group |
| House(s) | Each current child’s house |
| Form class(es) | Each current child’s form |
Current Students
Student details are drawn from the Engage current pupil record (API method getcurrentpupilinfo). Only students with a status of Current are included. Students who no longer appear as current in Engage are marked as no longer current in PortalHQ on the next sync.
| PortalHQ field | Source in Engage | Notes |
|---|---|---|
| First name | Pupil: forename | |
| Surname | Pupil: surname | |
| Email address | Pupil: studentEmailAddress | |
| Student ID | Pupil: pupilId | Used to match the same student on each sync. |
| Year level | Pupil: yearGroup | Where several schools share one Engage database, the school prefix on the year group is removed and only that school’s students are included. |
| House | Pupil: house | The first 25 characters are kept. |
| Form class | Pupil: formName | |
| Gender | Pupil: genderCode | M and F map to Male and Female. Any other value is recorded as Other. |
| Parents and carers | Pupil: contacts | See Current Families above. |
Staff
Staff details are drawn from the Engage current staff record (API method getcurrentstaffinfo). A staff member is only brought in if they have a staff category and an email address. Only staff with a status of Current are included in Newsroom by PortalHQ, and staff who no longer appear in Engage are removed on the next sync. Individual staff members can also be excluded from Newsroom by PortalHQ contacts within PortalHQ.
| PortalHQ field | Source in Engage | Notes |
|---|---|---|
| Title | Staff: title | |
| First name | Staff: forename | |
| Preferred name | Staff: preferredForename | |
| Surname | Staff: surname | |
| Email address | Staff: email, the one marked as primary | If none is marked primary, the last listed address is used. Where two staff records share an email address, only the first is kept. |
| Phone | Staff: telephone | |
| Position | Staff: staffCategory | Available for targeting in Newsroom by PortalHQ. Where several schools share one Engage database, the school prefix is removed and only that school’s staff are included. |
| Teaching staff | Staff: isTeacher | |
| Staff number | Staff: employeeId | |
| Engage staff ID | Staff: id | Used to match the same person on each sync. |
| Active | Staff: status | Only staff with a status of Current are active. |
Alumni
Alumni are not retrieved from Engage by the automatic sync, which reads current students, families and staff only. Instead, alumni are loaded into Newsroom by PortalHQ from a spreadsheet export, and each contact is tagged as alumni with a Class Of year so that cohorts can be targeted (for example, a Class of 2016 reunion). The import can be repeated whenever the school’s alumni records are updated.
Schools that maintain alumni records in another system, such as a CRM or foundation database, can also push contacts into Newsroom by PortalHQ through the PortalHQ API.
| Newsroom by PortalHQ field | Spreadsheet column |
|---|---|
| First name | Given name |
| Surname | Surname |
| Email address | Email (rows without an email are skipped) |
| Class Of | Graduating year |
| Is Alumni | Set automatically on import |
Privacy and Preferences
- Newsroom by PortalHQ only reads contact data from Engage. It never writes contact details back to Engage.
- Contacts who unsubscribe in Newsroom by PortalHQ remain unsubscribed. A subsequent sync does not re-subscribe them.
- Parents and carers marked Do Not Contact in Engage are kept unsubscribed in Newsroom by PortalHQ on every sync. If the flag is later removed in Engage, they are not re-subscribed automatically.
- Every email sent from Newsroom by PortalHQ includes an unsubscribe link.
Enquiries
For any queries regarding this integration, please contact TeamHQ at support@teamhq.com.au or +61 2 8387 7321.