Looking for the FullContact Address Book App? You can now find it at Contacts+

Learn More
FullContact API for Java Library

Introducing Version 2.0 of FullContact for Java

We are excited to announce that we’ve released a new major version of our Java library for interacting with the FullContact suite of public API’s. We think you’ll like the changes.

FullContact4j 2.0 is designed from the ground up to be as painless to use as possible. FullContact clients are customizable and require just one line of code to set up; requests take only one line to create and one to execute. FullContact4j abstracts away all the headaches associated with HTTP communication with the API, ranging from managing possible response scenarios to keeping your requests below your account’s rate limit (queries per second). Make a request object, execute it, and get a response object back. Read on, or check out the code on GitHub.

Interacting with the Library

Firstly, read the API documentation! FullContact4j provides an object layer to FullContact API communication, but understanding webhooks, response flows, request parameters, and common snags is still important.

Once you’re on board with the API behavior, using FullContact4j is easy. Look up social and demographic data for an email address in just 3 lines of code:

FullContact fullContact = FullContact.withApiKey("your-api-key").build();
PersonRequest personRequest = fullContact.buildPersonRequest().email("bart@fullcontact.com").build();
PersonResponse personResponse = fullContact.sendRequest(personRequest);

(Don’t have an API key? You can pick one up for free right here.)

Behind the scenes, FullContact4j has done a lot for you:

  • authenticated with FullContact
  • accounted for rate limiting, sending the request if you are below your rate limit (or waiting to send your request until the time is right if you have exceeded your account limit).
  • checked for errors and parsed useful messages/data
  • turned the response JSON into a perfectly normal Java object.
  • If you prefer asynchronous calls, that requires only one change:
fullContact.sendRequest(personRequest, new FCCallback() {
    public void success(PersonResponse response) {
        System.out.println("got a response back!");

    public void failure(FullContactException exception) {
        System.out.println("got an error :( ");

Making Requests

First, let’s get our request builder.


All API requests can be made by calling their corresponding build____Request() method. Then, add relevant parameters and build:


It’s generally good practice to specify webhooks in your request, in case of a 202 response from Person API or a Card Reader upload for instance. That’s all configurable as well:


If the webhook URL is specified, all Person API responses will by default return a 202 response code (see webhooks documentation for more detail). If you need to test webhooks before implementing them in your own technology, you can always use something like requestb.in.

If you clearly mis-configured your request (adding two search parameters to Person API, or not giving a name to the name deducer API, etc), build() will throw an IllegalArgumentException with a message about what you did wrong:

java.lang.IllegalArgumentException: Request must specify exactly one: email or username
at com.fullcontact.api.libs.fullcontact4j.http.name.NameDeduceRequest$Builder.validate(NameDeduceRequest.java:51)

Now let’s send our request. Since FullContact4j uses a thread pool to execute requests, multiple consumers should be fine to make thread-safe requests from the same client instance. This can be done synchronously or asynchronously.

Synchronously is a little easier:

PersonRequest request = fullContact.buildPersonRequest().email(“bart@fullcontact.com”).build();
PersonResponse response = fullContact.sendRequest(request);

Every request has a corresponding response that it will return when sendRequest is called. This object contains all response data back from FullContact.

Asynchronous requests are similar. sendRequest() just takes one more parameter — a FCCallback. It has a generic type parameter of the response type (PersonRequest corresponds to PersonResponse, LocationNormalizationRequest to LocationNormalizationResponse, etc). success() is called when a useful response is returned from the APIs:

fullContact.sendRequest(locationEnrichmentRequest, new FCCallback() {
    public void success(LocationEnrichmentResponse response) {
        System.out.println("got a response back!");
    public void failure(FullContactException exception) {
        System.out.println("got an error :( ");

Error Handling

If an error is encountered (these correspond to yellow/red non-2xx response codes on the API flow diagrams), a FullContactException is created with useful information about the error, including errorCode and a message from the FullContact APIs about the nature of the error. For synchronous requests, this will cause sendRequest() to throw a FullContactException. In asynchronous requests, FCCallback.failure(FullContactException exception) is called instead.

Supported APIs

FullContact4j supports all Person, Email, Name, Location, Card Reader, and Account Statistics endpoints. These can all be accessed from their respective build_____Request() methods in the FullContact client. Some will need required parameters (like CardReaderRequest’s requirement for a front image InputStream) and automatically create a builder with those required parameters set.

Advanced Configuration

In the background, FullContact4j is making requests using an OkHttpClient. You can supply your own OkHttpClient.

OkHttpClient client = new OkHttpClient();
client.setReadTimeout(3000, TimeUnit.MILLISECONDS);
FullContact fcClient = FullContact.withApiKey("your-api-key").httpClient(client).build();

The user agent and request executor thread count are also configurable. The client will rate limit the amount of requests sent based on the rate limit for your plan. It will hold a request queue and execute at the maximum every 1/ratelimit seconds with some leeway if you haven’t sent requests in a certain period of time. This does not make you immune from Rate Limit exceptions if multiple clients (you should only ever need one, even with multiple consumers) with the same api key are being used or that rate limit is being used too heavily. Likewise, overages are still possible. Make sure to check your account stats periodically to avoid overages.

Release / GitHub

FullContact4j is available, open-source, at GitHub. Head there to read documentation, check out the shiny new source code, and find out what you need to get this client in your project.

We look forward to seeing what you build with it!

Quickly build contact management features into your app.

Get Started for FreeNo Credit Card Required

Recent Posts