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

# Java SDK forms client

> Retrieve Paubox Form schemas and submit form responses using the Java 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

```java theme={null}
import com.paubox.service.FormsService;

FormsService service = new FormsService();
```

No config loading is required for `getForm` and `submitForm`.

## Get a form

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

```java theme={null}
import com.paubox.data.Form;

Form form = service.getForm("your-form-uuid");

System.out.println("Title: " + form.getTitle());
System.out.println("HTML: "  + form.getFormHtml());
```

Key `Form` getters:

| Method | Description |
| - | - |
| `getTitle()` | Display name of the form |
| `getFormJson()` | Parsed field schema |
| `getFormHtml()` | Rendered HTML for embedding |
| `getFormCss()` | Associated stylesheet |
| `isActive()` | Whether the form is accepting submissions |
| `getSubmissionCount()` | Number of submissions received |

## Submit a form

```java theme={null}
import com.paubox.data.FormSubmissionRequest;
import java.util.HashMap;
import java.util.Map;

Map<String, Object> formData = new HashMap<>();
formData.put("first_name", "Jane");
formData.put("last_name",  "Smith");
formData.put("email",      "jane@example.com");

FormSubmissionRequest request = new FormSubmissionRequest();
request.setFormData(formData);

service.submitForm("your-form-uuid", request);
```

`submitForm` returns `void` on success (HTTP 201) and throws on failure.

### Submitting with file attachments

The maximum total request size is 250 MB.

```java theme={null}
import com.paubox.data.FormSubmissionAttachment;
import java.nio.file.Files;
import java.nio.file.Paths;
import java.util.Base64;
import java.util.ArrayList;
import java.util.List;

byte[] fileBytes = Files.readAllBytes(Paths.get("consent.pdf"));
String encoded   = Base64.getEncoder().encodeToString(fileBytes);

FormSubmissionAttachment attachment = new FormSubmissionAttachment();
attachment.setName("consent.pdf");
attachment.setContent(encoded);

List<FormSubmissionAttachment> attachments = new ArrayList<>();
attachments.add(attachment);

FormSubmissionRequest request = new FormSubmissionRequest();
request.setFormData(formData);
request.setAttachments(attachments);

service.submitForm("your-form-uuid", request);
```

## Manage forms

These methods need a `forms`-scoped API key, sent as `Authorization: Bearer YOUR_API_KEY`. Use `new FormsService("YOUR_API_KEY")`, or set `FORMSAPIKEY` in `config.properties`, load it with `ConfigurationManager.getProperties`, and then call `new FormsService()`. Without a key they throw an `Exception`.

| Method | Returns |
| - | - |
| `listForms(FormListRequest)` | `FormListResponse` |
| `createForm(CreateFormRequest)` | `String` ID of the new form |
| `getFormById(formId)` | `Form` |
| `updateForm(formId, UpdateFormRequest)` | `UpdateFormResponse` |
| `archiveForm(formId)` / `unarchiveForm(formId)` | `void` |
| `copyForm(formId, newTitle)` | `Form` |
| `getFormStats(customerId)` | `FormStats`; pass `null` for the key's customer |
| `listFormSubmissions(formId, FormSubmissionListRequest)` | `FormSubmissionListResponse` |
| `downloadSubmissionsCsv(formId)` | `byte[]` CSV |
| `downloadSubmissionCsv(formId, submissionId)` | `byte[]` CSV |
| `downloadSubmissionPdf(formId, submissionId)` | `byte[]` PDF |

```java theme={null}
import com.paubox.data.FormListRequest;
import com.paubox.data.FormListResponse;

FormsService formsAdmin = new FormsService("YOUR_API_KEY");

FormListRequest query = new FormListRequest();
query.setCustomerId(12345);
query.setActive(true);
query.setItems(25);

FormListResponse list = formsAdmin.listForms(query);
for (Form f : list.getResults()) {
    System.out.println(f.getId() + ": " + f.getTitle());
}
```

## Error handling

```java theme={null}
try {
    Form form = service.getForm("your-form-uuid");
    service.submitForm("your-form-uuid", request);
} catch (Exception e) {
    System.err.println("Forms error: " + e.getMessage());
}
```

`getForm` and `submitForm` throw `Exception` on HTTP 400 (bad request) and 404 (form not found).


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