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

# Rails SDK 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
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.