PortalHQ exposes REST APIs so other systems at your school can read (and in some cases write) PortalHQ data. Common uses: feeding co-curricular participation into a reporting dashboard, pulling slip submissions into a compliance system, pushing data from PortalHQ into a finance system for billing.
When to use the APIs
Use the APIs when:
- Another system needs PortalHQ data that doesn’t have a built-in integration with you.
- You want to build a dashboard or report PortalHQ doesn’t provide natively.
- You’re automating a workflow that currently involves manual export/import.
Don’t use the APIs for things PortalHQ already does — if the answer is “fix this in PortalHQ instead”, do that.
What’s available
The APIs cover most of PortalHQ’s data model. The most commonly-used endpoints:
| Endpoint | What it returns |
|---|---|
| Students | Roster of active students with year group, contact info, parents. |
| Staff | Roster of staff with email, role. |
| Activities and Activity Groups | Co-curricular structure for the current term. |
| Activity Signups | Who has signed up to what, with payment status. |
| Sessions and Rolls | Co-curricular session schedule and attendance. |
| Slips and Submissions | Slip configuration and parent/student responses. |
| Forms and Submissions | Form responses. |
| Newsroom Contacts | Mailing list members. |
| Notices | Published notices. |
For the full list and the latest schema, see the interactive API docs at /doc/swagger/ on your PortalHQ instance.
Authentication
PortalHQ APIs use token-based authentication:
- Generate an API token in your PortalHQ admin settings under API tokens. Tokens are tied to a specific user — the API call has the same permissions as that user.
- Use the token in the
Authorizationheader on each request:
Authorization: Token <your-token-here>
- Rotate tokens periodically — treat them like passwords. If a token is compromised, revoke it from the same settings page and issue a new one.
Request and response format
- All endpoints return JSON.
- Filter and search via query parameters where supported.
- Pagination is via standard
?page=N&page_size=Mparameters. Large result sets are paginated; check the response fornextandpreviousURLs.
Rate limits
PortalHQ enforces per-token rate limits to protect the service. The default limit is suitable for most integrations — sync once an hour or once a day. If you have a use case that needs higher throughput, talk to your PortalHQ rep about a token with elevated limits.
Writing data
Most endpoints are read-only. A subset supports write operations:
- Creating new students or staff — for schools that maintain their roster in a system other than the SIS (uncommon, but possible).
- Creating notices or newsroom items — for automated daily-notice pipelines.
- Updating activity enrolments — for schools managing co-curricular outside PortalHQ.
Write endpoints follow standard REST conventions — POST to create, PATCH to update, DELETE to remove.
Versioning
PortalHQ APIs are versioned. The current version is documented in the Swagger docs. Older versions remain available for a deprecation window (typically 12 months) before they’re removed.
Pin your integration to a specific API version where possible — that way a new API version doesn’t break your code without warning.
Webhooks
For workflows that need to react in real time (e.g. email the office whenever a parent submits a slip), PortalHQ supports webhooks. Configure a webhook URL and pick which events trigger a POST to it.
Webhooks are configured in the same area as API tokens.
Documentation
Two formats:
- Swagger / OpenAPI UI at
/doc/swagger/— interactive API explorer where you can try requests against your school’s data. - Redoc at
/doc/redoc/— read-only API reference, cleaner for reading.
Both are kept up-to-date with the live API surface.
Getting help
For API design questions, edge cases or feature requests, contact PortalHQ support. Common topics:
- “Which endpoint returns the data I want?”
- “Can the API do X?”
- “Why is my response missing field Y?”
- “How do I authenticate as a different user for an admin operation?”
Build a minimal reproduction (a curl command that shows the issue) before reaching out — it speeds up support.