> ## 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 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

```ruby theme={null}
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:

```ruby theme={null}
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

```ruby theme={null}
result = client.submit_form(
  "your-form-uuid",
  form_data: {
    "first_name" => "Jane",
    "last_name"  => "Smith",
    "email"      => "jane@example.com"
  }
)
# result => true
```

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

### Submitting with file attachments

The maximum total request size is 250 MB.

```ruby theme={null}
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

```ruby theme={null}
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
```