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

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

## Instantiation

```perl theme={null}
use Paubox_Forms_SDK;

my $forms = Paubox_Forms_SDK->new();
```

## Get a form

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

```perl theme={null}
my $response = $forms->getForm("your-form-uuid");
```

The response is a raw JSON string. Decode it to access fields:

```perl theme={null}
use JSON;
my $form = decode_json($response);

print "Title: " . $form->{title} . "\n";
print "HTML: "  . $form->{form_html} . "\n";
```

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 |

`getForm` dies if the form UUID is invalid or the form is not found.

## Submit a form

```perl theme={null}
my $result = $forms->submitForm(
    "your-form-uuid",
    { first_name => "Jane", last_name => "Smith", email => "jane@example.com" }
);
# $result is an empty string on success (HTTP 201)
```

`submitForm` dies on failure with a message containing the HTTP status code and response body.

### Submitting with file attachments

The maximum total request size is 250 MB.

```perl theme={null}
use MIME::Base64;

open(my $fh, '<:raw', 'consent.pdf') or die "Cannot open file: $!";
local $/;
my $encoded = encode_base64(<$fh>);
close($fh);

my $result = $forms->submitForm(
    "your-form-uuid",
    { first_name => "Jane" },
    [ { name => "consent.pdf", content => $encoded } ]
);
```

Each attachment in the arrayref is a hashref with two keys:

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

## Error handling

Wrap calls in `eval` to catch failures:

```perl theme={null}
eval {
    my $form   = $forms->getForm("your-form-uuid");
    my $result = $forms->submitForm("your-form-uuid", \%formData);
};
if ($@) {
    print "Error: $@\n";
}
```