Trials API

Overview

The Trials API manages trial periods where candidates work on real tasks before a final hiring decision. This is a key differentiator of the Hireable platform.

Endpoints

Method	Endpoint	Description	Permission
GET	`/api/trials`	List trials	`trials:read`
GET	`/api/trials/:id`	Get trial details	`trials:read`
POST	`/api/trials`	Create trial	`trials:write`
PATCH	`/api/trials/:id`	Update trial	`trials:manage`
POST	`/api/trials/:id/tasks`	Add task	`trials:manage`
PATCH	`/api/trials/:id/tasks/:taskId`	Update task	`trials:read`
POST	`/api/trials/:id/feedback`	Submit feedback	`trials:manage`

Trial Status Flow

scheduled → active → completed
              ↓
          cancelled

Status	Description
`scheduled`	Trial dates set, not yet started
`active`	Trial in progress
`completed`	Trial finished, feedback submitted
`cancelled`	Trial cancelled

List Trials

Get trials with optional filters.

Request

GET /api/trials?status=active
Authorization: Bearer <token>

Query Parameters

Parameter	Type	Description
`status`	string	Filter by status
`jobId`	string	Filter by job
`page`	number	Page number
`limit`	number	Items per page

Response

{
  "data": [
    {
      "id": "trial_123",
      "job": {
        "id": "job_456",
        "title": "Senior Software Engineer"
      },
      "talent": {
        "id": "user_789",
        "firstName": "John",
        "lastName": "Doe"
      },
      "employer": {
        "id": "user_101",
        "firstName": "Jane",
        "lastName": "Smith"
      },
      "status": "active",
      "startDate": "2024-01-20T09:00:00Z",
      "endDate": "2024-01-27T18:00:00Z",
      "tasks": [
        {
          "id": "task_1",
          "title": "Build login page",
          "completed": true
        }
      ]
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 10,
    "total": 5,
    "totalPages": 1
  }
}

Get Trial Details

Get detailed information about a specific trial.

Request

GET /api/trials/trial_123
Authorization: Bearer <token>

Response

{
  "id": "trial_123",
  "job": {
    "id": "job_456",
    "title": "Senior Software Engineer",
    "company": {
      "id": "company_789",
      "name": "Tech Corp"
    }
  },
  "talent": {
    "id": "user_789",
    "firstName": "John",
    "lastName": "Doe",
    "email": "john@example.com"
  },
  "employer": {
    "id": "user_101",
    "firstName": "Jane",
    "lastName": "Smith"
  },
  "status": "active",
  "startDate": "2024-01-20T09:00:00Z",
  "endDate": "2024-01-27T18:00:00Z",
  "tasks": [
    {
      "id": "task_1",
      "title": "Build login page",
      "description": "Create a responsive login page with...",
      "completed": true,
      "completedAt": "2024-01-22T15:30:00Z"
    },
    {
      "id": "task_2",
      "title": "Implement API integration",
      "description": "Connect the frontend to...",
      "completed": false
    }
  ],
  "feedback": null
}

Create Trial

Create a new trial for a candidate (employer only).

Request

POST /api/trials
Authorization: Bearer <token>
Content-Type: application/json
 
{
  "jobId": "job_456",
  "talentId": "user_789",
  "startDate": "2024-01-20T09:00:00Z",
  "endDate": "2024-01-27T18:00:00Z",
  "tasks": [
    {
      "title": "Build login page",
      "description": "Create a responsive login page with form validation"
    },
    {
      "title": "Implement API integration",
      "description": "Connect the frontend to the backend API"
    }
  ]
}

Response

{
  "id": "trial_123",
  "status": "scheduled",
  "startDate": "2024-01-20T09:00:00Z",
  "endDate": "2024-01-27T18:00:00Z"
}

Update Trial

Update trial status or dates.

Request

PATCH /api/trials/trial_123
Authorization: Bearer <token>
Content-Type: application/json
 
{
  "status": "active"
}

Response

{
  "id": "trial_123",
  "status": "active",
  "updatedAt": "2024-01-20T09:00:00Z"
}

Add Task

Add a new task to an active trial.

Request

POST /api/trials/trial_123/tasks
Authorization: Bearer <token>
Content-Type: application/json
 
{
  "title": "Write unit tests",
  "description": "Add unit tests for the login component"
}

Response

{
  "id": "task_3",
  "title": "Write unit tests",
  "description": "Add unit tests for the login component",
  "completed": false
}

Update Task

Mark a task as completed (talent) or update details (employer).

Request (Talent - Complete Task)

PATCH /api/trials/trial_123/tasks/task_1
Authorization: Bearer <token>
Content-Type: application/json
 
{
  "completed": true
}

Response

{
  "id": "task_1",
  "completed": true,
  "completedAt": "2024-01-22T15:30:00Z"
}

Submit Feedback

Submit final feedback after trial completion (employer only).

Request

POST /api/trials/trial_123/feedback
Authorization: Bearer <token>
Content-Type: application/json
 
{
  "rating": 4,
  "comment": "John demonstrated excellent technical skills...",
  "strengths": [
    "Strong React knowledge",
    "Good communication",
    "Meets deadlines"
  ],
  "improvements": [
    "Could improve testing practices"
  ]
}

Response

{
  "id": "trial_123",
  "status": "completed",
  "feedback": {
    "rating": 4,
    "comment": "John demonstrated excellent technical skills...",
    "strengths": ["Strong React knowledge", "Good communication", "Meets deadlines"],
    "improvements": ["Could improve testing practices"]
  }
}

Types

type TrialStatus = "scheduled" | "active" | "completed" | "cancelled";
 
interface Trial {
  id: string;
  job: Job;
  talent: User;
  employer: User;
  status: TrialStatus;
  startDate: string;
  endDate: string;
  tasks: TrialTask[];
  feedback?: TrialFeedback;
}
 
interface TrialTask {
  id: string;
  title: string;
  description: string;
  completed: boolean;
  completedAt?: string;
}
 
interface TrialFeedback {
  rating: number;        // 1-5
  comment: string;
  strengths: string[];
  improvements: string[];
}

Frontend Integration

import { trialsService } from "@/features/trials";
 
// List my trials
const trials = await trialsService.getMyTrials();
 
// Get trial details
const trial = await trialsService.getById("trial_123");
 
// Create trial (employer)
const newTrial = await trialsService.create({
  jobId: "job_456",
  talentId: "user_789",
  startDate: "2024-01-20",
  endDate: "2024-01-27",
  tasks: [{ title: "...", description: "..." }],
});
 
// Complete task (talent)
await trialsService.completeTask("trial_123", "task_1");
 
// Submit feedback (employer)
await trialsService.submitFeedback("trial_123", {
  rating: 4,
  comment: "...",
  strengths: ["..."],
  improvements: ["..."],
});

Permission Matrix

Action	ADMIN	EMPLOYER	TALENT
View trials	✓	✓ (own)	✓ (own)
Create trial	✓	✓	-
Update trial	✓	✓ (own)	-
Add tasks	✓	✓ (own)	-
Complete tasks	✓	-	✓ (own)
Submit feedback	✓	✓ (own)	-

On this page