Skip to main content
The Documents API handles uploading CVs and job descriptions for interview sessions. It supports multiple file formats for CVs and performs text extraction for AI analysis.

​
Endpoints

​
Get Upload Page

​
GET /session/<session_id>/upload
endpoint
Retrieve the document upload page for a session.

​
Path Parameters

​
session_id
integer
required
The unique identifier of the interview session.

​
Response

Returns an HTML page with upload forms for CV and job description.
​
session
object
Session details.
​
id
integer
Session identifier.
​
job_title
string
Job title for this session.
​
company_name
string
Company name.
​
cv_text
string | null
Extracted CV text if already uploaded.
​
job_description_text
string | null
Job description if already provided.

​
Example Request

curl -X GET https://your-domain.com/session/123/upload \
  -H "Cookie: session=your_session_cookie"

​
Error Responses

  • 403 Forbidden: “You don’t have access to this session”
  • 404 Not Found: Session does not exist

​
Upload CV

​
POST /session/<session_id>/upload-cv
endpoint
Upload a CV file for text extraction and analysis.

​
Path Parameters

​
session_id
integer
required
The unique identifier of the interview session.

​
Request Parameters

​
cv_file
file
required
The CV file to upload. Supported formats:
  • PDF (.pdf)
  • Microsoft Word (.docx)
  • Plain text (.txt)

​
Response

Redirects back to the upload page with a success or error message.
​
success
boolean
Whether the upload was successful.
​
message
string
Success or error message.
​
cv_text
string
Extracted text from the CV (minimum 50 characters required).

​
Example Request

curl -X POST https://your-domain.com/session/123/upload-cv \
  -H "Cookie: session=your_session_cookie" \
  -F "cv_file=@/path/to/resume.pdf"

​
Success Response

{
  "success": true,
  "message": "CV uploaded and processed successfully!",
  "redirect": "/session/123/upload"
}

​
Error Responses

​
ValidationError
object
Returned when the file is invalid or cannot be processed.
​
error
string
Error message.
Example Errors:
  • “No file was uploaded”
  • “CV seems too short. Please upload a complete CV (at least 50 characters)”
  • “Unsupported file format”
  • “Could not read file: [parsing error details]“

​
Upload Job Description

​
POST /session/<session_id>/upload-job
endpoint
Submit the job description text for interview preparation.

​
Path Parameters

​
session_id
integer
required
The unique identifier of the interview session.

​
Request Parameters

​
job_description
string
required
The complete job description text.
  • Minimum: 50 characters
  • Maximum: 10,000 characters

​
Response

Redirects back to the upload page with a success or error message.
​
success
boolean
Whether the submission was successful.
​
message
string
Success or error message.

​
Example Request

curl -X POST https://your-domain.com/session/123/upload-job \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -H "Cookie: session=your_session_cookie" \
  -d "job_description=We are seeking a Senior Software Engineer with 5+ years of experience in distributed systems. The ideal candidate will have strong knowledge of microservices architecture, Docker, Kubernetes, and cloud platforms..."

​
Success Response

{
  "success": true,
  "message": "Job description saved successfully!",
  "redirect": "/session/123/upload"
}

​
Error Responses

​
ValidationError
object
Returned when the job description is invalid.
​
error
string
Error message.
Example Errors:
  • “Job description cannot be empty”
  • “Job description seems too short. Please provide a complete job description (at least 50 characters)”
  • “Job description too long (max 10,000 characters)“

​
Supported CV File Formats

The API supports the following CV file formats:
​
PDF
.pdf
Portable Document Format. Text is extracted using pdfplumber.
​
Word Document
.docx
Microsoft Word document. Text is extracted using python-docx.
​
Plain Text
.txt
Plain text file with UTF-8 encoding.

​
Document Processing

​
CV Processing Pipeline

  1. Upload: File is received via multipart form-data
  2. Storage: Temporarily saved to the server’s upload folder
  3. Extraction: Text is extracted based on file format:
    • PDF: Uses pdfplumber to extract text from all pages
    • DOCX: Uses python-docx to read paragraphs and tables
    • TXT: Direct UTF-8 text reading
  4. Validation: Ensures extracted text is at least 50 characters
  5. Save: Text is stored in the session’s cv_text field
  6. Cleanup: Original file is deleted from server

​
Job Description Processing

  1. Receive: Text submitted via form field
  2. Validation:
    • Strips whitespace
    • Checks minimum length (50 characters)
    • Checks maximum length (10,000 characters)
  3. Save: Text is stored in the session’s job_description_text field

​
Validation Rules

​
CV Upload

​
File Required
validation
A file must be included in the request.
​
Minimum Length
validation
Extracted text must be at least 50 characters.
​
File Format
validation
Must be PDF, DOCX, or TXT format.

​
Job Description

​
Required
validation
Cannot be empty or whitespace-only.
​
Minimum Length
validation
Must be at least 50 characters.
​
Maximum Length
validation
Cannot exceed 10,000 characters.

​
Error Handling

​
HTTP Status Codes

  • 302 Found: Successful redirect after upload
  • 400 Bad Request: Validation error
  • 403 Forbidden: Unauthorized session access
  • 404 Not Found: Session not found
  • 500 Internal Server Error: File processing error

​
Flash Messages

Success and error messages are displayed via Flask flash messages: Success Messages:
  • “CV uploaded and processed successfully!”
  • “Job description saved successfully!”
Error Messages:
  • “No file was uploaded”
  • “CV seems too short. Please upload a complete CV (at least 50 characters)”
  • “Could not read file: [error details]”
  • “Job description cannot be empty”
  • “Job description seems too short. Please provide a complete job description (at least 50 characters)”
  • “Job description too long (max 10,000 characters)”
  • “Session not found”

​
Workflow Integration

The Documents API is the second step in the interview preparation workflow:
  1. Create Session (Sessions API)
  2. Upload Documents (Documents API) ← You are here
  3. Conduct Interview (Interviews API)
  4. Receive Feedback (Feedback API)
Both CV and job description must be uploaded before proceeding to the interview. The system checks this with the is_ready_for_interview() method and will redirect back to the upload page if either is missing.

​
Example: Complete Upload Flow

# Upload a PDF CV
curl -X POST https://your-domain.com/session/123/upload-cv \
  -H "Cookie: session=your_session_cookie" \
  -F "cv_file=@john_doe_resume.pdf"

# Response: Redirects to /session/123/upload with success message

Build docs developers (and LLMs) love

Get started for freeTalk to us