/onfido-java

Java library for the Onfido API

Primary LanguageJavaMIT LicenseMIT

Onfido Java Library

The official Java library for integrating with the Onfido API. Refer to the full API documentation for details of expected requests and responses for all resources.

This version uses Onfido API v3.5. Refer to our API versioning guide for details of which client library versions use which versions of the API.

Installation

For Maven projects, add the below to your pom file:

<dependency>
      <groupId>com.onfido</groupId>
      <artifactId>onfido-api-java</artifactId>
      <version>LATEST_VERSION_HERE</version>
</dependency>

For Gradle projects add the below to your build.gradle file:

implementation 'com.onfido:onfido-api-java:LATEST_VERSION_HERE'

The latest version can be found at: https://search.maven.org/artifact/com.onfido/onfido-api-java

Getting Started

Import the Onfido object, this is the main object used for interfacing with the API:

import com.onfido.Onfido;

import com.onfido.exceptions.ApiException;
import com.onfido.exceptions.OnfidoException;

Instantiate and configure an Onfido instance with your API token, and region if necessary:

Onfido onfido = Onfido.builder()
                .apiToken(System.getenv("ONFIDO_API_TOKEN"))
                // Supports .regionEU, .regionUS() and .regionCA()
                .build();

Making a call to the API

Using your configured and instantiated instance of the Onfido object you can make calls to the API by calling one of the methods on the resources inside of it. For example, to create an applicant:

import com.onfido.models.Applicant;

onfido.applicant.create(<REQUEST_BODY_HERE>);

All request bodies can be created using a builder pattern on the Request subclass of the desired resource. For example in the request above an Applicant.Request object is needed as the body, this would look something like:

Applicant.request().firstName("First").lastName("Last");

The above will return an Applicant.Request object that can be provided to the create() method as the request body, so a full call to to the API will look something like:

try {
    Applicant newApplicant = onfido.applicant.create(
            Applicant.request().firstName("First").lastName("Last")
    );
} catch (ApiException e) {
    // An error response was received from the Onfido API, extra info is available.
    System.out.println(e.getMessage());
    System.out.println(e.getType());
    System.out.println(e.isClientError());
} catch (OnfidoException e) {
    // No response was received for some reason e.g. a network error.
    System.out.println(e.getMessage());
}

The above method will return the corresponding resource object, as most methods will. In this particular case an Applicant object will return with all information present for the newly created applicant. To access the information call the getter of the desired property on the object, for example:

newApplicant.getFirstName();

Contributing

  1. Fork it (https://github.com/onfido/onfido-java/fork)
  2. Create your feature branch (git checkout -b my-new-feature)
  3. Make your changes, see below sections for project setup and testing.
  4. Before you commit your changes, run google-java-format for the whole project. See the README in the linked repository for install and running instructions.
  5. Commit your changes (git commit -am 'Add some feature')
  6. Push to the branch (git push origin my-new-feature)
  7. Create a new Pull Request

Project Setup

  1. Install JDK 1.8 or above, details for which can be found below:
  2. Install Apache Maven, details for which can be found below:
  3. Inside of the top level directory of the project run the following command: 
    mvn clean install
    This will install all necessary dependencies and build the model classes used by the project.

Testing

  1. Run mvn test to run all existing automated tests.
  2. View tests in onfido-java/src/test/java/com/onfido for examples of writing tests of your own.

More Documentation

More documentation and code examples can be found at https://documentation.onfido.com