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, comment), 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 is 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). Write actions are task and contact_person (add_comment is task only).

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": false,
      "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"
    }
  ]
}

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 is scoped to workers of the specified project.

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 are ordered by creation date descending (newest first).

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
}

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