All Collections
Advanced Java SDK Migration Guide
Advanced Java SDK Migration Guide

Support for migrating to our Advanced Java SDK!

Matthew Ho avatar
Written by Matthew Ho
Updated over a week ago

Based on customer feedback, we have been working on improving our all-category SDKs. We recently released our Advanced Java SDK. It is currently available for anyone to use.

Note that the existing Java SDKs are fully functional and will continue to work.

There are key benefits in using this Advanced SDK. We understand that migrating will take both time and effort, which is why we’ve worked on putting together this helpful migration guide.

We strongly recommend to use the new SDKs. You’ll play an integral role in providing feedback on our SDKs, making them more usable and robust and get a head start on migrating over.

We would love any and all feedback by reaching out to your engagement manager or [email protected]. All your feedback will be promptly addressed.

Migration Guide

This guide is for Merge customers using the gen-0 and gen-1 Java SDKs:


SDK Name


Package Name





ATS Java



Kotlin multi-category


We recommend all customers move to the Advanced SDK:

  • package manager:

    # maven 
    # gradle implementation("dev.merge.api:merge-java-client:0.0.1")

This SDK has the following advantages:



Better base client

The earlier kotlin multicategory SDK relied on ktor-client as a base http client which is harder to work in Java than okhttp, so we have moved back to okhttp for this generation of SDK.

Safer threading semantics

Due to the aforementioned ktor base library decision, threading and callback events were harder to work with and had memory leak issues that are no longer present with the new SDK.

Flexible JSON inputs

The earlier SDKs had a tough time with customizability, but the new SDKs allow for more flexible inputs to highly-dynamic endpoints such as our CREATE and PASSTHROUGH endpoints.

More builder pattern usage

The builder pattern will result in cleaner code as customers construct request parameters.


This SDK ships with a much more comprehensive set of unit tests compared with the prior SDK.

This SDK has all Merge categories, which makes it easy for Merge customers to find all endpoint methods in one package. The earlier single-category SDKs as well as the multi-category SDK all have the same style of method call, so let’s consider what it looks like to move from an existing employees list call to the new SDK.

Earlier SDK Code

AccountsApi accountsApi = new AccountsApi();
accountsApi.setApiKey("your API key");

CompletableFuture<MergePaginatedResponse<Account>> accountingAccountsPromise = accountsApi.accountsListAsync(
new AccountsApi.AccountsListRequest()

MergePaginatedResponse<Account> accountingAccountsResponse = accountingAccountsPromise.get();

Advanced SDK Equivalent

MergeApiClient mergeClient = MergeApiClient.builder()

CandidatesListRequest request = CandidatesListRequest.builder()

PaginatedCandidateList list = mergeClient.ats().candidates().list(request);

if (list.getResults().isPresent()) {
List<Candidate> resultList = (List<Candidate>) list.getResults().get();
for(Candidate candidate : resultList) {

int iterations = 0;
while (list.getNext().isPresent() && iterations < 10) {
CandidatesListRequest iterParams = CandidatesListRequest.builder().cursor(list.getNext().get()).build();
list = mergeClient.ats().candidates().list(iterParams);

if (list.getResults().isPresent()) {
List<Candidate> resultList = (List<Candidate>) list.getResults().get();
for(Candidate candidate : resultList) {

iterations += 1;

Here are some key advantages from the new client class:

  • Increased use of Optional wrappers to help prevent null pointer exceptions.

  • Ability to override account_token in the SDK call to allow for dynamic reference to multiple linked accounts in the same organization.

Did this answer your question?