# Java SDK
Easily integrate BoldSign's e-signature features into your Java applications. This SDK simplifies sending documents for signature, embedding signing ceremonies, tracking document status, downloading signed documents, and managing e-signature workflows.
The Java SDK is available on {% customlink href="https://central.sonatype.com/artifact/com.boldsign/boldsign-java" text="Maven Central" /%} and the source code can be found in the {% customlink href="https://github.com/boldsign/boldsign-java-sdk" text="GitHub repository" /%}.
## Install the package
Follow the steps to install the BoldSign Java SDK package using both Maven and Gradle.
### Maven users
Add this dependency to your project's POM:
```shell
com.boldsign
boldsign-java
1.0.0-beta.1
compile
```
To install the API client library to your local Maven repository,
```shell
mvn clean install
```
To deploy it to a remote Maven repository instead, configure the settings of the repository and execute:
```shell
mvn clean deploy
```
Refer to the {% customlink href="https://central.sonatype.org/publish/publish-guide/" text="OSSRH Guide" /%} for more information.
### Gradle users
Add this dependency to your project's build file:
```shell
repositories {
mavenCentral() // Needed if the 'boldsign-java' jar has been published to maven central.
mavenLocal() // Needed if the 'boldsign-java' jar has been published to the local maven repo.
}
dependencies {
implementation "com.boldsign:boldsign-java:1.0.0-beta.1"
}
```
Build and run on Windows:
```shell
.\gradlew.bat clean build
.\gradlew.bat run
```
## Authentication
You can authenticate and configure the BoldSign Java SDK using either an API Key or a Bearer Token. Depending on your authentication method, you can set up with one of the two configurations outlined below.
### API Key
To authenticate using an API Key, you'll need to first generate your API key. You can refer to the {% customlink href="https://developers.boldsign.com/authentication/api-key/?region=us" text="API-Key" /%} for more details .
Once you have your API key, you can configure as follows:
```java
ApiClient client = Configuration.getDefaultApiClient();
client.setBasePath("https://api.boldsign.com");
client.setApiKey("Your-API-Key-Here");
```
Replace "Your-API-Key-Here" with the actual API key you generated. After setting this up, the SDK will use this API key for authenticating all API requests.
### OAuth 2.0
To authenticate using an Bearer Token(Access Token), you'll need to first generate your Bearer Token. You can refer to the {% customlink href="https://developers.boldsign.com/authentication/oauth-2-0/?region=us" text="OAuth 2.0" /%} for more details .
Once you have your Bearer Token, you can configure as follows:
```java
ApiClient client = Configuration.getDefaultApiClient();
client.setBasePath("https://api.boldsign.com");
client.setAccessToken("Your-Bearer-Token-Here");
```
Replace "Your-Bearer-Token-Here" with the actual Bearer Token you generated. After setting this up, the SDK will use this Bearer Token for authenticating all API requests.
### Base URLs
BoldSign SDK supports region-specific API base URLs to ensure data residency and compliance. Use the appropriate base URL for your region:
| Region | API Base URL |
|---------- |-------------------------------|
| US | `https://api.boldsign.com` |
| Europe | `https://api-eu.boldsign.com` |
| Canada | `https://api-ca.boldsign.com` |
| Australia | `https://api-au.boldsign.com` |
The **US region** uses the default base URL (https://api.boldsign.com), so no additional configuration is required.
If your account is in another region, set the base path explicitly in your SDK configuration. Refer to the code example below:
```java
ApiClient apiClient = Configuration.getDefaultApiClient();
apiClient.setBasePath("https://api-eu.boldsign.com");
```
## Getting started
To prepare for sending a document for signing, you can authenticate using an API key after importing the BoldSign SDK. This example demonstrates the authentication process using an API key.
```java
// Configure API key authorization: X-API-KEY
ApiClient client = Configuration.getDefaultApiClient();
client.setBasePath("https://api.boldsign.com");
client.setApiKey("YOUR_API_KEY");
// Create an instance of the DocumentApi class
DocumentApi documentApi = new DocumentApi(client);
```
Now, define the signature field that will be added to your document. This involves specifying the field type (Signature), page number, and the bounds (position and size) of the field on the page.
```java
// Define the signature field to be added to the document
List formFields = new ArrayList();
FormField signatureField = new FormField();
signatureField.setFieldType(FieldTypeEnum.SIGNATURE);
signatureField.setPageNumber(1);
Rectangle rectangle = new Rectangle().x(100f).y(100f).width(100f).height(50f);
signatureField.setBounds(rectangle);
formFields.add(signatureField);
signatureField.setBounds(bounds);
```
The document and its form fields require signing. So, specify the signer to sign the form fields, including their name and email address.
```java
// Define the signer with a name and email address
List signers = new ArrayList();
DocumentSigner signer = new DocumentSigner();
signer.setName("Signer");
signer.setEmailAddress("hankwhite@cubeflakes.com");
signer.setFormFields(formFields);
signers.add(signer);
```
Now, prepare the document you want to send for signature. Specify the title of the document, the signers involved, and the file(s) to be signed. In this case, we are sending a PDF document.
```java
// Prepare the request body for sending the document for signature
SendForSign sendForSign = new SendForSign();
sendForSign.setTitle("Agreement");
sendForSign.setFiles(files);
sendForSign.setSigners(signers);
```
The last step is to send the document for signing with the defined document, form fields and signer.
```java
// Send the document for signature and capture the response
DocumentCreated document = documentApi.sendDocument(sendForSign);
```
The return type `document` will contain the document ID of the document created, which can be used in later stages to get the particular document related operations.
## Examples
You can find the Java example application in the official {% customlink href="https://github.com/boldsign/angular-java-eSignature-example" text="GitHub repository" /%}. Additional code examples are available in {% customlink href="https://github.com/boldsign/boldsign-java-sdk/tree/main/examples" text="this" /%} GitHub repository.
## Class reference
Refer to the Java SDK {% customlink href="https://github.com/boldsign/boldsign-java-sdk?tab=readme-ov-file#documentation-for-api-endpoints" text="class reference documentation" /%} here.