Which Java version do these examples need?

Java 17 or later. HttpClient has existed since Java 11, but the examples use switch expressions and records, which are standard features in Java 17 and later LTS releases.

Can I use OkHttp or Apache HttpClient instead?

Yes. Any client that sends a POST with a bearer token and a JSON body works. The JDK client is shown because it adds no dependencies beyond the JSON library you likely already use.

How do I make async Finowl calls in Java?

Use HttpClient.sendAsync, which returns a CompletableFuture. Chain thenApply to parse the JSON, and keep concurrency bounded so the account stays within 60 requests per minute.

Where should a Spring Boot app keep the API key?

Supply FINOWL_API_KEY as an environment variable or through your secrets manager, and bind it with @Value or a @ConfigurationProperties class. Do not commit it to application.yml.

Language · Java

Call the Finowl API from Java 17 with HttpClient

Since Java 11 the JDK has shipped java.net.http.HttpClient, a modern client with HTTP/2 support, per-request timeouts and both blocking and async APIs. That makes it a good default for calling Finowl from Spring Boot services, Quarkus apps or plain command-line tools without pulling in a separate HTTP library. The only addition is a JSON library, and the examples here use Jackson because most Java stacks already have it on the classpath.

The client class below holds one HttpClient and one ObjectMapper, both thread-safe and meant to be shared. It reads FINOWL_API_KEY from the environment, sends JSON, and returns a Jackson JsonNode on success. Errors become a FinowlException with the status, the error code and the Retry-After value. The examples use Java 17 features such as switch expressions and records, so they compile on any current LTS release.

Get an API key Read the quickstart

STEP 1

A reusable Java client

Keep your key in the FINOWL_API_KEY environment variable and route every call through one helper, so authentication, timeouts and error handling live in one place.

Install

# java.net.http ships with the JDK; add Jackson for JSON
# Gradle
implementation("com.fasterxml.jackson.core:jackson-databind:2.17.2")
# Maven: groupId com.fasterxml.jackson.core, artifactId jackson-databind, version 2.17.2

Java client

import com.fasterxml.jackson.databind.JsonNode;
import com.fasterxml.jackson.databind.ObjectMapper;
import java.io.IOException;
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.time.Duration;

public final class FinowlClient {
    private static final String BASE_URL = "https://api.finowl.co";
    private final HttpClient http = HttpClient.newBuilder().connectTimeout(Duration.ofSeconds(5)).build();
    private final ObjectMapper mapper = new ObjectMapper();
    private final String apiKey = System.getenv("FINOWL_API_KEY");

    public static final class FinowlException extends RuntimeException {
        public final int status;
        public final String code;
        public final long retryAfterSeconds;

        FinowlException(int status, String code, long retryAfterSeconds) {
            super("Finowl API error " + status + ": " + code);
            this.status = status;
            this.code = code;
            this.retryAfterSeconds = retryAfterSeconds;
        }
    }

    public JsonNode post(String path, Object body) throws IOException, InterruptedException {
        HttpRequest request = HttpRequest.newBuilder(URI.create(BASE_URL + path))
                .timeout(Duration.ofSeconds(10))
                .header("Authorization", "Bearer " + apiKey)
                .header("Content-Type", "application/json")
                .POST(HttpRequest.BodyPublishers.ofString(mapper.writeValueAsString(body)))
                .build();
        HttpResponse<String> response = http.send(request, HttpResponse.BodyHandlers.ofString());
        JsonNode json = response.body().isEmpty() ? mapper.createObjectNode() : mapper.readTree(response.body());
        if (response.statusCode() == 200) {
            return json;
        }
        String code = json.path("error").path("code").asText("unknown_error");
        long retryAfter = response.headers().firstValueAsLong("Retry-After").orElse(0);
        throw new FinowlException(response.statusCode(), code, retryAfter);
    }
}

STEP 2

Call the API you need

Check email breaches in Java with HttpClient
This Java example uses Jackson's tree model, which is a pragmatic way to read the email breach response without defining a class for every field. path() returns a missing node instead of null, so reading Title, BreachDate or DataClasses never throws a NullPointerException. When you are ready to map into domain objects, the same JSON binds cleanly to records with @JsonProperty annotations for the PascalCase keys.
Check breached passwords in Java at registration
A breached password check fits into the registration and password change paths of a Java application, right before you encode the password with BCryptPasswordEncoder or a similar encoder. Finowl receives the plaintext over HTTPS, hashes it with SHA-1, searches by a 5-character prefix with padding, and returns breached and count. The value is processed transiently and never logged, stored or returned.
Predict gender from names in Java 17
The Java gender example maps the prediction into a record, which keeps calling code tidy and makes the nullable fields explicit. Jackson binds the snake_case JSON keys through @JsonProperty, and @JsonIgnoreProperties lets the record model only the fields you care about. Passing a country alongside the name gives Finowl a hint for names like Kim or Andrea, whose usage differs between countries.

A FEW GOOD QUESTIONS

Java questions

Other languages and frameworks

Ship with Java today

100 free credits every month. Try every request in the sandbox first.

Start building View pricing