> For the complete documentation index, see [llms.txt](https://help.nightfall.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://help.nightfall.ai/developer-api/nightfall-use-cases/scan_api.md).

# Using Scan API (with Python)

Say you have a number of files containing customer or patient data and you are not sure which of them are ok to share in a less secure manner. By leveraging Nightfall’s API you can easily verify whether a file contains sensitive PII, PHI, or PCI.

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

* A Nightfall API key
* A list of data types you wish to scan for
* Data to scan. Note that the API interprets data as plaintext, so you may pass it in any structured or unstructured format.

You can read more about [obtaining a Nightfall API key](https://help.nightfall.ai/firewall-for-ai/key-concepts/setting-up-nightfall/creating-api-key) or about our [available data detectors](https://help.nightfall.ai/sensitive-data-protection/detection-engine/nightfall-detector-glossary) in the linked reference guides.

To run the following API call, we will be using Python's standard json, os, and requests libraries.

```python
import json
import os
import requests
```

First we define the endpoint we want to reach with our API call.

```
endpoint = 'https://api.nightfall.ai/v1/scan'
```

Next we define the headers of our API request. In this example, we have our API key set via an environment variable called "NIGHTFALL\_API\_KEY". Your API key should **never** be hard-coded directly into your script.

```
h = {
    'Content-Type': 'application/json',
    'x-api-key': os.getenv('NIGHTFALL_API_KEY')
}
```

Next we define the detectors with which we wish to scan our data. The detectors must be formatted as a list of key-value pairs of format {‘name’:’DETECTOR\_NAME’}.<br>

{% tabs %}
{% tab title="Detectors" %}

```
detector_list = ['US_SOCIAL_SECURITY_NUMBER', 'ICD9_CODE', 'US_DRIVERS_LICENSE_NUMBER']

detector_object = [{'name':detector} for detector in detector_list]
```

{% endtab %}

{% tab title="Example Detectors Object" %}

```
[{'name':'US_SOCIAL_SECURITY_NUMBER'}, 
 {'name':'ICD9_CODE'}, 
 {'name':'US_DRIVERS_LICENSE_NUMBER'}]
```

{% endtab %}
{% endtabs %}

Next, we build the request body, which contains the detectors from above, as well as the raw data that you wish to scan. In this example, we will read it from a file called sample\_data.csv.

Here we assume that the file is under the 500 KB payload limit of the Scan API. If your file is larger than the limit, consider breaking it down into smaller pieces across multiple API requests.

{% tabs %}
{% tab title="Data" %}

```python
with open('sample_data.csv', 'r') as f:
  raw_data = f.read()

d = {
    'detectors': detector_object,
    'payload':{'items':[raw_data]}
}
```

{% endtab %}

{% tab title="file-size check" %}

```
import os

if os.stat('sample_data.csv').st_size < 500000:
  print('This file will fit in a single API call.')
else:
  print('This file will need to be broken into pieces across multiple calls.')
```

{% endtab %}
{% endtabs %}

Now we are ready to call the Nightfall API to check if there is any sensitive data in our file. If there are no sensitive findings in our file, the response will be *"\[\[]]"*.

{% tabs %}
{% tab title="Request" %}

```python
response = requests.post(endpoint, headers = h, data = json.dumps(d))

if (response.status_code == 200) & (len(response.content.decode()) > 4):
  print('This file contains sensitive data.')
  print(json.loads(response.content.decode()))
elif response.status_code == 200:
  print('No sensitive data detected. Hooray!')
else:
  print(f'Something went wrong -- Response {response.status_code}.')
```

{% endtab %}

{% tab title="Empty Response" %}
\[\[]]

{% endtab %}

{% tab title="Positive Response" %}

```python
[
  [
  {'fragment': '172-32-1176',
   'detector': 'US_SOCIAL_SECURITY_NUMBER',
   'confidence': {'bucket': 'LIKELY'},
   'location': {'byteRange': {'start': 122, 'end': 133},
    'unicodeRange': {'start': 122, 'end': 133}}},
  {'fragment': '514-14-8905',
   'detector': 'US_SOCIAL_SECURITY_NUMBER',
   'confidence': {'bucket': 'LIKELY'},
   'location': {'byteRange': {'start': 269, 'end': 280},
    'unicodeRange': {'start': 269, 'end': 280}}},
  {'fragment': '213-46-8915',
   'detector': 'US_SOCIAL_SECURITY_NUMBER',
   'confidence': {'bucket': 'LIKELY'},
   'location': {'byteRange': {'start': 418, 'end': 429},
    'unicodeRange': {'start': 418, 'end': 429}}}
  ]
 ]
```

{% endtab %}
{% endtabs %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://help.nightfall.ai/developer-api/nightfall-use-cases/scan_api.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.