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 DMS API currently covers tasks (create, read, update, add/read comments, organization user search), projects (read-only: fields, users, and document lists), contact persons (create, read, update), and clients / parties (read-only: fields, users, and document lists). Other DMS registers are not available through this API yet. Data created or updated here is the same data shown in the DMS web interface.

Note: Only dvs_section=task, dvs_section=project_2, dvs_section=contact_person, and dvs_section=client are supported. Additional registers and actions are planned.

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.

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:

1. Organization membership: the authenticated user must belong to an organization that has DMS enabled.
2. Section write permission: the user's user-group must have write permission on the target DMS register (dvs_section). Read-only users cannot currently reach the DMS API.

Missing section access or an unavailable section returns HTTP 405. If authentication does not establish a session organization, the API returns HTTP 401.

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}

For actions with no extra parameters (for example get_fields), the JSON body only needs user and user_access_token. Prefer the URL path for action and dvs_section; do not rely on overriding them from the body.

HTTP status codes

On error, the response body is empty. Use the HTTP status code (and status text) to determine the failure; there is no JSON error payload.

Supported registers

The {dvs_section} path segment must be one of the values below. Any other section returns HTTP 400 (Invalid DVS section).

create_document and update_document are available for tasks and contact persons. add_comment, get_comments and search_users are tasks only. Projects and clients are read-only through this API.

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).

Endpoint summary

{dvs_section} is task, project_2, contact_person, or client for the read actions (get_users is task, project_2, and client only; get_comments and search_users are task only). Write actions are task and contact_person (add_comment is task only).

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.

Example — open tasks of one person, oldest first:

1. task/get_fields → read dropdown_status.options and pick the "open" status ID; check that actions contains search_users.
2. task/search_users with {"pattern": "Anna Smith"} → user ID (or use actor.id for your own queue).
3. task/get_documents with {"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 available options for dropdown fields. 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

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
}

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"
}

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]
  }
}

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 task and contact_person.

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"
  }
}

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. There is no documented idempotency key. Reconcile an uncertain write with reads before retrying; invalid relation IDs can fail after part of a write has occurred. A failure does not guarantee rollback.

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 and contact_person.

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"
  }
}

The same field-level validation rules as create_document apply. The project (dvs_project_id) of a task cannot be changed through the API.

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 task comments using POST /api_dvs/task/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 write permission and active document lookup as get_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 by checking 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 the same section write permission as the other actions.

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
}

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 comment on a task. Same storage and notifications as the DMS web interface (htmlspecialchars on save; HTML is shown in comment emails like task descriptions). Available for task only.

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."
}

Response:

{
  "dvs_document_id": 4821
}