apideck-libraries/apideck-java

Apideck Java SDK Skill

Overview

The Apideck Unified API provides a single integration layer to connect with 200+ third-party services across accounting, CRM, HRIS, file storage, ATS, e-commerce, and more. The official Java SDK (com.apideck:unify) provides typed clients for all unified APIs.

Installation

Gradle:

implementation 'com.apideck:unify:0.30.3'

Maven:

<dependency>
    <groupId>com.apideck</groupId>
    <artifactId>unify</artifactId>
    <version>0.30.3</version>
</dependency>

Requires JDK 11 or later.

IMPORTANT RULES

• ALWAYS use the com.apideck:unify SDK. DO NOT make raw HTTP calls to the Apideck API.
• ALWAYS pass apiKey, appId, and consumerId when building the client.
• USE serviceId on requests to specify which downstream connector to use.
• USE the fluent builder pattern for constructing requests.
• ALWAYS handle errors with try/catch using ApideckError as the base class.
• DO NOT store API keys in source code. Use environment variables.

Quick Start

import com.apideck.unify.Apideck;
import com.apideck.unify.models.operations.*;

Apideck sdk = Apideck.builder()
    .consumerId("your-consumer-id")
    .appId("your-app-id")
    .apiKey(System.getenv("APIDECK_API_KEY"))
    .build();

sdk.crm().contacts().list()
    .serviceId("salesforce")
    .limit(20)
    .callAsStream()
    .forEach(page -> {
        page.getContactsResponse().ifPresent(res ->
            res.getData().forEach(contact ->
                System.out.println(contact.getName())
            )
        );
    });

SDK Patterns

Client Setup

import com.apideck.unify.Apideck;

Apideck sdk = Apideck.builder()
    .consumerId("your-consumer-id")
    .appId("your-app-id")
    .apiKey(System.getenv("APIDECK_API_KEY"))
    .build();

Async client:

import com.apideck.unify.AsyncApideck;

AsyncApideck asyncSdk = Apideck.builder()
    .consumerId("your-consumer-id")
    .appId("your-app-id")
    .apiKey(System.getenv("APIDECK_API_KEY"))
    .build()
    .async();

CRUD Operations

Uses a fluent builder pattern: sdk.{category}().{resource}().{operation}().

import com.apideck.unify.models.components.*;
import com.apideck.unify.models.operations.*;

// LIST
sdk.crm().contacts().list()
    .serviceId("salesforce")
    .limit(20)
    .filter(ContactsFilter.builder().email("[email protected]").build())
    .sort(ContactsSort.builder()
        .by(ContactsSortBy.UPDATED_AT)
        .direction(SortDirection.DESC)
        .build())
    .call();

// CREATE
sdk.crm().contacts().create()
    .serviceId("salesforce")
    .contact(ContactInput.builder()
        .firstName("John")
        .lastName("Doe")
        .emails(List.of(Email.builder()
            .email("[email protected]")
            .type(EmailType.PRIMARY)
            .build()))
        .phoneNumbers(List.of(PhoneNumber.builder()
            .number("+1234567890")
            .type(PhoneNumberType.MOBILE)
            .build()))
        .build())
    .call();

// GET
sdk.crm().contacts().get()
    .id("contact_123")
    .serviceId("salesforce")
    .call();

// UPDATE
sdk.crm().contacts().update()
    .id("contact_123")
    .serviceId("salesforce")
    .contact(ContactInput.builder().firstName("Jane").build())
    .call();

// DELETE
sdk.crm().contacts().delete()
    .id("contact_123")
    .serviceId("salesforce")
    .call();

Pagination

Multiple approaches available:

// Stream (recommended)
sdk.accounting().invoices().list()
    .serviceId("quickbooks")
    .limit(50)
    .callAsStream()
    .forEach(page -> {
        // handle page
    });

// Iterable
for (var page : sdk.accounting().invoices().list()
    .serviceId("quickbooks")
    .limit(50)
    .callAsIterable()) {
    // handle page
}

// Reactive Streams (for Project Reactor, RxJava, etc.)
var publisher = sdk.accounting().invoices().list()
    .serviceId("quickbooks")
    .limit(50)
    .callAsPublisher();

Async Support

Returns CompletableFuture<T> for standard operations:

AsyncApideck asyncSdk = sdk.async();

asyncSdk.crm().contacts().list()
    .serviceId("salesforce")
    .limit(20)
    .call()
    .thenAccept(res -> {
        // handle response
    });

Error Handling

import com.apideck.unify.models.errors.*;

try {
    sdk.crm().contacts().get()
        .id("invalid")
        .serviceId("salesforce")
        .call();
} catch (BadRequestResponse e) {
    System.err.println("Bad request: " + e.message());
} catch (UnauthorizedResponse e) {
    System.err.println("Invalid API key");
} catch (NotFoundResponse e) {
    System.err.println("Record not found");
} catch (PaymentRequiredResponse e) {
    System.err.println("API limit reached");
} catch (UnprocessableResponse e) {
    System.err.println("Validation error: " + e.message());
} catch (ApideckError e) {
    System.err.println("API error " + e.code() + ": " + e.message());
}

Retry Configuration

import com.apideck.unify.utils.BackoffStrategy;
import com.apideck.unify.utils.RetryConfig;
import java.util.concurrent.TimeUnit;

Apideck sdk = Apideck.builder()
    .retryConfig(RetryConfig.builder()
        .backoff(BackoffStrategy.builder()
            .initialInterval(1L, TimeUnit.MILLISECONDS)
            .maxInterval(50L, TimeUnit.MILLISECONDS)
            .maxElapsedTime(1000L, TimeUnit.MILLISECONDS)
            .baseFactor(1.1)
            .jitterFactor(0.15)
            .retryConnectError(false)
            .build())
        .build())
    .consumerId("your-consumer-id")
    .appId("your-app-id")
    .apiKey(System.getenv("APIDECK_API_KEY"))
    .build();

API Namespaces

| Namespace | Resources | |-----------|-----------| | sdk.accounting().* | invoices, bills, payments, customers, suppliers, ledgerAccounts, journalEntries, taxRates, creditNotes, purchaseOrders, balanceSheet, profitAndLoss, and more | | sdk.crm().* | contacts, companies, leads, opportunities, activities, notes, pipelines, users | | sdk.hris().* | employees, companies, departments, payrolls, timeOffRequests | | sdk.fileStorage().* | files, folders, drives, driveGroups, sharedLinks, uploadSessions | | sdk.ats().* | applicants, applications, jobs | | sdk.vault().* | connections, consumers, sessions, customMappings, logs | | sdk.webhook().* | webhooks, eventLogs |