Skip to content

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:

EntityPurposeCommon Document TypesMax File Size
EmployeePersonnel records and HR filesContracts, IDs, certifications, tax forms50 MB
Leave RequestLeave supporting documentationMedical certificates, approvals, doctor notes50 MB
Performance ReviewPerformance documentationReviews, feedback, goals, assessments50 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

TagPurposeExample Use Case
contractEmployment contractsOffer letters, employment agreements
id_documentIdentification documentsPassport, driver's license, work permits
resumeCV/ResumeEmployee resumes, CVs
certificationProfessional certificationsProfessional licenses, certifications
tax_formTax documentsW-4, W-2, tax forms
emergency_contactEmergency contact informationEmergency contact forms
performance_reviewPerformance reviewsAnnual reviews, evaluations
disciplinaryDisciplinary recordsWarning letters, disciplinary actions
trainingTraining certificatesTraining completion certificates
background_checkBackground check resultsBackground screening reports
referenceReference lettersEmployment references

Common Scenarios

Scenario 1: Employee Onboarding

Complete new hire documentation:

bash
# 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:

bash
# 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:

bash
# 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:

bash
# 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:

bash
# 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 file
  • type - Document type

Optional Fields:

  • tags - Array of tags (validated against allowed list)
  • name, description
  • is_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

TagPurposeExample Use Case
medical_certificateMedical certificatesDoctor's medical certificates
supporting_documentSupporting documentationTravel documents, death certificates
approvalApproval documentsManager approvals, HR approvals
emergency_documentEmergency-related documentsEmergency situation proof
doctor_noteDoctor's notesMedical notes from physician
prescriptionMedical prescriptionsPrescription documents

Common Scenarios

Scenario 1: Sick Leave Request

Document sick leave with medical certificate:

bash
# 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:

bash
# 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:

bash
# 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:

bash
# 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, description
  • is_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

TagPurposeExample Use Case
reviewPerformance reviewsAnnual/quarterly reviews
feedbackFeedback documentsGeneral feedback forms
goalGoal-setting documentsPerformance goals, objectives
improvement_planImprovement plansPerformance improvement plans (PIP)
achievementAchievement recordsAwards, recognition documents
self_assessmentSelf-assessment formsEmployee self-evaluations
manager_feedbackManager feedbackManager's evaluation
peer_feedbackPeer feedback360-degree peer reviews
quarterlyQuarterly reviewsQ1, Q2, Q3, Q4 reviews
annualAnnual reviewsYear-end performance reviews

Common Scenarios

Scenario 1: Annual Performance Review

Complete annual review documentation:

bash
# 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:

bash
# 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:

bash
# 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:

bash
# 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:

bash
# 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, description
  • is_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:

bash
# 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:

bash
# 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_at for 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

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_at date 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_archived status
  • Confirm upload succeeded (201 status)
  • Re-upload if necessary

Problem: Performance review history incomplete

Solution:

  • Use include_archived=true to see all historical reviews
  • Check both employee and performance entity documents
  • Verify documents tagged correctly
  • Search by year or tag combinations

API Reference

For complete API specifications:

  • OpenAPI Specification: /docs/openapi.yaml
  • Interactive Documentation: Scribe-generated API docs
  • Endpoint Group: HRM Module → Document Management

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

Documentation for SynthesQ CRM/ERP Platform