Bundles

A Bundle is the API/SDK term for the feature called Share Links in the web interface. The API provides the full set of actions related to Share Links, including sending them via E-Mail.

Please note that we very closely monitor the E-Mailing feature and any abuse will result in disabling of your site.

SDK Method

files_sdk.bundle.list()

Return Object

ListObj[Bundle]

Authorization Requirement

Available to all authenticated keys or sessions.

Method Arguments

Parameter access is subject to this endpoint's authorization requirement and the caller's access to the affected resource. Site Administrator access also includes Site-Wide API keys.

Argument	Description
user_id int64	User ID. Provide a value of `0` to operate the current session's user. Can be set by: Site Administrator; Read-only Administrator; Workspace Administrator.
deleted boolean	If true, only list deleted Share Links.

Additional Arguments

Example Request

import files_sdk

try:
  bundles = files_sdk.bundle.list({
    "user_id": 1
  })
  for bundle in bundles.auto_paging_iter():
    # Operate on bundle
except files_sdk.error.NotAuthenticatedError as err:
  print(f"Authentication Error Occurred ({type(err).__name__}):", err)
except files_sdk.error.Error as err:
  print(f"Unknown Error Occurred ({type(err).__name__}):", err)

SDK Method

files_sdk.bundle.find()

Return Object

Bundle

Authorization Requirement

Available to all authenticated keys or sessions.

Method Arguments

Argument	Description
id int64 Required	Bundle ID.
deleted boolean	If true, show a deleted Share Link.

Example Request

import files_sdk

try:
  bundle = files_sdk.bundle.find(id, {
    "deleted": False
  })
  # Operate on bundle
except files_sdk.error.NotAuthenticatedError as err:
  print(f"Authentication Error Occurred ({type(err).__name__}):", err)
except files_sdk.error.Error as err:
  print(f"Unknown Error Occurred ({type(err).__name__}):", err)

SDK Method

files_sdk.bundle.create()

Return Object

Bundle

Authorization Requirement

Available to all authenticated keys or sessions.

Method Arguments

Parameter access is subject to this endpoint's authorization requirement and the caller's access to the affected resource. Site Administrator access also includes Site-Wide API keys.

Argument	Default	Description
user_id int64		User ID. Provide a value of `0` to operate the current session's user. Can be set by: Site Administrator; Workspace Administrator.
paths array(string) Required		A list of paths to include in this bundle.
password string		Password for this bundle.
bypasses_site_expiration_rules boolean	`false`	If true, this Share Link bypasses site-wide expiration rules. Only site admins may set this. Can be set by: Site Administrator.
form_field_set_id int64		Id of Form Field Set to use with this bundle
create_snapshot boolean		If true, create a snapshot of this bundle's contents.
dont_separate_submissions_by_folder boolean	`false`	Do not create subfolders for files uploaded to this share. Note: there are subtle security pitfalls with allowing anonymous uploads from multiple users to live in the same folder. We strongly discourage use of this option unless absolutely required.
expires_at string		Explicit Bundle expiration date/time. If not set, the site-wide expiration setting may apply.
finalize_snapshot boolean		If true, finalize the snapshot of this bundle's contents. Note that `create_snapshot` must also be true.
max_uses int64		Maximum number of times bundle can be accessed
group_id int64		Owning group ID. If set, members of this group can view, edit, and share this Share Link.
internal_name string		Internal name for identifying this Share Link.
description string		Public description
note string		Bundle internal note
code string		Bundle code. This code forms the end part of the Public URL.
path_template string		Template for creating submission subfolders. Can use the uploader's name, email address, ip, company, `strftime` directives, and any custom form data.
path_template_time_zone string		Timezone to use when rendering timestamps in path templates.
permissions string	`"read"`	Permissions that apply to Folders in this Share Link. Possible values: `read`, `write`, `read_write`, `full`, `none`, `preview_only`
require_registration boolean	`false`	Show a registration page that captures the downloader's name and email address?
clickwrap_id int64		ID of the clickwrap to use with this bundle.
inbox_id int64		ID of the associated inbox, if available.
require_share_recipient boolean	`false`	Only allow access to recipients who have explicitly received the share via an email sent through the Files.com UI?
send_one_time_password_to_recipient_at_registration boolean	`false`	If true, require_share_recipient bundles will send a one-time password to the recipient when they register. Cannot be enabled if the bundle has a password set.
send_email_receipt_to_uploader boolean	`false`	Send delivery receipt to the uploader. Note: For writable share only
skip_email boolean		BundleRegistrations can be saved without providing email?
skip_name boolean		BundleRegistrations can be saved without providing name?
skip_company boolean		BundleRegistrations can be saved without providing company?
start_access_on_date string		Date when share will start to be accessible. If `nil` access granted right after create.
snapshot_id int64		ID of the snapshot containing this bundle's contents.
workspace_id int64	`0`	Workspace ID. `0` means the default workspace.
watermark_attachment_file file		Preview watermark image applied to all bundle items. See Attaching Files to API Requests.
watermark_value object		Preview watermark settings applied to all bundle items. Uses the same keys as Behavior.value

Example Request

import files_sdk

try:
  bundle = files_sdk.bundle.create({
    "paths": ["file.txt"]
  })
  # Operate on bundle
except files_sdk.error.NotAuthenticatedError as err:
  print(f"Authentication Error Occurred ({type(err).__name__}):", err)
except files_sdk.error.Error as err:
  print(f"Unknown Error Occurred ({type(err).__name__}):", err)

Send email(s) with a link to bundle

SDK Method

bundle.share()

Return Object

No return value.

Authorization Requirement

Available to all authenticated keys or sessions.

Method Arguments

Argument	Description
to array(string)	A list of email addresses to share this bundle with. Required unless `recipients` is used.
note string	Note to include in email.
recipients array(object)	A list of recipients to share this bundle with. Required unless `to` is used.

Example Request

import files_sdk

try:
  # Find the bundle object by its id.
  bundle = files_sdk.bundle.find(id)
  bundle.share({
    "to": ["johndoe@gmail.com"]
  })
except files_sdk.error.NotAuthenticatedError as err:
  print(f"Authentication Error Occurred ({type(err).__name__}):", err)
except files_sdk.error.Error as err:
  print(f"Unknown Error Occurred ({type(err).__name__}):", err)

SDK Method

bundle.update()

Return Object

Bundle

Authorization Requirement

Available to all authenticated keys or sessions.

Method Arguments

Parameter access is subject to this endpoint's authorization requirement and the caller's access to the affected resource. Site Administrator access also includes Site-Wide API keys.

Argument	Description
paths array(string)	A list of paths to include in this bundle.
password string	Password for this bundle.
bypasses_site_expiration_rules boolean	If true, this Share Link bypasses site-wide expiration rules. Only site admins may set this. Can be set by: Site Administrator.
form_field_set_id int64	Id of Form Field Set to use with this bundle
clickwrap_id int64	ID of the clickwrap to use with this bundle.
code string	Bundle code. This code forms the end part of the Public URL.
create_snapshot boolean	If true, create a snapshot of this bundle's contents.
description string	Public description
dont_separate_submissions_by_folder boolean	Do not create subfolders for files uploaded to this share. Note: there are subtle security pitfalls with allowing anonymous uploads from multiple users to live in the same folder. We strongly discourage use of this option unless absolutely required.
expires_at string	Explicit Bundle expiration date/time. If not set, the site-wide expiration setting may apply.
finalize_snapshot boolean	If true, finalize the snapshot of this bundle's contents. Note that `create_snapshot` must also be true.
inbox_id int64	ID of the associated inbox, if available.
max_uses int64	Maximum number of times bundle can be accessed
group_id int64	Owning group ID. If set, members of this group can view, edit, and share this Share Link. Can be set by: Site Administrator; Workspace Administrator.
internal_name string	Internal name for identifying this Share Link.
note string	Bundle internal note
path_template string	Template for creating submission subfolders. Can use the uploader's name, email address, ip, company, `strftime` directives, and any custom form data.
path_template_time_zone string	Timezone to use when rendering timestamps in path templates.
permissions string	Permissions that apply to Folders in this Share Link. Possible values: `read`, `write`, `read_write`, `full`, `none`, `preview_only`
require_registration boolean	Show a registration page that captures the downloader's name and email address?
require_share_recipient boolean	Only allow access to recipients who have explicitly received the share via an email sent through the Files.com UI?
send_one_time_password_to_recipient_at_registration boolean	If true, require_share_recipient bundles will send a one-time password to the recipient when they register. Cannot be enabled if the bundle has a password set.
send_email_receipt_to_uploader boolean	Send delivery receipt to the uploader. Note: For writable share only
skip_company boolean	BundleRegistrations can be saved without providing company?
start_access_on_date string	Date when share will start to be accessible. If `nil` access granted right after create.
skip_email boolean	BundleRegistrations can be saved without providing email?
skip_name boolean	BundleRegistrations can be saved without providing name?
user_id int64	The owning user id. Only site admins can set this. Can be set by: Site Administrator; Workspace Administrator.
watermark_attachment_delete boolean	If true, will delete the file stored in watermark_attachment
watermark_attachment_file file	Preview watermark image applied to all bundle items. See Attaching Files to API Requests.
watermark_value object	Preview watermark settings applied to all bundle items. Uses the same keys as Behavior.value
workspace_id int64	Workspace ID. `0` means the default workspace.

Example Request

import files_sdk

try:
  # Find the bundle object by its id.
  bundle = files_sdk.bundle.find(id)
  bundle.update({
    "paths": ["file.txt"]
  })
except files_sdk.error.NotAuthenticatedError as err:
  print(f"Authentication Error Occurred ({type(err).__name__}):", err)
except files_sdk.error.Error as err:
  print(f"Unknown Error Occurred ({type(err).__name__}):", err)

SDK Method

bundle.delete()

Return Object

No return value.

Authorization Requirement

Available to all authenticated keys or sessions.

Example Request

import files_sdk

try:
  # Find the bundle object by its id.
  bundle = files_sdk.bundle.find(id)
  bundle.delete()
except files_sdk.error.NotAuthenticatedError as err:
  print(f"Authentication Error Occurred ({type(err).__name__}):", err)
except files_sdk.error.Error as err:
  print(f"Unknown Error Occurred ({type(err).__name__}):", err)

The Bundle Object

Some of the methods above return a Bundle object. The attributes of this object are listed below.

Attribute	Description
code string	Bundle code. This code forms the end part of the Public URL.
color_left string	Page link and button color
color_link string	Top bar link color
color_text string	Page link and button color
color_top string	Top bar background color
color_top_text string	Top bar text color
url string	Public URL of Share Link
description string	Public description
expires_at date-time	Explicit Bundle expiration date/time. If not set, the site-wide expiration setting may apply.
password_protected boolean	Is this bundle password protected?
permissions string	Permissions that apply to Folders in this Share Link. Possible values: `read`, `write`, `read_write`, `full`, `none`, `preview_only`
preview_only boolean
require_registration boolean	Show a registration page that captures the downloader's name and email address?
require_share_recipient boolean	Only allow access to recipients who have explicitly received the share via an email sent through the Files.com UI?
require_logout boolean	If true, we will hide the 'Remember Me' box on the Bundle registration page, requiring that the user logout and log back in every time they visit the page.
clickwrap_body string	Legal text that must be agreed to prior to accessing Bundle.
form_field_set FormFieldSet	Custom Form to use
skip_name boolean	BundleRegistrations can be saved without providing name?
skip_email boolean	BundleRegistrations can be saved without providing email?
start_access_on_date date-time	Date when share will start to be accessible. If `nil` access granted right after create.
skip_company boolean	BundleRegistrations can be saved without providing company?
id int64	Bundle ID
bypasses_site_expiration_rules boolean	If true, this Share Link bypasses site-wide expiration rules. Only site admins may set this.
created_at date-time	Bundle created at date/time
deleted boolean	Indicates if the bundle has been deleted.
deleted_at date-time	Bundle deleted at date/time
dont_separate_submissions_by_folder boolean	Do not create subfolders for files uploaded to this share. Note: there are subtle security pitfalls with allowing anonymous uploads from multiple users to live in the same folder. We strongly discourage use of this option unless absolutely required.
effective_expires_at date-time	Read-only expiration date/time, using the explicit expiration or the site-wide setting when applicable. Null when the Share Link does not expire.
max_uses int64	Maximum number of times bundle can be accessed
internal_name string	Internal name for identifying this Share Link.
note string	Bundle internal note
path_template string	Template for creating submission subfolders. Can use the uploader's name, email address, ip, company, `strftime` directives, and any custom form data.
path_template_time_zone string	Timezone to use when rendering timestamps in path templates.
send_email_receipt_to_uploader boolean	Send delivery receipt to the uploader. Note: For writable share only
snapshot_id int64	ID of the snapshot containing this bundle's contents.
user_id int64	Bundle creator user ID
username string	Bundle creator username
group_id int64	Owning group ID. If set, members of this group can view, edit, and share this Share Link.
clickwrap_id int64	ID of the clickwrap to use with this bundle.
inbox_id int64	ID of the associated inbox, if available.
watermark_attachment Image	Preview watermark image applied to all bundle items.
watermark_value object	Preview watermark settings applied to all bundle items. Uses the same keys as Behavior.value
send_one_time_password_to_recipient_at_registration boolean	If true, require_share_recipient bundles will send a one-time password to the recipient when they register. Cannot be enabled if the bundle has a password set.
workspace_id int64	Workspace ID. `0` means the default workspace.
has_inbox boolean	Does this bundle have an associated inbox?
dont_allow_folders_in_uploads boolean	Should folder uploads be prevented?
requested_upload_slots array(object)	Upload slots requested by the associated Inbox. Each slot contains a name used as its label and destination subfolder name.
paths array(string)	A list of paths in this bundle. For performance reasons, this is not provided when listing bundles.
bundlepaths array(object)	A list of bundlepaths in this bundle. For performance reasons, this is not provided when listing bundles.

watermark_value

Value Hash Parameter	Description
gravity string	Where to locate the watermark? Valid values: `Center`, `East`, `NorthEast`, `North`, `NorthWest`, `SouthEast`, `South`, `SouthWest`, `West`. Possible values: `Center`, `East`, `NorthEast`, `North`, `NorthWest`, `SouthEast`, `South`, `SouthWest`, `West`.
max_height_or_width integer	Max width/height as percent of image preview.
transparency integer	Percentage applied to the watermark.
dynamic_text string	Watermark text. Use {{user}} to embed a username into the string.

Example watermark_value

{
  "gravity": "SouthWest",
  "max_height_or_width": 20,
  "transparency": 25
}

requested_upload_slots

Upload slots requested by the associated Inbox. Each slot contains a name used as its label and destination subfolder name.

Value type	Description
array of objects	Upload slots requested by the associated Inbox. Each slot contains a name used as its label and destination subfolder name.

Example requested_upload_slots

[
  {
    "name": "Photo ID"
  }
]

Bundles

List Share Links

SDK Method

Return Object

Authorization Requirement

Method Arguments

Additional Arguments

Pagination

Sorting

Filtering

Show Share Link

SDK Method

Return Object

Authorization Requirement

Method Arguments

Create Share Link

SDK Method

Return Object

Authorization Requirement

Method Arguments

Send email(s) with a link to bundle

SDK Method

Return Object

Authorization Requirement

Method Arguments

Update Share Link

SDK Method

Return Object

Authorization Requirement

Method Arguments

Delete Share Link

SDK Method

Return Object

Authorization Requirement

The Bundle Object

watermark_value

requested_upload_slots

Requested upload slot