REST API (v1)
Alle primaire resources: organisaties, gebruikers, cursussen, trajecten, inschrijvingen, certificaten, attestaties. Getypeerde OpenAPI 3.1-spec op /api/openapi.json. Rate-limited per tenant (ruim bemeten).
Ontwikkelaars
Een LMS dat jouw stack spreekt
ColPort Hall heeft standaard een getypeerde REST API, ondertekende webhooks, native xAPI/Tin Can-uitstoot en OIDC SSO. Elk endpoint is gedocumenteerd in OpenAPI 3.1. Elke klant kan gratis een sandbox-tenant aanvragen.
Kern-API's
Vier manieren om te integreren
Webhooks
Ondertekende webhooks (HMAC-SHA256) bij elke belangrijke gebeurtenis: enrolment.created, course.completed, certificate.issued, compliance.gap_detected. 72 uur lang opnieuw geprobeerd met exponentiële back-off.
xAPI-statementstroom
Elke leergebeurtenis genereert in realtime xAPI-statements. Stream ze naar je eigen LRS via de uitgaande webhook of poll het xAPI GET-endpoint. SCORM-runtime-events worden ook vertaald naar xAPI.
OIDC SSO + HR-webhook
OIDC single sign-on met voorinstellingen voor Microsoft Entra ID, Google Workspace en Okta, of elke OpenID Connect-provider. Een HR-webhook, ondertekend met HMAC-SHA256, ontvangt employee.hired- en employee.updated-events.
Snelstart
Je eerste API-aanroep, ~60 seconden
Na het aanmaken van je sandbox ontvang je een tenant-URL en een persoonlijk API-token. Vervang
$TOKEN en $TENANT hieronder. Deze aanroep toont de eerste tien cursussen in je tenant.curl -X GET "https://$TENANT.hall.colport.io/api/v1/courses?limit=10" \
-H "Authorization: Bearer $TOKEN" \
-H "Accept: application/json"
# Response (trimmed):
# {
# "data": [
# {
# "id": "crs_01H...",
# "title": "GDPR awareness 2026",
# "status": "PUBLISHED",
# "durationMinutes": 25,
# "enrollments_count": 184,
# "createdAt": "2026-01-14T09:42:00Z"
# }
# ],
# "pagination": { "nextCursor": null, "limit": 10 }
# }xAPI-voorbeeld
Hoe een leergebeurtenis eruitziet
Telkens wanneer een cursist een cursus afrondt, genereert Hall een xAPI-statement. Stream deze naar je LRS, datawarehouse of downstream-analyse, wat je systeem ook aan JSON-LD verwerkt.
POST https://your-lrs.example.com/xapi/statements
{
"actor": {
"account": { "homePage": "https://hall.colport.io", "name": "usr_01H..." },
"name": "Jan de Vries"
},
"verb": {
"id": "http://adlnet.gov/expapi/verbs/completed",
"display": { "en": "completed" }
},
"object": {
"id": "https://hall.colport.io/courses/crs_01H...",
"definition": {
"name": { "en": "GDPR awareness 2026" },
"type": "http://adlnet.gov/expapi/activities/course"
}
},
"result": { "score": { "scaled": 0.92, "raw": 46, "max": 50 }, "completion": true, "success": true },
"timestamp": "2026-04-21T14:22:18Z"
}Limieten + conventies
Wat je moet weten om tegen Hall te bouwen
Ratelimieten
1.000 verzoeken/minuut/tenant op REST. 10.000 statements/minuut op xAPI. Webhook-retries tellen niet mee voor je quotum. Enterprise-abonnement verhoogt het plafond.
Versiebeheer
v1 is stabiel. Breaking changes verschijnen als v2 met een parallel-run-periode van 12 maanden. Deprecaties worden 90 dagen van tevoren aangekondigd met een migratiehandleiding.
Authenticatie
Bearer-tokens voor server-naar-server. PAT's (persoonlijke toegangstokens) voor integraties die je voor je eigen organisatie bouwt. OAuth 2.0 voor door eindgebruikers geautoriseerde derde partijen (Enterprise).
Idempotentie
Er is geen Idempotency-Key-header. Twee endpoints kunnen veilig worden herhaald: POST /api/v1/users en POST /api/v1/enrollments geven het lid of de inschrijving terug die al bestaat, met created: false. Een gedeactiveerd lid is de uitzondering: het inschrijven van zo'n lid geeft elke keer 410 deactivated. Webhook-leveringen hebben geen vaste event-ID: X-ColPort-Delivery is bij elke poging nieuw, herhaalpogingen inbegrepen.
Referentie
Waar de documentatie staat
OpenAPI 3.1-spec
Beschikbaar op /api/openapi.json bij elke tenant. Genereert via openapi-generator een getypeerde client in elke grote taal.
Webhook-eventcatalogus
Live bijgewerkte catalogus van elk webhookevent met payload-schema's. Gelinkt vanaf de admin-integratiespagina.
xAPI-profiel
ColPort Hall genereert een gedocumenteerd xAPI-profiel: verb-extensies, context-extensies, activiteitstypen. Handig als je normaliseert naar een gedeelde LRS over meerdere tools heen.
Sandbox-tenants
Gratis sandbox-tenant (onbeperkt aantal testplekken, volledige functieset, wekelijks gereset) op aanvraag. Ideaal voor CI-integratietests.
Klaar om te bouwen?
Mail devs@colport.io met je use case en een globale architectuur. We leveren sandbox-inloggegevens binnen 1 werkdag.
Demo aanvragen