Scan Profiles API Tutorial
- How to create a new scan profile using the Scan Profiles API.
- How to specify only the data sources you want to scan.
- How to configure the scan as a one-time or scheduled job.
- How to verify the scan profile was created successfully.
In this tutorial, we'll use SAMPLE as our session token. This is unique to the training sandbox and will not work in other environments. See BigID API/Tutorial for information on authenticating with BigID.
To view the complete code for all steps, see the section labelled Code Samples.
For more information on the API capabilities used in this tutorial, check out the Scan Profiles API Docs or the Data Sources API Docs.
1. Authenticate Using Your API Key
All API requests require authentication using a valid API key. Refer to BigID Documentation to obtain your token. Then, define the Authorization header using the format `Authorization: Bearer YOUR_API_KEY`. This header must be included in every request to ensure proper authentication and access to BigID’s API endpoints. Throughout the tutorial, we will be using SAMPLE as our token.
2. Gather Data Source IDs
Before creating your scan profile, you need to gather the unique IDs of the data sources you want to include in your scan. If you have not obtained them already, whether by browsing the BigID UI or using the API, this step ensures you have the correct identifiers to specify exactly which sources to scan.
You can retrieve this information using the GET /api/v1/ds-connections endpoint. This API returns the details of one or more data sources in your BigID environment.
Depending on which data sources you're interested in, this endpoint supports several optional query parameters to help you narrow down and customize the results:
- skip (integer): Number of data sources to skip for pagination.
- limit (integer): Maximum number of data sources to return.
- requireTotalCount (boolean): If true, returns the total count of matching data sources.
- sort (string): Sort results by a specified field and order.
- filter (string): Filter results based on field values.
The response provides common fields for each data source. From this, you can compile the _id values for all the data sources you want to include in your scan profile. These IDs will be used in the dataSourceList field when creating the scan profile in the next step.
3. Create a Scan Profile
Once you have a list of all the data sources you’d like to include in the scan, you can proceed to create a new scan profile using the Scan Profiles API. This profile defines what you want to scan, when you want to scan it, and how it should behave.
Use the POST /api/v1/scanProfiles endpoint to define the profile details, including:
- A name and optional description
- A list of dataSourceList IDs (targeted sources only)
- A valid scanTemplateId
- A schedule for recurring scans or isSingleRunScan: true for a one-time run
For example, to establish a scan profile named "Targeted Marketing Data Scan" that runs a one-time scan on two specific data sources (e.g., marketing-related databases), you can use the following request:
{ "name": "Targeted Marketing Data Scan", "description": "Scans only marketing-related sources for compliance", "dataSourceList": [ "64f7df00cc834f0001a44e85", "64f7df00cc834f0001a44e86" ], "scanTemplateId": "standard-privacy-template-001", "isSingleRunScan": true }
Once submitted, BigID will create the scan profile and queue the scan based on the schedule you've defined (or start it right away for a one-time scan). Upon success, the API response will return the newly created scan profile, including its unique ID. Be sure to save this ID, as you’ll need it in the next step to verify and manage the scan profile.
4. Verify Scan Profile Creation
After creating your scan profile, you’ll want to double-check that BigID received and saved it correctly. Using the id returned in the previous step, you can retrieve the scan profile directly to confirm its details and status.
Use the GET /api/v1/scanProfiles/{id} endpoint, replacing {id} with your unique scan profile id returned from the creation step, to retrieve and verify the details of your scan profile.
At this step, you’re primarily confirming a successful API response and that the scan profile exists with the expected ID. If the request returns a valid profile object (status code 200), you know your scan profile was created correctly and is ready to rock!
5. Troubleshooting
If your request fails, here’s what the server might tell you, and how to fix it:
| Status Code | Example Response | What It Means | How to Fix It |
|---|---|---|---|
| 200 | Successful response with scan data | Everything’s looking good! | Keep cruising. |
| 400 | { "error": "Scan ID is invalid" } |
Bad or malformed scan ID provided | Double-check the scan ID you’re using. |
| 404 | { "error": "Scan 1234 was not found" } |
Scan ID doesn’t exist | Make sure the ID is valid and fetched from the parent scans endpoint. |
| 401 | Unauthorized | API key missing or invalid | Verify your API key and authorization header. |
| 500 | { "status": "error", "message": "Server error", "errors": [{}] } |
BigID server hit a snag (internal error) | Wait a moment and retry. If it persists, reach out to support. |
Code Samples
# Scan Profiles API Tutorial in progress
// Scan Profiles API Tutorial in progress
Summary
Congratulations! In this tutorial, you have learned how to create a targeted scan profile in BigID by specifying the exact data sources you want to include. You’ve mastered how to submit a scan profile via the API, retrieve its unique ID, and verify that the profile was successfully created and saved.
Now that you’ve set up and verified your scan profile, you can take it further by monitoring or managing scan execution using the Scan Insights API.