The Positions API enables you to manage job positions, upload candidate resumes, invite candidates to assessments, and retrieve comprehensive results and analytics.
Available Endpoints
Position Management
| Endpoint | Method | Description |
|---|
/positions/{position_id} | GET | Get position information with candidates |
/positions/{position_id}/upload-resume | POST | Upload a resume for a position |
/positions/retrieve-ai-score | POST | Get AI Score for a resume |
Candidate Invitation & Management
| Endpoint | Method | Description |
|---|
/positions/invite/{position_id} | POST | Invite a candidate to a position |
/positions/re-invite/{position_id}/{candidate_id} | POST | Re-send invitation to a candidate |
/positions/{position_id}/{candidate_id}/status | PUT | Change candidate status in the position |
Results & Analytics
| Endpoint | Method | Description |
|---|
/positions/{position_id}/{candidate_id}/results | GET | Get candidate results for a specific position |
/positions/{position_id}/{candidate_id}/videos | GET | Get all video files for a candidate's test |
/positions/{position_id}/{candidate_id}/videos/{video_id}/download | GET | Download a specific video file |
Position Workflow
Standard Assessment Process
- Resume Upload: Upload candidate resumes to specific positions using the upload endpoint
- AI Analysis: Automatic resume parsing and skill extraction occurs after upload
- Candidate Invitation: Send email invitations to candidates using the invite endpoint
- Assessment Completion: Candidates complete tests and assessments through the platform
- Status Management: Update candidate status through hiring pipeline using the status endpoint
- Results Retrieval: Access scores, detailed results, and video recordings through results endpoints
Upload Options
With Candidate Email
- Links resume to existing candidate or creates new candidate record
- Associates candidate with the position automatically
- Triggers AI processing for resume analysis
Without Candidate Email
- Creates placeholder candidate record
- AI processes resume and extracts candidate information
- Candidate details filled in during processing
Candidate Status Management
Available Status Values
| Status | Description | Use Case |
|---|
Invited | Candidate has been invited but hasn't started | Initial invitation sent |
In Progress | Candidate has started the assessment | Assessment in progress |
Completed | Candidate has finished the assessment | Ready for review |
Rejected | Candidate has been rejected | Not moving forward |
Interviewing | Candidate is in interview phase | Moving to next stage |
Hired | Candidate has been hired | Successful completion |
Status Updates
- Status changes are tracked with timestamps
- Use the PUT status endpoint to update candidate progress
- Status updates help track candidates through your hiring pipeline
File Upload Support
- PDF documents
- Microsoft Word (.doc, .docx)
Upload Process
- Files are validated automatically upon upload
- Text content is extracted for AI analysis
- Resume data is parsed and structured for easy access
- AI generates candidate scores based on position requirements
Results and Analytics
Test Results
- Access overall scores across all tests
- Get individual test performance data
- View detailed question-level results including candidate answers and correctness
Video Recordings
- Retrieve video files recorded during assessments (if enabled)
- Access transcriptions and language analysis
- Download individual video files for detailed review