> ## Documentation Index
> Fetch the complete documentation index at: https://docs.formabledocs.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Java

> Install and use formable-sdk, the official Java SDK for the Formable API.

[`formable-sdk`](https://central.sonatype.com/artifact/com.formabledocs/formable-sdk) is the official Java SDK for the Formable API (v1). It covers templates, signature requests, redlining, and billing.

* Typed request and response models
* Uses the JDK `HttpClient` (Java 17+)
* One runtime dependency: Jackson Databind

Source code is on [GitHub](https://github.com/FormableDocs/formable-java).

## Installation

<CodeGroup>
  ```xml Maven theme={null}
  <dependency>
    <groupId>com.formabledocs</groupId>
    <artifactId>formable-sdk</artifactId>
    <version>0.1.0</version>
  </dependency>
  ```

  ```kotlin Gradle theme={null}
  implementation("com.formabledocs:formable-sdk:0.1.0")
  ```
</CodeGroup>

## Initialize the client

Pass your API key from [Settings](https://app.formabledocs.com/settings). It's sent as a bearer token on every request.

```java theme={null}
import com.formabledocs.Formable;

Formable formable = new Formable(System.getenv("FORMABLE_API_KEY"));
```

## Templates

Upload a document to create a reusable template, then mint edit URLs to place fields in the embedded editor. See the [embedded templates walkthrough](/walkthroughs/embedded-templates).

```java theme={null}
import com.formabledocs.model.TemplateSignerRole;
import java.nio.file.Path;
import java.util.List;

var created = formable.templates.create(
    Path.of("nda.docx"),
    List.of(
        new TemplateSignerRole("Client", 0),
        new TemplateSignerRole("Witness", 1)
    )
);

String templateId = created.templateId();

// Mint a fresh edit URL later (expires after 1 day)
var edit = formable.templates.createEditUrl(templateId);
```

## Signature requests

Send a template for signing by email, or embed the signing experience in your product. See the [embedded signing walkthrough](/walkthroughs/embedded-signing).

```java theme={null}
import com.formabledocs.model.CreateSignatureRequest;
import com.formabledocs.model.Signer;
import java.time.Instant;

// Formable emails each signer a signing link
var request = formable.signatureRequests.create(
    CreateSignatureRequest.builder()
        .templateId(templateId)
        .addSigner(new Signer("jane@example.com", "Jane Doe", "Client"))
        .addSigner(new Signer("bob@example.com", "Bob Smith", "Witness"))
        .build()
);

// Embedded flow: mint signing URLs to embed in an iframe yourself
var embedded = formable.signatureRequests.createEmbedded(
    CreateSignatureRequest.builder()
        .templateId(templateId)
        .addSigner(new Signer("jane@example.com", "Jane Doe", "Client"))
        .testMode(true)
        .build()
);

var signer = embedded.signers().get(0);
var signing = formable.signatureRequests.createSigningUrl(signer.recipientSignatureId());

// Track progress
var current = formable.signatureRequests.get(embedded.signatureRequestId());
var all = formable.signatureRequests.list(Instant.parse("2026-01-01T00:00:00Z"));
var events = formable.signatureRequests.getEvents(embedded.signatureRequestId());

// Download the signed document once completed
var envelope = formable.signatureRequests.getSignedEnvelope(embedded.signatureRequestId());
```

<Note>
  `getSignedEnvelope` throws a `409` until the document is complete. Wait for the [`document_completed`](/webhooks/events#document_completed) webhook, or poll `get` until `status` is `Completed`.
</Note>

## Redline requests

Run turn-based contract negotiation before signing. See the [redlining walkthrough](/walkthroughs/redlining).

```java theme={null}
import com.formabledocs.model.CreateRedlineRequest;
import com.formabledocs.model.RedlineMember;
import com.formabledocs.model.RedlineMemberRole;
import com.formabledocs.model.RedlineRequestMetadata;
import java.util.List;

var created = formable.redlineRequests.create(
    CreateRedlineRequest.builder()
        .templateId(templateId)
        .addMember(new RedlineMember("us@example.com", "John Doe", RedlineMemberRole.DISCLOSING_PARTY))
        .addMember(new RedlineMember("them@example.com", "Jane Smith", RedlineMemberRole.RECEIVING_PARTY))
        .metadata(new RedlineRequestMetadata("Mutual NDA"))
        .build()
);

String redlineRequestId = created.redlineRequestId();

// Mint a redline URL for a member (embed in an iframe)
var url = formable.redlineRequests.createUrl(redlineRequestId, "them@example.com");

// Manage members and track progress
formable.redlineRequests.updateMembers(
    redlineRequestId,
    List.of(new RedlineMember("counsel@example.com", "Counsel", RedlineMemberRole.RECEIVING_COUNSEL))
);
var redline = formable.redlineRequests.get(redlineRequestId);
var events = formable.redlineRequests.getEvents(redlineRequestId);
```

## Billing and health

```java theme={null}
var billing = formable.billing();
var health = formable.health();
```

## Error handling

All non-2xx responses throw a `FormableException` with the server's error message, HTTP status, and parsed response body.

```java theme={null}
import com.formabledocs.FormableException;

try {
    formable.signatureRequests.get("missing-id");
} catch (FormableException error) {
    System.err.println(error.status() + " " + error.getMessage());
}
```

## Configuration

The builder takes an API key, then optional `baseUrl`, `timeout`, and JDK `HttpClient` values.

```java theme={null}
import com.formabledocs.Formable;
import java.net.http.HttpClient;
import java.time.Duration;

Formable formable = Formable.builder()
    .apiKey(System.getenv("FORMABLE_API_KEY"))
    .baseUrl("https://api.formabledocs.com/v1")
    .timeout(Duration.ofSeconds(60))
    .httpClient(HttpClient.newHttpClient())
    .build();
```

| Option       | Description                                               | Default                             |
| ------------ | --------------------------------------------------------- | ----------------------------------- |
| `apiKey`     | Your Formable API key (sent as a bearer token). Required. | -                                   |
| `baseUrl`    | Override the API base URL.                                | `https://api.formabledocs.com/v1`   |
| `timeout`    | Per-request timeout.                                      | 60 seconds                          |
| `httpClient` | Custom `java.net.http.HttpClient`.                        | JDK client with 60s connect timeout |

## Next steps

<CardGroup cols={2}>
  <Card title="Quickstart" icon="rocket" href="/quickstart">
    Go from a plain document to a signed PDF in 4 calls.
  </Card>

  <Card title="API reference" icon="code" href="/api-reference/introduction">
    Every endpoint the SDK wraps, with a live playground.
  </Card>
</CardGroup>