APPRAISIUM Documentation

Login Endpoint

Authenticate and receive a JWT token for API access:

Content-Type: application/json

{
    "email": "user@example.com",
    "password": "password123"
}

Response Format

{
    "success": true,
    "message": "Login successful",
    "data": {
        "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
        "user": {
            "id": 1,
            "email": "user@example.com",
            "name": "John Doe",
            "role": "employee"
        },
        "expires_in": 3600
    }
}

Using the Token

Include the JWT token in the Authorization header for all subsequent requests:

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Token Refresh

Refresh your token before it expires:

Authorization: Bearer your_current_token

{
    "refresh_token": "your_refresh_token"
}

User Management

GET    /api/v1/users              # List all users
POST   /api/v1/users              # Create new user
GET    /api/v1/users/{id}         # Get user by ID
PUT    /api/v1/users/{id}         # Update user
DELETE /api/v1/users/{id}         # Delete user
GET    /api/v1/users/profile      # Get current user profile
PUT    /api/v1/users/profile      # Update current user profile

Organization Management

GET    /api/v1/organizations     # List organizations
POST   /api/v1/organizations     # Create organization
GET    /api/v1/organizations/{id} # Get organization
PUT    /api/v1/organizations/{id} # Update organization
DELETE /api/v1/organizations/{id} # Delete organization

Department Management

GET    /api/v1/departments       # List departments
POST   /api/v1/departments       # Create department
GET    /api/v1/departments/{id}  # Get department
PUT    /api/v1/departments/{id}  # Update department
DELETE /api/v1/departments/{id}  # Delete department

Key Result Areas (KRA)

GET    /api/v1/kra               # List KRAs
POST   /api/v1/kra               # Create KRA
GET    /api/v1/kra/{id}          # Get KRA
PUT    /api/v1/kra/{id}          # Update KRA
DELETE /api/v1/kra/{id}          # Delete KRA
GET    /api/v1/kra/{id}/sub-initiatives # Get sub-initiatives

Performance Appraisals

GET    /api/v1/appraisals        # List appraisals
POST   /api/v1/appraisals        # Create appraisal
GET    /api/v1/appraisals/{id}   # Get appraisal
PUT    /api/v1/appraisals/{id}   # Update appraisal
DELETE /api/v1/appraisals/{id}   # Delete appraisal
POST   /api/v1/appraisals/{id}/submit # Submit appraisal

Task Management

GET    /api/v1/assignments       # List tasks
POST   /api/v1/assignments       # Create task
GET    /api/v1/assignments/{id}  # Get task
PUT    /api/v1/assignments/{id}  # Update task
DELETE /api/v1/assignments/{id}  # Delete task
PUT    /api/v1/assignments/{id}/progress # Update progress

Reports

GET    /api/v1/reports           # List available reports
POST   /api/v1/reports/generate  # Generate report
GET    /api/v1/reports/{id}      # Get report
GET    /api/v1/reports/{id}/download # Download report

Success Response

{
    "success": true,
    "message": "Operation completed successfully",
    "data": {
        // Response data here
    },
    "pagination": {
        "page": 1,
        "page_size": 10,
        "total": 100,
        "total_pages": 10
    }
}

Error Response

{
    "success": false,
    "message": "Error description",
    "error_code": "ERROR_CODE",
    "errors": [
        {
            "field": "field_name",
            "message": "Field-specific error message"
        }
    ]
}

Pagination

List endpoints support pagination with the following query parameters:

• page: Page number (default: 1)
• page_size: Items per page (default: 10, max: 100)
• sort: Sort field (e.g., "name", "-created_at")
• filter: Filter criteria (varies by endpoint)

HTTP Status Codes

• 200 OK: Request successful
• 201 Created: Resource created successfully
• 400 Bad Request: Invalid request data
• 401 Unauthorized: Authentication required
• 403 Forbidden: Insufficient permissions
• 404 Not Found: Resource not found
• 422 Unprocessable Entity: Validation errors
• 500 Internal Server Error: Server error

Validation Errors

{
    "success": false,
    "message": "Validation failed",
    "error_code": "VALIDATION_ERROR",
    "errors": [
        {
            "field": "email",
            "message": "Email is required"
        },
        {
            "field": "password",
            "message": "Password must be at least 8 characters"
        }
    ]
}

Common Error Codes

• INVALID_CREDENTIALS: Login failed
• TOKEN_EXPIRED: JWT token has expired
• INSUFFICIENT_PERMISSIONS: User lacks required permissions
• RESOURCE_NOT_FOUND: Requested resource doesn't exist
• VALIDATION_ERROR: Request data validation failed
• RATE_LIMIT_EXCEEDED: Too many requests

Rate Limits

• Authentication: 5 requests per minute per IP
• General API: 1000 requests per hour per user
• Report Generation: 10 requests per hour per user
• Bulk Operations: 5 requests per hour per user

Rate Limit Headers

Rate limit information is included in response headers:

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 999
X-RateLimit-Reset: 1640995200

Rate Limit Exceeded

{
    "success": false,
    "message": "Rate limit exceeded",
    "error_code": "RATE_LIMIT_EXCEEDED",
    "retry_after": 3600
}