Skip to main content

Intake API

The DataGrail DSR intake API is built to enable customers and integration partners to programmatically create and manage privacy requests from anywhere. Whether originating from a web or mobile application or a bulk upload through a script, you can create a DSR in the DataGrail platform from wherever you see fit.

API Conventions​

All URLs listed in the documentation should have the same base URL that precedes each route. This consists of your organization's DataGrail URL along with the API version:

https://${yourDataGrailDomain}/api/v1

For example, if your DataGrail URL is camelot.datagrail.io, each endpoint will be preceded with:

https://camelot.datagrail.io/api/v1

Authentication​

The DataGrail API uses API keys to authenticate requests. Please reach out to your DataGrail CSM directly for an API key at support@datagrail.io.

Authentication to the API is performed by passing your API token in the Authorization header using the Bearer Scheme: Authorization: Bearer <api_key>

All API requests must be made over HTTPS.

You can test if your credentials are valid, by sending a GET request to the /ping endpoint.

A successful response will be an empty request with status 200

curl -i "https://${yourDataGrailDomain}/api/v1/ping" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <api_key>"
info

The above command returns a response with no content and a status code of 200.

Create a Privacy Request​

Creates a privacy request to access or delete personal data.

A privacy request is a request for access or deletion of personal data that is made directly from a data subject, data processor on behalf of a data subject, or any other avenue that pertains to your supported dynamic policies.

Endpoint​

POST /privacy_requests

Parameters​

ParameterRequiredDescription
privacy_righttrueaccess, access_categories, or deletion
identifierstrueJSON object that contains values used to identify personal data
customfalseJSON object containing any custom data associated with the privacy request

Identifiers​

Supports an array with a single email:

{ "emails": ["guinevere@camelotknights.com"] }

Custom​

Values can be strings, numbers, arrays, booleans, or null.

Example custom data can be seen below.

curl -XPOST "https://${yourDataGrailDomain}/api/v1/privacy_requests" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <api_key>" \
  -d '{
      "privacy_right": "access",
      "custom": {
        "first_name": "Queen",
        "last_name": "Guinevere",
        "phone_numbers": ["555-555-1234", "555-555-5678"],
        "country": "Britain",
        "app_id": "holy_grail_app",
        "user_id": "123abc",
        "notes": "Apple Account Deletion", 
        "origin": "iOS"
      },
      "identifiers": {
        "emails": ["guinevere@camelotknights.com"]
      }
  }'

The above command returns JSON structured like this:

{
  "id": "80edbafc-4ec6-45a0-b341-73080457890e",
  "status": "open",
  "privacy_right": "deletion",
  "dynamic_policy": [
    "CCPA"
  ],
  "identifiers": {
    "emails": [
      "guinevere@camelotknights.com"
    ]
  },
  "custom": {
    "first_name": "Queen",
    "last_name": "Guinevere",
    "phone_numbers": ["555-555-1234", "555-555-5678"],
    "country": "Britain",
    "app_id": "holy_grail_app",
    "user_id": "123abc",
    "notes": "Apple Account Deletion",
    "origin": "iOS"
  }
}

Get a Privacy Request​

Returns information related to a submitted privacy request.

Endpoint​

GET /privacy_requests/${id}

Parameters​

ParameterRequiredDescription
idtrueThe ID of the privacy request. The ID is the 36 character string that is returned in the id field after creating a privacy request.
curl "https://${yourDataGrailDomain}/api/v1/privacy_requests/80edbafc-4ec6-45a0-b341-73080457890e" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <api_key>"

The above command returns JSON structured like this:

{
  "id": "80edbafc-4ec6-45a0-b341-73080457890e",
  "status": "open",
  "privacy_right": "deletion",
  "identifiers": {
    "emails": [
      "guinevere@camelotknights.com"
    ]
  },
  "custom": {
    "first_name": "Queen",
    "last_name": "Guinevere",
    "phone_numbers": ["555-555-1234", "555-555-5678"],
    "country": "Britain",
    "app_id": "holy_grail_app",
    "user_id": "123abc",
    "notes": "Apple Account Deletion",
    "origin": "iOS"
  }
}

Error Codes​

The DataGrail API uses the following error codes:

CodeDescription
400Bad Request -- The request is invalid.
401Unauthorized -- Your API key is incorrect or invalid.
404Not Found -- The privacy request or route could not be found. Confirm the route or request id are correct.
422Unprocessable Entity - The request body cannot be processed. Ensure that you're passing the correct parameters.
500Internal Server Error -- An internal and unexpected error condition occurred.

 

Contact Us

To learn more about Platform API and availability within your current package, please reach out to your dedicated CSM or support@datagrail.io.

Disclaimer: The information contained in this message does not constitute as legal advice. We would advise seeking professional counsel before acting on or interpreting any material.