DVS tasks integration quickstart
Use this workflow to discover IDs and prepare a correct task request without guessing. DVS and DMS name the same public data-management API. The full DMS reference describes the actions and field types.
Prerequisites
- A dedicated Files.fm user in an organization with DVS enabled.
- An API access token from the account's API-key settings.
- Read permission (or write permission) on the registers you query. Creating/updating tasks requires task and project edit access; project and contact/client lookups use their own section permissions. Own-record access is also supported where documented in the DMS reference.
- The name of the existing project.
project_2is the DVS projects register; it is not the separate Objects API.
Base URL: https://api.files.fm. Every DVS action uses POST JSON and includes user and user_access_token, except file attachments (section 4a), which use multipart/form-data with the same fields. A website session alone and an MCP Bearer token are not this authentication format. Never put credentials in URLs.
1. Discover fields and projects
POST /api_dvs/task/get_fields
Content-Type: application/json
{"user":"YOUR_USER","user_access_token":"YOUR_API_TOKEN"}
Read fields[].name, type, required, filter, options, section, and depends_on. Required task fields currently include name and dvs_project_id. Dropdown option IDs belong to this organization; example values from documentation are not reusable IDs.
The response also contains actions (actions this server supports for the section) and actor ({id, org_id} of the authenticated account). Check actions before relying on newer actions such as search_users or get_comments.
POST /api_dvs/project_2/get_documents
Content-Type: application/json
{"user":"YOUR_USER","user_access_token":"YOUR_API_TOKEN","limit":200,"offset":0}
Match the requested project against items[].name and retain its integer dvs_document_id. Continue with offset += items.length until offset >= total. Stop and ask for a choice if a name is absent or ambiguous. A short page is not itself the documented completion condition; use total.
Filters use field names with filter: true from get_fields. Unknown filter names are ignored, not rejected. Multiple values for a field are OR; different fields are AND. Lists omit HTML descriptions; use get_document for full content.
2. Discover assignable users and status options
POST /api_dvs/task/get_users
Content-Type: application/json
{"user":"YOUR_USER","user_access_token":"YOUR_API_TOKEN","dvs_project_id":123}
Here 123 represents the project ID just discovered. Resolve users[].display_name to an integer id; do not substitute email addresses or usernames in task user fields. Only use the users returned for that project — responsible and followers reject other IDs, including IDs found with search_users.
Resolve dropdown_status, dropdown_priority, and other dropdown values from the task field's options. For external followers, look up contact_person document IDs; those are different from platform user IDs. Contact and client relationships
3. Create a task
After discovery, construct this body using the real IDs and any additional required fields:
{
"user": "YOUR_USER",
"user_access_token": "YOUR_API_TOKEN",
"create_params": {
"dvs_project_id": 123,
"name": "Review integration",
"responsible": 456,
"dropdown_status": 789,
"description": "<p>Review the integration.</p>"
}
}
Send to POST /api_dvs/task/create_document. Optional fields may be omitted. IDs 123, 456, and 789 above are illustrative; replace them with discovery results.
{"dvs_document_id":4822}
Retain the returned task ID. Creation and updates can send notifications. Task create, update and comment actions accept an optional idempotency_key; uploads do not. With a key, retry the exact same request using the same key. After a timeout or uncertain write outcome, reconcile with task reads/comments before retrying. Requests without a key retain legacy behavior and have no deduplication guarantee; model hooks may still leave partial state, so a failure is not proof that nothing was saved.
3a. Inspect a person's task queue
- Status ID: from
task/get_fields, pick the wanted entry of thedropdown_statusfield'soptionsbydisplay_nameand keep itsid. - User ID: for your own queue use
actor.idfromget_fields. For someone else, search the organization by name:
POST /api_dvs/task/search_users
Content-Type: application/json
{"user":"YOUR_USER","user_access_token":"YOUR_API_TOKEN","pattern":"anna smith","limit":5}
search_users returns up to limit (max 20) active organization users as {id, display_name, has_access}; refine the pattern if the person is not in the result or if several people match. task/get_users for a known project is an alternative, but it lists only users assignable in that project.
- List the queue; both filters are applied on the server (different fields are AND, several values of one field are OR):
POST /api_dvs/task/get_documents
Content-Type: application/json
{"user":"YOUR_USER","user_access_token":"YOUR_API_TOKEN","filters":{"responsible":456,"dropdown_status":[789,790]},"order":"oldest","limit":20}
responsible matches the task's responsible person only, not followers. Use task/get_comments to read and paginate a task's comment history, including author organization and activity.
4. Read, update, and comment
Call task/get_document with auth and dvs_document_id to read the full saved record. IDs in read responses are often objects such as { "id": 456, "display_name": "..." }; write requests need the scalar IDs.
{
"user": "YOUR_USER",
"user_access_token": "YOUR_API_TOKEN",
"dvs_document_id": 4822,
"update_params": { "dropdown_status": 790 }
}
Send to POST /api_dvs/task/update_document. Discover 790 from get_fields. This is a partial update: omitted fields keep their values; arrays supplied for workers/relations replace that field's selection. The task's project cannot be changed through this API.
{
"user": "YOUR_USER",
"user_access_token": "YOUR_API_TOKEN",
"dvs_document_id": 4822,
"comment": "Integration reviewed."
}
Send to POST /api_dvs/task/add_comment. Mention a platform user with @[USER:456]; mentions can notify users. There is no documented task delete action in this API. Clean up test records through the authorized DVS UI.
4a. Attach a file
When get_fields lists upload_document_file in actions, attach one file per request as multipart/form-data:
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=789 -F file=@report.pdf
The response contains file_hash and upload_hash (the task's attachment folder, created on first use). If the response has "success": false instead, the file was not saved; read error_message. A file whose name already exists is saved with a numbered name, for example report (1).pdf. To list a task's files, read upload_hash from get_document and call POST /api_v2/get_folder_content with folder_hash. See upload_document_file.
curl
Set credentials in your local environment. The following uses Node to write JSON to stdin, keeping the token out of the URL and curl arguments:
export FILESFM_USER='YOUR_USER'
export FILESFM_API_TOKEN='YOUR_API_TOKEN'
node -e 'process.stdout.write(JSON.stringify({user:process.env.FILESFM_USER,user_access_token:process.env.FILESFM_API_TOKEN}))' |
curl --silent --show-error --fail-with-body --max-time 30 \
'https://api.files.fm/api_dvs/task/get_fields' \
-H 'Content-Type: application/json' --data-binary @-
For write calls, prepare the JSON body from discovered IDs in a local private file and use --data-binary @request.json. Protect and remove credential-bearing files after use. Do not use verbose HTTP traces with real credentials.
JavaScript (Node 18+ or a trusted server)
async function dvs(section, action, params = {}) {
const response = await fetch(`https://api.files.fm/api_dvs/${section}/${action}`, {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({ ...params, user: process.env.FILESFM_USER,
user_access_token: process.env.FILESFM_API_TOKEN }),
signal: AbortSignal.timeout(30000)
});
const text = await response.text();
if (!response.ok) throw new Error(`DVS HTTP ${response.status}`);
if (!text) throw new Error('Missing success response');
return JSON.parse(text);
}
const { fields } = await dvs('task', 'get_fields');
const projects = [];
let offset = 0;
while (true) {
const page = await dvs('project_2', 'get_documents', { limit: 200, offset });
projects.push(...page.items);
offset += page.items.length;
if (offset >= page.total) break;
if (!page.items.length) throw new Error('Incomplete project listing');
}
const matches = projects.filter(p => p.name === process.env.FILESFM_PROJECT_NAME);
if (matches.length !== 1) throw new Error('Choose one existing project');
const projectId = matches[0].dvs_document_id;
const { users } = await dvs('task', 'get_users', { dvs_project_id: projectId });
const statusOptions = fields.find(f => f.name === 'dropdown_status')?.options || [];
// Select a user and status from users/statusOptions; omit them if not needed.
const createParams = { dvs_project_id: projectId, name: 'Review integration' };
console.log({ endpoint: '/api_dvs/task/create_document', create_params: createParams });
// Only run the following block when task creation and notifications are authorized:
// const created = await dvs('task', 'create_document', { create_params: createParams });
// const task = await dvs('task', 'get_document', { dvs_document_id: created.dvs_document_id });
// await dvs('task', 'update_document', { dvs_document_id: task.dvs_document_id,
// update_params: { description: '<p>Integration verified.</p>' } });
// await dvs('task', 'add_comment', { dvs_document_id: task.dvs_document_id,
// comment: 'Integration reviewed.' });
Keep API tokens on a trusted server, not in shipped browser JavaScript. Client-side UI should call your own authorized integration backend.
PHP 7.4+
<?php
function dvs($section, $action, array $params = []) {
$params['user'] = getenv('FILESFM_USER');
$params['user_access_token'] = getenv('FILESFM_API_TOKEN');
$curl = curl_init('https://api.files.fm/api_dvs/' . $section . '/' . $action);
curl_setopt_array($curl, [
CURLOPT_POST => true, CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => ['Content-Type: application/json'],
CURLOPT_POSTFIELDS => json_encode($params, JSON_THROW_ON_ERROR),
CURLOPT_CONNECTTIMEOUT => 10, CURLOPT_TIMEOUT => 30,
]);
$body = curl_exec($curl);
$status = curl_getinfo($curl, CURLINFO_HTTP_CODE);
$failed = $body === false;
curl_close($curl);
if ($failed) { throw new RuntimeException('DVS transport failed'); }
if ($status !== 200) { throw new RuntimeException('DVS HTTP ' . $status); }
return json_decode($body, true, 512, JSON_THROW_ON_ERROR);
}
$fields = dvs('task', 'get_fields')['fields'];
$projects = []; $offset = 0;
do {
$page = dvs('project_2', 'get_documents', ['limit' => 200, 'offset' => $offset]);
$projects = array_merge($projects, $page['items']);
$offset += count($page['items']);
if (!$page['items'] && $offset < $page['total']) {
throw new RuntimeException('Incomplete project listing');
}
} while ($offset < $page['total']);
$matches = array_values(array_filter($projects, function ($p) {
return $p['name'] === getenv('FILESFM_PROJECT_NAME');
}));
if (count($matches) !== 1) { throw new RuntimeException('Choose one existing project'); }
$projectId = $matches[0]['dvs_document_id'];
$users = dvs('task', 'get_users', ['dvs_project_id' => $projectId])['users'];
$createParams = ['dvs_project_id' => $projectId, 'name' => 'Review integration'];
// After explicit write authorization:
// $created = dvs('task', 'create_document', ['create_params' => $createParams]);
// $task = dvs('task', 'get_document', ['dvs_document_id' => $created['dvs_document_id']]);
// dvs('task', 'update_document', ['dvs_document_id' => $task['dvs_document_id'],
// 'update_params' => ['description' => '<p>Integration verified.</p>']]);
// dvs('task', 'add_comment', ['dvs_document_id' => $task['dvs_document_id'],
// 'comment' => 'Integration reviewed.']);
Failure handling and MCP
DVS errors can have an empty body. Check status first: 400 parameters, 401 authentication or missing session organization, 405 method/section/permission/not-found conditions, 500 backend failure. Do not log request bodies containing tokens. No universal public DVS request quota is promised; infrastructure can enforce additional limits.
Public MCP filesfm_search_docs and filesfm_get_doc can find and retrieve this guide without auth. Where enabled, the MCP DVS tools also read and change supported registers, add section-aware comments, manage project members with separate consent, and attach files to tasks with the user's own permissions and discovered IDs.