Files and documents
The trial's files are its eTMF: protocols, approvals, contracts, CVs, SOPs, each with a history of versions and, where you want one, a record of who approved it. Files can be trial-wide or belong to a site. Getting started, part 11 walks through the feature.
Reading files needs trial.readFiles (or trial.readApprovedFiles for approved versions only; site.readFiles / site.readApprovedFiles on a site); adding and editing needs trial.writeFiles or site.writeFiles; deleting needs trial.deleteFiles or site.deleteFiles; approving needs trial.approveFiles or site.approveFiles; asking for approval needs trial.requestFileApproval or site.requestFileApproval.
Endpoints
| Method | Path | Description |
|---|---|---|
GET |
/trials/<trialId>/files |
The files you can see, as {"files": [...]}, each with its versions and a temporary download url per version. |
POST |
/trials/<trialId>/files |
Create a file record with no version yet. |
POST |
/trials/<trialId>/files/batch |
Create a file with its first version, in one or more sites at once. |
GET |
/files/<fileId> |
One file, with its latestVersion. |
PUT |
/files/<fileId> |
Update a file's details. |
DELETE |
/files/<fileId> |
Delete a file and every version. |
GET |
/files/<fileId>/preview |
A temporary URL for a browser-viewable rendering of the latest version. |
POST |
/files/<fileId>/copy |
Copy the file to other sites: {"sites": [...], "fullHistory": true}. |
GET |
/files/<fileId>/versions |
The file's versions. |
POST |
/files/<fileId>/versions |
Add a version. |
GET |
/files/<fileId>/approvals |
Approval requests on the file. |
POST |
/files/<fileId>/approvals |
Ask people to approve it. |
DELETE |
/files/<fileId>/approvals/<approvalId> |
Withdraw a request. |
POST |
/trials/<trialId>/files/reports |
Generate the eTMF report PDF; returns a temporary url. |
Adding a file
Upload the bytes first — see Uploading files, with forType=trial — and keep the fileName you are given. Then:
POST /trials/<trialId>/files/batch:
| Field | Type | Notes |
|---|---|---|
name |
string | Required. 2–100 characters. |
storedName |
string | Required. The fileName from the upload. |
type |
string | Its place in the eTMF: protocol, amendments, crf, contract, correspondence, cv, ethics, financial, hra, laboratory, legal, managementDocumentation, monitoringAndAudit, participants, plans, regulatory, reports, researchAndDevelopment, sop, staff, workingInstruction, draft or other. |
status |
draft, approved, rejected |
The first version's status. approved needs the approve permission. |
sites |
list of site _ids |
Where to file it. Omit, or include null, for the trial level. One independent file is created per site. |
Returns {"files": [...]}. POST /trials/<trialId>/files creates the record alone (name, type, site, description, tags, assignees), for a file whose first version you will add afterwards.
File details
PUT /files/<fileId> takes name, type, description (up to 500 characters), tags and assignees (user _ids, who are notified). A file's site is fixed when it is created.
Versions
POST /files/<fileId>/versions with {"name", "storedName", "status"} adds a version from an uploaded object; versions are kept in order and each has its own url, createdAt, uploader and status. A file's status is its latest version's.
Approvals
POST /files/<fileId>/approvals with {"approvers": [{"id": "<userId>", "email": "…", "role": "…"}], "message": "…"} emails each approver a link to review the file and record their decision. Decisions appear on GET /files/<fileId>/approvals with who approved or rejected, when, and any comment. The pages approvers use are reached by that link and are not part of the API.