Form Field Sets

A Form Field Set is a custom form to be used for bundle and inbox registrations.

Each Form Field Set contains one or more Form Fields. A form and all of its form fields are submitted in a single create request. The order of form fields in the array is the order they will be displayed.

Once created, a form field set can then be associated with one or more bundle(s) and/or inbox(s). Once associated, you will be required to submit well-formatted form-data when creating a bundle-registration or inbox registration.

Custom answers saved on a registration are saved as Custom Metadata on each file uploaded through that registration, with field labels as keys. This applies to existing registrations as well as new ones. Unanswered optional fields and values exceeding 1024 characters are omitted; the first 32 remaining answers in saved form-answer order are captured. Dates use YYYY-MM-DD. Existing answers with unavailable field definitions or unparseable dates are omitted. Built-in name, email, and company fields are excluded. Form answers take precedence over explicit upload metadata with matching keys, including keeping omitted answer labels absent.

Enable require_complete_metadata_capture to reject answers exceeding these value or count limits instead of omitting them. Uploaded files use the labels and answers accepted at registration even if the form is edited later.

Editing a field definition creates a replacement field with a new ID and preserves the original definition for existing registration answers. Unchanged fields and fields moved within the layout retain their IDs. Use the returned form_layout when submitting new answers or editing the form again.

Authenticated form field set responses include historical definitions in form_fields so existing answers can still be interpreted. Only IDs in form_layout are current fields. Forms embedded in Share Link and Inbox responses contain current definitions only.

List Form Field Sets

SDK Method

Files::FormFieldSet.list

Return Object

List<FormFieldSet>

Authorization Requirement

Available to all authenticated keys or sessions.

Method Arguments

ArgumentDescription
user_id
int64		User ID. Provide a value of 0 to operate the current session's user.

Additional Arguments

Example Request

begin
  form_field_sets = Files::FormFieldSet.list(
    user_id: 1
  )
  form_field_sets.auto_paging_each do |form_field_set|
    # Operate on form_field_set
  end
rescue Files::NotAuthenticatedError => e
  puts "Authentication Error Occurred (#{e.class.to_s}): " + e.message
rescue Files::Error => e
  puts "Unknown Error Occurred (#{e.class.to_s}): " + e.message
end

Show Form Field Set

SDK Method

Files::FormFieldSet.find

Return Object

FormFieldSet

Authorization Requirement

Available to all authenticated keys or sessions.

Method Arguments

ArgumentDescription
id
int64
Required		Form Field Set ID.

Example Request

begin
  form_field_set = Files::FormFieldSet.find(id)
  # Operate on form_field_set
rescue Files::NotAuthenticatedError => e
  puts "Authentication Error Occurred (#{e.class.to_s}): " + e.message
rescue Files::Error => e
  puts "Unknown Error Occurred (#{e.class.to_s}): " + e.message
end

Create Form Field Set

SDK Method

Files::FormFieldSet.create

Return Object

FormFieldSet

Authorization Requirement

Available to all authenticated keys or sessions.

Method Arguments

ArgumentDefaultDescription
user_id
int64		User ID. Provide a value of 0 to operate the current session's user.
title
string		Title to be displayed
require_complete_metadata_capture
boolean		falseReject answers over 1024 characters or more than 32 answered custom fields to ensure complete file metadata capture
workspace_id
int64		Workspace ID
skip_email
boolean		Skip validating form email
skip_name
boolean		Skip validating form name
skip_company
boolean		Skip validating company
form_fields
array(object)

Example Request

begin
  form_field_set = Files::FormFieldSet.create(
    user_id: 1
  )
  # Operate on form_field_set
rescue Files::NotAuthenticatedError => e
  puts "Authentication Error Occurred (#{e.class.to_s}): " + e.message
rescue Files::Error => e
  puts "Unknown Error Occurred (#{e.class.to_s}): " + e.message
end

Update Form Field Set

SDK Method

form_field_set.update

Return Object

FormFieldSet

Authorization Requirement

Available to all authenticated keys or sessions.

Method Arguments

ArgumentDescription
title
string		Title to be displayed
require_complete_metadata_capture
boolean		Reject answers over 1024 characters or more than 32 answered custom fields to ensure complete file metadata capture
workspace_id
int64		Workspace ID
skip_email
boolean		Skip validating form email
skip_name
boolean		Skip validating form name
skip_company
boolean		Skip validating company
form_fields
array(object)

Example Request

begin
  # Find the form_field_set object by its id.
  form_field_set = Files::FormFieldSet.find(id)
  form_field_set.update(
    title: "Sample Form Title"
  )
rescue Files::NotAuthenticatedError => e
  puts "Authentication Error Occurred (#{e.class.to_s}): " + e.message
rescue Files::Error => e
  puts "Unknown Error Occurred (#{e.class.to_s}): " + e.message
end

Delete Form Field Set

SDK Method

form_field_set.delete

Return Object

nil

Authorization Requirement

Available to all authenticated keys or sessions.

Example Request

begin
  # Find the form_field_set object by its id.
  form_field_set = Files::FormFieldSet.find(id)
  form_field_set.delete
rescue Files::NotAuthenticatedError => e
  puts "Authentication Error Occurred (#{e.class.to_s}): " + e.message
rescue Files::Error => e
  puts "Unknown Error Occurred (#{e.class.to_s}): " + e.message
end

The FormFieldSet Object

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

AttributeDescription
id
int64		Form field set id
title
string		Title to be displayed
require_complete_metadata_capture
boolean		Reject answers over 1024 characters or more than 32 answered custom fields to ensure complete file metadata capture
form_layout
array(int64)		Layout of the form
form_fields
array(object)		Associated form field definitions; authenticated form field set responses include historical definitions, while form_layout identifies current fields
skip_name
boolean		Any associated InboxRegistrations or BundleRegistrations can be saved without providing name
skip_email
boolean		Any associated InboxRegistrations or BundleRegistrations can be saved without providing email
skip_company
boolean		Any associated InboxRegistrations or BundleRegistrations can be saved without providing company
in_use
boolean		Form Field Set is in use by an active Inbox / Bundle / Inbox Registration / Bundle Registration