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

The Forms client does not require API credentials. 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.

## 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);
```

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