Skip to content

Upload & attach file

Attaching files to form fields via Tallyfy’s API is a two-step process:

  1. Upload the file - send the file to Tallyfy’s upload endpoint and get back an asset object.
  2. Attach to the field - use that asset object to update the task or template, linking the file to the right form field.

Step 1 - Upload the file

Endpoint

POST /organizations/{org_id}/file

Both /file and /assets route to the same handler, but /file is the standard endpoint for uploads.

Request type

multipart/form-data

Headers

  • Authorization: Bearer {your_access_token}
  • Accept: application/json
  • X-Tallyfy-Client: APIClient

Don’t set Content-Type manually - your HTTP client sets it automatically for multipart requests.

Form data fields

FieldRequiredDescriptionExample
nameYesThe file binary data (max 100MB)(file input)
subject_idYesID of the parent object - run_id for tasks, checklist_id for kick-offrun_abc123
subject_typeYesRun for task fields, Checklist for kick-off fieldsRun
uploaded_fromYesThe form field’s Capture ID for tasks, or ko_field for kick-off fieldscapture_id_abc123
sourceNoHow the file is provided - local or urllocal
step_idNoStep ID within the template (only for task uploads)step_xyz789
checklist_idNoTemplate ID the process was launched from (only for task uploads)template_efg456
systemNoExternal storage system if applicableDropbox, Google Drive, etc.

Allowed file types

The API accepts these extensions: xlsx, xls, pptx, docx, ppt, doc, rtf, pdf, txt, mpga, mov, qt, mp4, webm, jpg, jpeg, gif, png, ai, psd, zip, xml, xps, dwg, csv, tif, bmp.

Code samples for upload

const accessToken = 'YOUR_PERSONAL_ACCESS_TOKEN';
const orgId = 'YOUR_ORGANIZATION_ID';
const apiUrl = `https://go.tallyfy.com/api/organizations/${orgId}/file`;
// --- For task field ---
const formFieldId = 'CAPTURE_ID_OF_FILE_FIELD';
const runId = 'PROCESS_RUN_ID';
const stepId = 'STEP_ID_CONTAINING_FIELD';
const checklistId = 'TEMPLATE_ID_OF_RUN';
// --- OR for kick-off field ---
// const checklistIdForKO = 'TEMPLATE_ID_WITH_KICKOFF';
const fileInput = document.getElementById('yourFileInputId');
if (!fileInput?.files?.length) {
throw new Error('No file selected.');
}
const file = fileInput.files[0];
const formData = new FormData();
formData.append('name', file, file.name);
formData.append('source', 'local');
// For task field:
formData.append('uploaded_from', formFieldId);
formData.append('subject_type', 'Run');
formData.append('subject_id', runId);
formData.append('step_id', stepId);
formData.append('checklist_id', checklistId);
// For kick-off field:
// formData.append('uploaded_from', 'ko_field');
// formData.append('subject_type', 'Checklist');
// formData.append('subject_id', checklistIdForKO);
const response = await fetch(apiUrl, {
method: 'POST',
headers: {
'Authorization': `Bearer ${accessToken}`,
'Accept': 'application/json',
'X-Tallyfy-Client': 'APIClient'
},
body: formData
});
if (!response.ok) {
const errData = await response.json().catch(() => response.text());
console.error('Upload failed:', errData);
throw new Error(`HTTP error! status: ${response.status}`);
}
const result = await response.json();
console.log('Uploaded file asset:', JSON.stringify(result, null, 2));
// Use result.data for Step 2

Upload response

A successful upload returns 200 OK with the asset object wrapped in data. You’ll need this object for Step 2.

{
"data": {
"id": "asset_id_abc123xyz",
"filename": "document.pdf",
"version": 1,
"uploaded_from": "capture_id_abc123",
"uploaded_at": "2024-01-15T10:00:00Z",
"step_id": "step_id_xyz789",
"source": "local",
"system": null,
"uploaded_to_s3": true,
"subject": {
"id": "run_id_abc",
"type": "Run"
}
}
}

Step 2 - Attach the uploaded file to a field

Use the asset object from Step 1 to update the task or template, linking the file to the form field.

Endpoint

  • Task field: PUT /organizations/{org_id}/runs/{run_id}/tasks/{task_id}
  • Kick-off field: PUT /organizations/{org_id}/checklists/{checklist_id}

Request type

application/json

Headers

  • Authorization: Bearer {your_access_token}
  • Accept: application/json
  • X-Tallyfy-Client: APIClient
  • Content-Type: application/json

Body for task fields

The taskdata object uses the form field’s Capture ID as the key. The value is an array containing the asset object from Step 1.

{
"taskdata": {
"CAPTURE_ID_OF_FILE_FIELD": [
{
"id": "asset_id_abc123xyz",
"filename": "document.pdf",
"version": 1,
"uploaded_from": "capture_id_abc123",
"uploaded_at": "2024-01-15T10:00:00Z",
"step_id": "step_id_xyz789",
"source": "local",
"uploaded_to_s3": true,
"subject": {
"id": "run_id_abc",
"type": "Run"
}
}
]
}
}

Body for kick-off fields

Update the template’s prerun array. Set the value for your file field to an array containing the asset object from Step 1.

{
"prerun": [
{
"id": "PRERUN_FIELD_ID_FOR_FILE",
"value": [
{
"id": "asset_id_abc123xyz",
"filename": "document.pdf",
"version": 1,
"uploaded_from": "ko_field",
"uploaded_at": "2024-01-15T10:00:00Z",
"source": "local",
"uploaded_to_s3": true,
"subject": {
"id": "checklist_id_abc",
"type": "Checklist"
}
}
]
}
]
}

Code samples for attaching

These examples assume you have the assetObject from Step 1 and the required IDs.

async function attachFileToTask(assetObject, orgId, runId, taskId, formFieldId, accessToken) {
const apiUrl = `https://go.tallyfy.com/api/organizations/${orgId}/runs/${runId}/tasks/${taskId}`;
const payload = {
taskdata: {
[formFieldId]: [assetObject]
}
};
const response = await fetch(apiUrl, {
method: 'PUT',
headers: {
'Authorization': `Bearer ${accessToken}`,
'Accept': 'application/json',
'X-Tallyfy-Client': 'APIClient',
'Content-Type': 'application/json'
},
body: JSON.stringify(payload)
});
const responseData = await response.json();
if (!response.ok) {
console.error('Failed to attach file:', responseData);
throw new Error(`HTTP error! status: ${response.status}`);
}
console.log('File attached successfully:', JSON.stringify(responseData, null, 2));
}

Attach response

A successful PUT returns 200 OK with the updated task or template object. The file attachment appears under the field’s Capture ID in taskdata.

{
"data": {
"taskdata": {
"CAPTURE_ID_OF_FILE_FIELD": [
{
"id": "asset_id_abc123xyz",
"filename": "document.pdf",
"version": 1,
"uploaded_from": "capture_id_abc123",
"uploaded_at": "2024-01-15T10:00:00Z",
"step_id": "step_id_xyz789",
"source": "local",
"uploaded_to_s3": true,
"subject": {
"id": "run_id_abc",
"type": "Run"
}
}
]
}
}
}

Code Samples > Managing files

Tallyfy’s API provides endpoints to upload files up to 100MB and attach them to tasks or kick-off forms as well as download retrieve metadata for and permanently delete those file assets.

Files > Get file metadata

Tallyfy’s API lets you retrieve metadata for any uploaded file (asset) by calling GET on the asset endpoint with your organization and asset IDs and it returns details like the filename and upload date and which process or task the file is attached to.

Postman > Task operations and automation

Tallyfy’s API lets you list and filter tasks by status or assignee and complete them via a POST to the completed-tasks endpoint while saving form field captures separately and handling file uploads through multipart form-data and managing task assignments and comments programmatically through Postman.

Files > Download file

Tallyfy’s API provides two GET endpoints for retrieving uploaded files: one that returns the file inline with its original MIME type for browser display and another with a /dl suffix that forces a download as an attachment with the original filename preserved in the Content-Disposition header.