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.

List Share Links

SDK Method

bundle.List()

Return Object

[]*Bundle

Authorization Requirement

Available to all authenticated keys or sessions.

BundleListParams Fields

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.

FieldDescription
UserId
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 (
    "fmt"
    "errors"

    files_sdk "github.com/Files-com/files-sdk-go/v3"
    "github.com/Files-com/files-sdk-go/v3/bundle"
)

bundleIterator, err := bundle.List(files_sdk.BundleListParams{UserId: 1})
if err != nil {
    var respErr files_sdk.ResponseError
    if errors.As(err, &respErr) {
        fmt.Println("Response Error Occurred (" + respErr.Type + "): " + respErr.ErrorMessage)
    } else {
        fmt.Printf("Unexpected Error: %s\n", err.Error())
    }
}

for bundleIterator.Next() {
    bundle := bundleIterator.bundle()
}
err = bundleIterator.Err()
if err != nil {
    var respErr files_sdk.ResponseError
    if errors.As(err, &respErr) {
        fmt.Println("Response Error Occurred (" + respErr.Type + "): " + respErr.ErrorMessage)
    } else {
        fmt.Printf("Unexpected Error: %s\n", err.Error())
    }
}

Show Share Link

SDK Method

bundle.Find()

Return Object

Bundle

Authorization Requirement

Available to all authenticated keys or sessions.

BundleFindParams Fields

FieldDescription
Id
int64
Required		Bundle ID.
Deleted
boolean		If true, show a deleted Share Link.

Example Request

import (
    "fmt"
    "errors"

    files_sdk "github.com/Files-com/files-sdk-go/v3"
    "github.com/Files-com/files-sdk-go/v3/bundle"
)

bundle, err := bundle.Find(files_sdk.BundleFindParams{Id: 1})
if err != nil {
    var respErr files_sdk.ResponseError
    if errors.As(err, &respErr) {
        fmt.Println("Response Error Occurred (" + respErr.Type + "): " + respErr.ErrorMessage)
    } else {
        fmt.Printf("Unexpected Error: %s\n", err.Error())
    }
}

Create Share Link

SDK Method

bundle.Create()

Return Object

Bundle

Authorization Requirement

Available to all authenticated keys or sessions.

BundleCreateParams Fields

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.

FieldDefaultDescription
UserId
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.
BypassesSiteExpirationRules
boolean		falseIf true, this Share Link bypasses site-wide expiration rules. Only site admins may set this.

Can be set by: Site Administrator.
FormFieldSetId
int64		Id of Form Field Set to use with this bundle
CreateSnapshot
boolean		If true, create a snapshot of this bundle's contents.
DontSeparateSubmissionsByFolder
boolean		falseDo 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.
ExpiresAt
string		Explicit Bundle expiration date/time. If not set, the site-wide expiration setting may apply.
FinalizeSnapshot
boolean		If true, finalize the snapshot of this bundle's contents. Note that create_snapshot must also be true.
MaxUses
int64		Maximum number of times bundle can be accessed
GroupId
int64		Owning group ID. If set, members of this group can view, edit, and share this Share Link.
InternalName
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.
PathTemplate
string		Template for creating submission subfolders. Can use the uploader's name, email address, ip, company, strftime directives, and any custom form data.
PathTemplateTimeZone
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
RequireRegistration
boolean		falseShow a registration page that captures the downloader's name and email address?
ClickwrapId
int64		ID of the clickwrap to use with this bundle.
InboxId
int64		ID of the associated inbox, if available.
RequireShareRecipient
boolean		falseOnly allow access to recipients who have explicitly received the share via an email sent through the Files.com UI?
SendOneTimePasswordToRecipientAtRegistration
boolean		falseIf 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.
SendEmailReceiptToUploader
boolean		falseSend delivery receipt to the uploader. Note: For writable share only
SkipEmail
boolean		BundleRegistrations can be saved without providing email?
SkipName
boolean		BundleRegistrations can be saved without providing name?
SkipCompany
boolean		BundleRegistrations can be saved without providing company?
StartAccessOnDate
string		Date when share will start to be accessible. If nil access granted right after create.
SnapshotId
int64		ID of the snapshot containing this bundle's contents.
WorkspaceId
int64		0Workspace ID. 0 means the default workspace.
WatermarkAttachmentFile
file		Preview watermark image applied to all bundle items. See Attaching Files to API Requests.
WatermarkValue
object		Preview watermark settings applied to all bundle items. Uses the same keys as Behavior.value

Example Request

import (
    "fmt"
    "errors"

    files_sdk "github.com/Files-com/files-sdk-go/v3"
    "github.com/Files-com/files-sdk-go/v3/bundle"
)

bundle, err := bundle.Create(files_sdk.BundleCreateParams{Paths: []string{"file.txt"}})
if err != nil {
    var respErr files_sdk.ResponseError
    if errors.As(err, &respErr) {
        fmt.Println("Response Error Occurred (" + respErr.Type + "): " + respErr.ErrorMessage)
    } else {
        fmt.Printf("Unexpected Error: %s\n", err.Error())
    }
}

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.

BundleShareParams Fields

FieldDescription
Id
int64
Required		Bundle ID.
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 (
    "fmt"
    "errors"

    files_sdk "github.com/Files-com/files-sdk-go/v3"
    "github.com/Files-com/files-sdk-go/v3/bundle"
)

err := bundle.Share(files_sdk.BundleShareParams{Id: 1})
if err != nil {
    var respErr files_sdk.ResponseError
    if errors.As(err, &respErr) {
        fmt.Println("Response Error Occurred (" + respErr.Type + "): " + respErr.ErrorMessage)
    } else {
        fmt.Printf("Unexpected Error: %s\n", err.Error())
    }
}

Update Share Link

SDK Method

bundle.Update()

Return Object

Bundle

Authorization Requirement

Available to all authenticated keys or sessions.

BundleUpdateParams Fields

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.

FieldDescription
Id
int64
Required		Bundle ID.
Paths
array(string)		A list of paths to include in this bundle.
Password
string		Password for this bundle.
BypassesSiteExpirationRules
boolean		If true, this Share Link bypasses site-wide expiration rules. Only site admins may set this.

Can be set by: Site Administrator.
FormFieldSetId
int64		Id of Form Field Set to use with this bundle
ClickwrapId
int64		ID of the clickwrap to use with this bundle.
Code
string		Bundle code. This code forms the end part of the Public URL.
CreateSnapshot
boolean		If true, create a snapshot of this bundle's contents.
Description
string		Public description
DontSeparateSubmissionsByFolder
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.
ExpiresAt
string		Explicit Bundle expiration date/time. If not set, the site-wide expiration setting may apply.
FinalizeSnapshot
boolean		If true, finalize the snapshot of this bundle's contents. Note that create_snapshot must also be true.
InboxId
int64		ID of the associated inbox, if available.
MaxUses
int64		Maximum number of times bundle can be accessed
GroupId
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.
InternalName
string		Internal name for identifying this Share Link.
Note
string		Bundle internal note
PathTemplate
string		Template for creating submission subfolders. Can use the uploader's name, email address, ip, company, strftime directives, and any custom form data.
PathTemplateTimeZone
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
RequireRegistration
boolean		Show a registration page that captures the downloader's name and email address?
RequireShareRecipient
boolean		Only allow access to recipients who have explicitly received the share via an email sent through the Files.com UI?
SendOneTimePasswordToRecipientAtRegistration
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.
SendEmailReceiptToUploader
boolean		Send delivery receipt to the uploader. Note: For writable share only
SkipCompany
boolean		BundleRegistrations can be saved without providing company?
StartAccessOnDate
string		Date when share will start to be accessible. If nil access granted right after create.
SkipEmail
boolean		BundleRegistrations can be saved without providing email?
SkipName
boolean		BundleRegistrations can be saved without providing name?
UserId
int64		The owning user id. Only site admins can set this.

Can be set by: Site Administrator; Workspace Administrator.
WatermarkAttachmentDelete
boolean		If true, will delete the file stored in watermark_attachment
WatermarkAttachmentFile
file		Preview watermark image applied to all bundle items. See Attaching Files to API Requests.
WatermarkValue
object		Preview watermark settings applied to all bundle items. Uses the same keys as Behavior.value
WorkspaceId
int64		Workspace ID. 0 means the default workspace.

Example Request

import (
    "fmt"
    "errors"

    files_sdk "github.com/Files-com/files-sdk-go/v3"
    "github.com/Files-com/files-sdk-go/v3/bundle"
)

bundle, err := bundle.Update(files_sdk.BundleUpdateParams{
  Id: 1,
  Paths: []string{"file.txt"}
})
if err != nil {
    var respErr files_sdk.ResponseError
    if errors.As(err, &respErr) {
        fmt.Println("Response Error Occurred (" + respErr.Type + "): " + respErr.ErrorMessage)
    } else {
        fmt.Printf("Unexpected Error: %s\n", err.Error())
    }
}

Delete Share Link

SDK Method

bundle.Delete()

Return Object

No return value.

Authorization Requirement

Available to all authenticated keys or sessions.

BundleDeleteParams Fields

FieldDescription
Id
int64
Required		Bundle ID.

Example Request

import (
    "fmt"
    "errors"

    files_sdk "github.com/Files-com/files-sdk-go/v3"
    "github.com/Files-com/files-sdk-go/v3/bundle"
)

err := bundle.Delete(files_sdk.BundleDeleteParams{Id: 1})
if err != nil {
    var respErr files_sdk.ResponseError
    if errors.As(err, &respErr) {
        fmt.Println("Response Error Occurred (" + respErr.Type + "): " + respErr.ErrorMessage)
    } else {
        fmt.Printf("Unexpected Error: %s\n", err.Error())
    }
}

The Bundle Object

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

AttributeDescription
Code
string		Bundle code. This code forms the end part of the Public URL.
ColorLeft
string		Page link and button color
ColorLink
string		Top bar link color
ColorText
string		Page link and button color
ColorTop
string		Top bar background color
ColorTopText
string		Top bar text color
Url
string		Public URL of Share Link
Description
string		Public description
ExpiresAt
date-time		Explicit Bundle expiration date/time. If not set, the site-wide expiration setting may apply.
PasswordProtected
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
PreviewOnly
boolean
RequireRegistration
boolean		Show a registration page that captures the downloader's name and email address?
RequireShareRecipient
boolean		Only allow access to recipients who have explicitly received the share via an email sent through the Files.com UI?
RequireLogout
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.
ClickwrapBody
string		Legal text that must be agreed to prior to accessing Bundle.
FormFieldSet
FormFieldSet		Custom Form to use
SkipName
boolean		BundleRegistrations can be saved without providing name?
SkipEmail
boolean		BundleRegistrations can be saved without providing email?
StartAccessOnDate
date-time		Date when share will start to be accessible. If nil access granted right after create.
SkipCompany
boolean		BundleRegistrations can be saved without providing company?
Id
int64		Bundle ID
BypassesSiteExpirationRules
boolean		If true, this Share Link bypasses site-wide expiration rules. Only site admins may set this.
CreatedAt
date-time		Bundle created at date/time
Deleted
boolean		Indicates if the bundle has been deleted.
DeletedAt
date-time		Bundle deleted at date/time
DontSeparateSubmissionsByFolder
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.
EffectiveExpiresAt
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.
MaxUses
int64		Maximum number of times bundle can be accessed
InternalName
string		Internal name for identifying this Share Link.
Note
string		Bundle internal note
PathTemplate
string		Template for creating submission subfolders. Can use the uploader's name, email address, ip, company, strftime directives, and any custom form data.
PathTemplateTimeZone
string		Timezone to use when rendering timestamps in path templates.
SendEmailReceiptToUploader
boolean		Send delivery receipt to the uploader. Note: For writable share only
SnapshotId
int64		ID of the snapshot containing this bundle's contents.
UserId
int64		Bundle creator user ID
Username
string		Bundle creator username
GroupId
int64		Owning group ID. If set, members of this group can view, edit, and share this Share Link.
ClickwrapId
int64		ID of the clickwrap to use with this bundle.
InboxId
int64		ID of the associated inbox, if available.
WatermarkAttachment
Image		Preview watermark image applied to all bundle items.
WatermarkValue
object		Preview watermark settings applied to all bundle items. Uses the same keys as Behavior.value
SendOneTimePasswordToRecipientAtRegistration
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.
WorkspaceId
int64		Workspace ID. 0 means the default workspace.
HasInbox
boolean		Does this bundle have an associated inbox?
DontAllowFoldersInUploads
boolean		Should folder uploads be prevented?
RequestedUploadSlots
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 ParameterDescription
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 typeDescription
array of objectsUpload 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"
  }
]