# PortalHQ APIs 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: 1. **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. 2. **Use the token in the `Authorization` header** on each request: ``` Authorization: Token ``` 3. **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=M` parameters. Large result sets are paginated; check the response for `next` and `previous` URLs. ## 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.