Using Pre-Configured Detection Rules

In this example, we'll walk through making a request to the scan endpoint, which inspects the data you provide via the request body and reports any detected occurrences of the sensitive data types you are searching for.

Please refer to the API reference of the scan endpoint for more detailed information on the request and response schemas.

In this sample request, we provide two main fields:

  1. a Detection Rule that we want to use when scanning the text payload
  2. a list of text strings to scan

In this case we will use a pre-configured Detection Rule by supplying its UUID.

The aggregate length of all strings in that list must not exceed 500 KB, and the number of items in the payload may not exceed 50,000.

curl --request POST \
     --url https://api.nightfall.ai/v3/scan \
     --header 'Accept: application/json' \
     --header 'Authorization: Bearer NF-rEpLaCeM3w1ThYoUrNiGhTfAlLKeY123' \
     --header 'Content-Type: application/json' \
     --data '
{
     "policy": {
          "detectionRuleUUIDs": [
               "950833c9-8608-4c66-8a3a-0734eac11157"
          ]
     },
     "payload": [
          "4916-6734-7572-5015 is my credit card number",
          "This string does not have any sensitive data",
          "my api key is yr+ZWwIZp6ifFgaHV8410b2BxbRt5QiAj1EZx1qj and my 💳 credit card number 💰 is 30204861594838"
     ]
}
'

Executing this curl request will yield a response as follows.

{
    "findings": [
        [
            {
                "finding": "4916-6734-7572-5015",
                "detector": {
                    "name": "Credit card number",
                    "uuid": "74c1815e-c0c3-4df5-8b1e-6cf98864a454"
                },
                "confidence": "VERY_LIKELY",
                "location": {
                    "byteRange": {
                        "start": 0,
                        "end": 19
                    },
                    "codepointRange": {
                        "start": 0,
                        "end": 19
                    }
                },
                "matchedDetectionRuleUUIDs": [
                    "950833c9-8608-4c66-8a3a-0734eac11157"
                ],
                "matchedDetectionRules": []
            }
        ],
        [],
        [
            {
                "finding": "30204861594838",
                "detector": {
                    "name": "Phone number",
                    "uuid": "d08edfc4-b5e2-420a-a5fe-3693fb6276c4"
                },
                "confidence": "LIKELY",
                "location": {
                    "byteRange": {
                        "start": 94,
                        "end": 108
                    },
                    "codepointRange": {
                        "start": 88,
                        "end": 102
                    }
                },
                "matchedDetectionRuleUUIDs": [
                    "950833c9-8608-4c66-8a3a-0734eac11157"
                ],
                "matchedDetectionRules": []
            },
            {
                "finding": "30204861594838",
                "detector": {
                    "name": "Credit card number",
                    "uuid": "74c1815e-c0c3-4df5-8b1e-6cf98864a454"
                },
                "confidence": "LIKELY",
                "location": {
                    "byteRange": {
                        "start": 94,
                        "end": 108
                    },
                    "codepointRange": {
                        "start": 88,
                        "end": 102
                    }
                },
                "matchedDetectionRuleUUIDs": [
                    "950833c9-8608-4c66-8a3a-0734eac11157"
                ],
                "matchedDetectionRules": []
            }
        ]
    ]
}
 
      "location": {
        "byteRange": {
          "start": 94,
          "end": 108
        },
        "codepointRange": {
          "start": 88,
          "end": 102
        }
      },
      "matchedDetectionRuleUUIDs": [
        "950833c9-8608-4c66-8a3a-0734eac11157"
      ],
      "matchedDetectionRules": []
    },
    {
      "finding": "30204861594838",
      "detector": {
        "name": "Credit card number",
        "uuid": "74c1815e-c0c3-4df5-8b1e-6cf98864a454"
      },
      "confidence": "LIKELY",
      "location": {
        "byteRange": {
          "start": 94,
          "end": 108
        },
        "codepointRange": {
          "start": 88,
          "end": 102
        }
      },
      "matchedDetectionRuleUUIDs": [
        "950833c9-8608-4c66-8a3a-0734eac11157"
      ],
      "matchedDetectionRules": []
    }
  ]
]

The API call returns a list, where the item at each index is a sublist of matches for the provided detector types.

The indices of the response list correspond directly to the indices of the list provided in the request payload.

In this example, the first item in the response list contains a finding because one credit card number was detected in the first string we provided. The second item in the response list is an empty list because there is no sensitive data in the second input string we provided. The third item in the returned list contains multiple findings as a result of multiple Detectors within the Detection Rule being triggered.

You can read further about the fields in the response object in the API Reference.