Assessment API Documentation

Overview

This API provides endpoints to manage and interact with assessments and submissions in the system. Each API request requires an API token (assessment_api_token) which is associated with a partner in the system. The token must be provided in the Authorization header as a Bearer token.

Base URL

https://assessify.co.za

Authentication
All API requests must include the following header:
Authorization: Bearer <assessment_api_token>

If the token is invalid or missing, the API will respond with a 401 Unauthorized error.

Endpoints
1. Get All Assessments
Endpoint: /api/assessments
Method: GET
Description: Retrieves a paginated list of all assessments.
Query Parameters:

• page (optional): Page number (default: 1).
• per_page (optional): Number of records per page (default: 20).

​
{
    "total_count": 100,
    "page": 1,
    "per_page": 20,
    "records": [
        {
            "title": "Assessment 1",
            "description": "Description of assessment",​
            "state": "draft",
            "uuid": "1234-5678",
            "price": 50.0​
        },
        ...
    ]
}

2. Get a Single Assessment

Endpoint: /api/assessment/<assessment_uuid>

Method: GET

Description: Retrieves details of a single assessment.

Path Parameters:

• assessment_uuid (string): Unique identifier for the assessment.

Response:

{
    "title": "Assessment 1",
    "description": "Description of assessment",
    "state": "draft",
    "uuid": "1234-5678",
    "price": 50​.0,
    "time_limit": 30,
    "category_name": "Category 1",
    "questions": [
        {
            "title": "Question 1",
            "description": "Description of question",
            "question_type": "multiple_choice",
            "difficulty_level": "easy"
        },
        ...
    ]
}

3. Invite Participants to an Assessment

Endpoint: /api/assessment/<assessment_uuid>/invite

Method: POST

Description: Sends an assessment invitation to a list of email addresses.

Path Parameters:

• assessment_uuid (string): Unique identifier for the assessment.

Body Parameters:

• emails (string): Comma-separated list of email addresses (required).
• deadline (string): Deadline for the assessment in ISO 8601 format (YYYY-MM-DDTHH:MM) (optional).

Response:

{
    "total_count": 50,
    "page": 1,
    "per_page": 20,
    "records": [
        {
            "email": "user@example.com",
            "state": "completed",
            "scoring_percentage": 85,
            "access_token": "submission-token"
        },
        ...
    ]
}​

5. Get a Single Submission

Endpoint: /api/submission/<submission_uuid>

Method: GET

Description: Retrieves details of a single submission.

Path Parameters:

• submission_uuid (string): Unique identifier for the submission.

 {

    "assessment_id": "1234-5678",

    "email": "user@example.com",

    "state": "completed",

    "scoring_percentage": 85,

    "scoring_total": 42,

    "total_possible_score": 50,

    "scoring_success": true,

    "access_token": "submission-token",

    "difficulty_level": "medium",

    "assessment_state": "open",

    "lou": null,

    "strengths": "Analytical thinking",

    "weaknesses": "Time management",

    "areas_for_improvement": "Communication",

    "recommendations": "Focus on time-bound tasks",

    "analysis": "Detailed feedback here..."

}

Error Responses

Common Errors:

• 401 Unauthorized: Invalid or missing API token.
• 404 Not Found: Resource not found (e.g., invalid assessment_uuid or submission_uuid).
• 429 Too Many Requests: Rate limit exceeded.
• 500 Internal Server Error: Unexpected error on the server.

Rate Limiting

• Each API key is subject to rate limits to prevent abuse:
  • Per Minute Limit: Requests exceeding this limit will receive a 429 Too Many Requests error.
  • Per Hour Limit: Similar behavior for hourly limits.

Logging

Each API request is logged with the following details:

• Request method
• Request path
• Request body
• Request headers
• Remote address