Asynchronous operations provide several key benefits:

• Non-blocking I/O: Your threads stay free for other work while operations are in flight
• Better resource utilization: Handle more concurrent operations with fewer threads
• Improved scalability: Build highly responsive applications that can handle thousands of concurrent requests
• Reactive integration: Works seamlessly with reactive streams and backpressure handling

The SDK returns Reactive Streams Publisher<T> instances for operations dealing with streams involving multiple I/O interactions. We use Reactive Streams instead of JDK Flow API to provide broader compatibility with the reactive ecosystem, as most reactive libraries natively support Reactive Streams.

Why Reactive Streams over JDK Flow?

• Broader ecosystem compatibility: Most reactive libraries (Project Reactor, RxJava, Akka Streams, etc.) natively support Reactive Streams
• Industry standard: Reactive Streams is the de facto standard for reactive programming in Java
• Better interoperability: Seamless integration without additional adapters for most use cases

Integration with Popular Libraries:

• Project Reactor: Use Flux.from(publisher) to convert to Reactor types
• RxJava: Use Flowable.fromPublisher(publisher) for RxJava integration
• Akka Streams: Use Source.fromPublisher(publisher) for Akka Streams integration
• Vert.x: Use ReadStream.fromPublisher(vertx, publisher) for Vert.x reactive streams
• Mutiny: Use Multi.createFrom().publisher(publisher) for Quarkus Mutiny integration

For JDK Flow API Integration: If you need JDK Flow API compatibility (e.g., for Quarkus/Mutiny 2), you can use adapters:

// Convert Reactive Streams Publisher to Flow Publisher
Flow.Publisher<T> flowPublisher = FlowAdapters.toFlowPublisher(reactiveStreamsPublisher);

// Convert Flow Publisher to Reactive Streams Publisher
Publisher<T> reactiveStreamsPublisher = FlowAdapters.toPublisher(flowPublisher);

For standard single-response operations, the SDK returns CompletableFuture<T> for straightforward async execution.

Async support is available for:

• Server-sent Events: Stream real-time events with Reactive Streams Publisher<T>
• JSONL Streaming: Process streaming JSON lines asynchronously
• Pagination: Iterate through paginated results using callAsPublisher() and callAsPublisherUnwrapped()
• File Uploads: Upload files asynchronously with progress tracking
• File Downloads: Download files asynchronously with streaming support
• Standard Operations: All regular API calls return CompletableFuture<T> for async execution

• getAll - Get all ACH transactions for a company

• get - Get all company bank accounts
• create - Create a company bank account
• verify - Verify a company bank account
• createFromPlaidToken - Create a bank account from a plaid processor token
• deleteV1CompaniesCompanyIdBankAccountsBankAccountId - Delete a company bank account

• createPartnerManaged - Create a partner managed company
• get - Get a company
• update - Update a company
• getV1PartnerManagedCompaniesCompanyUuidMigrationReadiness - Check company migration readiness
• acceptTermsOfService - Accept terms of service for a company user
• retrieveTermsOfService - Retrieve terms of service status for a company user
• createAdmin - Create an admin for the company
• listAdmins - Get all the admins at a company
• getOnboardingStatus - Get company onboarding status
• finishOnboarding - Finish company onboarding
• getCustomFields - Get the custom fields of a company

• get - Get suspensions for this company
• suspend - Suspend a company's account

• getDownloadUrl - Get a temporary url to download the Company Attachment file

• getDetails - Get Company Attachment Details
• getList - Get List of Company Attachments
• create - Create Company Attachment and Upload File

• create - Create a company benefit
• list - Get benefits for a company
• get - Get a company benefit
• update - Update a company benefit
• delete - Delete a company benefit
• getAll - Get all supported benefits
• getSupported - Get a supported benefit
• getSummary - Get company benefit summary by company benefit id.
• getEmployeeBenefits - Get all employee benefits for a company benefit
• updateEmployeeBenefits - Bulk update employee benefits for a company benefit
• getRequirements - Get benefit fields requirements by benefit type
• getV1CompanyBenefitsCompanyBenefitIdContributionExclusions - Get contribution exclusions for a company benefit
• putV1CompanyBenefitsCompanyBenefitIdContributionExclusions - Update contribution exclusions for a company benefit

• getAll - Get all company forms
• get - Get a company form
• getPdf - Get a company form pdf
• sign - Sign a company form

• getAll - Get all contractor documents
• get - Get a contractor document
• getPdf - Get the contractor document pdf
• sign - Sign a contractor document

• list - Get all contractor forms
• get - Get a contractor form
• getPdf - Get the contractor form pdf
• generate1099 - Generate a 1099 form [DEMO]

• getList - Get contractor payment groups for a company
• create - Create a contractor payment group
• preview - Preview a contractor payment group
• get - Get a contractor payment group
• delete - Cancel a contractor payment group
• fund - Fund a contractor payment group [DEMO]
• getV1ContractorPaymentGroupsIdPartnerDisbursements - Get partner disbursements for a contractor payment group
• patchV1ContractorPaymentGroupsIdPartnerDisbursements - Update partner disbursements for a contractor payment group

• getBankAccounts - Get all contractor bank accounts
• get - Get a contractor's payment method
• update - Update a contractor's payment method

• createBankAccount - Create a contractor bank account

• getReceipt - Get a single contractor payment receipt
• fund - Fund a contractor payment [DEMO]
• create - Create a contractor payment
• list - Get contractor payments for a company
• get - Get a single contractor payment
• delete - Cancel a contractor payment
• preview - Preview contractor payment debit date

• create - Create a contractor
• list - Get contractors of a company
• get - Get a contractor
• update - Update a contractor
• delete - Delete a contractor
• getOnboardingStatus - Get the contractor's onboarding status
• updateOnboardingStatus - Change the contractor's onboarding status
• getAddress - Get a contractor address
• updateAddress - Create or update a contractor's address
• getV1CompaniesCompanyIdContractorsPaymentDetails - List contractor payment details

• create - Create a department
• getAll - Get all departments of a company
• get - Get a department
• update - Update a department
• delete - Delete a department
• addPeople - Add people to a department
• removePeople - Remove people from a department

• create - Create a custom earning type
• list - Get all earning types for a company
• update - Update an earning type
• delete - Deactivate an earning type

• get - Get an employee's home addresses
• create - Create an employee's home address
• retrieveHomeAddress - Get an employee's home address
• update - Update an employee's home address
• delete - Delete an employee's home address
• getWorkAddresses - Get an employee's work addresses
• createWorkAddress - Create an employee work address
• retrieveWorkAddress - Get an employee work address
• updateWorkAddress - Update an employee work address
• deleteWorkAddress - Delete an employee's work address

• create - Create an employee benefit
• get - Get all benefits for an employee
• retrieve - Get an employee benefit
• update - Update an employee benefit
• delete - Delete an employee benefit
• getYtdBenefitAmountsFromDifferentCompany - Get year-to-date benefit amounts from a different company
• createYtdBenefitAmountsFromDifferentCompany - Create year-to-date benefit amounts from a different company
• getV1EmployeesEmployeeUuidSection603HighEarnerStatuses - Get all Section 603 high earner statuses for an employee
• postV1EmployeesEmployeeUuidSection603HighEarnerStatuses - Create a Section 603 high earner status
• getV1EmployeesEmployeeUuidSection603HighEarnerStatusesEffectiveYear - Get a Section 603 high earner status for a specific year
• patchV1EmployeesEmployeeUuidSection603HighEarnerStatusesEffectiveYear - Update a Section 603 high earner status

• createTermination - Create an employee termination
• getTerminations - Get terminations for an employee
• deleteTermination - Delete an employee termination
• updateTermination - Update an employee termination
• createRehire - Create an employee rehire
• rehire - Update an employee rehire
• getRehire - Get an employee rehire
• deleteRehire - Delete an employee rehire
• getHistory - Get employment history for an employee

• generateW2 - Generate a W2 form [DEMO]
• list - Get all employee forms
• get - Get an employee form
• getPdf - Get the employee form pdf
• sign - Sign an employee form

• create - Create an employee bank account
• deleteBankAccount - Delete an employee bank account
• updateBankAccount - Update an employee bank account
• get - Get payment method for an employee
• update - Update payment method for an employee

• getBankAccounts - Get all employee bank accounts

• list - Get employees of a company
• create - Create an employee
• getV1CompaniesCompanyIdEmployeesPaymentDetails - Get employee payment details for a company
• createHistorical - Create a historical employee
• get - Get an employee
• update - Update an employee.
• delete - Delete an onboarding employee
• getCustomFields - Get an employee's custom fields
• updateOnboardingDocumentsConfig - Update employee onboarding documents config
• getOnboardingStatus - Get the employee's onboarding status
• updateOnboardingStatus - Update the employee's onboarding status
• getTimeOffActivities - Get employee time off activities

• getFederalTaxes - Get federal taxes for an employee
• updateFederalTaxes - Update federal taxes for an employee
• getStateTaxes - Get an employee's state taxes
• updateStateTaxes - Update an employee's state taxes

• get - Get all events

• create - Create a new external payroll for a company
• get - Get external payrolls for a company
• retrieve - Get an external payroll
• delete - Delete an external payroll
• update - Update an external payroll
• calculateTaxes - Get tax suggestions for an external payroll
• listTaxLiabilities - Get tax liabilities
• updateTaxLiabilities - Update tax liabilities
• finalizeTaxLiabilities - Finalize tax liabilities options and convert into processed payrolls

• get - Get a company's federal tax details
• update - Update a company's federal tax details

• create - Create a flow

• create - Create a garnishment
• list - Get garnishments for an employee
• get - Get a garnishment
• update - Update a garnishment
• getChildSupportData - Get child support garnishment data

• get - Get a generated document

• update - Update a historical employee

• get - Get a company's holiday pay policy
• create - Create a holiday pay policy for a company
• update - Update a company's holiday pay policy
• delete - Delete a company's holiday pay policy
• addEmployees - Add employees to a company's holiday pay policy
• removeEmployees - Remove employees from a company's holiday pay policy
• previewPaidHolidays - Preview a company's paid holidays

• getAuthorization - Get an employee's I-9 authorization
• update - Create or update an employee's I-9 authorization
• getDocumentOptions - Get an employee's I-9 verification document options
• getDocuments - Get an employee's I-9 verification documents
• createDocuments - Create an employee's I-9 authorization verification documents
• deleteDocument - Delete an employee's I-9 verification document
• employerSign - Employer sign an employee's Form I-9

• get - Get a company industry selection
• update - Update a company industry selection

• getInformationRequests - Get all information requests for a company
• submit - Submit information request responses

• getInfo - Get info about the current access token
• oauthAccessToken - Create a System Access Token or Refresh an Access Token

• get - Retrieve invoicing data for companies

• createJob - Create a job
• getJobs - Get jobs for an employee
• getJob - Get a job
• update - Update a job
• delete - Delete an individual job
• getCompensations - Get compensations for a job
• createCompensation - Create a compensation
• getCompensation - Get a compensation
• updateCompensation - Update a compensation
• deleteCompensation - Delete a compensation

• create - Create a company location
• get - Get all company locations
• retrieve - Get a location
• update - Update a location
• getMinimumWages - Get minimum wages for a location

• getDetails - Get a notification's details
• getCompanyNotifications - Get notifications for company

• get - Get a company's payment configs
• update - Update a company's payment configs

• list - Get all payrolls for a company
• createOffCycle - Create an off-cycle payroll
• getApprovedReversals - Get approved payroll reversals
• get - Get a single payroll
• update - Update a payroll by ID
• delete - Delete a payroll
• prepare - Prepare a payroll for update
• getReceipt - Get a single payroll receipt
• getBlockers - Get all payroll blockers for a company
• calculateGrossUp - Calculate gross up for a payroll
• calculate - Calculate a payroll
• submit - Submit payroll
• cancel - Cancel a payroll
• getPayStub - Get an employee pay stub (pdf)
• getPayStubs - Get an employee's pay stubs
• generatePrintableChecks - Generate printable payroll checks (pdf)
• getV1CompaniesCompanyIdPayrollsIdPartnerDisbursements - Get partner disbursements for a payroll
• patchV1CompaniesCompanyIdPayrollsIdPartnerDisbursements - Update partner disbursements for a payroll

• create - Create a new pay schedule
• getAll - Get the pay schedules for a company
• getPreview - Preview pay schedule dates
• get - Get a pay schedule
• update - Update a pay schedule
• getPayPeriods - Get pay periods for a company
• getUnprocessedTerminationPeriods - Get termination pay periods for a company
• getAssignments - Get pay schedule assignments for a company
• previewAssignment - Preview pay schedule assignments for a company
• assign - Assign pay schedules for a company

• postV1CompaniesCompanyIdPeopleBatches - Create a people batch
• getV1PeopleBatchesPeopleBatchUuid - Get a people batch

• get - Get all recovery cases for a company
• redebit - Initiate a redebit for a recovery case

• getV1EmployeesEmployeeIdRecurringReimbursements - Get recurring reimbursements for an employee
• postV1EmployeesEmployeeIdRecurringReimbursements - Create a recurring reimbursement
• getV1RecurringReimbursements - Get a recurring reimbursement
• putV1RecurringReimbursements - Update a recurring reimbursement
• deleteV1RecurringReimbursements - Delete a recurring reimbursement

• createCustom - Create a custom report
• postPayrollsPayrollUuidReportsGeneralLedger - Create a general ledger report
• getReportsRequestUuid - Get a report
• getTemplate - Get a report template
• postV1CompaniesCompanyIdReportsEmployeesAnnualFicaWage - Create an employees annual FICA wage report

• postV1EmployeesEmployeeIdSalaryEstimates - Create a salary estimate for an employee
• getV1SalaryEstimatesId - Get a salary estimate
• putV1SalaryEstimatesId - Update a salary estimate
• postV1SalaryEstimatesUuidAccept - Accept a salary estimate
• getV1SalaryEstimatesOccupations - Search for BLS occupations

• create - Create a signatory
• list - Get the signatories for a company
• invite - Invite a signatory
• update - Update a signatory
• delete - Delete a signatory

• get - Get tax requirements for a state
• updateState - Update tax requirements for a state
• getAll - Get all tax requirements for a company

• calculateAccruingTimeOffHours - Calculate accruing time off hours
• get - Get a time off policy
• update - Update a time off policy
• getAll - Get all time off policies for a company
• create - Create a time off policy
• addEmployees - Add employees to a time off policy
• removeEmployees - Remove employees from a time off policy
• updateBalance - Update employee time off balances
• deactivate - Deactivate a time off policy

• createSubscription - Create a webhook subscription
• listSubscriptions - List webhook subscriptions
• updateSubscription - Update a webhook subscription
• getSubscription - Get a webhook subscription
• deleteSubscription - Delete a webhook subscription
• verify - Verify the webhook subscription
• requestVerificationToken - Request the webhook subscription verification_token
• getV1WebhooksHealthCheck - Get the webhooks health status

• get - Get a single Wire In Request
• submit - Submit a wire in request
• list - Get all Wire In Requests for a company

Network errors:

• java.io.IOException (always wrapped by java.io.UncheckedIOException). Commonly encountered subclasses of IOException include java.net.ConnectException, java.net.SocketTimeoutException, EOFException (there are many more subclasses in the JDK platform).

Inherit from GustoEmbeddedException:

• com.gusto.embedded_api.models.errors.NotFoundErrorObject: Not Found The requested resource does not exist. Make sure the provided ID/UUID is valid. Applicable to 162 of 280 methods.*
• com.gusto.embedded_api.models.errors.UnprocessableEntityErrorObject: Unprocessable Entity This may happen when the body of your request contains errors such as invalid_attribute_value, or the request fails due to an invalid_operation. See the Errors Categories guide for more details. Applicable to 143 of 280 methods.*
• com.gusto.embedded_api.models.errors.PeopleBatchConflictError: Error response when a people batch idempotency key conflict occurs. Status code 409. Applicable to 1 of 280 methods.*
• com.gusto.embedded_api.models.errors.GetCompaniesCompanyUuidContractorPaymentsPreviewResponseBody: Unprocessable Entity (WebDAV). Status code 422. Applicable to 1 of 280 methods.*
• com.gusto.embedded_api.models.errors.CompanySuspensionCreationErrors: Unprocessable Entity This may happen when the body of your request contains errors such as invalid_attribute_value, or the request fails due to an invalid_operation. See the Errors Categories guide for more details. Status code 422. Applicable to 1 of 280 methods.*

You can also provide a completely custom HTTP client with your own configuration:

import com.gusto.embedded_api.GustoEmbedded;
import com.gusto.embedded_api.utils.HTTPClient;
import com.gusto.embedded_api.utils.Blob;
import com.gusto.embedded_api.utils.ResponseWithBody;

import java.io.IOException;
import java.net.URISyntaxException;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.io.InputStream;
import java.time.Duration;
import java.util.concurrent.Executors;
import java.util.concurrent.CompletableFuture;

public class Application {
    public static void main(String[] args) {
        // Custom HTTP client with custom configuration
        HTTPClient customHttpClient = new HTTPClient() {
            private final HttpClient client = HttpClient.newBuilder()
                .executor(Executors.newFixedThreadPool(10))
                .connectTimeout(Duration.ofSeconds(30))
                // .sslContext(customSslContext) // Add custom SSL context if needed
                .build();

            @Override
            public HttpResponse<InputStream> send(HttpRequest request) throws IOException, URISyntaxException, InterruptedException {
                return client.send(request, HttpResponse.BodyHandlers.ofInputStream());
            }

            @Override
            public CompletableFuture<HttpResponse<Blob>> sendAsync(HttpRequest request) {
                // Convert response to HttpResponse<Blob> for async operations
                return client.sendAsync(request, HttpResponse.BodyHandlers.ofPublisher())
                    .thenApply(resp -> new ResponseWithBody<>(resp, Blob::from));
            }
        };

        GustoEmbedded sdk = GustoEmbedded.builder()
            .client(customHttpClient)
            .build();
    }
}