Forms client

Retrieve Paubox Form schemas and submit form responses using the Rails SDK.

The Forms client does not require API credentials. Forms are identified by a UUID that you obtain from the Paubox dashboard.

Create a client

client = PauboxRails::Forms.client

PauboxRails::Forms.client returns a new PauboxRails::Forms::Client instance.

Get a form

Retrieve a form’s metadata, field schema, and rendered HTML/CSS:

form = client.get_form("your-form-uuid")

puts form["title"]
puts form["form_html"]
puts form["form_json"].inspect

The return value is a Hash with the following keys:

Key	Description
"title"	Display name of the form
"form_json"	Parsed field schema
"form_html"	Rendered HTML for embedding
"form_css"	Associated stylesheet
"active"	Whether the form is accepting submissions
"submission_count"	Number of submissions received

get_form raises PauboxRails::Forms::NotFoundError if the form UUID is invalid.

Submit a form

result = client.submit_form(
  "your-form-uuid",
  form_data: {
    "first_name" => "Jane",
    "last_name"  => "Smith",
    "email"      => "[e-mail]"
  }
)
# result => true

submit_form returns true on a successful submission (HTTP 201).

Submitting with file attachments

The maximum total request size is 250 MB.

require "base64"

encoded = Base64.strict_encode64(File.read(Rails.root.join("tmp/consent.pdf")))

result = client.submit_form(
  "your-form-uuid",
  form_data: { "first_name" => "Jane" },
  attachments: [
    { name: "consent.pdf", content: encoded }
  ]
)

Each attachment is a Hash with two keys:

Key	Description
:name	File name including extension
:content	Base64-encoded file content

Error handling

begin
  form   = client.get_form("your-form-uuid")
  result = client.submit_form("your-form-uuid", form_data: data)
rescue PauboxRails::Forms::NotFoundError
  # Form UUID not found (HTTP 404)
rescue PauboxRails::Forms::BadRequestError
  # Malformed request (HTTP 400)
rescue PauboxRails::Forms::Error => e
  # Any other Forms API error
  Rails.logger.error("Forms error: #{e.message}")
end