All Collections
Advanced Go SDK Migration Guide
Advanced Go SDK Migration Guide

Support for migrating to our Advanced Go 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 New Generation Go SDK. It is currently available for anyone to use.

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

There are key benefits in using this new generation 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 merge-<category>-go SDKs:

We recommend all customers move to the Advanced SDK:

This SDK has the following advantages:



Multi-category SDK

The new Go SDK contains support for all released Merge categories meaning expanding to a new vertical doesn’t require using a second SDK.

More http layer configurability

Easier configuration options to change timeouts, retries, etc.

Error handling

Structured error types are returned from API calls that return non-success status codes. For example, you can check if the error was due to a bad request (i.e. status code 400). These errors are also compatible with the errors.Is and errors.As APIs.


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 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.

Go Instantiation

First, you need to run the following command to use the Merge Go library in your Go module

go get
go get
go get

Then put the package under your project folder and add the following import.

import sw "./merge_hris_client"

To bring in the new package, swap out the go get commands with the following:

... go get ...

Then import the new package with the following:

import (
merge ""
mergeclient ""

Earlier SDK Code

package main

import (
openapiclient "./openapi"

func main() {
xAccountToken := "xAccountToken_example"
companyId := "companyId_example"
createdAfter := time.Now()
createdBefore := time.Now()
cursor := "cD0yMDIxLTAxLTA2KzAzJTNBMjQlM0E1My40MzQzMjYlMkIwMCUzQTAw"
displayFullName := "displayFullName_example"
employmentStatus := "employmentStatus_example"
firstName := "firstName_example"
groups := "groups_example"
includeDeletedData := true
includeRemoteData := true
includeSensitiveFields := true
lastName := "lastName_example"
managerId := "managerId_example"
modifiedAfter := time.Now()
modifiedBefore := time.Now()
pageSize := int32(56)
payGroupId := "payGroupId_example"
personalEmail := "[email protected]"
remoteFields := "employment_status,ethnicity,gender,marital_status"
remoteId := "remoteId_example"
showEnumOrigins := "employment_status,ethnicity,gender,marital_status"
startedAfter := time.Now()
startedBefore := time.Now()
teamId := "teamId_example"
terminatedAfter := time.Now()
terminatedBefore := time.Now()
workEmail := "[email protected]"
workLocationId := "workLocationId_example"

configuration := openapiclient.NewConfiguration()
api_client := openapiclient.NewAPIClient(configuration)
resp, r, err := api_client.EmployeesApi.EmployeesList(context.Background()).XAccountToken(xAccountToken).CompanyId(companyId).CreatedAfter(createdAfter).CreatedBefore(createdBefore).Cursor(cursor).DisplayFullName(displayFullName).EmploymentStatus(employmentStatus).FirstName(firstName).Groups(groups).IncludeDeletedData(includeDeletedData).IncludeRemoteData(includeRemoteData).IncludeSensitiveFields(includeSensitiveFields).LastName(lastName).ManagerId(managerId).ModifiedAfter(modifiedAfter).ModifiedBefore(modifiedBefore).PageSize(pageSize).PayGroupId(payGroupId).PersonalEmail(personalEmail).RemoteFields(remoteFields).RemoteId(remoteId).ShowEnumOrigins(showEnumOrigins).StartedAfter(startedAfter).StartedBefore(startedBefore).TeamId(teamId).TerminatedAfter(terminatedAfter).TerminatedBefore(terminatedBefore).WorkEmail(workEmail).WorkLocationId(workLocationId).Execute()
if err != nil {
fmt.Fprintf(os.Stderr, "Error when calling `EmployeesApi.EmployeesList``: %v\n", err)
fmt.Fprintf(os.Stderr, "Full HTTP response: %v\n", r)
// response from `EmployeesList`: PaginatedEmployeeList
fmt.Fprintf(os.Stdout, "Response from `EmployeesApi.EmployeesList`: %v\n", resp)

Advanced SDK Equivalent

import (

merge ""
mergeclient ""

client := mergeclient.NewClient(
employee, err := client.Hris().Employees().Retrieve(
IncludeRemoteData: merge.Bool(true),
if err != nil {
return err
fmt.Printf("Retrieved employee with ID %q\n", *employee.Id)Here are some key advantages from the new client class:

Here are some key advantages from the new client class:

  • Authentication configuration has been somewhat simplified, you do not need to specify "Bearer" prefix anymore as it is assumed.

  • Pagination is easier, there are helper methods as well as the built-in iterator

Did this answer your question?