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

# Perl SDK forms client

> Retrieve Paubox Form schemas and submit form responses using the Perl SDK.

`getForm` and `submitForm` do not require API credentials. The form management methods require an API key with the `forms` scope (see [Manage forms](#manage-forms)). 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 |

## Manage forms

These methods need a `forms`-scoped API key, sent as `Authorization: Bearer YOUR_API_KEY`. Create the client with `Paubox_Forms_SDK->new('apiKey' => 'YOUR_API_KEY')`, or set `FORMS_API_KEY` in `config.cfg`. Without a key they die. Call them as methods on the object.

| Method | Description |
| - | - |
| `listForms(\%params)` | List forms; `customer_id` is required |
| `createForm(\%attrs)` | Create a form |
| `getFormById($formId)` | Get any of your forms, including archived and inactive ones |
| `updateForm($formId, \%updates)` | Update a form |
| `archiveForm($formId)` / `unarchiveForm($formId)` | Archive or restore a form |
| `copyForm($formId, $newTitle)` | Copy a form under a new title |
| `getFormStats(\%params)` | Form and submission counts; `customer_id` is optional |
| `listFormSubmissions($formId, \%params)` | List a form's submissions |
| `getSubmissionsCsv($formId, $submissionId)` | Export all submissions, or one when `$submissionId` is set, as CSV |
| `getSubmissionPdf($formId, $submissionId)` | Export one submission as PDF |

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

my $formsAdmin = Paubox_Forms_SDK->new('apiKey' => 'YOUR_API_KEY');

my $list = decode_json($formsAdmin->listForms({ customer_id => 12345, active => 1, items => 25 }));
print "$_->{id}: $_->{title}\n" for @{ $list->{results} };
```

## 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";
}
```


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