Skip to main content

Custom API Connection Overview

Custom API integrations enable you to programatically retrieve verified privacy requests that are ready for processing. Once retrieved, you can manage the request within your infrastructure or pass it to a third-party system, allowing you to handle the request and confirm its completion.

Webhooks Alternative

If you are looking for a webhook based integration, see the Webhooks Integration Overview.

Prerequisites

Before you begin, ensure that an Internal Systems (Manual) integration has been created, and that you have retrieved the Integration ID from the URL.

API Key Permissions​

To interact with the API endpoints used below, ensure that you have an API key with the necessary permissions for the request types being processed:

PermissionAccessDeletionOpt Out
PrivacyRequestRead + UpdateRead + Update
IntegrationFileCreate
OptOutRead + Update

Request Processing​

Below is an overview of the steps needed to process Access, Deletion and Opt Out Requests using the DataGrail API v2.

Additional Examples

The examples on this page are using curl to make requests. Additional examples for other languages can be found in the API documentation.

Access Requests​

Use the following steps to locate and process Access Requests.

1. Retrieve Privacy Requests​

Using the Get a list of privacy requests endpoint, retrieve a list of privacy requests by filtering on status=extracting_personal_data and privacy_right=access.

Example Curl Request
curl -L 'https://<subdomain>.datagrail.io/api/v2/privacy_requests?status=extracting_personal_data&privacy_right=access' \
-H 'Accept: application/json' \
-H 'Authorization: Bearer <api key>'

2. Retrieve Request Integrations​

For each privacy request retrieved in the last step, retrieve all associated integrations with the request by using the Get a list of privacy request integrations endpoint.

Example Curl Request
curl -L 'https://<subdomain>.datagrail.io/api/v2/privacy_requests/<request id>/integrations' \
-H 'Accept: application/json' \
-H 'Authorization: Bearer <api key>'

Filter the list of integrations returned to locate the integration_id that you will be processing. If the integration has a state of processing and access_done_at is null, then it is ready to be processed.

Example Response
{
  "data": [
    {
      "uuid": "677a70c6-2a5a-4ad9-b266-566e44a6d50b",
      "integration_id": "7efa58a8-9b7d-4faf-8082-5f7f7f407db7",
      "name": "AWS RDS Postgres",
      "state": "processing",
      "paused": false,
      "excluded": false,
      "is_connected": true,
      "access_type": "api",
      "access_done_at": null
    }
  ]
}

3. Upload Results​

If data was found when processing an Access Request, there are two options for returning it.

Upload the files directly to DataGrail, which will then be stored in your configured cloud storage.

Example Curl Request
curl -L 'https://<subdomain>.datagrail.io/api/v2/privacy_requests/<request id>/integrations/<integration id>/files' \
-H 'Content-Type: multipart/form-data' \
-H 'Accept: application/json' \
-H 'Authorization: Bearer <api key>' \
-F 'files[]=@/path/to/results/file.csv'

4. Update Privacy Integration State​

With the request processed internally and any applicable results associated with the integration, in this last step you will update the privacy request integration to completed.

Example Curl Request
curl -L -X PUT 'https://<subdomain>.datagrail.io/api/v2/privacy_requests/<request id>/integrations/<integration id>' \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'Authorization: Bearer <api key>' \
-d '{"state": "completed"}'

Deletion Requests​

Use the following steps to locate and process Deletion Requests.

1. Retrieve Privacy Requests​

Using the Get a list of privacy requests endpoint, retrieve a list of privacy requests by filtering on status=pending_delete and privacy_right=deletion.

Example Curl Request
curl -L 'https://<subdomain>.datagrail.io/api/v2/privacy_requests?status=pending_delete&privacy_right=deletion' \
-H 'Accept: application/json' \
-H 'Authorization: Bearer <api key>'

2. Retrieve Request Integrations​

For each privacy request retrieved in the last step, retrieve all associated integrations with the request by using the Get a list of privacy request integrations endpoint.

Example Curl Request
curl -L 'https://<subdomain>.datagrail.io/api/v2/privacy_requests/<request id>/integrations' \
-H 'Accept: application/json' \
-H 'Authorization: Bearer <api key>'

Filter the list of integrations returned to locate the integration_id that you will be processing. If the integration has a state of processing and deletion_done_at is null, then it is ready to be processed.

Example Response
{
  "data": [
    {
      "uuid": "677a70c6-2a5a-4ad9-b266-566e44a6d50b",
      "integration_id": "7efa58a8-9b7d-4faf-8082-5f7f7f407db7",
      "name": "AWS RDS Postgres",
      "state": "processing",
      "paused": false,
      "excluded": false,
      "is_connected": true,
      "deletion_type": "api",
      "deletion_done_at": null
    }
  ]
}

3. Update Privacy Integration State​

After processing the Deletion Request, the last step is to update the privacy request integration to completed.

Example Curl Request
curl -L -X PUT 'https://<subdomain>.datagrail.io/api/v2/privacy_requests/<request id>/integrations/<integration id>' \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'Authorization: Bearer <api key>' \
-d '{"state": "completed"}'

Opt Out Requests​

Use the following steps to locate and process Opt Out Requests.

1. Retrieve Opt Outs​

Using the Get a list of opt out requests endpoint, retrieve a list of Opt Out Requests by filtering on status=in_progress.

Example Curl Request
curl -L 'https://<subdomain>.datagrail.io/api/v2/opt_outs?status=in_progress' \
-H 'Accept: application/json' \
-H 'Authorization: Bearer <api key>'

2. Retrieve Opt Out Integrations​

For each Opt Out Request retrieved in the last step, use the uuid to retrieve all associated integrations by using the Get a list of opt out integrations endpoint.

Example Curl Request
curl -L 'https://<subdomain>.datagrail.io/api/v2/opt_outs/<opt out uuid>/integration_states' \
-H 'Accept: application/json' \
-H 'Authorization: Bearer <api key>'

Filter the list of integrations returned to locate the integration (authentication.uuid) that you will be processing. If the integration has a state of processing, then it is ready to be processed.

Example Response
{
  "data": [
    {
      "id": "12345",
      "status": "processing",
      "status_message": null,
      "created_at": "2025-10-11T01:23:45.678Z",
      "processed_at": null,
      "authentication": {
        "name": "AWS RDS Postgres",
        "uuid": "7efa58a8-9b7d-4faf-8082-5f7f7f407db7"
      }
    }
  ]
}

3. Update Opt Out State​

After processing the Opt Out Request, the last step is to update the integration to complete.

Example Curl Request
curl -L -X PUT 'https://<subdomain>.datagrail.io/api/v2/opt_outs/<opt out uuid>/integration_states/<integration id>' \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'Authorization: Bearer <api key>' \
-d '{"state": "complete"}'

Lifecycle Diagram​

 

Need help?
If you have any questions, please reach out to your dedicated Account Manager or contact us at 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.