Download file

Endpoints

GET /organizations/{org_id}/file/{file_id} - View the file inline (returns the file’s actual MIME type).
GET /organizations/{org_id}/file/{file_id}/dl - Download the file as an attachment (always returns application/octet-stream).

Both endpoints return raw file content for an asset that’s been uploaded to Tallyfy. Use the /dl suffix when you want to force a download with a Content-Disposition: attachment header.

Request

Replace {org_id} with your organization ID and {file_id} with the asset ID of the file. You’ll get this ID when uploading the file or from task/process data.

Headers

Authorization: Bearer {your_access_token}
X-Tallyfy-Client: APIClient

Code samples (download as attachment)

These samples fetch the file from the /dl endpoint and save it locally.

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 headers = new Headers();
headers.append('Authorization', `Bearer ${accessToken}`);
headers.append('X-Tallyfy-Client', 'APIClient');

fetch(apiUrl, { method: 'GET', headers })
.then(response => {
    if (!response.ok) {
        throw new Error(`HTTP error! status: ${response.status}`);
    }
    // Extract filename from Content-Disposition header
    const disposition = response.headers.get('content-disposition');
    let filename = `downloaded_${fileId}`;
    if (disposition) {
        const match = /filename="?([^";\n]+)"?/i.exec(disposition);
        if (match) filename = match[1];
    }
    return response.blob().then(blob => ({ blob, filename }));
})
.then(({ blob, filename }) => {
    const url = window.URL.createObjectURL(blob);
    const a = document.createElement('a');
    a.href = url;
    a.download = filename;
    document.body.appendChild(a);
    a.click();
    window.URL.revokeObjectURL(url);
    a.remove();
    console.log('File download started.');
})
.catch(error => console.error('Download failed:', error.message));

import requests
import os
import re

access_token = os.environ.get('TALLYFY_ACCESS_TOKEN', 'YOUR_PERSONAL_ACCESS_TOKEN')
org_id = os.environ.get('TALLYFY_ORG_ID', 'YOUR_ORGANIZATION_ID')
file_id = 'ASSET_ID_TO_DOWNLOAD'
api_url = f'https://go.tallyfy.com/api/organizations/{org_id}/file/{file_id}/dl'

headers = {
    'Authorization': f'Bearer {access_token}',
    'X-Tallyfy-Client': 'APIClient'
}

response = requests.get(api_url, headers=headers, stream=True)
response.raise_for_status()

# Extract filename from Content-Disposition header
filename = f'downloaded_{file_id}'
cd = response.headers.get('content-disposition', '')
match = re.search(r'filename="?([^";\n]+)"?', cd)
if match:
    filename = match.group(1)

with open(filename, 'wb') as f:
    for chunk in response.iter_content(chunk_size=8192):
        if chunk:
            f.write(chunk)

print(f'File saved as: {filename}')
response.close()

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.nio.file.Path;
import java.nio.file.Paths;
import java.nio.file.Files;
import java.nio.file.StandardCopyOption;
import java.util.regex.Matcher;
import java.util.regex.Pattern;

public class DownloadFile {
    public static void main(String[] args) throws Exception {
        String accessToken = System.getenv().getOrDefault("TALLYFY_ACCESS_TOKEN", "YOUR_PERSONAL_ACCESS_TOKEN");
        String orgId = System.getenv().getOrDefault("TALLYFY_ORG_ID", "YOUR_ORGANIZATION_ID");
        String fileId = "ASSET_ID_TO_DOWNLOAD";
        String apiUrl = String.format(
            "https://go.tallyfy.com/api/organizations/%s/file/%s/dl", orgId, fileId);

        HttpClient client = HttpClient.newBuilder()
            .followRedirects(HttpClient.Redirect.NORMAL).build();

        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create(apiUrl))
            .header("Authorization", "Bearer " + accessToken)
            .header("X-Tallyfy-Client", "APIClient")
            .GET().build();

        Path tempPath = Paths.get("temp_download_" + fileId);
        HttpResponse<Path> response = client.send(
            request, HttpResponse.BodyHandlers.ofFile(tempPath));

        if (response.statusCode() == 200) {
            String filename = "downloaded_" + fileId;
            String disposition = response.headers()
                .firstValue("content-disposition").orElse("");
            Matcher m = Pattern.compile("filename=\"?([^\";\n]+)\"?")
                .matcher(disposition);
            if (m.find()) filename = m.group(1);

            Path finalPath = Paths.get(filename);
            Files.move(tempPath, finalPath, StandardCopyOption.REPLACE_EXISTING);
            System.out.println("Downloaded to: " + finalPath.toAbsolutePath());
        } else {
            System.err.println("Download failed. Status: " + response.statusCode());
            Files.deleteIfExists(tempPath);
        }
    }
}

package main

import (
  "fmt"
  "io"
  "mime"
  "net/http"
  "os"
  "path/filepath"
  "time"
)

func main() {
  accessToken := os.Getenv("TALLYFY_ACCESS_TOKEN")
  if accessToken == "" {
    accessToken = "YOUR_PERSONAL_ACCESS_TOKEN"
  }
  orgId := os.Getenv("TALLYFY_ORG_ID")
  if orgId == "" {
    orgId = "YOUR_ORGANIZATION_ID"
  }
  fileId := "ASSET_ID_TO_DOWNLOAD"
  apiUrl := fmt.Sprintf(
    "https://go.tallyfy.com/api/organizations/%s/file/%s/dl", orgId, fileId)

  client := &http.Client{Timeout: 60 * time.Second}
  req, _ := http.NewRequest("GET", apiUrl, nil)
  req.Header.Set("Authorization", "Bearer "+accessToken)
  req.Header.Set("X-Tallyfy-Client", "APIClient")

  resp, err := client.Do(req)
  if err != nil {
    fmt.Printf("Request failed: %v\n", err)
    return
  }
  defer resp.Body.Close()

  if resp.StatusCode != http.StatusOK {
    body, _ := io.ReadAll(resp.Body)
    fmt.Printf("Error %d: %s\n", resp.StatusCode, string(body))
    return
  }

  // Extract filename from Content-Disposition header
  filename := "downloaded_" + fileId
  if cd := resp.Header.Get("Content-Disposition"); cd != "" {
    _, params, err := mime.ParseMediaType(cd)
    if err == nil && params["filename"] != "" {
      filename = filepath.Base(params["filename"])
    }
  }

  outFile, err := os.Create(filename)
  if err != nil {
    fmt.Printf("Cannot create file: %v\n", err)
    return
  }
  defer outFile.Close()

  written, _ := io.Copy(outFile, resp.Body)
  fmt.Printf("Saved %s (%d bytes)\n", filename, written)
}

#include <iostream>
#include <fstream>
#include <string>
#include <cpprest/http_client.h>
#include <cpprest/filestream.h>

using namespace web;
using namespace web::http;
using namespace web::http::client;
using namespace concurrency::streams;

pplx::task<void> DownloadFileAsset(const utility::string_t& fileId)
{
    utility::string_t accessToken = U("YOUR_PERSONAL_ACCESS_TOKEN");
    utility::string_t orgId = U("YOUR_ORGANIZATION_ID");
    utility::string_t apiUrl = U("https://go.tallyfy.com/api/organizations/")
        + orgId + U("/file/") + fileId + U("/dl");
    utility::string_t defaultFilename = U("downloaded_") + fileId;

    http_client client(apiUrl);
    http_request request(methods::GET);
    request.headers().add(U("Authorization"), U("Bearer ") + accessToken);
    request.headers().add(U("X-Tallyfy-Client"), U("APIClient"));

    return client.request(request).then([defaultFilename](http_response response)
    {
        if (response.status_code() == status_codes::OK)
        {
            utility::string_t filename = defaultFilename;
            if (response.headers().has(header_names::content_disposition)) {
                auto disposition = response.headers()[header_names::content_disposition];
                std::wsmatch match;
                std::wregex pattern(U("filename=\"?([^\";\n]+)\"?"));
                if (std::regex_search(disposition, match, pattern))
                    filename = match[1].str();
            }

            return file_stream<uint8_t>::open_ostream(filename)
                .then([response](ostream os) {
                    return response.body().read_to_end(os.streambuf());
                })
                .then([filename](size_t size) {
                    std::wcout << L"Downloaded " << filename
                               << L" (" << size << L" bytes)" << std::endl;
                });
        }
        else
        {
            return response.extract_string().then([response](utility::string_t body) {
                std::wcerr << L"Error " << response.status_code()
                           << L": " << body << std::endl;
            });
        }
    });
}

int main()
{
    try {
        DownloadFileAsset(U("ASSET_ID_TO_DOWNLOAD")).wait();
    } catch (const std::exception& e) {
        std::cerr << "Error: " << e.what() << std::endl;
    }
    return 0;
}
// Requires C++ REST SDK (Casablanca)

using System;
using System.IO;
using System.Net.Http;
using System.Net.Http.Headers;
using System.Threading.Tasks;

public class TallyfyFileDownloader
{
    private static readonly HttpClient client = new HttpClient();

    public static async Task DownloadFileAsync(string fileId)
    {
        var accessToken = Environment.GetEnvironmentVariable("TALLYFY_ACCESS_TOKEN")
            ?? "YOUR_PERSONAL_ACCESS_TOKEN";
        var orgId = Environment.GetEnvironmentVariable("TALLYFY_ORG_ID")
            ?? "YOUR_ORGANIZATION_ID";
        var apiUrl = $"https://go.tallyfy.com/api/organizations/{orgId}/file/{fileId}/dl";

        using var request = new HttpRequestMessage(HttpMethod.Get, apiUrl);
        request.Headers.Authorization = new AuthenticationHeaderValue("Bearer", accessToken);
        request.Headers.Add("X-Tallyfy-Client", "APIClient");

        var response = await client.SendAsync(request,
            HttpCompletionOption.ResponseHeadersRead);

        if (response.IsSuccessStatusCode)
        {
            // Get filename from Content-Disposition or use default
            string filename = response.Content.Headers.ContentDisposition?.FileName?.Trim('"')
                ?? $"downloaded_{fileId}";

            using var fileStream = new FileStream(filename, FileMode.Create);
            using var httpStream = await response.Content.ReadAsStreamAsync();
            await httpStream.CopyToAsync(fileStream);
            Console.WriteLine($"Downloaded: {filename}");
        }
        else
        {
            var error = await response.Content.ReadAsStringAsync();
            Console.WriteLine($"Error {response.StatusCode}: {error}");
        }
    }
}

Viewing inline

To display the file inline (when the browser supports the MIME type), use the endpoint without /dl. This returns the file’s original Content-Type instead of application/octet-stream:

curl -X GET \
  -H "Authorization: Bearer $TALLYFY_ACCESS_TOKEN" \
  -H "X-Tallyfy-Client: APIClient" \
  "https://go.tallyfy.com/api/organizations/$TALLYFY_ORG_ID/file/$FILE_ID"

Response

A successful request returns 200 OK. The response body is the raw file content — not JSON.

Download endpoint (/dl) headers:

Content-Type: application/octet-stream
Content-Disposition: attachment; filename="<original_name>"
Content-Length: <bytes>

Inline endpoint (without /dl) headers:

Content-Type: <actual MIME type> (e.g., image/png, application/pdf)
Content-Length: <bytes>

If the file ID is invalid or you don’t have access, the API returns 404 or 403 with an error message.

Files > Delete file

Tallyfy’s API lets you permanently delete an uploaded file and its storage record by sending a…

Files > Get file metadata

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

Code Samples > Managing files

Tallyfy’s API lets you upload files up to 100MB and attach them to tasks or kick-off forms. You…

Files > Upload & attach file

Tallyfy”s API uses a two-step process to attach files to form fields. First upload the file via…

Was this helpful?

Get in touch

About Tallyfy