> ## Documentation Index
> Fetch the complete documentation index at: https://docs.paubox.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Forms client

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

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

## Instantiation

```ruby theme={null}
require 'paubox'

forms_client = Paubox::FormsClient.new
```

## Get a form

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

```ruby theme={null}
form = forms_client.get_form('your-form-uuid')

puts form.title
puts form.form_html
```

The returned `Paubox::Form` object exposes:

| Method / Attribute         | 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            |
| `#signable?`               | Whether the form supports e-signatures    |
| `#deleted?` / `#archived?` | Form state flags                          |

## Submit a form

```ruby theme={null}
form_data = {
  first_name: 'Jane',
  last_name:  'Smith',
  email:      'jane@example.com'
}

response = forms_client.submit_form('your-form-uuid', form_data: form_data)
# response is 201 Created on success
```

### Submitting with file attachments

The maximum total request size is 250 MB.

```ruby theme={null}
require 'base64'

encoded = Base64.strict_encode64(File.read('consent.pdf'))

attachments = [
  { name: 'consent.pdf', content: encoded }
]

response = forms_client.submit_form(
  'your-form-uuid',
  form_data:   form_data,
  attachments: attachments
)
```

## Error handling

```ruby theme={null}
require 'rest-client'

begin
  form     = forms_client.get_form('your-form-uuid')
  response = forms_client.submit_form('your-form-uuid', form_data: form_data)
rescue RestClient::ExceptionWithResponse => e
  puts "HTTP #{e.response.code}: #{e.response.body}"
end
```