Retrieves a paginated list of interviews for your account. Supports filtering by status, date range, candidate email, and position.
Query Parameters
Pagination cursor for retrieving next page of results
Number of interviews to return per page (1-100)
Filter by interview status
scheduled: Interview is scheduled but not startedin_progress: Interview is currently activecompleted: Interview has finishedcancelled: Interview was cancelled
Filter by candidate email address
Filter by job position or role
ISO 8601 timestamp to filter interviews created after this date
ISO 8601 timestamp to filter interviews created before this date
ISO 8601 timestamp to filter interviews scheduled after this date
ISO 8601 timestamp to filter interviews scheduled before this date
Include basic result scores in the response (for completed interviews)
Response
Array of interview objects
Unique interview identifier
Candidate’s email address
Job position for the interview
Array of skills being assessed
ISO 8601 timestamp when interview is scheduled
ISO 8601 timestamp when interview was created
Basic results (when include_results=true and status=completed)
Overall interview score (0-100)
AI recommendation: hire, maybe, no_hire
Pagination information
Cursor for next page (null if no more pages)
Whether there are more results available
Total number of interviews matching filters
Examples
curl -X GET "https://backend.jobhive.ai/v1/interviews" \
-H "Authorization: Bearer YOUR_API_KEY"
{
"success": true,
"data": [
{
"id": "int_abc123def456",
"status": "completed",
"candidate_email": "[email protected]",
"position": "Full Stack Developer",
"skills": ["JavaScript", "React", "Node.js"],
"scheduled_at": "2024-01-15T15:30:00Z",
"created_at": "2024-01-15T14:30:00Z"
},
{
"id": "int_def456ghi789",
"status": "scheduled",
"candidate_email": "[email protected]",
"position": "Frontend Developer",
"skills": ["React", "TypeScript", "CSS"],
"scheduled_at": "2024-01-16T10:00:00Z",
"created_at": "2024-01-15T16:45:00Z"
}
],
"pagination": {
"next_cursor": "eyJpZCI6ImludF9kZWY0NTZnaGk3ODkifQ==",
"has_more": true,
"total_count": 156
},
"meta": {
"timestamp": "2024-01-15T20:30:00Z",
"request_id": "req_list_int_001"
}
}
Common Use Cases
Generate Hiring Reports
async function generateHiringReport(startDate, endDate) {
const interviews = await jobhive.interviews.list({
created_after: startDate,
created_before: endDate,
status: 'completed',
include_results: true,
limit: 100
});
const stats = {
total: interviews.data.length,
hired: interviews.data.filter(i => i.results.recommendation === 'hire').length,
maybe: interviews.data.filter(i => i.results.recommendation === 'maybe').length,
rejected: interviews.data.filter(i => i.results.recommendation === 'no_hire').length,
averageScore: interviews.data.reduce((sum, i) => sum + i.results.overall_score, 0) / interviews.data.length
};
return stats;
}
Monitor Interview Pipeline
def get_pipeline_status():
pipeline = {
'scheduled': client.interviews.list(status='scheduled').pagination.total_count,
'in_progress': client.interviews.list(status='in_progress').pagination.total_count,
'completed_today': len([
i for i in client.interviews.list(
status='completed',
created_after=datetime.now().date().isoformat()
).data
])
}
return pipeline
async function findTopPerformers(position, minScore = 80) {
const interviews = await jobhive.interviews.list({
position,
status: 'completed',
include_results: true,
limit: 100
});
return interviews.data
.filter(interview => interview.results.overall_score >= minScore)
.sort((a, b) => b.results.overall_score - a.results.overall_score)
.map(interview => ({
candidate: interview.candidate_email,
score: interview.results.overall_score,
date: interview.scheduled_at
}));
}
Use pagination for large result sets. The API returns a maximum of 100 interviews per request.
Combine multiple filters to create specific reports. For example, filter by position and date range to analyze hiring trends for specific roles.
