Skip to main content
Documents have a dedicated section in the API Reference. The current Public API operates on documents belonging to a specific client in the authenticated company. All writes require an Idempotency-Key header. Registering a document stores an existing HTTP(S) URL; it does not upload a file. Archiving hides the document from Public API and company MCP document listings; it does not delete the document or its file from FITsociety or the external host. Company-wide document listing and management are not currently exposed through the Public API. Client routes do not provide a company-wide document collection.

List document folders

Required scope: documents:read Response fields:

List documents

Required scope: documents:read Validation: Response fields: Not exposed in v1: delete, folder rename/delete, nested folders, signed document download URLs, raw media, provider metadata, message IDs, or file contents.

Create a client folder

Send POST /public/v1/clients/{clientId}/document-folders with {"name":"Progress"}, Bearer authentication, documents:write, health consent, and an Idempotency-Key. The response is 201 with data.folder using the folder fields above. Names must be non-empty and at most 160 characters. Folders are client-owned and flat; parentFolderId and parentId are rejected.

Upload and publish a file

  1. Call POST /public/v1/clients/{clientId}/documents/uploads with fileName, mimeType, sizeBytes (an integer), optional name, and optional folderId. The folder must belong to this client and must not be a shared/default folder.
  2. Read data.upload: uploadId, method (POST), url, expiresAt (UTC), and fields (an array of {name,value} entries). Using an HTTP client, send a multipart form to that URL with every field unchanged, followed by the binary file in a field named file. Do not send your FITsociety Bearer token to the upload endpoint. A prepared upload expires after 15 minutes.
  3. After the file upload succeeds, call POST /public/v1/clients/{clientId}/documents/uploads/{uploadId}/complete. An empty body is allowed. The response is 200 with data.document, using the document fields above. Only then does the document appear for the client.
Both FITsociety POST calls require documents:write, health consent and their own Idempotency-Key. Reuse a key only for the exact same request. If an upload fails validation, correct the problem and retry completion with a new key. Completion is also safe to repeat with a new key: it returns the same document. Replaying a preparation response does not extend its upload expiry. Supported file types: Extension and declared type must match. Maximum size is 26,214,400 bytes (25 MiB); empty files are rejected. Completion checks the actual byte count and declared MIME type. Retrying an upload cannot overwrite a published document. These checks do not inspect file contents or replace malware scanning. Expected errors include missing upload (404), inaccessible folder (404), expired/missing/in-progress upload (409), and size/type mismatch (400). Document lists still omit file contents and download URLs. Upload publication does not send email or chat messages.
Use the exact byte count of your file. Transfer the binary file with all returned upload fields before completing. A successful preparation alone does not upload the file.

Example: deliver an onboarding PDF from Make

Use HTTP requests when your Make connector does not expose the upload operations. Choose the PDF for the assigned programme, then obtain its binary data and exact byte count before preparing the upload.
  1. Send a JSON request to prepare the upload:
    Replace 12345 with the actual file size in bytes. Omit folderId to place the document at the client’s document root.
  2. Send a multipart/form-data HTTP POST to data.upload.url. Add one text form part for each entry in data.upload.fields, preserving its name and value. Add the PDF binary as a file part named file, after the text parts. Let the HTTP module generate the multipart boundary; do not manually set the Content-Type header. Use no FITsociety authentication on this request.
  3. After the transfer succeeds, publish the document:
    Map {uploadId} from data.upload.uploadId in step 1. A successful response contains data.document.documentId; the document is now available in the client’s Documents section. The 15-minute expiry applies to the upload authorization, not the published document.
  4. Only after publication succeeds, send the welcome message through your existing conversation-message request. Document publication does not send that message automatically.
Use an assignment-specific key for each FITsociety request and retain it for retries of that same request. A new assignment or a different PDF needs a new key. Both document requests require documents:write and health data consent; documents:read is only needed if the scenario also lists documents or folders.
Required scope: documents:write This endpoint stores metadata for a document managed outside FITsociety. It does not upload binary files and does not expose raw download links in list/read responses. The linked document appears in the client’s Documents section. Use a stable HTTPS URL that the client can open. FITsociety does not copy the file from that URL or extend its validity: if the external file is removed or the URL expires, the link stops working. A temporary FITsociety download URL copied from another client’s document is therefore unsuitable as a stable source. The Public API does not expose a copy-from-document operation or stable download URLs for existing FITsociety files. To publish the same PDF for another client, upload the source file for that client using the flow above, or register a stable externally hosted URL. Request body: Validation: Response fields:
Response (201 Created):

Update document metadata

Required scope: documents:write Allowed fields: name, documentUrl, externalUrl, mimeType, type, fileSize, and folderId. At least one field is required. The same name, URL, type, file-size, client, and folder validations as Link external document metadata apply. Response fields:

Archive document metadata

Required scope: documents:write Archive is a metadata-only soft archive. The document is excluded from Public API list responses after archiving. It does not delete a binary file from external storage. Response fields: