Skip to content

Download file

Endpoint

GET /organizations/{org_id}/file/{file_id}/dl

This endpoint downloads the actual content of a file (asset) that was previously uploaded (e.g., via a task form field or kick-off field).

Note the /dl suffix, which distinguishes this from potentially getting file metadata.

Request

Replace {org_id} with your Organization ID and {file_id} with the Asset ID of the file you want to download (this ID is obtained when uploading the file or potentially from getting task/process data).

Headers

  • Authorization: Bearer {your_access_token}
  • X-Tallyfy-Client: APIClient
  • (Accept header might be omitted or set based on expected file type, but the API primarily controls the response Content-Type)

Query parameters (optional)

No common query parameters are typically needed for this endpoint.

Code samples

These samples demonstrate how to fetch the file content and save it locally. Error handling should check the response status and Content-Type header.

// Note: This JS example is designed for a browser environment
// to leverage Blob creation and download triggering.
// For Node.js, you would pipe the response stream to a file.
const accessToken = 'YOUR_PERSONAL_ACCESS_TOKEN';
const orgId = 'YOUR_ORGANIZATION_ID';
const fileId = 'ASSET_ID_TO_DOWNLOAD';
const apiUrl = `https://go.tallyfy.com/api/organizations/${orgId}/file/${fileId}/dl`;
const defaultLocalFilename = 'downloaded_file'; // Default name if header is missing
const headers = new Headers();
headers.append('Authorization', `Bearer ${accessToken}`);
headers.append('X-Tallyfy-Client', 'APIClient');
fetch(apiUrl, {
method: 'GET',
headers: headers
})
.then(response => {
if (!response.ok) {
// Attempt to read error as text, as it might not be JSON for file endpoints
return response.text().then(text => {
console.error(`Error Response Body: ${text}`);
throw new Error(`HTTP error! status: ${response.status}`);
}).catch(() => {
// Fallback if reading text also fails
throw new Error(`HTTP error! status: ${response.status}`);
});
}
// Try to get filename from Content-Disposition header
const disposition = response.headers.get('content-disposition');
let filename = defaultLocalFilename;
if (disposition && disposition.includes('attachment')) {
const filenameRegex = /filename[^;=\n]*=((['"])(.*?)\2|[^;\n]*)/i;
const matches = filenameRegex.exec(disposition);
if (matches != null && matches[3]) {
filename = decodeURIComponent(matches[3].replace(/\+/g, ' ')); // Decode URI component
// Basic sanitization (replace potentially problematic characters)
filename = filename.replace(/[^\w\.\-]/g, '_');
} else {
// Fallback if regex fails but header exists
filename = `${defaultLocalFilename}_${fileId}`;
}
}
else {
// If no header, construct a name
filename = `${defaultLocalFilename}_${fileId}`;
const contentType = response.headers.get('content-type');
if (contentType) {
const ext = contentType.split('/')[1]; // Basic extension guess
if (ext && !filename.includes('.')) {
filename += `.${ext}`;
}
}
}
console.log(`Attempting to download as: ${filename}`);
// Return the blob and the determined filename
return response.blob().then(blob => ({ blob, filename }));
})
.then(({ blob, filename }) => {
// Create a link element to trigger the download in the browser
const url = window.URL.createObjectURL(blob);
const a = document.createElement('a');
a.style.display = 'none';
a.href = url;
a.download = filename; // Use the determined filename
document.body.appendChild(a);
a.click();
window.URL.revokeObjectURL(url);
a.remove();
console.log('File download initiated.');
})
.catch(error => {
console.error('Error downloading file:', error.message);
});

Response

A successful request returns a 200 OK status code. The response body is the raw file content, not JSON.

  • The Content-Type header indicates the MIME type of the file (e.g., image/png, application/pdf).
  • The Content-Disposition header often suggests a filename (e.g., attachment; filename="report.pdf"). Your code should parse this header to save the file with its original name if desired.

If the file ID is invalid or access is denied, an appropriate error status code (404, 403) will be returned, likely with an error message in the body (which might be JSON or plain text).


Files > Get file metadata

The GET endpoint allows retrieval of file metadata including filename upload date and related object details by providing organization ID and asset ID in the request URL path.

Files > Delete file

A DELETE endpoint that removes uploaded files from tasks or kick-off forms by making authorized requests to either /organizations/[org_id]/file/[asset_id] or /organizations/[org]/assets/[assetID] endpoints and returns a 200 OK status code upon successful deletion.

Code Samples > Managing files

The API enables file management functionalities including uploading downloading getting metadata and removing files associated with tasks or kick-off forms.

Tasks > Get task

A GET endpoint retrieves comprehensive task details including status owners deadlines and form fields through unique organization and task IDs with optional related data parameters.