API documentation and developer portal
Welcome to the technical core of UnhostCampus — the tools and information you need to integrate our services into your school stack. The API follows REST, so it is predictable, testable and usable from modern languages. This documentation is for developers who want the full potential of our database infrastructure for their own apps and extensions.
Section index
REST API over the school database
The UnhostCampus communication layer is a stateless RESTful API. Each endpoint is a resource — a student, a card, a transaction or an inventory item — and accepts standard HTTP methods. Payloads are JSON, which keeps integration straightforward in PHP, Python, JavaScript and C#. Developers work with predictable URLs and a consistent response schema across the platform.
HTTPS / TLS 1.2+
All traffic is encrypted.
application/json
Request and response in JSON.
Bearer Token
API key in the Authorization header.
Communication basics and authentication
Access to the UnhostCampus API is token-based so only authorised parties with the right scopes can touch data. All requests must use HTTPS; payloads travel as JSON for readability and processing.
This section shows how to generate your first API key and how to set request headers so the connection succeeds. Tokens expire and can be revoked at any time, which lets you react quickly to a security incident.
curl -X GET https://api.unhostcampus.com/v1/students -H "Authorization: Bearer {API_KEY}" -H "Content-Type: application/json" -H "Accept: application/json"
api.unhostcampus.com/v1
Renewable via the refresh endpoint
Student and staff entities
The core of the API is profile endpoints that sync with your primary information system. You can create, update and query person records, assign identity media and manage organisational placement inside the school.
The docs describe every field and data type the platform uses, including bulk-operation limits. A typical person object includes name, national ID number, class, role and a list of active cards. Bulk operations are capped at 500 records per request.
Credit-operation integration
For internal-credit operations we provide endpoints to post events, check balances and read history on virtual accounts. The API supports atomic operations, which is critical for ledger integrity and concurrent requests. Developers will find samples from a simple till tap through to recurring service charges — still internal credits, not bank payments.
{
"student_id": "STU-2026-0148",
"amount": -45.50,
"description": "Lunch — canteen",
"terminal_id": "TERM-003",
"idempotency_key": "tx_17356a2b"
{
"transaction_id": "TX-88472",
"status": "completed",
"balance_after": 312.00,
"timestamp": "2026-08-25T11:42:01Z"
Pole idempotency_key guarantees that resending the same request does not post the event twice. That matters when a network drop must not change the account state after the fact.
Working with identity media
This part of the docs covers low-level chip-card traffic and how cards bind to digital identities. We describe registering new UIDs, mapping cards to users and instant deauthorisation if a medium is lost. You will also find recommended patterns for readers and terminals from vendors our platform works with.
Mapping cards to users
A new physical medium is registered by sending the chip UID to a dedicated endpoint. After a successful map, the card works immediately for door passage and internal-credit charges within that person’s rights.
Instant block
If a card is lost or stolen, the medium can be deactivated with a single call. The block propagates to every reader and terminal within seconds, so misuse is limited to the shortest possible window.
Supported readers
The platform talks to readers that support MIFARE and EMV. You choose the hardware vendor — the API accepts a vendor-neutral format, so the terminal brand does not matter.
Webhooks and real-time events
So your apps can react at once, we offer webhooks for important events in real time — a door passage, a low credit balance, or a completed inventory in a given location.
The docs list every supported event type and the payload sent to your server. Each webhook has a unique event ID, an ISO 8601 timestamp and a payload specific to that notification type.
Failed delivery uses exponential backoff with a retry window of up to 24 hours. Your endpoint must answer HTTP 200 or the system retries.
credit.low_balance
Balance fell below the set threshold.
door.access_granted
Successful door passage.
card.deauthorized
The card was blocked.
asset.inventory_completed
Inventory completed.
credit.transaction_created
New transaction on the account.
Error states and debugging
Solid development needs a clear reason when a request fails, so the API returns standard HTTP error codes plus a detailed text description. This section is a full catalogue of error messages and how to handle them in code — for example retrying on a temporary connectivity drop.
We also provide a sandbox where you can test integrations without touching production data. The sandbox uses the same API endpoints on its own URL with fully independent datasets.
Bad Request
The request has invalid or missing fields. Check the payload against the schema in the reference.
Unauthorized
The token is missing, expired or unrecognised. Renew it via the refresh endpoint.
Forbidden
The token is valid but lacks permission for that resource. Ask an administrator to widen the scope.
Conflict
Collision — for example a duplicate UID registration or an idempotency-key conflict. Return the response from the previous successful call.
Too Many Requests
The rate limit was exceeded. Response headers include time until the quota resets. Implement exponential backoff.
Internal Server Error
Unexpected server-side error. Retry after a short pause. If it persists, contact support.
Request limits and performance
To keep the platform stable for everyone, we limit API calls over a time window (rate limiting). The docs explain how to read those limits in response headers and how to page and filter queries so you stay under them.
We also cover client-side cache use, which speeds your app and reduces server load. Paging is the default on list endpoints, with offset and limit parameters.
600
requests / window
412
remaining
epoch
quota reset
The measurement window is 60 seconds. When the limit is hit the API returns status 429 Too Many Requests together with the header Retry-After, which gives seconds until reset. Bulk-operation endpoints have a lower limit — see each reference.
JSON API Reference
The full reference lists every endpoint, parameter, data type and request/response example. It is generated from platform source and updated with each release.
Testujte bez rizika
The sandbox is available to every registered developer. It matches production API behaviour on its own URL with independent datasets, so you can test without touching live student or staff data.
Request access →Need a hand?
If the docs are unclear or you need integration advice, developer support is available in business hours. Write to the email below and we reply within one working day.
support@unhostcampus.com / martin.macek.zak@zsunhost.cz