# Java SDK

> AI agents: search and read all Moov docs with the docs MCP server at https://docs.moov.io/mcp (no API key). Setup: https://docs.moov.io/guides/developer-tools/mcp-ai/docs-mcp/index.md

Repository: https://github.com/moovfinancial/moov-java
Current release for API v2026.07.00: v26.8.7

Pin the package version you install so your integration stays on the API version it was built against. API versions: https://docs.moov.io/api-versions.json

## SDK Installation

### Getting started

JDK 11 or later is required.

The samples below show how a published SDK artifact is used:

Gradle:
```groovy
implementation 'io.moov:sdk:26.8.7'
```

Maven:
```xml
<dependency>
    <groupId>io.moov</groupId>
    <artifactId>sdk</artifactId>
    <version>26.8.7</version>
</dependency>
```

### How to build
After cloning the git repository to your file system you can build the SDK artifact from source to the `build` directory by running `./gradlew build` on *nix systems or `gradlew.bat` on Windows systems.

If you wish to build from source and publish the SDK artifact to your local Maven repository (on your filesystem) then use the following command (after cloning the git repo locally):

On *nix:
```bash
./gradlew publishToMavenLocal -Pskip.signing
```
On Windows:
```bash
gradlew.bat publishToMavenLocal -Pskip.signing
```

## SDK Example Usage

### Example

```java
package hello.world;

import io.moov.sdk.Moov;
import io.moov.sdk.models.components.*;
import io.moov.sdk.models.errors.CreateAccountError;
import io.moov.sdk.models.errors.GenericError;
import io.moov.sdk.models.operations.CreateAccountResponse;
import java.lang.Exception;

public class Application {

    public static void main(String[] args) throws GenericError, CreateAccountError, Exception {

        Moov sdk = Moov.builder()
                .security(Security.builder()
                    .username("")
                    .password("")
                    .build())
            .build();

        CreateAccount req = CreateAccount.builder()
                .accountType(CreateAccountType.BUSINESS)
                .profile(CreateProfile.builder()
                    .business(CreateBusinessProfile.builder()
                        .legalBusinessName("Whole Body Fitness LLC")
                        .build())
                    .build())
                .build();

        CreateAccountResponse res = sdk.accounts().create()
                .request(req)
                .call();

        if (res.account().isPresent()) {
            System.out.println(res.account().get());
        }
    }
}
```

#### Union Consumption Patterns

When a response field is a union model:

- Discriminated unions: branch on the discriminator (`switch`) and then narrow to the concrete type.
- Non-discriminated unions: use generated accessors (for example `string()`, `asLong()`, `simpleObject()`) to determine the active variant.

For full model-specific examples (including Java 11/16/21 variants), see each union model's **Supported Types** section in the generated model docs.

## Authentication

### Per-Client Security Schemes

This SDK supports the following security scheme globally:

| Name                      | Type | Scheme     |
| ------------------------- | ---- | ---------- |
| `username`<br/>`password` | http | HTTP Basic |

You can set the security parameters through the `security` builder method when initializing the SDK client instance. For example:
```java
package hello.world;

import io.moov.sdk.Moov;
import io.moov.sdk.models.components.*;
import io.moov.sdk.models.errors.CreateAccountError;
import io.moov.sdk.models.errors.GenericError;
import io.moov.sdk.models.operations.CreateAccountResponse;
import java.lang.Exception;

public class Application {

    public static void main(String[] args) throws GenericError, CreateAccountError, Exception {

        Moov sdk = Moov.builder()
                .security(Security.builder()
                    .username("")
                    .password("")
                    .build())
            .build();

        CreateAccount req = CreateAccount.builder()
                .accountType(CreateAccountType.BUSINESS)
                .profile(CreateProfile.builder()
                    .business(CreateBusinessProfile.builder()
                        .legalBusinessName("Whole Body Fitness LLC")
                        .build())
                    .build())
                .build();

        CreateAccountResponse res = sdk.accounts().create()
                .request(req)
                .call();

        if (res.account().isPresent()) {
            System.out.println(res.account().get());
        }
    }
}
```

### Per-Operation Security Schemes

Some operations in this SDK require the security scheme to be specified at the request level. For example:
```java
package hello.world;

import io.moov.sdk.Moov;
import io.moov.sdk.models.components.AvatarUploadRequest;
import io.moov.sdk.models.components.AvatarUploadRequestFile;
import io.moov.sdk.models.errors.GenericError;
import io.moov.sdk.models.operations.UploadAvatarResponse;
import io.moov.sdk.models.operations.UploadAvatarSecurity;
import io.moov.sdk.utils.Utils;
import java.io.FileInputStream;
import java.lang.Exception;

public class Application {

    public static void main(String[] args) throws GenericError, Exception {

        Moov sdk = Moov.builder()
            .build();

        UploadAvatarResponse res = sdk.avatars().upload()
                .security(UploadAvatarSecurity.builder()

                    .build())
                .uniqueID("<id>")
                .avatarUploadRequest(AvatarUploadRequest.builder()
                    .file(AvatarUploadRequestFile.builder()
                        .fileName("example.file")
                        .content(Utils.readBytesAndClose(new FileInputStream("example.file")))
                        .build())
                    .build())
                .call();

    }
}
```

Full README: https://github.com/moovfinancial/moov-java