BigID API/DSAR Tutorial

In this article, you'll learn:

Find a DSAR profile using the BigID API
Search for individuals using attributes using the BigID API
Run a DSAR scan using the BigID API
Get a DSAR report using the BigID API

scenarioYou already have your own account management portal that also manages other tasks for your business. You already have BigID for your security and data governance teams and they've mentioned that it can perform DSARs too. Run the DSAR calls required to integrate your management portal with BigID's DSAR capabilities

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.

Getting DSAR Profiles[edit]

BigID uses DSAR profiles to specify what data sources we should use to look for user data. You can create these using the APIs, but creating them via the UI is preferred since the UI will provide suggestions as you work. In our case, we already have a few data sources within our system.

From this API call we can see a list of DSAR profiles. This also gives us insight into why organizations use DASR profiles. Different groups of systems can have users with the same unique ID (employee number 1 and customer number 1 are probably different people). Profiles allow us to segment those user groups. Below we see a different profile for US customers to illustrate that.

{
  "profiles": [
    {
      "_id": "5d93e8431810782ce9173ae0",
      "name": "Default Profile",
      "allEnabledEs": true,
      "allEnabledDs": true,
      "scopes": [
        "root"
      ],
      "isCustom": false
    },
    {
      "_id": "614d7794dfa3fdf8bd71cacb",
      "allEnabledDs": true,
      "allEnabledEs": false,
      "name": "ALL PI for US Customer",
      "scopes": [
        "root"
      ],
      "shouldAttributesEnrichment": true,
      "isCustom": true
    }
  ]
}

In our case, we know a user with the email [email protected] is present in the default profile. However, we need to figure out what attributes we can use to execute a DSAR with this profile so we get the names correct.

We can see that there's an idsor_attribute named Email that has an identifiability of 1. This means that 100% of the sampled users have a different Email which is perfect for our DSAR. Let's initiate a DSAR on this user using that Email attribute.

Initiating a DSAR[edit]

Because the amount of data scanned as part of a DSAR can be well into the petabytes, the DSAR API is asynchronous. The below request will start a DSAR and return immediately with an ID you can use to track its progress. Execute the below request to start your DSAR.

Checking DSAR Status[edit]

Let's check the status of your DSAR. Replace REQUESTID in the URL of the below request with the requestId you received above when you initiated the DSAR.

When checking the status, we can see the state of our DSAR overall as well as each individual data source. The sample below has 17/18 data sources in the scan completed so the overall state is still "Started". Rerun the above request until you have a state of "Complete".

{
    "status": "success",
    "statusCode": 200,
    "data": {
        "requestId": "61784c9b1a1d3e0ea3b21a53",
        "userId": "DSAR",
        "state": "Started",
        "statuses": {
            "Completed": 17,
            "Queued": 1,
            "InProgress": 1
        }
        ...
    },
    "message": null
}

Retrieving DSAR Results[edit]

After your DSAR has completed, there's a variety of ways we can get and display the results. For a full view of the options, visit the BigID Docs. Some common reports are:

Full report - Includes internal information like what data source information was found in and column names. Can be JSON or CSV.
Short Report - Includes attribute names and values. Respects profile settings for hiding columns. Useful for returning to consumers. Can be in JSON, CSV, or a PDF.
Personal Info report - PDF report with information, consent records, purposes of processing, and data source information. Formatted as a PDF. Useful as a pretty report for consumers and is an expanded version of the short report.

Since we want to automate what we would return to consumers, we're going to retrieve the short report in JSON. You can also replace json in the URL with csv to change the format. Replace REQUESTID with the requestId of your DSAR that can be found above.

Now that we know the required APIs to perform a DSAR we can add this into our account portal and give users self service access to their data.