Files.fm Document Management System (DMS) API
Files.fm provides a Document Management System (DMS) for organizing business documents with metadata, workflows, reminders, e-signatures, and access control integrated with cloud file storage.
The general DMS API supports the reviewed registers in the table below: tasks, projects, partners, contacts, articles, links, and the additional document registers published through the same /api_dvs/{dvs_section}/{action} contract. list_sections is authoritative for one organization: a register appears only when that organization has it enabled and the actor can use it. A separate legacy csb_client_contract integration exposes only contract creation and file attachment. invoice_2 is published: an omitted VAT line list and partner list are kept, a caller cannot set the calculated total, and deletion stays closed. lvf_invoice is published the same way. sg_invoice is published the same way. invoice_outgoing is published with its product lines reloaded when omitted; the total stays calculated. sg_invoice_outgoing is published the same way. litk_invoice and the simple invoice register are published with the amounts stored on the document; they have no line list. ADM stays unpublished. Creating or updating a notification sends that register's reminder email and clears the previous sent time; an omitted receiver list is kept. Notification deletion stays unpublished because it also sends email. Warehouse movements and the BD register are published with the limits in the register table below. Data created or updated here is the same data shown in the DMS web interface.
Base URL
https://api.files.fm/api_dvs/{dvs_section}/{action}
Example:
POST https://api.files.fm/api_dvs/task/create_document
Authentication
Authenticate every request with user and user_access_token. Always use HTTPS.
| Field | Description |
|---|---|
user |
Files.fm username or email |
user_access_token |
API access token. Generate/revoke at https://files.fm/account#api_keys. |
Send both in a JSON body (Content-Type: application/json) next to the action parameters. Do not put credentials in the URL. Do not send pass. A website login cookie by itself is not accepted.
curl -X POST 'https://api.files.fm/api_dvs/task/get_fields' \
-H 'Content-Type: application/json' \
-d '{"user":"YOUR_USER","user_access_token":"YOUR_API_TOKEN"}'
Organization and DMS requirements
Beyond authentication, the DMS API has two additional requirements:
- Organization membership: the authenticated user must belong to an organization that has DMS enabled.
- Action and record permissions: reads accept register
readorwrite. Tasks, articles and projects also acceptread_own/write_ownwith record scoping: task access requires project membership (manager or participant), article access requires membership in its project, and own-project access requires being a project manager. Writes requirewrite, or applicablewrite_ownrights. Uselist_sectionsand, where supported,get_fieldsto discover the actor's available actions.
Missing section access or an unavailable section returns HTTP 405. If authentication does not establish a session organization, the API returns HTTP 401.
Direct document reads, comments, updates and attachment uploads also check access to the specific active record. Document-type restrictions apply in addition to register permission. A request to sign an attached file can contribute to read access under the register's existing rules, but does not grant document editing through the API. Writing requires a separate document edit grant (including applicable creator/worker rules); the API does not inherit the web editor's signing-derived edit grant. An inaccessible record returns 405, and a denied upload does not create an attachment folder.
MCP access
AI clients can use the supported DVS registers through the Files.fm MCP server instead of calling this API directly. The MCP tools use the same organization, register, record and edit-permission checks and the same field names and IDs. OAuth reads require dvs:read; record changes require dvs:read dvs:write; project membership changes also require explicit dvs:manage_access, and attachments require files:write. Files.fm API keys use the account's DVS permissions.
Register discovery
POST https://api.files.fm/api_dvs/catalog/list_sections with user and user_access_token. catalog is a discovery route placeholder; it is not a document register. The response contains items with section, name (the organization's own register name when set, otherwise the register title shown in DMS), and actions, plus the authenticated actor. Only API-enabled organization registers available to the account are returned. General pages such as email/settings and registers without reviewed API adapters are excluded. get_fields.actions also reflects the actor's available register-level actions; record-specific checks still apply when calling them.
List results and total are scoped before pagination. With own-task access, get_users also requires access to the requested task project; it cannot be used to inspect another project's assignees. The same project check applies to task creation.
Request format
The URL names the register and the action. Send action-specific parameters in a JSON body (Content-Type: application/json). user and user_access_token in that JSON are used for authentication and are not treated as document fields.
https://api.files.fm/api_dvs/{dvs_section}/{action}
| Path segment | Description |
|---|---|
{dvs_section} |
A reviewed register from Supported registers, or the limited legacy csb_client_contract integration. list_sections is the organization-specific list. |
{action} |
Operation name (see Endpoint summary) |
For actions with no extra parameters (for example get_fields), the JSON body only needs user and user_access_token. The only exception is upload_document_file, which sends the same fields and the file as multipart/form-data. Prefer the URL path for action and dvs_section; do not rely on overriding them from the body.
HTTP status codes
| Status | Meaning | Action |
|---|---|---|
200 OK |
Request succeeded. | Process the returned JSON. |
400 Bad Request |
Invalid or incomplete parameters. The body is {"error": "invalid_arguments", "message": "..."}; validation messages name each rejected field. |
Correct the named fields. |
401 Unauthorized |
Authorization failed or is missing. | Check user and user_access_token. |
405 Method Not Allowed |
Operation not permitted (missing required section/record permission, section not enabled for the org, or wrong HTTP method). | Check permissions, dvs_section, and method. |
409 Conflict |
An operation key has different data or is pending/uncertain. | Inspect the saved DVS state before retrying; do not bypass uncertainty with a new key. |
500 Internal Server Error |
Backend/API service error. | Retry later or contact Files.fm support. |
503 Service Unavailable |
The operation receipt store is unavailable. | Inspect persisted state before retrying. |
400, 409 and 503 responses have a JSON body {"error": "...", "message": "..."} (invalid_arguments, operation_conflict, temporarily_unavailable). Other errors (401, 405, 500) have an empty body, so missing permissions and missing records are not distinguished. Exception: when upload_document_file cannot save the file itself (for example file too large or quota exceeded), it returns 200 with {"success": false, "error_code": ..., "error_message": "..."} and no file_hash.
Supported registers
The {dvs_section} path segment must be one of the values below. Any other section returns HTTP 400 (Invalid DVS section).
dvs_section |
Register | Supported actions |
|---|---|---|
task |
Tasks (project tasks) | get_fields, get_users, search_users, get_document, get_documents, get_comments, create_document, update_document, add_comment, upload_document_file |
project_2 |
Projects (parent container for tasks) | get_fields, get_users, get_document, get_documents, create_document, update_document, get_comments, add_comment, set_project_members, upload_document_file |
contact_person |
Contact persons (external notification receivers on tasks) | get_fields, get_document, get_documents, get_comments, add_comment, create_document, update_document, upload_document_file |
client |
Clients / parties (companies and partners) | get_fields, get_users, get_document, get_documents, get_comments, add_comment, create_document, update_document, upload_document_file |
article |
Project articles / knowledge records | get_fields, get_document, get_documents, get_comments, add_comment, create_document, update_document, upload_document_file |
link |
Link records | get_fields, get_document, get_documents, get_comments, add_comment, create_document, update_document, upload_document_file |
csb_client_contract |
Legacy CSB client contracts; available only to organizations with this register enabled | create_document, upload_document_file |
Reviewed registers expose get_fields, get_document, get_documents, create_document, update_document, get_comments, add_comment and upload_document_file, plus get_users when the register assigns users. Project membership stays on set_project_members. New writes, including comments and file uploads on registers other than task, require idempotency_key. Discover organization-specific availability with list_sections; the CSB route has no generic read, field-discovery, update or comment actions, and its file upload stays on that legacy route.
The additional reviewed registers use that same action set. Their saved fields are the editor fields for that register. Omitted values are preserved on update. Dates are sent as YYYY-MM-DD. A linked document must belong to the same organization and be readable by the actor. Incoming and outgoing letters can schedule the register's existing reminder notifications when their reminder fields change. Project creation and metadata update do not set members or folder access; use set_project_members for people.
dvs_section |
Register |
|---|---|
received, sent, resource, training, review_tracker, audit, capa, data_room, signal_detection |
Flat standard registers |
incoming_letter, outgoing_letter, meeting, meeting_decision |
Letters and meetings |
contract, contract_2, contract_3, contract_4, personnel_contract, author_company_contract, authority, power, order, general_order, structural_order, personnel_order, acceptance_act, business_trip, business_trip_2, employment_start, object_handover, geo_works, geo_construction_supervision, subcontractor_evaluation, arc_contact_person |
Contracts, orders and related standard registers |
k2_contract, k2_incoming_letter, k2_order, k2_outgoing_letter, litk_contract, litk_incoming_letter, litk_order, litk_outgoing_letter, litk_power, sg_contract, sg_incoming_letter, sg_order, sg_outgoing_letter, sg_personnel_order, edic_contract, edic_incoming_letter, edic_outgoing_letter, cx_incoming_letter, cx_outgoing_letter, merk_incoming_letter, merk_outgoing_letter, merk_maf, san_contract, san_copyright_contract, rs_contract |
Customer-specific registers |
bd |
Construction documents. An API write stays on the selected document and does not rewrite linked-document sums or warranty dates. |
warehouse, stock_movement |
Warehouse items and stock movements. An omitted balance is kept. A movement requires a warehouse, type IN or OUT, a positive amount and a date. An update applies only the quantity difference. A busy document folder returns HTTP 503 and can be retried with the same key. |
metta_application_form, metta_event, metta_event_student_registration, metta_guardian, metta_location, metta_schedule, metta_student, metta_training_group, metta_training_group_student_registration |
Metta registers. Saves stay on the selected document. An omitted responsible user is kept. |
client_cabinet_discount |
Client-cabinet discount records. Currency and status are normalized by the existing model, and the save does not send mail. |
notification |
Reminders. Create and update send the existing reminder email and clear the previous sent time. An omitted notif_receiver list is kept. Deletion is not available. |
invoice_2 |
Incoming invoices. Send VAT lines as the editor list sums, keyed sum-{id} or new-0, with dvs_vat_id, sum_without_vat, vat_sum and sum_with_vat. An omitted list is kept. The document total is calculated by the existing invoice total and is not an input. An omitted partner list is kept. Deletion is not available. |
lvf_invoice |
LVF incoming invoices. The sums line list and partner list follow the same rules as invoice_2. An omitted list is kept, the total is calculated, and deletion is not available. |
sg_invoice |
SG incoming invoices. The sums line list and partner list follow the same rules as invoice_2. An omitted list is kept, the total is calculated, and deletion is not available. |
invoice_outgoing |
Outgoing invoices. Send product lines as products, keyed by the stored id or new-0, with name, unit_name, count, price, discount_percent and dvs_vat_id. An omitted list is kept. Calculated totals are not an input. Display flags use true or false. Deletion is not available. |
sg_invoice_outgoing |
SG outgoing invoices. Product lines follow the same rules as invoice_outgoing. An omitted list is kept, the total stays calculated, and deletion is not available. |
litk_invoice |
LITK invoices. Amounts are the document fields sum, vat and sum_vat; there is no child line list. An omitted partner list is kept. Deletion is not available. |
invoice |
Simple invoices. Amounts are the document fields sum, vat and sum_vat; there is no child line list. An omitted partner list is kept. Deletion is not available. |
The CSB entry is a narrow compatibility adapter. Its create payload has no public get_fields schema and is omitted from the general OpenAPI contract; do not treat it as a generic writable register. Use organization-specific integration instructions for its payload, and use list_sections to confirm whether it is enabled.
Project create_document and update_document change number, name, type, status, dates and comment. They start with no members and do not rewrite membership or folder access. projectmanager and participant have create: false and update: false in the generic field schema. They can be changed only through the dedicated operation below.
set_project_members
POST /api_dvs/project_2/set_project_members with user, user_access_token, dvs_document_id, projectmanager, participant and idempotency_key. Both member fields are required arrays (at most 1,000 IDs each); each replaces the full list, and an explicit empty array clears it. Get assignable active organization user IDs from project_2/get_users; users with own-project permissions are included as in the DVS editor. Unknown, foreign and non-assignable users are rejected before any mutation. Ordinary metadata is preserved.
The operation requires project edit rights, including manager-scoped write_own where applicable. A signing request does not grant edit access. Full account API credentials use these native rights. MCP OAuth grants additionally require explicit dvs:manage_access, dvs:write and dvs:read consent; MCP OAuth tokens are not credentials for this REST endpoint.
Access effects: replacing managers/participants synchronizes the related task/article folder access through the same rules as the DVS editor, updates the project document folder where applicable, records member changes in the existing audit and sends the usual project notification. It does not accept arbitrary folder hashes or raw sharing rights. Removing your own manager role can remove your own-record access; replay still rechecks current rights. Replacements of the same project wait for one another. If that project is still busy after 10 seconds, the request returns 503 and does not reserve an operation key. A partial folder synchronization can still leave membership ahead of folder rights; that key stays uncertain and is not replayed.
The response contains status: updated, dvs_document_id, and the saved integer-ID lists projectmanager and participant. Each newly executed replacement synchronizes related task/article folders and the existing project document folder even if member lists already match, so a separately authorized repair can reconcile stale folder access after a partial failure. It does not create a missing project document folder. Completed operation keys replay the original result without running synchronization again. Legacy membership and folder synchronization is not one atomic transaction: on a partial failure the key remains uncertain and must not be bypassed with a new key. Inspect project membership, derived folder rights and audit before authorizing a separate repair operation.
Partner writes require a top-level idempotency_key. Create requires a nonempty name; other editable fields come from get_fields, including email, address, registration number, bank details, projectmanager and multi_dropdown_group. Basic and additional partner fields are saved through their existing DVS model paths. Omitted fields/lists remain unchanged on update; explicit empty lists clear them. is_foreign_company accepts booleans and the legacy true/false or 1/0 representations. is_sync_active is read-only: this API does not initiate company-registry synchronization. get_fields returns per-field create and update flags, combined with the actor's register-level permissions.
Articles and links
article and link create/update require idempotency_key. Creation requires number and number_year, matching the native editor's numeric validation and uniqueness checks; full_number is computed by the model and is not writable. When both are omitted, the next number is assigned. Omitted fields are preserved on update.
Articles additionally require dvs_project_id on create. read_own/write_own uses project membership like tasks, including direct IDs and list totals. The project cannot change on update (update: false). description is an HTML field: the native sanitizer/storage encoding is reused, and only single-record reads return its content.
Links expose name, optional dvs_project_id, link, and comment. A supplied nonempty link must be an absolute HTTP/HTTPS URL; empty is valid for a draft. The server stores the URL without fetching it. Updating another field preserves an omitted historical URL, including values created through older interfaces. A stored project that is no longer active does not block an update which leaves that project unchanged; a different selected project must still be active. Link access uses the register's normal read/write rights rather than task-style own-project rights.
Use contact_person get_documents / get_document to look up contact IDs, then pass those IDs as ext_notif_receiver when creating or updating a task. You can also create or update contact persons through this API.
Use client get_documents / get_document to look up client document IDs for contact company (and other relation fields that reference client).
Email tools
These actions are not document registers. They list and edit drafts and paused preparations, and they read the address book, recipient lists, recipient count, monthly quota and content versions. scheduled_at is YYYY-MM-DDTHH:mm in Europe/Riga; an empty value means immediate. A known inactive address is rejected, duplicate addresses are collapsed, and the monthly limit is checked before a draft or preparation is saved. After sending has started, only content can change; recipients and the schedule stay as they are. The tools do not reserve quota, start, resume or test a mailing, and they do not connect to SMTP. The user sends from the product. A paused preparation returns /dvs/email-mailings/edit/{id}?prepared for review.
| Action | Endpoint | Purpose |
|---|---|---|
search_email_addresses |
POST /api_dvs/email/search_email_addresses |
Address-book search |
save_email_draft |
POST /api_dvs/email/save_email_draft |
Save a draft; requires idempotency_key |
get_email_draft |
POST /api_dvs/email/get_email_draft |
Read a draft |
get_email_preparation |
POST /api_dvs/email/get_email_preparation |
Read an unstarted preparation and its review link |
list_email_drafts |
POST /api_dvs/email/list_email_drafts |
List drafts |
list_email_preparations |
POST /api_dvs/email/list_email_preparations |
List paused preparations that have not started |
get_email_quota |
POST /api_dvs/email/get_email_quota |
Read the monthly limit without reserving it |
list_email_addresses |
POST /api_dvs/email/list_email_addresses |
List the address book |
list_email_lists |
POST /api_dvs/email/list_email_lists |
List recipient lists and member counts |
count_email_recipients |
POST /api_dvs/email/count_email_recipients |
Count supplied addresses without saving |
list_email_revisions |
POST /api_dvs/email/list_email_revisions |
List content versions of a visible mailing |
list_email_mailings |
POST /api_dvs/email/list_email_mailings |
List visible mailings in every state with sent, failed and opened counts; optional page (50 per page) |
get_email_mailing |
POST /api_dvs/email/get_email_mailing |
Read one mailing with recipient counts per status (mailing_id); no recipient addresses |
save_email_preparation |
POST /api_dvs/email/save_email_preparation |
Update a preparation; requires idempotency_key and does not start sending |
Endpoint summary
| Action | Method | Endpoint | Purpose |
|---|---|---|---|
get_fields |
POST |
/api_dvs/{dvs_section}/get_fields |
Field schema and dropdown options for create/update/filter. |
get_users |
POST |
/api_dvs/{dvs_section}/get_users |
Users that may be assigned (for tasks: assignable in one project). |
search_users |
POST |
/api_dvs/task/search_users |
Find any active organization user by name; bounded, no paging. |
get_document |
POST |
/api_dvs/{dvs_section}/get_document |
Read one document by ID. |
get_documents |
POST |
/api_dvs/{dvs_section}/get_documents |
List/filter documents with pagination. |
get_comments |
POST |
/api_dvs/{dvs_section}/get_comments |
Read a document's comment history with pagination. |
create_document |
POST |
/api_dvs/{dvs_section}/create_document |
Create a document in a reviewed writable register. |
update_document |
POST |
/api_dvs/{dvs_section}/update_document |
Partially update a document in a reviewed writable register. |
add_comment |
POST |
/api_dvs/{dvs_section}/add_comment |
Add a document comment using normal register notifications. Use @[USER:user_id] to mention a user. |
upload_document_file |
POST (multipart) |
/api_dvs/{dvs_section}/upload_document_file |
Attach a new file to a reviewed document. Task and the legacy CSB route may omit idempotency_key. |
search_email_addresses |
POST |
/api_dvs/email/search_email_addresses |
Search the address book. Does not send mail. |
save_email_draft |
POST |
/api_dvs/email/save_email_draft |
Save a draft. Requires idempotency_key and does not start sending. |
get_email_draft |
POST |
/api_dvs/email/get_email_draft |
Read one draft. |
get_email_preparation |
POST |
/api_dvs/email/get_email_preparation |
Read a paused preparation that has not started. |
list_email_drafts |
POST |
/api_dvs/email/list_email_drafts |
List drafts. |
list_email_preparations |
POST |
/api_dvs/email/list_email_preparations |
List paused preparations that have not started. |
get_email_quota |
POST |
/api_dvs/email/get_email_quota |
Read the monthly quota without reserving it. |
list_email_addresses |
POST |
/api_dvs/email/list_email_addresses |
List the address book. |
list_email_lists |
POST |
/api_dvs/email/list_email_lists |
List recipient lists. |
count_email_recipients |
POST |
/api_dvs/email/count_email_recipients |
Count addresses without saving. |
list_email_revisions |
POST |
/api_dvs/email/list_email_revisions |
List mailing content versions. |
list_email_mailings |
POST |
/api_dvs/email/list_email_mailings |
List mailings and their delivery counters. |
get_email_mailing |
POST |
/api_dvs/email/get_email_mailing |
Read one mailing's delivery counters. |
save_email_preparation |
POST |
/api_dvs/email/save_email_preparation |
Update a preparation without starting it. Requires idempotency_key. |
Reads, comments and create/update use the reviewed registers listed above. The csb_client_contract compatibility section supports only create and attachment. search_users supports tasks only. get_users is available for registers that assign users. Project membership uses the separate set_project_members action. Discover the actor's available actions with list_sections and, where supported, get_fields.
Finding IDs
All IDs are organization-specific. Read them from the API at run time; do not hard-code status, project or user IDs between organizations or environments.
| You need | Where to get it |
|---|---|
| Your own user ID and organization | get_fields → actor.id, actor.org_id |
| Which actions this server supports | get_fields → actions (for example, check for search_users before calling it) |
| Dropdown value IDs (status, type, priority, …) | get_fields → the field's options ({id, display_name}); match display_name, send id |
| Project ID | project_2/get_documents (filter or page through), or dvs_project_id of an existing task |
User ID to assign (responsible, followers) |
task/get_users with dvs_project_id — only these IDs are accepted on create/update |
User ID of anyone in the organization (queue filter, @[USER:id] mention) |
task/search_users with a name pattern |
| User IDs already on records | responsible / followers / creator in get_document(s), author.id in get_comments |
| Contact person / client IDs | contact_person/get_documents, client/get_documents |
Example — open tasks of one person, oldest first:
task/get_fields→ readdropdown_status.optionsand pick the "open" status ID; check thatactionscontainssearch_users.task/search_userswith{"pattern": "Anna Smith"}→ user ID (or useactor.idfor your own queue).task/get_documentswith{"filters": {"responsible": 1042, "dropdown_status": 12}, "order": "oldest", "limit": 20}.
Actions
get_fields
Returns the field schema for a register: field names, labels, types, whether the field is required, and the allowed values. required is true for every field the server requires on create (the same check that rejects the request). filter is true only for fields that get_documents can filter by. options lists the allowed values of dropdown fields and of plain select columns (for example currency, VAT rate, number type, invoice status or language); IDs of documents in another register instead carry section and list_action. Use this to discover what fields to pass to create_document / update_document and which fields support filtering in get_documents.
POST https://api.files.fm/api_dvs/task/get_fields
Request body: authorization only.
Response:
{
"fields": [
{
"name": "dvs_project_id",
"label": "Project",
"type": "relation",
"required": true,
"filter": true,
"section": "project_2",
"list_action": "get_documents"
},
{
"name": "name",
"label": "Name",
"type": "text",
"required": true,
"filter": false
},
{
"name": "dropdown_status",
"label": "Status",
"type": "dropdown",
"required": false,
"filter": true,
"options": [
{ "id": 12, "display_name": "Open" },
{ "id": 13, "display_name": "In progress" },
{ "id": 14, "display_name": "Done" }
]
},
{
"name": "responsible",
"label": "Responsible",
"type": "user_id",
"required": false,
"filter": true,
"depends_on": "dvs_project_id",
"list_action": "get_users"
},
{
"name": "followers",
"label": "Followers",
"type": "user_ids",
"required": false,
"filter": false,
"depends_on": "dvs_project_id",
"list_action": "get_users"
},
{
"name": "ext_notif_receiver",
"label": "External followers",
"type": "relation_ids",
"required": false,
"filter": false,
"section": "contact_person",
"list_action": "get_documents"
}
],
"actions": ["get_fields", "get_users", "search_users", "get_document", "get_documents", "get_comments", "create_document", "update_document", "add_comment"],
"actor": { "id": 1042, "org_id": 450 }
}
actions lists the actions this section supports on the server, so clients can detect newly deployed capabilities. actor is the authenticated account's user ID and organization; use actor.id as the responsible filter for "my tasks".
Field types
| Type | Description | Input format (create/update) | Output format (get_document/get_documents) |
|---|---|---|---|
text |
Plain text. With options, one of the option id values (for example "NO") |
string | "value" or null |
lines |
Invoice lines; line_fields describes each line, with options where a line field has allowed values |
array of line objects | array of line objects with id and calculated sums (only in get_document) |
number |
Number or numeric ID column. With options, one of the option id values; with section, a document ID from that register |
number or numeric string | "value" or null |
date |
Calendar date | "YYYY-MM-DD" string |
"YYYY-MM-DD" or null |
datetime |
Date and time | "YYYY-MM-DD HH:MM" string |
"YYYY-MM-DD HH:MM:SS" or null |
html |
Rich text (HTML markup) | HTML string | Full HTML string (only in get_document; omitted in get_documents) |
dropdown |
Org-specific enum value | integer id from options |
{ "id": N, "display_name": "..." } or null |
dropdown_ids |
Multiple org-specific enum values | array of integer ids from options |
array of { "id", "display_name" } objects |
relation |
Link to a document in another register | integer document id | { "id": N, "display_name": "..." } or null |
relation_ids |
Multiple links to documents in another register | array of integer document ids | array of { "id", "display_name" } objects |
user_id |
Single assignable user | integer user id from get_users |
{ "id": N, "display_name": "Full Name" } or null |
user_ids |
Multiple assignable users | array of integer user ids | array of { "id", "display_name" } objects |
Fields with "filter": true can be used as filters in get_documents. Fields with "depends_on" require the named field's value to be supplied when calling get_users.
Fields with "list_action": "get_users" contain user references; call get_users with the relevant context parameters to get the allowed values. Fields with "list_action": "get_documents" contain references to documents in another register; call get_documents on that register (see "section") to list possible values.
get_users
Returns assignable platform user IDs for user_id and user_ids fields in the current register. Only available on registers that expose those field types (task, project_2, client); not on contact_person (use get_documents there for contact document IDs). For tasks, the list contains users who may be assigned in the specified project: users with task read or write permission, plus users with own-record permission who are workers of that project. It is not an organization-wide directory — use search_users to find any organization user by name.
POST https://api.files.fm/api_dvs/task/get_users
Content-Type: application/json
Request:
{
"dvs_project_id": 51
}
| Parameter | Required for | Description |
|---|---|---|
dvs_project_id |
task |
ID of the project whose workers are listed. Required for task; not needed for project_2 or client. |
Response:
{
"users": [
{ "id": 1042, "display_name": "Anna Smith" },
{ "id": 1105, "display_name": "John Doe" }
]
}
get_document
Returns a single document by its DMS document ID.
POST https://api.files.fm/api_dvs/task/get_document
Content-Type: application/json
Request:
{
"dvs_document_id": 4821
}
Response:
{
"dvs_document_id": 4821,
"full_number": "PROJ-7",
"dvs_project_id": { "id": 51, "display_name": "Website redesign" },
"dropdown_type": null,
"name": "Write API documentation",
"description": "<p>Document all DMS API endpoints.</p>",
"dropdown_priority": { "id": 17, "display_name": "High" },
"dropdown_status": { "id": 12, "display_name": "In progress" },
"responsible": { "id": 1042, "display_name": "Anna Smith" },
"followers": [
{ "id": 1105, "display_name": "John Doe" }
],
"ext_notif_receiver": [
{ "id": 901, "display_name": "Jane Client" }
],
"date_due": "2026-09-30",
"estimated_hours": "4",
"spent_hours": null,
"creator": { "id": 980, "display_name": "Maria Admin" },
"date_created": "2026-08-10 14:22:05",
"date_updated": "2026-08-24 09:45:11",
"upload_hash": "k3n8vz2qpw7r5xyt"
}
upload_hash (get_document only) is the task's attachment folder, or null when the task has no attachments yet or you cannot view the folder. List its files with the Files.fm API or the MCP filesfm_list_folder tool.
The html field type (description) is returned in full only for get_document. It is omitted from get_documents list results.
The creator, date_created, and date_updated fields are read-only metadata returned on get, not accepted in get_fields for create/update.
get_documents
Returns a paginated list of documents in a register, with optional filtering.
POST https://api.files.fm/api_dvs/task/get_documents
Content-Type: application/json
Request:
{
"limit": 20,
"offset": 0,
"filters": {
"dvs_project_id": 51,
"dropdown_status": [12, 13]
}
}
| Parameter | Type | Default | Maximum | Description |
|---|---|---|---|---|
limit |
integer | 50 | 200 | Number of results to return |
offset |
integer | 0 | — | Number of results to skip |
filters |
object | — | — | Only fields marked "filter": true in get_fields. Multiple values for one field are OR; multiple fields are AND. |
Response:
{
"items": [
{
"dvs_document_id": 4821,
"full_number": "PROJ-7",
"dvs_project_id": { "id": 51, "display_name": "Website redesign" },
"dropdown_type": null,
"name": "Write API documentation",
"dropdown_priority": { "id": 17, "display_name": "High" },
"dropdown_status": { "id": 12, "display_name": "In progress" },
"responsible": { "id": 1042, "display_name": "Anna Smith" },
"followers": [],
"ext_notif_receiver": [],
"date_due": "2026-09-30",
"estimated_hours": "4",
"spent_hours": null,
"creator": { "id": 980, "display_name": "Maria Admin" },
"date_created": "2026-08-10 14:22:05",
"date_updated": "2026-08-24 09:45:11"
}
],
"total": 1,
"limit": 20,
"offset": 0
}
Results default to creation date and document ID descending (newest first).
Use "order": "oldest" for ascending creation date and document ID, or
"order": "newest" for the default. Other order values return 400.
The response includes the effective order.
Task responsible is filterable: combine "filters": {"responsible": 1042, "dropdown_status": 12} to select an assignee's queue on the server. This filters
active RESPONSIBLE workers, not followers, while retaining organization access
boundaries. User IDs and dropdown IDs must come from the applicable organization.
Continue with offset += items.length until the offset reaches total. HTML fields are omitted from lists. Unknown filters are ignored; use only fields marked filter: true. No universal public DVS request quota is promised; infrastructure may apply additional limits.
To look up a contact ID for task ext_notif_receiver, call get_documents on contact_person. The contact list can be filtered by company and multi_dropdown_group ("filter": true in get_fields).
To look up a client ID for contact company, call get_documents on client. The client list can be filtered by dropdown fields, multi_dropdown_group, and projectmanager ("filter": true in get_fields).
create_document
Creates a new document. Only fields declared by get_fields are accepted; unknown fields are ignored. Available for every register whose list_sections actions include create_document. Missing required fields and values outside options are rejected with 400 before anything is saved, and the message names each field, for example Error on validation: date (required), dvs_vat_id (required). Registers with number and number_year assign the next number when both are omitted, the same way as the DMS add form: the last number of the current year (per dvs_number_type_id when the organization uses number types for that register) plus one, or 1. get_fields marks these fields generated_when_omitted. When the organization has number types for the register, dvs_number_type_id is required.
Invoice lines are lines fields: products on outgoing invoices (name, unit_name, count, price, optional discount_percent and dvs_vat_id) and sums on incoming invoices (dvs_vat_id, sum_without_vat, optional vat_sum and sum_with_vat, calculated from the VAT rate when omitted). Send the complete list: a line with id updates that stored line, a line without id is added, and stored lines left out are deleted. Omit the field to keep the stored lines. Line dvs_vat_id on an outgoing invoice applies only with show_different_vat; otherwise the invoice VAT rate is used. Every line is checked before saving, and errors name the line, for example products[1].price. Document totals (sum_with_vat, sum_for_payment, sum_vat, ...) are calculated and read-only. get_document returns the stored lines with their sums; get_documents does not.
POST https://api.files.fm/api_dvs/task/create_document
Content-Type: application/json
Auth: user and user_access_token in this JSON.
Request:
{
"user": "YOUR_USER",
"user_access_token": "YOUR_API_TOKEN",
"create_params": {
"dvs_project_id": 51,
"name": "Review pull request",
"dropdown_priority": 17,
"dropdown_status": 12,
"responsible": 1042,
"followers": [1105],
"ext_notif_receiver": [901],
"date_due": "2026-09-15",
"estimated_hours": "2"
}
}
| Parameter | Type | Required | Description |
|---|---|---|---|
create_params |
object | Yes | Document field values keyed by field name |
All fields declared as "required": true by get_fields must be present and non-empty. Fields marked "required": false may be omitted; the register sets sensible defaults.
User fields (user_id, user_ids) must contain IDs returned by get_users. Dropdown fields (dropdown, dropdown_ids) must contain option IDs returned by get_fields. Relation fields (relation, relation_ids) must contain document IDs from the register named in "section" (for task ext_notif_receiver: contact_person; for contact company: client). Invalid IDs return 400. Look up client IDs with client get_documents / get_document.
Response:
{
"dvs_document_id": 4822
}
Use the returned dvs_document_id with get_document to retrieve the full record including auto-generated fields such as full_number.
Creation and updates can send notifications. Explicitly supplied relation IDs are validated for the enabled target register, organization and active record before saving; omitted historical relations are preserved without revalidation. A failure in a later model hook still does not guarantee rollback.
Write operation keys
Every write requires top-level idempotency_key, except legacy task/contact create/update, task add_comment and task/CSB upload_document_file, which accept it optionally (1–128 ASCII letters, digits, ., _, :, -). Generate one key per intended mutation and keep it with the exact request. The same actor, organization, register, action, key and payload return the stored result instead of repeating the write. Object key order and transport credentials do not affect the fingerprint. A changed payload, running reservation or uncertain result returns 409; reconcile persisted state before retrying, and never choose a new key simply to bypass uncertainty. A request rejected before any write releases that reservation, so the same key can be sent again. A processing reservation with no result for 15 minutes is marked uncertain and is not executed again. Current permissions are checked again on replay.
With a supplied key and unavailable operation storage, the request fails with 503 before business dispatch. Requests without a key keep legacy behavior and have no deduplication guarantee. A repeated attachment upload key returns the first saved file. Uncertain results are never retried automatically. A rejected request may release its reservation, and a processing reservation older than 15 minutes is marked uncertain; completed receipts are not deleted. Receipts retain only identity hashes/status and result references, not request bodies or credentials; legacy model writes are not made transactionally atomic by the receipt.
update_document
Updates an existing document. Only the fields provided in update_params are changed; all other fields keep their current values. Available for task, contact_person, client, article and link.
POST https://api.files.fm/api_dvs/task/update_document
Content-Type: application/json
Auth: user and user_access_token in this JSON.
Request:
{
"user": "YOUR_USER",
"user_access_token": "YOUR_API_TOKEN",
"dvs_document_id": 4822,
"update_params": {
"dropdown_status": 14,
"spent_hours": "2.5"
}
}
| Parameter | Type | Required | Description |
|---|---|---|---|
dvs_document_id |
integer | Yes | ID of the document to update |
update_params |
object | Yes | Fields to change, keyed by field name |
The same field-level validation rules as create_document apply. The project (dvs_project_id) of a task cannot be changed through the API; a different project is rejected with 400, the current one is accepted.
Omitted fields keep their current values. Supplied array fields replace that field's selected values; read the record first when preserving followers or relations. See the tasks quickstart for complete curl, PHP and JavaScript workflows.
Response:
{
"dvs_document_id": 4822
}
get_comments
Read existing document comments using POST /api_dvs/{dvs_section}/get_comments with JSON
user, user_access_token, dvs_document_id, and optional limit (default 50,
range 1–200) and offset (default 0, nonnegative). Requires the same organization,
section read/record permission and active document lookup as get_document. Optional
comment_id restricts the result and total to that exact comment within the document.
Returns {items, total, limit, offset}. Items are sorted by comment ID ascending;
deleted comments are omitted. Each item contains id, sanitized and decoded
html, date_created, and author: {id, display_name, org_id, is_active}.
Unknown or foreign authors are null. Inactive same-organization authors remain
identifiable with is_active: false. Continue pagination until offset reaches
total; a page is not the full history unless all pages have been read.
This read does not notify people. It can verify an add_comment acknowledgement
using the returned comment_id, plus author, content and time. It provides no locking, conditional write,
or atomic snapshot guarantee.
search_users
Finds active users of your organization by name. Use it to get a user ID for the responsible filter in get_documents or for an @[USER:id] mention in add_comment, when you do not know a project the person works in. Available for task only; requires task read access. A supplied document ID is also checked against the actor's record scope.
POST https://api.files.fm/api_dvs/task/search_users
Content-Type: application/json
Request:
{
"user": "YOUR_USER",
"user_access_token": "YOUR_API_TOKEN",
"pattern": "anna smi",
"limit": 10
}
| Parameter | Type | Required | Description |
|---|---|---|---|
pattern |
string | Yes | 2–100 characters after trimming. Split into words; every word must occur (case-insensitive substring) in the user's login name, first name or surname. % and _ are literal characters. The separate email field is not searched. |
limit |
integer | No | Maximum number of users, 1–20 (default 10). There is no offset: refine the pattern instead of paging. |
dvs_document_id |
integer | No | Active task ID in your organization. Makes has_access specific to that task (own-record access through its project). Unknown or foreign IDs return 405. |
Response:
{
"users": [
{ "id": 1042, "display_name": "Anna Smith", "has_access": true },
{ "id": 1310, "display_name": "Annija Smiltēna", "has_access": false }
],
"limit": 10
}
Users are sorted by first name, surname and ID. display_name is the first name and surname, or the login name when both are empty. has_access is true when the user can read tasks (or the given task) — the same rule the DMS web interface uses when it marks mention suggestions with *. A user with has_access: false can still be mentioned and receives the mention email, but cannot open the task.
search_users does not change what may be assigned: responsible and followers on create/update still accept only IDs returned by get_users for the task's project. Invalid pattern, limit or dvs_document_id values return 400. The action reads data only and sends no notifications.
add_comment
Adds a document comment using the same storage, audit and notifications as the DMS web interface. Available for task, project_2, contact_person, client, article, and link. Requires register and record write rights; project comments do not require dvs:manage_access and do not change membership. New registers require idempotency_key; task comments retain optional-key compatibility. Normal register notifications and mention emails may be sent.
To mention a user, put @[USER:user_id] in the comment at the position you want (USER is the type prefix; user_id is the same integer id as in search_users / get_users / get_document). You can mention several users, including in the middle of a sentence. Plain @name, email addresses, and @[1042] without USER: stay as normal text. A mention id must belong to a user in the same organization. Mentions are not limited to project workers — the same as mentioning someone in the DMS web interface (they get the mention email even if they cannot open the task).
POST https://api.files.fm/api_dvs/task/add_comment
Content-Type: application/json
Auth: user and user_access_token in this JSON.
Request:
{
"user": "YOUR_USER",
"user_access_token": "YOUR_API_TOKEN",
"dvs_document_id": 4821,
"comment": "Please ask @[USER:1042] to review the draft before Friday."
}
| Parameter | Type | Required | Description |
|---|---|---|---|
dvs_document_id |
integer | Yes | ID of the document to comment on |
comment |
string | Yes | Comment body (same as the web editor). Must be non-empty after trimming. Insert @[USER:user_id] where a mention should appear. |
Response:
{
"dvs_document_id": 4821,
"comment_id": 125
}
upload_document_file
Attaches a new file to a reviewed document, the same as adding an attachment in the DMS web interface. The document folder is created on the first upload and is not a membership or folder-rights change. The upload is recorded in the document history. Existing files are not replaced: a file with the same name is saved with a numbered name, for example offer (1).pdf. Task and the legacy CSB route may omit idempotency_key. Every other reviewed register requires it; the key is reserved after the file and permission checks and before the folder is created. An uncertain result is not saved again automatically. The legacy CSB route is not part of the generic MCP upload tool.
Unlike the other actions, this request is multipart/form-data: send the credentials and dvs_document_id as form fields and the file in the file field.
curl -X POST 'https://api.files.fm/api_dvs/task/upload_document_file' \
-F user=YOUR_USER \
-F user_access_token=YOUR_API_TOKEN \
-F dvs_document_id=4821 \
-F file=@offer.pdf
| Parameter | Type | Required | Description |
|---|---|---|---|
dvs_document_id |
integer | Yes | ID of the document |
file |
file | Yes | The file to attach (multipart field), one file per request. The account's storage and file-size limits apply. |
idempotency_key |
string | For every register except task and csb_client_contract |
Stable key for this exact file. Reuse it only with the same document and file. |
Response:
{
"file_hash": "q7x2m9kd4wz1p8ht",
"upload_hash": "k3n8vz2qpw7r5xyt"
}
file_hash identifies the saved file; upload_hash is the task's attachment folder (also returned by get_document).
Errors: a missing, empty or failed file field, or more than one file, returns 400; an unknown task, a task in another organization, or missing upload permission returns 405, like other actions. Errors raised while saving the file itself (for example file too large, storage quota exceeded, or virus detected) currently return HTTP 200 with a JSON body {"success": false, "error_code": ..., "error_message": "..."}, so check for file_hash in the response.