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

# Python SDK 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)
```


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