This guide covers the FilesService, which provides a set of tools for managing file attachments on Acumatica records. You can use it to download existing files, upload new ones, and retrieve metadata like filenames and comments.

1. Accessing the Service

The FilesService is available as an attribute on your main AcumaticaClient instance.

Assuming 'client' is an initialized AcumaticaClient

files_service = client.files

2. Downloading a File

get_file(api_version, file_id)

This method retrieves the raw binary content of a file using its unique file_id (a GUID). This is useful when you know the specific ID of the file you want to download.

Example: Download a file and save it locally

file_id = "9be45eb7-f97d-400b-96a5-1c4cf82faa96" # The GUID of the file in Acumatica  
api_version = "24.200.001"

try:  
    file_bytes = client.files.get_file(api_version, file_id)  
    with open("downloaded_image.jpg", "wb") as f:  
        f.write(file_bytes)  
    print("File downloaded successfully.")  
except Exception as e:  
    print(f"Failed to download file: {e}")

3. Uploading a File

attach_file_to_record(href_template, filename, content, comment=None)

This method attaches a new file to an existing Acumatica record. The process involves two main steps:

1. Fetch the target record: First, you need to get the record you want to attach the file to. The response for this record will contain a special _links["files:put"] key, which holds the unique URL template needed for the upload.
2. Call attach_file_to_record: Use the template from step 1, along with the file's name and its binary content, to perform the upload.

Example: Attach a local image to a stock item

# Step 1: Fetch the record to get the upload URL template  
try:  
    stock_item = client.records.get_record_by_key_field(  
        "24.200.001", "StockItem", "InventoryID", "ITEM001"  
    )  
    # The href_template is required for the upload  
    href_template = stock_item["_links"]["files:put"]

    # Step 2: Read the local file and call the attach method  
    with open("product_image.png", "rb") as f:  
        file_content = f.read()

    client.files.attach_file_to_record(  
        href_template=href_template,  
        filename="product_image.png",  
        content=file_content,  
        comment="Main product view" # Optional: adds a comment to the file  
    )  
    print("File attached successfully.")

except Exception as e:  
    print(f"Failed to attach file: {e}")

4. Listing File Metadata

Sometimes you don't need the file itself, but rather information about the files attached to a record. These helper methods retrieve a list of file metadata objects, each containing the id, filename, and comment.

get_file_comments_by_id(api_version, entity, record_id)

Fetches file metadata for a record using its internal GUID.

get_file_comments_by_key_field(api_version, entity, key, value)

Fetches file metadata for a record using its primary key(s).

Example: List all attachments for a specific sales order

try:  
    # Get file info using the sales order's type and number  
    attachments = client.files.get_file_comments_by_key_field(  
        "24.200.001",  
        "SalesOrder",  
        key="SO", # Order Type  
        value="SO006724" # Order Number  
    )

    if attachments:  
        print("Files attached to SO006724:")  
        for file_info in attachments:  
            print(f"- Filename: {file_info['filename']}, Comment: {file_info.get('comment', 'N/A')}")  
    else:  
        print("No files found for this order.")

except Exception as e:  
    print(f"Could not retrieve file list: {e}")  

4. Deleting a File

delete_file(api_version, file_id)

This method permanently deletes a file attachment from Acumatica using its unique file_id.

Example: Delete a specific file attachment

# First, you need the ID of the file you want to delete.  
# You can get this from the file metadata.  
file_id_to_delete = "9be45eb7-f97d-400b-96a5-1c4cf82faa96"

try:  
    client.files.delete_file("24.200.001", file_id_to_delete)  
    print(f"File {file_id_to_delete} deleted successfully.")  
except Exception as e:  
    print(f"Failed to delete file: {e}")