HRM Module - Document Management
Overview
The HRM (Human Resource Management) module provides comprehensive document management capabilities for employee lifecycle, leave management, and performance tracking. This guide covers document handling for three key HRM entities: Employees, Leave Requests, and Performance Reviews.
HRM Document Capabilities:
- Employee onboarding and personnel files
- Contract and certification management
- Leave request supporting documents
- Performance review documentation
- Compliance and regulatory documentation
- Sensitive HR data with strict access controls
Supported Entities
The HRM module supports document management for these entities:
| Entity | Purpose | Common Document Types | Max File Size |
|---|---|---|---|
| Employee | Personnel records and HR files | Contracts, IDs, certifications, tax forms | 50 MB |
| Leave Request | Leave supporting documentation | Medical certificates, approvals, doctor notes | 50 MB |
| Performance Review | Performance documentation | Reviews, feedback, goals, assessments | 50 MB |
Employee Documents
Overview
Employee documents include employment contracts, ID documents, resumes, certifications, tax forms, emergency contacts, performance reviews, disciplinary records, training certificates, background checks, and references. These documents form the complete personnel file for each employee.
Endpoint: /api/v1/hrm/employees/{employeeId}/documents
Supported Tags
| Tag | Purpose | Example Use Case |
|---|---|---|
contract | Employment contracts | Offer letters, employment agreements |
id_document | Identification documents | Passport, driver's license, work permits |
resume | CV/Resume | Employee resumes, CVs |
certification | Professional certifications | Professional licenses, certifications |
tax_form | Tax documents | W-4, W-2, tax forms |
emergency_contact | Emergency contact information | Emergency contact forms |
performance_review | Performance reviews | Annual reviews, evaluations |
disciplinary | Disciplinary records | Warning letters, disciplinary actions |
training | Training certificates | Training completion certificates |
background_check | Background check results | Background screening reports |
reference | Reference letters | Employment references |
Common Scenarios
Scenario 1: Employee Onboarding
Complete new hire documentation:
# Upload employment contract
curl -X POST https://api.crm.test/api/v1/hrm/employees/30001/documents \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
-F "file=@employment_contract.pdf" \
-F "type=contract" \
-F "tags[]=contract" \
-F "name=Employment Contract - Full-Time" \
-F "description=Employment agreement effective 2025-01-15" \
-F "is_public=false" \
-F "is_sensitive=true"
# Upload ID documents
curl -X POST https://api.crm.test/api/v1/hrm/employees/30001/documents \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
-F "file=@passport.pdf" \
-F "type=form" \
-F "tags[]=id_document" \
-F "name=Passport Copy - Jane Smith" \
-F "is_public=false" \
-F "is_sensitive=true" \
-F "expires_at=2030-06-15T23:59:59Z"
# Upload tax forms
curl -X POST https://api.crm.test/api/v1/hrm/employees/30001/documents \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
-F "file=@w4_form.pdf" \
-F "type=form" \
-F "tags[]=tax_form" \
-F "name=W-4 Tax Withholding Form" \
-F "is_public=false" \
-F "is_sensitive=true"
# Upload emergency contact form
curl -X POST https://api.crm.test/api/v1/hrm/employees/30001/documents \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
-F "file=@emergency_contact.pdf" \
-F "type=form" \
-F "tags[]=emergency_contact" \
-F "name=Emergency Contact Information" \
-F "is_public=false" \
-F "is_sensitive=true"
# Upload background check
curl -X POST https://api.crm.test/api/v1/hrm/employees/30001/documents \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
-F "file=@background_check.pdf" \
-F "type=report" \
-F "tags[]=background_check" \
-F "name=Background Check Report" \
-F "description=Pre-employment background screening" \
-F "is_public=false" \
-F "is_sensitive=true"Scenario 2: Professional Certifications
Manage employee certifications and licenses:
# Upload professional certification
curl -X POST https://api.crm.test/api/v1/hrm/employees/30002/documents \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
-F "file=@pmp_certification.pdf" \
-F "type=certificate" \
-F "tags[]=certification" \
-F "name=PMP Certification - Project Management Professional" \
-F "description=Certified Project Management Professional" \
-F "is_public=false" \
-F "expires_at=2028-08-30T23:59:59Z"
# Upload professional license
curl -X POST https://api.crm.test/api/v1/hrm/employees/30002/documents \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
-F "file=@professional_license.pdf" \
-F "type=license" \
-F "tags[]=certification" \
-F "name=State Professional Engineering License" \
-F "is_public=false" \
-F "is_sensitive=true" \
-F "expires_at=2027-12-31T23:59:59Z"Scenario 3: Training Documentation
Track employee training completion:
# Upload training certificate
curl -X POST https://api.crm.test/api/v1/hrm/employees/30003/documents \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
-F "file=@safety_training.pdf" \
-F "type=certificate" \
-F "tags[]=training" \
-F "name=Workplace Safety Training Certificate" \
-F "description=Annual safety training completed" \
-F "is_public=false" \
-F "expires_at=2026-01-31T23:59:59Z"
# Upload skills training completion
curl -X POST https://api.crm.test/api/v1/hrm/employees/30003/documents \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
-F "file=@leadership_training.pdf" \
-F "type=certificate" \
-F "tags[]=training" \
-F "name=Leadership Development Program Certificate" \
-F "is_public=false"Scenario 4: Performance Reviews
Store performance review documents:
# Upload annual performance review
curl -X POST https://api.crm.test/api/v1/hrm/employees/30004/documents \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
-F "file=@annual_review_2024.pdf" \
-F "type=report" \
-F "tags[]=performance_review" \
-F "name=Annual Performance Review 2024" \
-F "description=Year-end performance evaluation" \
-F "is_public=false" \
-F "is_sensitive=true"Scenario 5: Disciplinary Actions
Document disciplinary procedures:
# Upload warning letter
curl -X POST https://api.crm.test/api/v1/hrm/employees/30005/documents \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
-F "file=@written_warning.pdf" \
-F "type=legal" \
-F "tags[]=disciplinary" \
-F "name=Written Warning - Attendance" \
-F "description=Formal written warning for attendance policy violation" \
-F "is_public=false" \
-F "is_sensitive=true"
# Upload improvement plan
curl -X POST https://api.crm.test/api/v1/hrm/employees/30005/documents \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
-F "file=@performance_improvement_plan.pdf" \
-F "type=report" \
-F "tags[]=disciplinary" \
-F "name=Performance Improvement Plan" \
-F "description=90-day performance improvement plan" \
-F "is_public=false" \
-F "is_sensitive=true"Validation Rules
File Requirements:
- Maximum size: 50 MB
- All file types accepted (PDFs, images for scanned documents)
Required Fields:
file- The document filetype- Document type
Optional Fields:
tags- Array of tags (validated against allowed list)name,descriptionis_public- Default: false (all employee documents should be private)is_sensitive- Recommended: true (all personnel files are sensitive)expires_at- Important for IDs, certifications, work permits
Leave Request Documents
Overview
Leave Request documents include medical certificates, doctor's notes, supporting documents, approval forms, emergency documents, and prescriptions. These documents justify leave requests and support absence management.
Endpoint: /api/v1/hrm/leave/{leaveId}/documents
Supported Tags
| Tag | Purpose | Example Use Case |
|---|---|---|
medical_certificate | Medical certificates | Doctor's medical certificates |
supporting_document | Supporting documentation | Travel documents, death certificates |
approval | Approval documents | Manager approvals, HR approvals |
emergency_document | Emergency-related documents | Emergency situation proof |
doctor_note | Doctor's notes | Medical notes from physician |
prescription | Medical prescriptions | Prescription documents |
Common Scenarios
Scenario 1: Sick Leave Request
Document sick leave with medical certificate:
# Upload medical certificate
curl -X POST https://api.crm.test/api/v1/hrm/leave/40001/documents \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
-F "file=@medical_certificate.pdf" \
-F "type=certificate" \
-F "tags[]=medical_certificate" \
-F "tags[]=doctor_note" \
-F "name=Medical Certificate - Dr. Johnson" \
-F "description=Sick leave medical certification for flu" \
-F "is_public=false" \
-F "is_sensitive=true"
# Upload prescription (if applicable)
curl -X POST https://api.crm.test/api/v1/hrm/leave/40001/documents \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
-F "file=@prescription.pdf" \
-F "type=form" \
-F "tags[]=prescription" \
-F "name=Medical Prescription" \
-F "is_public=false" \
-F "is_sensitive=true"Scenario 2: Extended Medical Leave
Document extended medical leave with multiple documents:
# Upload initial medical certificate
curl -X POST https://api.crm.test/api/v1/hrm/leave/40002/documents \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
-F "file=@medical_cert_initial.pdf" \
-F "type=certificate" \
-F "tags[]=medical_certificate" \
-F "name=Medical Certificate - Initial Diagnosis" \
-F "description=Surgery recommendation and recovery period" \
-F "is_public=false" \
-F "is_sensitive=true"
# Upload follow-up doctor's note
curl -X POST https://api.crm.test/api/v1/hrm/leave/40002/documents \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
-F "file=@doctor_note_followup.pdf" \
-F "type=report" \
-F "tags[]=doctor_note" \
-F "tags[]=supporting_document" \
-F "name=Follow-up Doctor's Note" \
-F "description=Post-surgery follow-up and recovery timeline" \
-F "is_public=false" \
-F "is_sensitive=true"
# Upload manager approval
curl -X POST https://api.crm.test/api/v1/hrm/leave/40002/documents \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
-F "file=@leave_approval.pdf" \
-F "type=form" \
-F "tags[]=approval" \
-F "name=Extended Leave Approval - Manager" \
-F "is_public=false" \
-F "is_sensitive=true"Scenario 3: Bereavement Leave
Document bereavement leave with supporting documents:
# Upload death certificate
curl -X POST https://api.crm.test/api/v1/hrm/leave/40003/documents \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
-F "file=@death_certificate.pdf" \
-F "type=certificate" \
-F "tags[]=supporting_document" \
-F "tags[]=emergency_document" \
-F "name=Death Certificate - Family Member" \
-F "is_public=false" \
-F "is_sensitive=true"Scenario 4: Maternity/Paternity Leave
Document parental leave:
# Upload doctor's certificate (expected due date)
curl -X POST https://api.crm.test/api/v1/hrm/leave/40004/documents \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
-F "file=@maternity_certificate.pdf" \
-F "type=certificate" \
-F "tags[]=medical_certificate" \
-F "name=Maternity Certificate - Expected Due Date" \
-F "is_public=false" \
-F "is_sensitive=true"
# Upload birth certificate (after birth)
curl -X POST https://api.crm.test/api/v1/hrm/leave/40004/documents \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
-F "file=@birth_certificate.pdf" \
-F "type=certificate" \
-F "tags[]=supporting_document" \
-F "name=Birth Certificate" \
-F "is_public=false" \
-F "is_sensitive=true"Validation Rules
File Requirements:
- Maximum size: 50 MB
- All file types accepted (typically PDFs, scanned documents)
Required Fields:
file,type
Optional Fields:
tags,name,descriptionis_public- Default: false (all leave documents should be private)is_sensitive- Recommended: true (medical information is sensitive)expires_at- Optional for time-limited medical certificates
Performance Review Documents
Overview
Performance Review documents include performance reviews, feedback forms, goal-setting documents, improvement plans, achievement records, self-assessments, manager feedback, and peer feedback. These documents support the performance management cycle.
Endpoint: /api/v1/hrm/performance/{performanceId}/documents
Supported Tags
| Tag | Purpose | Example Use Case |
|---|---|---|
review | Performance reviews | Annual/quarterly reviews |
feedback | Feedback documents | General feedback forms |
goal | Goal-setting documents | Performance goals, objectives |
improvement_plan | Improvement plans | Performance improvement plans (PIP) |
achievement | Achievement records | Awards, recognition documents |
self_assessment | Self-assessment forms | Employee self-evaluations |
manager_feedback | Manager feedback | Manager's evaluation |
peer_feedback | Peer feedback | 360-degree peer reviews |
quarterly | Quarterly reviews | Q1, Q2, Q3, Q4 reviews |
annual | Annual reviews | Year-end performance reviews |
Common Scenarios
Scenario 1: Annual Performance Review
Complete annual review documentation:
# Upload self-assessment
curl -X POST https://api.crm.test/api/v1/hrm/performance/50001/documents \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
-F "file=@self_assessment_2024.pdf" \
-F "type=report" \
-F "tags[]=self_assessment" \
-F "tags[]=annual" \
-F "name=Self-Assessment 2024" \
-F "description=Employee self-evaluation for annual review" \
-F "is_public=false" \
-F "is_sensitive=true"
# Upload manager feedback
curl -X POST https://api.crm.test/api/v1/hrm/performance/50001/documents \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
-F "file=@manager_review.pdf" \
-F "type=report" \
-F "tags[]=manager_feedback" \
-F "tags[]=review" \
-F "tags[]=annual" \
-F "name=Manager Review 2024" \
-F "description=Manager's performance evaluation" \
-F "is_public=false" \
-F "is_sensitive=true"
# Upload peer feedback (360 review)
curl -X POST https://api.crm.test/api/v1/hrm/performance/50001/documents \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
-F "file=@peer_feedback.pdf" \
-F "type=report" \
-F "tags[]=peer_feedback" \
-F "tags[]=feedback" \
-F "name=Peer Feedback Summary 2024" \
-F "description=360-degree peer review compilation" \
-F "is_public=false" \
-F "is_sensitive=true"
# Upload final review document
curl -X POST https://api.crm.test/api/v1/hrm/performance/50001/documents \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
-F "file=@final_review_2024.pdf" \
-F "type=report" \
-F "tags[]=review" \
-F "tags[]=annual" \
-F "name=Final Performance Review 2024" \
-F "description=Completed annual performance review with ratings" \
-F "is_public=false" \
-F "is_sensitive=true"Scenario 2: Quarterly Check-ins
Document quarterly performance check-ins:
# Upload Q1 review
curl -X POST https://api.crm.test/api/v1/hrm/performance/50002/documents \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
-F "file=@q1_review.pdf" \
-F "type=report" \
-F "tags[]=review" \
-F "tags[]=quarterly" \
-F "tags[]=manager_feedback" \
-F "name=Q1 Performance Check-in 2025" \
-F "is_public=false" \
-F "is_sensitive=true"Scenario 3: Goal Setting and Tracking
Document performance goals:
# Upload annual goals
curl -X POST https://api.crm.test/api/v1/hrm/performance/50003/documents \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
-F "file=@goals_2025.pdf" \
-F "type=report" \
-F "tags[]=goal" \
-F "name=Performance Goals 2025" \
-F "description=Annual performance objectives and KPIs" \
-F "is_public=false" \
-F "is_sensitive=true"
# Upload goal achievement documentation
curl -X POST https://api.crm.test/api/v1/hrm/performance/50003/documents \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
-F "file=@goal_achievements.pdf" \
-F "type=report" \
-F "tags[]=achievement" \
-F "tags[]=goal" \
-F "name=Q4 Goal Achievement Report" \
-F "description=Documentation of goals achieved in Q4" \
-F "is_public=false"Scenario 4: Performance Improvement Plan
Document performance improvement initiatives:
# Upload performance improvement plan
curl -X POST https://api.crm.test/api/v1/hrm/performance/50004/documents \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
-F "file=@improvement_plan.pdf" \
-F "type=report" \
-F "tags[]=improvement_plan" \
-F "tags[]=manager_feedback" \
-F "name=Performance Improvement Plan - 90 Days" \
-F "description=Detailed improvement plan with milestones" \
-F "is_public=false" \
-F "is_sensitive=true"
# Upload progress check-ins
curl -X POST https://api.crm.test/api/v1/hrm/performance/50004/documents \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
-F "file=@pip_30day_checkin.pdf" \
-F "type=report" \
-F "tags[]=improvement_plan" \
-F "tags[]=feedback" \
-F "name=PIP 30-Day Progress Check-in" \
-F "is_public=false" \
-F "is_sensitive=true"Scenario 5: Recognition and Awards
Document employee achievements:
# Upload achievement certificate
curl -X POST https://api.crm.test/api/v1/hrm/performance/50005/documents \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
-F "file=@employee_of_month.pdf" \
-F "type=certificate" \
-F "tags[]=achievement" \
-F "name=Employee of the Month - January 2025" \
-F "is_public=false"Validation Rules
File Requirements:
- Maximum size: 50 MB
- All file types accepted (typically PDFs)
Required Fields:
file,type
Optional Fields:
tags,name,descriptionis_public- Default: false (all performance documents should be private)is_sensitive- Recommended: true (performance reviews are sensitive)expires_at- Optional
Cross-Entity Workflows
Employee Performance Cycle
Link performance documents across workflow:
# 1. Upload to employee general file
POST /api/v1/hrm/employees/30001/documents
{
"file": <annual_review.pdf>,
"tags": ["performance_review"]
}
# 2. Upload to specific performance review record
POST /api/v1/hrm/performance/50001/documents
{
"file": <annual_review.pdf>,
"tags": ["review", "annual"]
}Leave Request Approval Chain
Document complete leave approval process:
# 1. Employee uploads medical certificate
POST /api/v1/hrm/leave/40001/documents
{
"file": <medical_cert.pdf>,
"tags": ["medical_certificate"]
}
# 2. Manager uploads approval
POST /api/v1/hrm/leave/40001/documents
{
"file": <approval.pdf>,
"tags": ["approval"]
}
# 3. HR uploads final authorization
POST /api/v1/hrm/leave/40001/documents
{
"file": <hr_approval.pdf>,
"tags": ["approval"]
}Best Practices
1. Employee File Management
Complete Personnel Files:
- Upload all required onboarding documents
- Maintain current certifications and licenses
- Track expiration dates for IDs and work permits
- Store performance reviews annually
Document Expiration Tracking:
- Set
expires_atfor all time-limited documents - Review expiring documents monthly
- Send renewal reminders 30-60 days before expiration
- Upload renewed documents before expiration
Privacy and Confidentiality:
- Mark ALL employee documents as
is_sensitive: true - Restrict access to HR team and direct managers only
- Never expose employee personal data
- Comply with privacy regulations (GDPR, CCPA)
2. Leave Documentation
Medical Leave:
- Require medical certificate for absences >3 days
- Upload all supporting medical documents
- Track doctor's notes and prescriptions
- Document approval chain completely
Emergency Leave:
- Upload supporting documents (death certificates, etc.)
- Document emergency circumstances
- Store approval authorizations
- Maintain confidentiality of sensitive situations
Leave Balance Tracking:
- Document all leave-related approvals
- Reference leave policy documents
- Store accrual calculations if needed
3. Performance Management
Review Cycle Documentation:
- Upload all components: self-assessment, manager review, peer feedback
- Store goal-setting documents at cycle start
- Track quarterly check-ins
- Maintain complete review history
360-Degree Feedback:
- Compile peer feedback into single document
- Anonymize peer feedback if required
- Store raw feedback separately if needed
- Upload summary to performance record
Performance Improvement:
- Document improvement plans clearly
- Track progress check-ins
- Upload evidence of improvement
- Document outcome of improvement period
4. Compliance and Legal
Document Retention:
- Retain personnel files per legal requirements (typically 3-7 years after employment ends)
- Keep medical records per HIPAA/ADA requirements
- Store performance reviews per company policy
- Maintain disciplinary records for legal protection
GDPR/Privacy Compliance:
- Mark all documents as sensitive
- Implement right to access (employees can request their files)
- Support right to erasure (with legal retention limits)
- Audit document access regularly
Employment Law Compliance:
- Document all disciplinary actions
- Maintain complete termination documentation
- Store evidence of accommodation requests
- Keep harassment/discrimination investigation files
5. Security Best Practices
Access Control:
- Restrict employee files to HR and direct managers
- Use role-based access control (RBAC)
- Audit file access regularly
- Log all document downloads
Data Protection:
- Encrypt sensitive HR documents
- Use secure document transmission
- Never email sensitive employee files
- Implement secure download mechanisms
Troubleshooting
Common Issues
Problem: Employee cannot access their own documents
Solution:
- Verify employee has self-service access policy
- Check document is not marked as restricted
- Confirm employee authentication
- Review role-based permissions
Problem: Certification expiration not being tracked
Solution:
- Ensure
expires_atdate is set on upload - Query documents with expiration dates
- Implement scheduled job to check expirations
- Send automated renewal reminders
Problem: Leave request missing medical certificate
Solution:
- Verify certificate was uploaded with correct tags
- Check
is_archivedstatus - Confirm upload succeeded (201 status)
- Re-upload if necessary
Problem: Performance review history incomplete
Solution:
- Use
include_archived=trueto see all historical reviews - Check both employee and performance entity documents
- Verify documents tagged correctly
- Search by year or tag combinations
Related Documentation
- Main Document Management Guide - System-wide documentation
- Employee Management - Complete employee management
- Leave Management - Leave request workflows
- Performance Reviews - Performance management system
API Reference
For complete API specifications:
- OpenAPI Specification:
/docs/openapi.yaml - Interactive Documentation: Scribe-generated API docs
- Endpoint Group: HRM Module → Document Management
Compliance and Legal Notes
Privacy Regulations:
- GDPR (EU): Right to access, right to erasure, data portability
- CCPA (California): Similar rights to access and deletion
- HIPAA: Medical information must be protected
- ADA: Accommodation requests and medical records
Employment Law:
- Document all employment decisions
- Maintain evidence for potential disputes
- Keep records of disciplinary actions
- Store termination documentation
Data Retention:
- Personnel files: 3-7 years after employment ends
- Medical records: Per HIPAA requirements (6 years)
- I-9 forms: 3 years after hire or 1 year after termination (whichever is later)
- Tax forms: 4 years minimum
Security Standards:
- Implement encryption for sensitive HR data
- Use secure access controls
- Audit trails for all access
- Regular security reviews