merge-api / merge-java-client

The JVM SDK for accessing various Merge Unified APIs

Merge Java Library

The Merge Java SDK provides convenient access to the Merge API from Java or Kotlin.

Documentation

API documentation is available at here.

Installation

Gradle

Add the dependency in your build.gradle:

dependencies {
    implementation 'dev.merge:merge-java-client:0.x.x'
}

Maven

Add the dependency in your pom.xml:

<dependency>
    <groupId>dev.merge</groupId>
    <artifactId>merge-java-client</artifactId>
    <version>0.x.x</version>
</dependency>

Instantiation

MergeApiClient mergeClient = MergeApiClient.builder()
    .accountToken("ACCOUNT_TOKEN")
    .apiKey("API_KEY")
    .build();

Request Options

Every endpoint has an overloaded equivalent which takes RequestOptions that allow you to override the account token and api key.

import com.merge.api.MergeApiClient;
import com.merge.api.resources.ats.types.Candidate;
import com.merge.api.resources.ats.candidates.requests.CandidatesRetrieveRequest;
import com.merge.api.core.RequestOptions;

MergeApiClient mergeClient = MergeApiClient.builder()
    .accountToken("ACCOUNT_TOKEN")
    .apiKey("API_KEY")
    .build();

Candidate candidate = mergeClient.ats().candidates().retrieve(
    "<CANDIDATE_UUID>", 
    CandidatesRetrieveRequest.builder()
            .includeRemoteData(true)
            .build(), 
    RequestOptions.builder()
        .accountToken("OVERRIDE_ACCOUNT_TOKEN")
        .build());

Usage

Below are code snippets of how you can use the Java SDK.

Create Link Token

import com.merge.api.MergeApiClient;
import com.merge.api.resources.ats.types.CategoriesEnum;
import com.merge.api.resources.ats.types.LinkToken;
import com.merge.api.resources.ats.linktoken.requests.EndUserDetailsRequest;

import java.util.List;

MergeApiClient mergeClient = MergeApiClient.builder()
    .accountToken("ACCOUNT_TOKEN")
    .apiKey("API_KEY")
    .build();

LinkToken linkToken = mergeClient.ats().linkToken().create(EndUserDetailsRequest.builder()
    .endUserEmailAddress("[email protected]")
    .endUserOrganizationName("acme")
    .endUserOriginId("1234")
    .categories(List.of(CategoriesEnum.ATS))
    .build());

System.out.println("Created link token", linkToken.getLinkToken())

Get Employee

import com.merge.api.MergeApiClient;
import com.merge.api.resources.hris.employees.requests.EmployeesRetrieveRequest;
import com.merge.api.resources.hris.types.Employee;

MergeApiClient mergeClient = MergeApiClient.builder()
    .accountToken("ACCOUNT_TOKEN")
    .apiKey("API_KEY")
    .build();

Employee employee = mergeClient.hris().employees().retrieve(
    "0958cbc6-6040-430a-848e-aafacbadf4ae",
    EmployeesRetrieveRequest.builder()
        .includeRemoteData(true)
        .build());

Get Candidate

import com.merge.api.MergeApiClient;
import com.merge.api.resources.ats.types.Candidate;
import com.merge.api.resources.ats.candidates.requests.CandidatesRetrieveRequest;

MergeApiClient mergeClient = MergeApiClient.builder()
    .accountToken("ACCOUNT_TOKEN")
    .apiKey("API_KEY")
    .build();

Candidate candidate = mergeClient.ats().candidates().retrieve(
    "521b18c2-4d01-4297-b451-19858d07c133", 
    CandidatesRetrieveRequest.builder()
        .includeRemoteData(true)
        .build());

Filter Candidate

import com.merge.api.MergeApiClient;
import com.merge.api.resources.ats.candidates.requests.CandidatesListRequest;
import com.merge.api.resources.ats.types.PaginatedCandidateList;

import java.time.OffsetDateTime;

MergeApiClient mergeClient = MergeApiClient.builder()
    .accountToken("ACCOUNT_TOKEN")
    .apiKey("API_KEY")
    .build();
    
PaginatedCandidateList candidate = mergeClient.ats().candidates().list(
    CandidatesListRequest.builder()
        .createdAfter(OffsetDateTime.parse("2007-12-03T10:15:30+01:00"))
        .build());

Get Contact

import com.merge.api.MergeApiClient;
import com.merge.api.resources.accounting.contacts.requests.ContactsRetrieveRequest;
import com.merge.api.resources.accounting.types.Contact;

MergeApiClient mergeClient = MergeApiClient.builder()
    .accountToken("ACCOUNT_TOKEN")
    .apiKey("API_KEY")
    .build();

Contact contact = mergeClient.accounting().contacts().retrieve(
    "c640b80b-fac9-409f-aa19-1f9221aec445", 
    ContactsRetrieveRequest.builder()
        .includeRemoteData(true)
        .build());

Create Ticket

import com.merge.api.MergeApiClient;
import com.merge.api.resources.ticketing.tickets.requests.TicketEndpointRequest;
import com.merge.api.resources.ticketing.types.TicketRequest;
import com.merge.api.resources.ticketing.types.TicketRequestStatus;
import com.merge.api.resources.ticketing.types.TicketStatusEnum;
import java.time.OffsetDateTime;

MergeApiClient mergeClient = MergeApiClient.builder()
    .accountToken("ACCOUNT_TOKEN")
    .apiKey("API_KEY")
    .build();

mergeClient.ticketing().tickets().create(TicketEndpointRequest.builder()
    .model(TicketRequest.builder()
        .name("Please add more integrations")
        .creator("3fa85f64-5717-4562-b3fc-2c963f66afa6")
        .dueDate(OffsetDateTime.parse("2022-10-11T00:00:00Z"))
        .status(TicketRequestStatus.of(TicketStatusEnum.CLOSED))
        .build())
    .build());

File Download

import com.merge.api.MergeApiClient;
import com.merge.api.resources.filestorage.types.PaginatedFileList;
import com.merge.api.resources.filestorage.files.requests.FilesListRequest;
import com.merge.api.resources.filestorage.types.File;

import java.io.InputStream;
import java.io.OutputStream;
import java.io.FileOutputStream;
import java.io.IOException;

MergeApiClient mergeClient = MergeApiClient.builder()
        .accountToken("ACCOUNT_TOKEN")
        .apiKey("API_KEY")
        .build();

PaginatedFileList fileResponse = mergeClient.filestorage().files().list(FilesListRequest.builder()
        .name("<FILE_NAME>")
        .build());

File file = fileResponse.getResults().get().get(0);
String fileId = file.getId().get();
InputStream fileContents = mergeClient.filestorage().files().downloadRetrieve(fileId);
byte[] buffer = new byte[1024]; // Set the buffer size to your desired value
try (OutputStream outputStream = new FileOutputStream("/path/to/file")) {
    int bytesRead;
    while ((bytesRead = fileContents.read(buffer)) != -1) {
        outputStream.write(buffer, 0, bytesRead);
    }
} catch (IOException e) {
    throw new RuntimeException(e);
}   

Staged Builders

The generated builders all follow the staged builder pattern. Read more here.

Staged builders only allow you to build the object once all required properties have been specified. For example, to build an ApplicationEndpointRequest the Merge SDK will require that you specify the model and remoteUserId properties.

Contributing

While we value open-source contributions to this SDK, this library is generated programmatically. Additions made directly to this library would have to be moved over to our generation code, otherwise they would be overwritten upon the next generated release. Feel free to open a PR as a proof of concept, but know that we will not be able to merge it as-is. We suggest opening an issue first to discuss with us!

On the other hand, contributions to the README are always very welcome!

merge-java-client's Issues

Creating a Ticketing Comment Fails with a 400 Bad Request.

We're attempting to migrate to this SDK version, but creating a comment doesn't seem to be working correctly.

Here's the snippet of code (Kotlin) we're using to perform this action:

// ticketId - the ticket to make a comment for
// customerAccountToken - specific merge account token for a specific install
// vendorMarkdownCommentBody - markdown that the ticketing vendor accept and displays nicely

val mergeClient = MergeApiClient.builder().apiKey(properties.apiKey).build()
val ticketingClient = mergeClient.ticketing()

val ticketsClient = ticketingClient.tickets()
val existingTicket = ticketsClient.retrieve(
                ticketId, TicketsRetrieveRequest.builder().build(),
                RequestOptions.builder().accountToken(customerAccountToken).build()
            )

val commentsClient = ticketingClient.comments()
val createCommentRequest =
            CommentEndpointRequest.builder()
                .model(
                    CommentRequest.builder()
                       // pass back in the whole 'existingTicket' object - `tags` is an (empty) array of string on this `Ticket` object
                        .ticket(CommentRequestTicket.of(existingTicket))
                        .body(vendorMarkdownCommentBody)
                        .build())
                .build()

// this blows up with a 400 from us to merge.
val createdComment = commentsClient.create(
                createCommentRequest,
                RequestOptions.builder().accountToken(customerAccountToken).build()
            )

Here's the request / response that is being generated and received.

Request:

{
  "model": {
    "body": "<!-- truncated, string -->",
    "ticket": {
      "id": "<uuid>",
      "remote_id": "<remote_id>",
      "name": "<!-- truncated, string -->",
      "assignees": [],
      "status": "OPEN",
      "description": "<!-- truncated, string -->",
      "collections": [
        "<uuid>"
      ],
      "ticket_type": "Issue",
      "attachments": [],
      "tags": [],
      "remote_created_at": "2024-02-01T23:32:42.307Z",
      "remote_updated_at": "2024-02-01T23:32:42.307Z",
      "remote_was_deleted": false,
      "ticket_url": "<!-- truncated, string -->",
      "created_at": "2024-02-01T23:32:41.877615Z",
      "modified_at": "2024-02-01T23:32:42.441999Z"
    }
  }
}

Response:

{
  "warnings": [],
  "errors": [
    {
      "source": {
        "pointer": "model/ticket/tags"
      },
      "title": "Incorrect Field Type",
      "detail": "Incorrect type for tags - expected type string, but got type array",
      "problem_type": "INCORRECT_FIELD_TYPE"
    }
  ]
}

From the SDK, tags is an empty array, so, either the API needs to accept the empty array, or the SDK needs to stringify? the array / or not send for this request?

merge-java-client#1.0.8: LinkTokenClient has No Such method error

Please help to fix the below issue asap. Refer the screenshots for more details, the order of the arguments are not matching with the RequestBody.create method.

In LinkTokenClient.java >> LineNo 45 >>

current code logic is as below:
body = RequestBody.create(
ObjectMappers.JSON_MAPPER.writeValueAsBytes(request), MediaTypes.APPLICATION_JSON);

expected code logic is as below:
body = RequestBody.create( MediaTypes.APPLICATION_JSON,
ObjectMappers.JSON_MAPPER.writeValueAsBytes(request));

Mvn Dependency:

	<dependency>
		<groupId>dev.merge</groupId>
		<artifactId>merge-java-client</artifactId>
		<version>1.0.8</version>
	</dependency>

Fetching a category agnostic link token

According to Merge's documentation, there is a way of fetching a category agnostic link token from this endpoint: https://api.merge.dev/api/integrations/create-link-token

In this SDK, it seems that you are forced to select a category specific client client (ats(), accounting(), etc.) in order to fetch a link token. E.g. From the README:

LinkToken linkToken = mergeClient.ats().linkToken().create(EndUserDetailsRequest.builder()
    .endUserEmailAddress("[email protected]")
    .endUserOrganizationName("acme")
    .endUserOriginId("1234")
    .categories(List.of(CategoriesEnum.ATS))
    .build());

And that link token is fetched from a different endpoint: <base_url>api/ats/v1/link-token

Is there a way to fetch a category agnostic link token so that Merge Link can be powered? Otherwise we would have to create custom UI to figure out what category the user would like to create the link for, then fetch the link token for that category, then use that to power Merge Link.

Ideally we would fetch a link token that's not tied to a category, and use that to power the Merge Link UI component without going through the first step.

Extended Employee Api

There was an option/method to fetch employees with extended option and get the extended employee data from the merge.dev (legacy java sdk), that is not in the new java client, is there a plan to support that or is it officially removed/deprecated?

accessToken required in v1.0.6 for linkToken creation

linkToken creation api fails saying that accessToken is required. This is a regression from v1.0.5 where this was not an issue. Now we cannot create new linked accounts in the new version and we had to revert

Exception with unknown phone_number_type when accessing a candidate list

When accessing a candidate list from Postman,
GET https://api.merge.dev/api/ats/v1/candidates?created_after=1953-11-23T13:06:29.055Z
I receive a full candidate list. However when accessing through the merge-java-client using the same API call I get an exception.

Exception in thread "main" java.lang.NoSuchFieldError: READ_UNKNOWN_ENUM_VALUES_USING_DEFAULT_VALUE
	at com.fasterxml.jackson.databind.deser.std.EnumDeserializer.createContextual(EnumDeserializer.java:211)
	at com.fasterxml.jackson.databind.DeserializationContext.handleSecondaryContextualization(DeserializationContext.java:867)
	at com.fasterxml.jackson.databind.DeserializationContext.findRootValueDeserializer(DeserializationContext.java:659)
	at com.fasterxml.jackson.databind.ObjectMapper._findRootDeserializer(ObjectMapper.java:4956)
	at com.fasterxml.jackson.databind.ObjectMapper._convert(ObjectMapper.java:4537)
	at com.fasterxml.jackson.databind.ObjectMapper.convertValue(ObjectMapper.java:4475)
	at com.merge.api.resources.ats.types.PhoneNumberPhoneNumberType$Deserializer.deserialize(PhoneNumberPhoneNumberType.java:84)
	at com.merge.api.resources.ats.types.PhoneNumberPhoneNumberType$Deserializer.deserialize(PhoneNumberPhoneNumberType.java:75)
	at com.fasterxml.jackson.databind.deser.std.ReferenceTypeDeserializer.deserialize(ReferenceTypeDeserializer.java:204)
	at com.fasterxml.jackson.databind.deser.impl.MethodProperty.deserializeSetAndReturn(MethodProperty.java:158)
	at com.fasterxml.jackson.databind.deser.BuilderBasedDeserializer.vanillaDeserialize(BuilderBasedDeserializer.java:293)
	at com.fasterxml.jackson.databind.deser.BuilderBasedDeserializer.deserialize(BuilderBasedDeserializer.java:217)
	at com.fasterxml.jackson.databind.deser.std.CollectionDeserializer._deserializeFromArray(CollectionDeserializer.java:359)
	at com.fasterxml.jackson.databind.deser.std.CollectionDeserializer.deserialize(CollectionDeserializer.java:244)
	at com.fasterxml.jackson.databind.deser.std.CollectionDeserializer.deserialize(CollectionDeserializer.java:28)
	at com.fasterxml.jackson.databind.deser.std.ReferenceTypeDeserializer.deserialize(ReferenceTypeDeserializer.java:204)
	at com.fasterxml.jackson.databind.deser.impl.MethodProperty.deserializeSetAndReturn(MethodProperty.java:158)
	at com.fasterxml.jackson.databind.deser.BuilderBasedDeserializer.vanillaDeserialize(BuilderBasedDeserializer.java:293)
	at com.fasterxml.jackson.databind.deser.BuilderBasedDeserializer.deserialize(BuilderBasedDeserializer.java:217)
	at com.fasterxml.jackson.databind.deser.std.CollectionDeserializer._deserializeFromArray(CollectionDeserializer.java:359)
	at com.fasterxml.jackson.databind.deser.std.CollectionDeserializer.deserialize(CollectionDeserializer.java:244)
	at com.fasterxml.jackson.databind.deser.std.CollectionDeserializer.deserialize(CollectionDeserializer.java:28)
	at com.fasterxml.jackson.databind.deser.std.ReferenceTypeDeserializer.deserialize(ReferenceTypeDeserializer.java:204)
	at com.fasterxml.jackson.databind.deser.impl.MethodProperty.deserializeSetAndReturn(MethodProperty.java:158)
	at com.fasterxml.jackson.databind.deser.BuilderBasedDeserializer.vanillaDeserialize(BuilderBasedDeserializer.java:293)
	at com.fasterxml.jackson.databind.deser.BuilderBasedDeserializer.deserialize(BuilderBasedDeserializer.java:217)
	at com.fasterxml.jackson.databind.deser.DefaultDeserializationContext.readRootValue(DefaultDeserializationContext.java:323)
	at com.fasterxml.jackson.databind.ObjectMapper._readMapAndClose(ObjectMapper.java:4825)
	at com.fasterxml.jackson.databind.ObjectMapper.readValue(ObjectMapper.java:3772)
	at com.fasterxml.jackson.databind.ObjectMapper.readValue(ObjectMapper.java:3740)
	at com.merge.api.resources.ats.candidates.CandidatesClient.list(CandidatesClient.java:121)
	at com.merge.api.resources.ats.candidates.CandidatesClient.list(CandidatesClient.java:48)

The distinct phone number types in the postman response were:

                     "phone_number_type": "OTHER"
                     "phone_number_type": "MOBILE"

The data used came from the Greeenhouse - Job Boards API sample data.

The version of the client code is here:

<dependency>
    <groupId>dev.merge</groupId>
    <artifactId>merge-java-client</artifactId>
    <version>1.0.8</version>
</dependency>

Using Client Java code:

        mergeClient = MergeApiClient.builder()
                .accountToken("TOKEN")
                .apiKey("KEY")
                .build();
                
        candidateList = mergeClient.ats().candidates().list(
            CandidatesListRequest.builder()
            .createdAfter(OffsetDateTime.parse("2007-12-03T10:15:30+01:00"))
            .build());
        
        

I was successful with this API call that returned valid data:

            mergeClient = MergeApiClient.builder()
                .accountToken("TOKEN")
                .apiKey("KEY")
                .build();

            candidate = mergeClient.ats().candidates().retrieve(
                    "a3632d60-21d0-46ec-96b0-23cf233e668d",
                    CandidatesRetrieveRequest.builder()
                    .includeRemoteData(true)
                    .build());