# Bundle ## Example Bundle Object ``` { "code": "abc123", "color_left": "#0066a7", "color_link": "#d34f5d", "color_text": "#0066a7", "color_top": "#000000", "color_top_text": "#ffffff", "url": "https://subdomain.files.com/f/12345678", "description": "The public description of the bundle.", "expires_at": "2000-01-01T01:00:00Z", "password_protected": true, "permissions": "read", "preview_only": true, "require_registration": true, "require_share_recipient": true, "require_logout": true, "clickwrap_body": "[Legal text]", "form_field_set": { "id": 1, "title": "Sample Form Title", "form_layout": [ 1, 2, 3, 4 ], "form_fields": [ null ], "skip_name": true, "skip_email": true, "skip_company": true }, "skip_name": true, "skip_email": true, "start_access_on_date": "2000-01-01T01:00:00Z", "skip_company": true, "id": 1, "created_at": "2000-01-01T01:00:00Z", "dont_separate_submissions_by_folder": true, "max_uses": 1, "note": "The internal note on the bundle.", "path_template": "{{name}}_{{ip}}", "send_email_receipt_to_uploader": true, "snapshot_id": 1, "user_id": 1, "username": "user", "clickwrap_id": 1, "inbox_id": 1, "watermark_attachment": null, "watermark_value": { "key": "example value" }, "has_inbox": true, "paths": [ "file.txt" ] } ``` * `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): Bundle expiration date/time * `password_protected` (boolean): Is this bundle password protected? * `permissions` (string): Permissions that apply to Folders in this Share Link. * `preview_only` (boolean): DEPRECATED: Restrict users to previewing files only. Use `permissions` instead. * `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 * `created_at` (date-time): Bundle created 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. * `max_uses` (int64): Maximum number of times bundle can be accessed * `note` (string): Bundle internal note * `path_template` (string): Template for creating submission subfolders. Can use the uploader's name, email address, ip, company, and any custom form data. * `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 * `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 * `has_inbox` (boolean): Does this bundle have an associated inbox? * `paths` (array): A list of paths in this bundle. For performance reasons, this is not provided when listing bundles. * `password` (string): Password for this bundle. * `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. * `finalize_snapshot` (boolean): If true, finalize the snapshot of this bundle's contents. Note that `create_snapshot` must also be true. * `watermark_attachment_file` (file): Preview watermark image applied to all bundle items. * `watermark_attachment_delete` (boolean): If true, will delete the file stored in watermark_attachment --- ## List Bundles ``` Files::Bundle.list( user_id: 1, per_page: 1 ) ``` ### Parameters * `user_id` (int64): User ID. Provide a value of `0` to operate the current session's user. * `cursor` (string): Used for pagination. When a list request has more records available, cursors are provided in the response headers `X-Files-Cursor-Next` and `X-Files-Cursor-Prev`. Send one of those cursor value here to resume an existing list from the next available record. Note: many of our SDKs have iterator methods that will automatically handle cursor-based pagination. * `per_page` (int64): Number of records to show per page. (Max: 10,000, 1,000 or less is recommended). * `sort_by` (object): If set, sort records by the specified field in either `asc` or `desc` direction (e.g. `sort_by[created_at]=desc`). Valid fields are `created_at` and `code`. * `filter` (object): If set, return records where the specified field is equal to the supplied value. Valid fields are `created_at`. * `filter_gt` (object): If set, return records where the specified field is greater than the supplied value. Valid fields are `created_at`. * `filter_gteq` (object): If set, return records where the specified field is greater than or equal the supplied value. Valid fields are `created_at`. * `filter_lt` (object): If set, return records where the specified field is less than the supplied value. Valid fields are `created_at`. * `filter_lteq` (object): If set, return records where the specified field is less than or equal the supplied value. Valid fields are `created_at`. --- ## Show Bundle ``` Files::Bundle.find(id) ``` ### Parameters * `id` (int64): Required - Bundle ID. --- ## Create Bundle ``` Files::Bundle.create( user_id: 1, paths: ["file.txt"], password: "Password", form_field_set_id: 1, create_snapshot: true, dont_separate_submissions_by_folder: true, expires_at: "2000-01-01T01:00:00Z", finalize_snapshot: true, max_uses: 1, description: "The public description of the bundle.", note: "The internal note on the bundle.", code: "abc123", path_template: "{{name}}_{{ip}}", permissions: "read", preview_only: true, require_registration: true, clickwrap_id: 1, inbox_id: 1, require_share_recipient: true, send_email_receipt_to_uploader: true, skip_email: true, skip_name: true, skip_company: true, start_access_on_date: "2000-01-01T01:00:00Z", snapshot_id: 1 ) ``` ### Parameters * `user_id` (int64): User ID. Provide a value of `0` to operate the current session's user. * `paths` (array(string)): Required - A list of paths to include in this bundle. * `password` (string): Password for this bundle. * `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): 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): Bundle expiration date/time * `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 * `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, and any custom form data. * `permissions` (string): Permissions that apply to Folders in this Share Link. * `preview_only` (boolean): DEPRECATED: Restrict users to previewing files only. Use `permissions` instead. * `require_registration` (boolean): 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): Only allow access to recipients who have explicitly received the share via an email sent through the Files.com UI? * `send_email_receipt_to_uploader` (boolean): 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. * `watermark_attachment_file` (file): Preview watermark image applied to all bundle items. --- ## Send email(s) with a link to bundle ``` Files::Bundle.share(id, to: ["johndoe@gmail.com"], note: "Just a note.", recipients: [{"name":"John Doe","company":"Acme Ltd","recipient":"johndoe@gmail.com"}] ) ``` ### Parameters * `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. --- ## Update Bundle ``` Files::Bundle.update(id, paths: ["file.txt"], password: "Password", form_field_set_id: 1, clickwrap_id: 1, code: "abc123", create_snapshot: true, description: "The public description of the bundle.", dont_separate_submissions_by_folder: true, expires_at: "2000-01-01T01:00:00Z", finalize_snapshot: true, inbox_id: 1, max_uses: 1, note: "The internal note on the bundle.", path_template: "{{name}}_{{ip}}", permissions: "read", preview_only: true, require_registration: true, require_share_recipient: true, send_email_receipt_to_uploader: true, skip_company: true, start_access_on_date: "2000-01-01T01:00:00Z", skip_email: true, skip_name: true, watermark_attachment_delete: true ) ``` ### Parameters * `id` (int64): Required - Bundle ID. * `paths` (array(string)): A list of paths to include in this bundle. * `password` (string): Password for this bundle. * `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): Bundle expiration date/time * `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 * `note` (string): Bundle internal note * `path_template` (string): Template for creating submission subfolders. Can use the uploader's name, email address, ip, company, and any custom form data. * `permissions` (string): Permissions that apply to Folders in this Share Link. * `preview_only` (boolean): DEPRECATED: Restrict users to previewing files only. Use `permissions` instead. * `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_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? * `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. --- ## Delete Bundle ``` Files::Bundle.delete(id) ``` ### Parameters * `id` (int64): Required - Bundle ID. --- ## Send email(s) with a link to bundle ``` bundle = Files::Bundle.list.first bundle.share( to: ["johndoe@gmail.com"], note: "Just a note.", recipients: [{"name":"John Doe","company":"Acme Ltd","recipient":"johndoe@gmail.com"}] ) ``` ### Parameters * `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. --- ## Update Bundle ``` bundle = Files::Bundle.list.first bundle.update( paths: ["file.txt"], password: "Password", form_field_set_id: 1, clickwrap_id: 1, code: "abc123", create_snapshot: true, description: "The public description of the bundle.", dont_separate_submissions_by_folder: true, expires_at: "2000-01-01T01:00:00Z", finalize_snapshot: true, inbox_id: 1, max_uses: 1, note: "The internal note on the bundle.", path_template: "{{name}}_{{ip}}", permissions: "read", preview_only: true, require_registration: true, require_share_recipient: true, send_email_receipt_to_uploader: true, skip_company: true, start_access_on_date: "2000-01-01T01:00:00Z", skip_email: true, skip_name: true, watermark_attachment_delete: true ) ``` ### Parameters * `id` (int64): Required - Bundle ID. * `paths` (array(string)): A list of paths to include in this bundle. * `password` (string): Password for this bundle. * `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): Bundle expiration date/time * `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 * `note` (string): Bundle internal note * `path_template` (string): Template for creating submission subfolders. Can use the uploader's name, email address, ip, company, and any custom form data. * `permissions` (string): Permissions that apply to Folders in this Share Link. * `preview_only` (boolean): DEPRECATED: Restrict users to previewing files only. Use `permissions` instead. * `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_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? * `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. --- ## Delete Bundle ``` bundle = Files::Bundle.list.first bundle.delete ``` ### Parameters * `id` (int64): Required - Bundle ID.