Java SDK

The Orbit Java SDK wraps the platform’s core API resources — messaging (SMS, WhatsApp, email), voice, contacts, campaigns, verify (OTP), and webhook signature verification — with typed methods. It requires JDK 11+ and has zero external runtime dependencies.

Pre-publish — source-only. This SDK is not yet on Maven Central — the dependencies below describe the future registry shape. Until first publish, vendor the source from the monorepo (packages/sdk-java/) or call the REST API directly. See Java: core-scope, not full parity on the SDK index for exactly what is and isn’t wrapped, and the low-level client.request(method, path, ...) escape hatch for uncovered routes (worked example below).

Installation

No registry dependency block is live yet — nothing here resolves today. Vendor the SDK source from the monorepo (packages/sdk-java/) and build it into your project, or call the REST API directly with any HTTP client until the first Maven Central release ships (coordinates change).

Client initialization

import io.devotel.orbit.OrbitClient;

OrbitClient client = OrbitClient.fromApiKey("dv_live_sk_...");

Or read the key from an environment variable (ORBIT_API_KEY):

OrbitClient client = OrbitClient.fromEnv();

Tune timeouts and retries with the builder:

OrbitClient client = OrbitClient.builder()
        .apiKey("dv_live_sk_...")
        .baseUrl("https://api.orbit.devotel.io/api/v1")
        .timeout(Duration.ofSeconds(30))
        .maxRetries(3)
        .initialBackoff(Duration.ofSeconds(1))
        .build();

OrbitClient is safe for concurrent use across threads — share a single instance per JVM.

Quickstart: send your first SMS

A runnable end-to-end — the key comes from ORBIT_API_KEY, never from source. Copy it into Main.java and run it:

import io.devotel.orbit.OrbitClient;

import java.util.Map;

OrbitClient client = OrbitClient.fromEnv();  // reads ORBIT_API_KEY

Map<String, Object> result = client.messages.sendSms("+14155552671", "Hello from Orbit!");
Map<?, ?> data = (Map<?, ?>) result.get("data");

System.out.println("message id: " + data.get("id"));        // msg_abc123
System.out.println("status: " + data.get("status"));        // "queued" — watch it reach "delivered"
System.out.println("status URL: /api/v1/messages/" + data.get("id"));

Point ORBIT_API_KEY at a sandbox key prefixed dv_test_sk_ first — sandbox sends are simulated, free, and never reach a carrier. Swap in your live key (dv_live_sk_...) when you’re ready to send for real; the code does not change. The response shape above comes from the Messages API reference — its language tabs include this exact call.

Messaging

Map<String, Object> result = client.messages.sendSms("+14155552671", "Hello!");
System.out.println(result.get("data"));

Sending is only the first half — fetch a message by id to read its delivery state (queued → sent → delivered), which is what a status poller or a support lookup does:

Map<String, Object> message = client.messages.get("msg_abc123");
Map<?, ?> messageData = (Map<?, ?>) message.get("data");
System.out.println("status: " + messageData.get("status"));   // "delivered"

client.messages also exposes sendWhatsApp and sendEmail; get (above) fetches a message by id.

Voice

A call’s full lifecycle fits in one flow: place it, poll its status, then hang up (or hand it off with a blind transfer). getCall returns the same call record createCall did — read status off it as it moves (queued → ringing → in-progress → completed):

// 1. Place an outbound call — routed through Orbit's own softswitch.
Map<String, Object> call = client.voice.createCall("+14155552671", "+14155550100");
String callId = (String) ((Map<?, ?>) call.get("data")).get("id");
System.out.println("call id: " + callId);       // call_abc123

// 2. Poll its status until it answers.
Map<String, Object> detail = client.voice.getCall(callId);
Map<?, ?> detailData = (Map<?, ?>) detail.get("data");
System.out.println("status: " + detailData.get("status"));   // "in-progress"

// 3a. Hang up.
client.voice.hangup(callId);

// 3b. …or transfer the live call to another destination (blind transfer).
client.voice.transfer(callId, "+14155552500");

List past calls with direction/status filters and cursor pagination — pass the filter map straight through (listCalls(null) for no filters):

Map<String, Object> filter = new LinkedHashMap<>();
filter.put("direction", "outbound");
filter.put("status", "completed");
filter.put("limit", 50);

Map<String, Object> page = client.voice.listCalls(filter);
java.util.List<?> calls = (java.util.List<?>) page.get("data");
System.out.println("calls on page: " + calls.size());

Every outbound call is dispatched by the Orbit API itself — this SDK never talks to a telephony carrier.

Verify (OTP)

The send-and-check round trip is the most common first integration on the platform — here as a complete flow. Send the code, keep the returned verification id, and check the code the user typed in against it:

// 1. Send an OTP (channel: sms | whatsapp | email).
Map<String, Object> sent = client.verify.send("+14155552671", "sms");
String verificationId = (String) ((Map<?, ?>) sent.get("data")).get("id");

// 2. Check the code the user typed in, against the id send() returned.
Map<String, Object> result = client.verify.check(verificationId, "482901");
Map<?, ?> data = (Map<?, ?>) result.get("data");

System.out.println("valid: " + data.get("valid"));      // true
System.out.println("status: " + data.get("status"));    // "approved"

A wrongly-typed or expired code reports valid: false — it never throws for a bad guess (only for transport/auth failures), so branch on the flag. The Verify API reference covers the full contract, and Starter examples ships a complete OTP sign-in starter repo (orbit-otp-nextjs). Resend the code for a still-pending verification — the same verification id is reused, so no new state is created:

Map<String, Object> resent = client.verify.resend(verificationId);
Map<?, ?> resentData = (Map<?, ?>) resent.get("data");
System.out.println("status: " + resentData.get("status"));   // "pending" — new code on its way

For anything beyond send/check/resend — e.g. a verification detail view — use the escape hatch (client.request) shown below; the verification detail endpoint is GET /api/v1/verify/{id}/detail.

Contacts

The full contact lifecycle reads off the id create returned — fetch it, patch it, tag it, page the directory, and delete it:

// Create, then keep the id for everything below.
Map<String, Object> contact = client.contacts.create("+14155552671");
String contactId = (String) ((Map<?, ?>) contact.get("data")).get("id");
System.out.println("contact id: " + contactId);      // ctn_abc123

// Fetch one contact.
Map<String, Object> detail = client.contacts.get(contactId);

// Partial update — the patch map carries only the fields you change.
Map<String, Object> patch = new LinkedHashMap<>();
patch.put("first_name", "Grace");
client.contacts.update(contactId, patch);

// Tag the contact.
client.contacts.addTags(contactId, java.util.List.of("vip"));

// Page through the directory with optional search (pass null for no filters).
Map<String, Object> query = new LinkedHashMap<>();
query.put("limit", 50);
query.put("search", "grace");
Map<String, Object> page = client.contacts.list(query);
java.util.List<?> contacts = (java.util.List<?>) page.get("data");
System.out.println("contacts on page: " + contacts.size());

// Permanently delete.
client.contacts.delete(contactId);

Campaigns

Create a campaign, trigger its send, then re-fetch it to watch the status progress (draft → sending → completed):

// Create and trigger a send.
Map<String, Object> campaign = client.campaigns.create("Welcome drip", "sms");
String campaignId = (String) ((Map<?, ?>) campaign.get("data")).get("id");
client.campaigns.send(campaignId);

Map<String, Object> state = client.campaigns.get(campaignId);
Map<?, ?> stateData = (Map<?, ?>) state.get("data");
System.out.println("status: " + stateData.get("status"));   // "sending"

Rename before the send fires, list every campaign in the organization, or delete one outright — the update map carries only the fields you change:

Map<String, Object> patch = new LinkedHashMap<>();
patch.put("name", "Welcome drip — Q4");
client.campaigns.update(campaignId, patch);

Map<String, Object> all = client.campaigns.list();
java.util.List<?> campaigns = (java.util.List<?>) all.get("data");
System.out.println("campaigns: " + campaigns.size());

client.campaigns.delete(campaignId);

Paginate a list

List endpoints are cursor-paginated — read meta.pagination.cursor and meta.pagination.has_more off each response and pass the cursor back as a query param until has_more is false. Page through SMS messages with the escape hatch:

Map<String, Object> query = new LinkedHashMap<>();
query.put("channel", "sms");
query.put("limit", 100);
int total = 0;

while (true) {
    Map<String, Object> page = client.request("GET", "/messages", query, null, null);

    java.util.List<?> data = (java.util.List<?>) page.get("data");
    total += data.size();

    Map<?, ?> pagination = (Map<?, ?>) ((Map<?, ?>) page.get("meta")).get("pagination");
    if (!Boolean.TRUE.equals(pagination.get("has_more"))) {
        break;
    }
    query.put("cursor", pagination.get("cursor"));
}

System.out.println("Fetched " + total + " messages");

The full pagination model (cursor vs. offset endpoints, page-size caps, and why cursors are not bookmarkable) is in the Pagination guide.

Error handling

All Orbit-originated errors inherit from OrbitError:

Exception	Raised when
`OrbitAuthenticationError`	401/403 — bad or missing-scope API key
`OrbitRateLimitError`	429 after retries exhausted; sleep `e.getRetryAfter()`
`OrbitClientError`	other 4xx (invalid request)
`OrbitServerError`	5xx after retries exhausted, or persistent network failure
`OrbitError`	base class — catch to handle any Orbit-originated error

try {
    client.messages.sendSms("+14155552671", "...");
} catch (OrbitRateLimitError e) {
    Thread.sleep(e.getRetryAfter().toMillis());
} catch (OrbitAuthenticationError e) {
    // rotate API key
} catch (OrbitError e) {
    log.error("orbit: {} ({}) — {}", e.getCode(), e.getStatusCode(), e.getMessage());
}

Every non-GET request automatically carries an Idempotency-Key header (UUIDv4); pass your own stable key as the fourth argument to sendSms when retrying from your own queue (client.messages.sendSms("+14155552671", "...", null, "job-7a3b9d-attempt-1")).

Covered route missing? Use the escape hatch

The typed clients wrap 8 core resources; the rest of the API — contact segments, event sinks, frequency caps, and everything else listed as out of scope on the SDK index — is reachable through client.request(method, path, ...). It returns the raw JSON body as a Map<String, Object>. Fetch a segment by id:

Map<String, Object> segment = client.request("GET", "/contacts/segments/seg_01hxyz", null, null, null);
System.out.println(((Map<?, ?>) segment.get("data")).get("name"));

The escape hatch carries the same auth, retry, and error model as the typed clients — treat it as a first-class client, not a fallback HttpClient.

Webhook signature verification

import io.devotel.orbit.Webhooks;
import io.devotel.orbit.errors.OrbitWebhookSignatureError;

try {
    Map<String, Object> event = Webhooks.verify(
            requestBody,
            request.getHeader("X-Orbit-Signature"),
            System.getenv("ORBIT_WEBHOOK_SECRET"));
    // event is a Map<String, Object>
} catch (OrbitWebhookSignatureError e) {
    response.setStatus(400);
    return;
}

Runnable examples

The package’s examples/ directory holds self-contained, runnable end-to-end files (each takes ORBIT_API_KEY / ORBIT_WEBHOOK_SECRET from the environment): first SMS send, cursor pagination over GET /messages, the OTP send+check round trip, a programmable outbound call with an answer_url callback, and webhook signature verification against a signed test payload. Compile the SDK with mvn package, then java -cp target/orbit-sdk-*.jar:examples <ExampleName>.

SDKs

Java SDK: Orbit quickstart for Java

Java SDK

Installation

Client initialization

Quickstart: send your first SMS

Messaging

Voice

Verify (OTP)

Contacts

Campaigns

Paginate a list

Error handling

Covered route missing? Use the escape hatch

Webhook signature verification

Runnable examples

​Java SDK

​Installation

​Client initialization

​Quickstart: send your first SMS

​Messaging

​Voice

​Verify (OTP)

​Contacts

​Campaigns

​Paginate a list

​Error handling

​Covered route missing? Use the escape hatch

​Webhook signature verification

​Runnable examples

Java SDK

Installation

Client initialization

Quickstart: send your first SMS

Messaging

Voice

Verify (OTP)

Contacts

Campaigns

Paginate a list

Error handling

Covered route missing? Use the escape hatch

Webhook signature verification

Runnable examples