API Referencev1

Java SDK

The official Odento Java SDK provides a type-safe interface to the Odento API. Built with OkHttp and Gson. Requires Java 11 or later. Available on Maven Central.

Installation

Maven

Add the dependency to your pom.xml:

Requestxml
<dependency>
    <groupId>app.odento</groupId>
    <artifactId>odento-sdk</artifactId>
    <version>1.0.0</version>
</dependency>

Gradle

Add the dependency to your build.gradle:

Requestgradle
dependencies {
    implementation 'app.odento:odento-sdk:1.0.0'
}

Gradle (Kotlin DSL)

Requestkotlin
dependencies {
    implementation("app.odento:odento-sdk:1.0.0")
}

Initialization

Create a client instance using the builder pattern. Load credentials from environment variables or your preferred configuration source:

Requestjava
import app.odento.sdk.Odento;
import app.odento.sdk.OdentoClient;

Odento client = OdentoClient.builder()
    .keyId(System.getenv("ODENTO_API_KEY_ID"))         // ok_live_...
    .keySecret(System.getenv("ODENTO_API_KEY_SECRET"))  // os_...
    .build();

// With custom options
Odento stagingClient = OdentoClient.builder()
    .keyId(System.getenv("ODENTO_API_KEY_ID"))
    .keySecret(System.getenv("ODENTO_API_KEY_SECRET"))
    .baseUrl("https://staging-api.odento.app")
    .timeout(60, TimeUnit.SECONDS)
    .maxRetries(5)
    .build();

JWT Authentication

For user-facing applications, authenticate with email and password:

Requestjava
import app.odento.sdk.Odento;
import app.odento.sdk.OdentoClient;
import app.odento.sdk.models.AuthResponse;

Odento client = OdentoClient.builder().build();

// Login — SDK stores tokens internally
AuthResponse auth = client.auth().login(AuthRequest.builder()
    .email("dr.sharma@dentalkare.in")
    .password("your-secure-password")
    .build());

System.out.println("Logged in as: " + auth.getUser().getName());

// All subsequent calls use the stored access token
// The SDK automatically refreshes when the token expires

Usage Examples

List Patients

Requestjava
import app.odento.sdk.models.PatientListResponse;

PatientListResponse result = client.patients().list(PatientListRequest.builder()
    .limit(10)
    .status("active")
    .build());

for (Patient patient : result.getItems()) {
    System.out.println(patient.getId() + ": " + patient.getFirstName() + " " + patient.getLastName());
}

System.out.println("Has more: " + result.getPagination().getHasMore());

Create a Patient

Requestjava
import app.odento.sdk.models.Patient;
import app.odento.sdk.models.Address;

Patient patient = client.patients().create(CreatePatientRequest.builder()
    .firstName("Priya")
    .lastName("Sharma")
    .email("priya.sharma@example.com")
    .phone("+919876543210")
    .dateOfBirth("1990-05-15")
    .gender("female")
    .address(Address.builder()
        .street("12 MG Road")
        .city("Bengaluru")
        .state("Karnataka")
        .postalCode("560001")
        .country("India")
        .build())
    .build());

System.out.println("Created patient: " + patient.getId()); // pat_5f8d3a2b1c9e4a7b

Create an Appointment

Requestjava
import app.odento.sdk.models.Appointment;

Appointment appointment = client.appointments().create(CreateAppointmentRequest.builder()
    .patientId("pat_5f8d3a2b1c9e4a7b")
    .dentistId("usr_abc123")
    .startTime("2025-01-22T10:00:00Z")
    .endTime("2025-01-22T11:00:00Z")
    .type("consultation")
    .locationId("loc_xyz789")
    .notes("Routine checkup")
    .build());

System.out.println("Created appointment: " + appointment.getId()); // apt_7a3b9c1d2e5f8a4b

Record a Payment

Requestjava
import app.odento.sdk.models.Payment;

Payment payment = client.billing().invoices()
    .recordPayment("inv_4a7b9c1d2e5f8a3b", RecordPaymentRequest.builder()
        .amount(59000)  // in paise
        .method("upi")
        .reference("UPI-987654321")
        .build());

System.out.println("Payment recorded: " + payment.getId());
System.out.println("Invoice status: " + payment.getInvoiceStatus()); // paid

Error Handling

The SDK throws OdentoException subclasses. Catch specific exception types to handle different error cases:

Requestjava
import app.odento.sdk.exceptions.*;

try {
    Patient patient = client.patients().create(CreatePatientRequest.builder()
        .firstName("Priya")
        // missing required fields...
        .build());
} catch (ValidationException e) {
    System.err.println("Validation failed: " + e.getMessage());
    for (ValidationError detail : e.getDetails()) {
        System.err.println("  " + detail.getField() + ": " + detail.getMessage());
    }
} catch (RateLimitException e) {
    System.err.println("Rate limited. Retry after " + e.getRetryAfter() + "s");
} catch (OdentoException e) {
    System.err.println("API error (" + e.getCode() + "): " + e.getMessage());
}

Configuration Options

OptionTypeDefaultDescription
keyIdString—API key ID (ok_live_*)
keySecretString—API key secret (os_*)
baseUrlStringapi.odento.appBase URL for API requests
timeoutDuration30sRequest timeout
maxRetriesint3Max retries for 5xx and 429 errors
autoRefreshbooleantrueAuto-refresh JWT tokens before expiry

Was this page helpful?

Help us improve our documentation