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 previously 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 DELETE request to the /file/ endpoint with your organization and asset IDs — though organization logos are protected from deletion and an alternative /assets/ endpoint only archives without removing the actual stored file.

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.

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 > Upload & attach file

Tallyfy’s API requires a two-step process to attach files to form fields: first upload the file via a multipart POST to the /file endpoint to receive an asset object and then use a PUT request to link that asset object to the specific task or kick-off form field using the correct capture IDs and subject parameters.

Was this helpful?

Get in touch

About Tallyfy