Employment HeroReturns an array of the employee's uploaded documents. The documents are returned based on the requesting user's access permissions.
https:/api.employmenthero.com/api/v1/organisations/:organisation_id/employees/:employee_id/documentsPath Parameters
The ID of the organisation to retrieve
The ID of the employee to retrieve documents for
Query Parameters
Search query to filter documents by title or filename
Current page index
11Number of items per page
20100Response Body
A hash with a data property that contains an array of document objects. Each document object includes metadata about the uploaded file, access permissions, and associated tags. The response includes pagination information for large result sets.
Unique identifier for the document.
The filename of the document.
The display title of the document.
The URL to access the document file.
The ID of the employee this document belongs to.
The date and time when the document was uploaded.
The date and time when the document was last modified.
Array of access permission levels.
Array of tags associated with the document.
Whether the document is restricted to admin access only.
Current page index
11Number of items per page
20100Total items
Total pages
Example
curl -X GET \ "https://api.employmenthero.com/api/v1/organisations/:organisation_id/employees/:employee_id/documents" \ -H "Authorization: Bearer AUXJ3123xyrj123fdsjkl124aAJKQ"Response
{ "data": { "items": [ { "id": "0139ebb7-6f3e-4bc0-954e-9e50614fccd1", "name": "employment_contract.pdf", "title": "Employment Contract", "url": "https://api.employmenthero.com/documents/0139ebb7-6f3e-4bc0-954e-9e50614fccd1", "member_id": "4a728243-8930-4a93-9bd8-a6843e7b59ec", "created_at": "2024-01-15T10:30:00+00:00", "updated_at": "2024-01-15T10:30:00+00:00", "access_permissions": [ "employee", "direct_managers", "payroll" ], "tag_list": [ "contract", "employment" ], "is_admin_only": false } ], "page_index": 1, "item_per_page": 20, "total_items": 1, "total_pages": 1 }}This endpoint uploads a document for a specific employee. The document file is uploaded as a multipart form data request.
https:/api.employmenthero.com/api/v1/organisations/:organisation_id/employees/:employee_id/documentsPath Parameters
The ID of the organisation
The ID of the employee to upload the document for
Request Body
The document file to upload
Document name (defaults to filename if not provided)
Array of tags for the document. Can be provided as comma-separated string or array
Array of access permission levels. Can be provided as comma-separated string or array
Supported File Types
| File Type | Extensions | Description |
|---|---|---|
.pdf | Portable Document Format files | |
| Microsoft Word | .doc, .docx | Microsoft Word documents |
| Microsoft Excel | .xml, .xls, .xlsx | Microsoft Excel spreadsheets |
| CSV | .csv | Comma-separated values files |
| JPEG Images | .jpg, .jpeg | JPEG image files |
| PNG Images | .png | Portable Network Graphics images |
Response Body
Returns the created document object with all document details.
Note: When you provide a name parameter with a different file extension than the actual uploaded file, the system will use the actual file's extension for the final document name. For example, if you upload a PDF file but specify name as "contract.txt", the final document will be named "contract.pdf".
Important: If multiple files are uploaded in a single request, only the latest file will be attached to the document. To upload multiple documents, make separate API calls for each file.
Unique identifier for the document.
The filename of the document.
The display title of the document.
The URL to access the document file.
The ID of the employee this document belongs to.
The date and time when the document was uploaded.
The date and time when the document was last modified.
Array of access permission levels.
Array of tags associated with the document.
Whether the document is restricted to admin access only.
Example
curl -X POST \ "https://api.employmenthero.com/api/v1/organisations/:organisation_id/employees/:employee_id/documents" \ -H "Authorization: Bearer AUXJ3123xyrj123fdsjkl124aAJKQ" \ -F "file=@/path/to/document.pdf" \ -F "name=Employment Contract" \ -F "tags=contract,employment" \ -F "access_permissions=employee,direct_managers"Response
{ "data": { "id": "0139ebb7-6f3e-4bc0-954e-9e50614fccd1", "name": "employment_contract.pdf", "title": "Employment Contract", "url": "https://api.employmenthero.com/documents/0139ebb7-6f3e-4bc0-954e-9e50614fccd1", "member_id": "4a728243-8930-4a93-9bd8-a6843e7b59ec", "created_at": "2024-01-15T10:30:00+00:00", "updated_at": "2024-01-15T10:30:00+00:00", "access_permissions": [ "employee", "direct_managers", "payroll" ], "tag_list": [ "contract", "employment" ], "is_admin_only": false }}