Skip to main content

Documents API

Endpoints for managing employee documents.

List All Employee Documents​

Retrieves all employee documents.

GET /employees/documents

Response: 200 OK

{
  "status": "SUCCESS",
  "data": [
    {
      "id": "1",
      "employee": "1",
      "document": "Employment Contract",
      "date_added": "2024-01-01",
      "valid_until": "2025-12-31",
      "status": "Active",
      "visible_to": "Admin"
    }
  ]
}

Get Documents by Employee​

Retrieves all documents for a specific employee.

GET /employees/{employee_id}/documents

Response: 200 OK

{
  "status": "SUCCESS",
  "data": [
    {
      "id": "1",
      "employee": "1",
      "document": "Employment Contract",
      "date_added": "2024-01-01",
      "valid_until": "2025-12-31",
      "status": "Active",
      "visible_to": "Admin"
    },
    {
      "id": "2",
      "employee": "1",
      "document": "ID Card Copy",
      "date_added": "2024-01-01",
      "valid_until": null,
      "status": "Active",
      "visible_to": "Admin"
    }
  ]
}

Get Single Document​

Retrieves details of a specific document.

GET /employees/documents/{document_id}

Response: 200 OK

{
  "status": "SUCCESS",
  "data": {
    "id": "1",
    "employee": "1",
    "document": "Employment Contract",
    "date_added": "2024-01-01",
    "valid_until": "2025-12-31",
    "status": "Active",
    "visible_to": "Admin",
    "attachment": "contract_2024.pdf",
    "details": "<p>Signed employment contract for 2024</p>"
  }
}

Get Document Download URL​

Retrieves a signed download URL for the document attachment.

GET /employees/documents/{document_id}/file

Response: 200 OK

{
  "status": "SUCCESS",
  "data": {
    "url": "https://your-icehrm-url.com/download?file=contract_2024.pdf&signature=abc123xyz"
  }
}

The download URL includes:

  • file: The filename
  • signature: A signed token for secure download
info

Download URLs are temporary and should be used immediately after retrieval.

Document Status Values​

  • Active: Document is current and valid
  • Expired: Document validity period has ended
  • Archived: Document has been archived

Visibility Options​

The visible_to field controls who can view the document:

  • Admin: Only administrators
  • Manager: Administrators and direct managers
  • Employee: The employee, their managers, and administrators