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