Java SDK

The official Audian SDK for Java.

Installation

Maven

Add to your pom.xml:

<dependency>
    <groupId>com.audian</groupId>
    <artifactId>audian-sdk</artifactId>
    <version>1.0.0</version>
</dependency>

Gradle

Add to your build.gradle:

dependencies {
    implementation 'com.audian:audian-sdk:1.0.0'
}

Quick Start

import com.audian.AudianClient;
import com.audian.models.SearchNumbersRequest;
import com.audian.models.SearchNumbersResponse;

public class Main {
    public static void main(String[] args) throws Exception {
        AudianClient client = new AudianClient("YOUR_API_KEY");

        // Search for phone numbers
        SearchNumbersResponse numbers = client.numbers.search(
            new SearchNumbersRequest()
                .setLocation("US-CA-415")
                .setLimit(10)
        );

        System.out.println("Found " + numbers.getData().getNumbers().size() + " numbers");
    }
}

Configuration

Initialize Client

import com.audian.AudianClient;
import java.time.Duration;

AudianClient client = new AudianClient.Builder()
    .apiKey("sk_live_...")
    .baseURL("https://api.audian.com:8443/v2") // Optional
    .timeout(Duration.ofSeconds(30)) // Optional
    .maxRetries(3) // Optional
    .backoffFactor(2) // Optional
    .build();

Environment Variables

export AUDIAN_API_KEY='sk_live_...'

AudianClient client = new AudianClient(System.getenv("AUDIAN_API_KEY"));

Phone Numbers API

Search Numbers

import com.audian.models.SearchNumbersRequest;

SearchNumbersResponse response = client.numbers.search(
    new SearchNumbersRequest()
        .setLocation("US-CA-415")
        .setPattern("415*")
        .setFeatures(Arrays.asList("sms", "mms"))
        .setLimit(20)
        .setOffset(0)
);

response.getData().getNumbers().forEach(number ->
    System.out.println("Number: " + number.getNumber())
);

List Your Numbers

import com.audian.models.ListNumbersRequest;

ListNumbersResponse response = client.numbers.list(
    new ListNumbersRequest()
        .setLimit(20)
        .setOffset(0)
        .setStatus("active")
);

response.getData().getNumbers().forEach(number ->
    System.out.println("Number: " + number.getNumber())
);

Get Number Details

import com.audian.models.Number;

Number number = client.numbers.get("num_abc123");
System.out.println("Number: " + number.getNumber());

Purchase a Number

import com.audian.models.PurchaseNumberRequest;

PurchaseNumberResponse purchased = client.numbers.purchase(
    new PurchaseNumberRequest()
        .setNumber("+14155551234")
        .setFriendlyName("Support Line")
);

System.out.println("Purchased: " + purchased.getData().getNumber());

Update Number Configuration

import com.audian.models.*;

UpdateNumberConfigRequest config = new UpdateNumberConfigRequest()
    .setFriendlyName("Support Line")
    .setCallForwarding(
        new CallForwarding()
            .setEnabled(true)
            .setForwardTo("+14155559999")
            .setRingsBeforeForward(4)
    )
    .setVoicemail(
        new Voicemail()
            .setEnabled(true)
            .setTranscription(true)
    );

UpdateNumberConfigResponse updated = client.numbers.updateConfig("num_abc123", config);

Set Caller ID

import com.audian.models.SetCallerIdRequest;

SetCallerIdResponse callerId = client.numbers.setCallerId(
    "num_abc123",
    new SetCallerIdRequest()
        .setCallerIdNumber("+14155551234")
        .setCallerIdName("Support")
);

Configure E911

import com.audian.models.SetE911Request;

SetE911Response e911 = client.numbers.setE911(
    "num_abc123",
    new SetE911Request()
        .setAddressLine1("123 Main Street")
        .setAddressLine2("Suite 100")
        .setCity("San Francisco")
        .setState("CA")
        .setPostalCode("94102")
        .setCountry("US")
        .setCustomerName("Acme Corp")
);

SMS API

Send SMS

import com.audian.models.SendSMSRequest;

SendSMSResponse response = client.sms.send(
    new SendSMSRequest()
        .setTo("+14155551234")
        .setFrom("+14155559999")
        .setMessage("Hello, World!")
);

System.out.println("SMS ID: " + response.getData().getId());

Send Batch SMS

import com.audian.models.*;

SendBatchSMSResponse response = client.sms.sendBatch(
    new SendBatchSMSRequest()
        .setMessages(Arrays.asList(
            new SMSMessage().setTo("+14155551234").setMessage("Hello 1"),
            new SMSMessage().setTo("+14155551235").setMessage("Hello 2"),
            new SMSMessage().setTo("+14155551236").setMessage("Hello 3")
        ))
);

Get SMS Details

import com.audian.models.SMS;

SMS sms = client.sms.get("sms_abc123");
System.out.println("Status: " + sms.getStatus());

List SMS Messages

import com.audian.models.ListSMSRequest;

ListSMSResponse messages = client.sms.list(
    new ListSMSRequest()
        .setLimit(20)
        .setOffset(0)
        .setStatus("delivered")
);

Voice API

Make a Call

import com.audian.models.MakeCallRequest;

MakeCallResponse call = client.voice.makeCall(
    new MakeCallRequest()
        .setTo("+14155551234")
        .setFrom("+14155559999")
        .setAction("connect")
        .setConnectTo("+14155559999")
);

System.out.println("Call ID: " + call.getData().getId());

Get Call Details

import com.audian.models.Call;

Call callDetails = client.voice.getCall("call_abc123");
System.out.println("Status: " + callDetails.getStatus());

List Calls

import com.audian.models.ListCallsRequest;

ListCallsResponse calls = client.voice.listCalls(
    new ListCallsRequest()
        .setLimit(20)
        .setStatus("completed")
);

Billing API

Get Usage

import com.audian.models.Usage;

Usage usage = client.billing.usage.get();

System.out.println("SMS Cost: " + usage.getUsage().getSmsMessages().getCost());
System.out.println("Voice Cost: " + usage.getUsage().getVoiceMinutes().getCost());

Get Usage Breakdown

import com.audian.models.UsageBreakdownRequest;

UsageBreakdownResponse breakdown = client.billing.usage.getBreakdown(
    new UsageBreakdownRequest()
        .setMetric("sms")
        .setGranularity("day")
);

List Invoices

import com.audian.models.ListInvoicesRequest;

ListInvoicesResponse invoices = client.billing.invoices.list(
    new ListInvoicesRequest()
        .setStatus("paid")
        .setLimit(20)
);

Get Invoice

import com.audian.models.Invoice;

Invoice invoice = client.billing.invoices.get("inv_abc123");
System.out.println("Total: " + invoice.getTotal());

Download Invoice PDF

import java.nio.file.Files;
import java.nio.file.Paths;

byte[] pdf = client.billing.invoices.getPdf("inv_abc123");
Files.write(Paths.get("invoice.pdf"), pdf);

Error Handling

import com.audian.exception.AudianException;

try {
    client.numbers.purchase(
        new PurchaseNumberRequest()
            .setNumber("+14155551234")
    );
} catch (AudianException e) {
    System.out.println("Error: " + e.getMessage());
    System.out.println("Code: " + e.getCode());
    System.out.println("HTTP Status: " + e.getHttpStatus());
}

Rate Limiting

The SDK automatically handles rate limiting with exponential backoff:

// Automatically retries with exponential backoff
SearchNumbersResponse numbers = client.numbers.search(
    new SearchNumbersRequest()
        .setLocation("US-CA-415")
);

Custom Retry Configuration

AudianClient client = new AudianClient.Builder()
    .apiKey("YOUR_API_KEY")
    .maxRetries(5)
    .backoffFactor(2)
    .initialRetryDelay(100) // milliseconds
    .build();

Monitor Rate Limit Headers

ListNumbersResponse response = client.numbers.list(null);

String limit = response.getHeaders().get("ratelimit-limit");
String remaining = response.getHeaders().get("ratelimit-remaining");
String reset = response.getHeaders().get("ratelimit-reset");

System.out.println("Limit: " + limit + ", Remaining: " + remaining + ", Reset: " + reset);

Webhooks

Verify Webhook Signature

import com.audian.webhooks.WebhookVerifier;
import com.audian.models.Event;

WebhookVerifier verifier = new WebhookVerifier("whsec_...");

@PostMapping("/webhook")
public ResponseEntity<?> handleWebhook(
    @RequestBody String payload,
    @RequestHeader("X-Audian-Signature") String signature
) {
    try {
        Event event = verifier.verify(payload, signature);
        System.out.println("Event type: " + event.getType());
        return ResponseEntity.ok().body(new HashMap<String, Boolean>() {{
            put("success", true);
        }});
    } catch (Exception e) {
        return ResponseEntity.status(401).body(new HashMap<String, String>() {{
            put("error", "Unauthorized");
        }});
    }
}

Handle Webhook Events

switch (event.getType()) {
    case "sms.received":
        SMSReceivedEvent smsEvent = (SMSReceivedEvent) event.getData();
        System.out.println("SMS from: " + smsEvent.getFrom());
        System.out.println("Message: " + smsEvent.getMessage());
        break;

    case "call.completed":
        CallCompletedEvent callEvent = (CallCompletedEvent) event.getData();
        System.out.println("Call duration: " + callEvent.getDuration() + "s");
        break;

    case "number.ported":
        NumberPortedEvent portEvent = (NumberPortedEvent) event.getData();
        System.out.println("Number " + portEvent.getNumber() + " ported successfully");
        break;
}

Complete Example

import com.audian.AudianClient;
import com.audian.models.*;
import java.util.List;

public class AudianExample {
    public static void main(String[] args) throws Exception {
        AudianClient client = new AudianClient(System.getenv("AUDIAN_API_KEY"));

        // Search for available numbers
        SearchNumbersResponse available = client.numbers.search(
            new SearchNumbersRequest()
                .setLocation("US-CA-415")
                .setLimit(5)
        );

        List<SearchResult> numbers = available.getData().getNumbers();
        System.out.println("Found " + numbers.size() + " numbers");

        // Purchase the first number
        if (!numbers.isEmpty()) {
            String number = numbers.get(0).getNumber();

            PurchaseNumberResponse purchased = client.numbers.purchase(
                new PurchaseNumberRequest()
                    .setNumber(number)
                    .setFriendlyName("Demo Number")
            );

            System.out.println("Purchased: " + purchased.getData().getNumber());

            // Send SMS from the number
            SendSMSResponse sms = client.sms.send(
                new SendSMSRequest()
                    .setFrom(purchased.getData().getNumber())
                    .setTo("+14155559999")
                    .setMessage("Hello from Audian!")
            );

            System.out.println("SMS sent: " + sms.getData().getId());
        }
    }
}

Support

• GitHub Repository
• Maven Central
• Issues and Bug Reports

Version History

See changelog