This guide describes how to use Nightfall with the Java programming language.

The example below will demonstrate how to use Nightfall’s text scanning functionality to verify whether a string contains sensitive PII using the Nightfall Java SDK.

In this tutorial, we will be downloading, setting up, and using the Java SDK provided by Nightfall.

To make a request to the Nightfall API you will need:

  • A Nightfall API key

  • Plaintext data to scan.

You can read more about obtaining a Nightfall API key or about our available (data detectors)[docs:detector-glossary] in the linked reference guides.

You can add the Nightfall package to your project by adding a dependency to your pom.xml:


<?xml version="1.0" encoding="UTF-8"?>
 <project xmlns=""




First add the required imports to the top of the file.

These are the objects we will use from the Nightfall SDK, as well as some collection classes for data handling.

//List of imports

import ai.nightfall.scan.NightfallClient;
 import ai.nightfall.scan.model.Confidence;
 import ai.nightfall.scan.model.DetectionRule;
 import ai.nightfall.scan.model.Detector;
 import ai.nightfall.scan.model.LogicalOp;
 import ai.nightfall.scan.model.NightfallAPIException;
 import ai.nightfall.scan.model.ScanTextConfig;
 import ai.nightfall.scan.model.ScanTextRequest;
 import ai.nightfall.scan.model.ScanTextResponse;

 import java.util.Arrays;
 import java.util.List;

We can then declare some data to scan in a List:

//Sample Payload

List<String> payload = Arrays.asList(
  "my data is 4242-4242-4242-4242 but shhhh 🙊 ", 
  "my ssn is 678-99-8212"

Create a ScanTextRequest to scan the payload with. First create a new instance of the credit card detector, and set to trigger if there are any findings that are confidence LIKELY or above.

Add a second detector, looking for social security numbers. Set it to be triggered if there is at least a possible finding.

Combine these detectors into a detection rule, which will return findings if either of these detectors are triggered.

Finally, combine the payload and configuration together as a new ScanTextRequest, and return it.

//Build the Scan Request

public static ScanTextRequest buildScanTextRequest() {
  	// Define some detectors to use to scan your data
  	Detector creditCard = new Detector("CREDIT_CARD_NUMBER");

    Detector ssn = new Detector("US_SOCIAL_SECURITY_NUMBER");
    DetectionRule rule = new DetectionRule(Arrays.asList(creditCard, ssn), LogicalOp.ANY);
    ScanTextConfig config = ScanTextConfig.fromDetectionRules(Arrays.asList(rule), 20);

    return new ScanTextRequest(payload, config);

Use the ScanTextRequest instance with a NightfallClient to send your request to Nightfall.

The resulting ScanTextResponse may be used to print out the results:

//Run the Scan Request

public class Runner {
     public static void main(String[] args) {
         try (NightfallClient c = NightfallClient.Builder.defaultClient()) {
             try {
                 ScanTextResponse response = c.scanText(buildScanTextRequest());
                 System.out.println("response: " + response.getFindings());
             } catch (NightfallAPIException e) {
                 // not a checked exception, just for illustrative purposes
                 System.out.println("got error: " + e);

And that's it 🎉

You are now ready to use the Java SDK for other scenarios.