API Reference

Overview

The skillSYMS API provides programmatic access to learner management, evidence collection, assessment recording, and QCTO MIS export functionality. The API follows REST conventions and returns JSON responses.

Base URL:

https://cloud.skillsyms.com/api/v1

Authentication

The skillSYMS API uses API keys for authentication. Include your API key in the Authorization header with the Bearer scheme:

Authorization: Bearer your_api_key_here

API keys are scoped to a tenant and have specific permissions. You can generate API keys from the Settings page in the skillSYMS dashboard.

Rate Limits

API requests are rate limited to ensure fair usage:

Plan	Requests/minute	Requests/day
Starter	60	1,000
Professional	300	10,000
Enterprise	1,000	Unlimited

Rate limit headers are included in every response:

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 45
X-RateLimit-Reset: 1702483200

Error Format

All API errors return a consistent JSON structure with an error code, message, and optional details:

{
  "error": {
    "code": "validation_error",
    "message": "Invalid request body",
    "details": [
      {
        "field": "email",
        "message": "Invalid email format"
      }
    ]
  }
}

Common error codes:

Code	HTTP Status	Description
unauthorized	401	Invalid or missing API key
forbidden	403	Insufficient permissions
not_found	404	Resource not found
validation_error	422	Invalid request data
rate_limited	429	Too many requests
internal_error	500	Server error

Pagination

List endpoints support cursor-based pagination using limit and cursor parameters:

GET /api/v1/learners?limit=20&cursor=abc123

Responses include pagination metadata:

{
  "data": [...],
  "pagination": {
    "hasMore": true,
    "nextCursor": "def456",
    "total": 150
  }
}

Endpoints

Learners

Method	Endpoint	Description
GET	/learners	List all learners
POST	/learners	Create a learner
GET	/learners/:id	Get learner details
PATCH	/learners/:id	Update learner
DELETE	/learners/:id	Delete learner (POPIA)

Example: Create Learner

POST /api/v1/learners
Content-Type: application/json

{
  "firstName": "Thabo",
  "lastName": "Mokoena",
  "idNumber": "9001015800088",
  "email": "thabo@example.co.za",
  "mobile": "+27821234567"
}

Enrolments

Method	Endpoint	Description
GET	/enrolments	List all enrolments
POST	/enrolments	Create an enrolment
GET	/enrolments/:id	Get enrolment details
PATCH	/enrolments/:id/status	Update enrolment status

Assessments

Method	Endpoint	Description
GET	/assessments	List assessments
POST	/assessments	Record assessment
GET	/assessments/:id	Get assessment details

Evidence

Method	Endpoint	Description
GET	/evidence	List evidence files
POST	/evidence/upload	Get upload URL
GET	/evidence/:id	Get evidence metadata
GET	/evidence/:id/download	Get download URL

Exports

Method	Endpoint	Description
POST	/exports/qcto01	Generate QCTO01 export
POST	/exports/qcto02	Generate QCTO02 export
GET	/exports/:id	Get export status
GET	/exports/:id/download	Download export file

Webhooks

Planned webhook events:

• learner.created — New learner registered
• enrolment.status_changed — Enrolment status updated
• assessment.completed — Assessment recorded
• evidence.uploaded — Evidence file uploaded
• export.completed — Export file ready