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

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

## Instantiation

```python theme={null}
from paubox import PauboxFormsClient

client = PauboxFormsClient()
```

## Get a form

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

```python theme={null}
response = client.get_form('your-form-uuid')
form     = response.to_dict

print('Title:', form['title'])
print('HTML:',  form['form_html'])
```

Key fields in the response:

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

## Submit a form

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

response = client.submit_form('your-form-uuid', form_data)
print('Status:', response.status_code)  # 201 on success
```

`submit_form` raises `ValueError` if `form_data` is empty or `None`.

### Submitting with file attachments

The maximum total request size is 250 MB.

```python theme={null}
import base64

with open('consent.pdf', 'rb') as f:
    encoded = base64.b64encode(f.read()).decode('utf-8')

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

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

Each attachment is a dict with two keys:

| Key       | Description                   |
| --------- | ----------------------------- |
| `name`    | File name including extension |
| `content` | Base64-encoded file content   |

## Error handling

```python theme={null}
import requests

try:
    response = client.get_form('your-form-uuid')
    response = client.submit_form('your-form-uuid', form_data)
except ValueError as e:
    print('Invalid input:', e)
except requests.exceptions.HTTPError as e:
    print('API error:', e.response.status_code, e.response.text)
```