Controlled Document Management
The Controlled Document Management API allows you to import documents and training assignments into the Egnyte Controlled Document Management app. Use this API to migrate existing document control systems or integrate external workflows.
Note: All endpoints require the Egnyte.controlleddocs OAuth scope.
Base URL
https://{domain}.egnyte.com/pubapi/v1/controlled-docs
Authentication
All requests require an OAuth 2.0 Bearer token in the Authorization header:
Authorization: Bearer {access_token}
See Authentication for details on obtaining a token.
Import a Document
Import a new document or a new version of an existing document into the Controlled Document Management app.
Request
POST /pubapi/v1/controlled-docs/documents/import
Permissions
- Admin: Can import documents to all categories
- Category Manager: Can import documents only to categories they manage
Request Body
| Field | Type | Required | Description |
|---|---|---|---|
docId | string | Yes | Document identifier used within Controlled Document Management (e.g., SOP-1) |
name | string | Yes | Name of the document (e.g., Change Management SOP) |
isDraft | boolean | No | Whether the document is a draft. Default: false |
version | string | Yes | Document version (e.g., 1.0, 1.1). Must be less than 1.0 if isDraft is true |
entryId | string | Yes | Unique ID of the file version to import (UUID format) |
responsibleDepartment | string | No | Department or personnel responsible for maintaining the document |
effectiveFromDate | string | Conditional | Date the document becomes effective (YYYY-MM-DD format). Required when isDraft is false. Must not be provided when isDraft is true |
effectiveToDate | string | No | Date the document's effective period ends (YYYY-MM-DD format). Must not be provided when isDraft is true |
approvedOn | string | Conditional | Date the document was approved (YYYY-MM-DD format). Required when isDraft is false. Must not be provided when isDraft is true |
Example Request
curl -i -X POST "https://{domain}.egnyte.com/pubapi/v1/controlled-docs/documents/import" \ -H "Content-Type: application/json" \ -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \ -d '{ "docId": "SOP-1", "name": "Change Management SOP", "isDraft": false, "version": "1.0", "entryId": "f450227d-044c-45b5-9dbb-c1120a856b81", "responsibleDepartment": "Clinical", "effectiveFromDate": "2023-01-22", "effectiveToDate": "2024-01-21", "approvedOn": "2022-12-17" }'
Response
201 Created
| Field | Type | Description |
|---|---|---|
id | string | Controlled Document Management internal identifier for the imported document |
Example Response
{
"id": "f450227d-044c-45b5-9dbb-c1120a856b81"
}
Error Response
{
"msg": "Detailed error message"
}
Import Training Assignments
Import training assignment records into the Controlled Document Management app. The system automatically calculates the training assignment status based on dueDate, completedDate, and canceledDate.
Request
POST /pubapi/v1/controlled-docs/assignments/import
Permissions
- Admin: Can import training records for users in all categories
- Category Manager: Can import training records for users only in categories they manage
Request Body
| Field | Type | Required | Description |
|---|---|---|---|
assigneeId | integer | Yes | ID of the user assigned the training |
docId | string | Yes | Document ID for which training is assigned (e.g., SOP-1) |
version | string | Yes | Document version for which training is assigned (e.g., 1.0, 1.1) |
assignedDate | string | No | Date the training assignment was created (ISO-8601 format). Defaults to current date if not provided |
dueDate | string | Yes | Due date of the training assignment (YYYY-MM-DD format) |
completedDate | string | No | Training assignment completion date (ISO-8601 format). Set only for completed assignments |
canceledDate | string | No | Date the training assignment was canceled (ISO-8601 format). Set only for canceled assignments |
assignedById | integer | No | ID of the user who assigned the training. Defaults to the requesting user if not provided |
Example Request
curl -i -X POST "https://{domain}.egnyte.com/pubapi/v1/controlled-docs/assignments/import" \ -H "Content-Type: application/json" \ -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \ -d '{ "assigneeId": 11, "docId": "SOP-1", "version": "1.0", "assignedDate": "2023-01-22T14:00:00Z", "dueDate": "2023-02-22", "completedDate": "2023-01-27T16:22:07Z", "assignedById": 22 }'
Response
201 Created
| Field | Type | Description |
|---|---|---|
id | string | Controlled Document Management training assignment identifier |
Example Response
{
"id": "e250227d-044c-45b5-9dbb-c1120a856b84"
}
Error Response
{
"msg": "Detailed error message"
}
Error Codes
| Status | Error | Description | Resolution |
|---|---|---|---|
| 400 | Bad Request | Document migration not enabled for this category | Enable document migration in category settings |
| 400 | Bad Request | Document version is not the next major or minor version | Ensure version follows sequential versioning (e.g., 1.0 → 1.1 or 2.0) |
| 400 | Bad Request | Approval date cannot be in the future | Set approvedOn to a past or current date |
| 400 | Bad Request | Approval date cannot be after the effective on date | Ensure approvedOn is before or equal to effectiveFromDate |
| 400 | Bad Request | Document version number does not match the effective time period | Align version number with the effective date range |
| 400 | Bad Request | Assignee does not have permission to view the category | Grant the assignee access to the category |
| 403 | Forbidden | User cannot add new documents to the category | Ensure the user is an admin or category manager for this category |
| 403 | Forbidden | Caller doesn't have permission to manage assignments for the category | Ensure the user is an admin or category manager for this category |
| 403 | Forbidden | Assignee doesn't have permissions to the document | Grant the assignee read access to the document |
| 404 | Not Found | Entry ID does not exist | Verify the entryId corresponds to a valid file version |
| 404 | Not Found | Referenced document not found | Verify the docId and version exist in the system |
| 409 | Conflict | Document version already exists for this document | Use a different version number or update the existing version |
| 409 | Conflict | Document identifier conflicts with an existing document | Use a unique docId or update the existing document |
| 409 | Conflict | Operation not allowed for an obsolete document | Training cannot be assigned to obsolete documents |
Code Examples
POST /pubapi/v1/controlled-docs/documents/import
curl -i -X POST "https://{domain}.egnyte.com/pubapi/v1/controlled-docs/documents/import" \ -H "Content-Type: application/json" \ -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \ -d '{ "docId": "SOP-1", "name": "Change Management SOP", "isDraft": false, "version": "1.0", "entryId": "f450227d-044c-45b5-9dbb-c1120a856b81", "responsibleDepartment": "Clinical", "effectiveFromDate": "2023-01-22", "effectiveToDate": "2024-01-21", "approvedOn": "2022-12-17" }'
POST /pubapi/v1/controlled-docs/assignments/import
curl -i -X POST "https://{domain}.egnyte.com/pubapi/v1/controlled-docs/assignments/import" \ -H "Content-Type: application/json" \ -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \ -d '{ "assigneeId": 11, "docId": "SOP-1", "version": "1.0", "assignedDate": "2023-01-22T14:00:00Z", "dueDate": "2023-02-22", "completedDate": "2023-01-27T16:22:07Z", "assignedById": 22 }'
Related Resources
- Authentication — How to obtain and refresh OAuth tokens
- File System API — Manage files and folders referenced by
entryId - User Management API — Retrieve user IDs for assignment operations