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

Files > Get file metadata

Tallyfy’s API lets you retrieve metadata for any uploaded file (asset) by calling GET on the…

Files > Download file

Tallyfy’s API provides two GET endpoints for retrieving uploaded files: one that returns the…