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

Currently supports an array of 1 email.
{ "emails": ["guinevere@camelotknights.com"] }

Custom

Values can be strings, numbers, arrays, booleans, or null.
Example custom data can 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:

Error 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. Check the route or request id is being passed in is 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.

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