Generic API Integration
Introduction
The ‘Generic’ integration option can be used to integrate with any product/tool that has a public API available. Currently, it can be used for data subject access and erasure requests.
Setting up the integration
In the Settings menu, go to Integrations, then click on ‘+ New Integration’. Select ‘Generic’ and give it the name you want, and select the ‘Authentication method’ > API Key. The API Key is encrypted after creation/update.
The ‘Request type’ is for the validation of the connector.
Headers: The integration comes by default with the header ‘Authorization’ because that is what most APIs use. You can add more headers if the API you’re connecting needs it. The same goes for Parameters.
If ‘Request type’ = GET, you don’t need to add anything in the ‘Body’ field. If you use POST or any other type of request type, you can add it as a plain JSON file, you just have to type the JSON instruction.
Response code handling: Anything that is not here, will have the action as ‘Accept’, so it’s not necessary to configure the ‘accept’ HTTP Status Code, but you can do it.
Create a workflow for the API
To use the integration, you need to first configure a data repository for automation. In the data repository, in details of Automation, you select ‘Generic’ integration and the integration you’ve created and activate it using the switch button.
Now you need to create a new workflow for data requests, including configuring the necessary API calls for user details and access requests. In this example, we have focused on data access request.
First, you add the trigger to the workflow, and then the ‘Access data’ action. In the action, you select the Data Repository you’ve just set up to work with the generic automation.
Then you can configure the integration in the action:
When you click there, a pop-up will show you how to use variables during this process. It uses Jinja2 notations. You will be able to configure multiple requests, following the same structure.
You can use previous request responses to feed into the next request. So the name you give the request is important because it’s this name that you will use in the following request to access data from this response.
Create the first request. You can name it, for example, ‘GetUser’. Then add the endpoint you know has the data and the required parameters. For example ‘Email’; use the variable from the example and replace it with the email variable: {{ dsr.email }}
You will see the option if you want the response to be in the final report. If it’s an intermediate request, like this first request example, that is to get the user ID, you deselect the option. This is if you need the ID to delete the user, for example.
You can also configure the response code handling.
Add another request to get the user details. Name it, for example, UserDetails. This response you probably want to add to the final report. Again, add the endpoint you know contains the data you want to retrieve. At the end, it has a path parameter for the user ID. Use the Jinja2 Notation; curly brackets with the name of the previous request. If the endpoint returns a list, put a 0 to retrieve the first position of that list and add the .id because you want the ID from this response, for example.
You need to know the response structure to use the variables in the request (variables can be used at any place eg. endpoint, headers, parameters, and JSON body).
It’s important to understand the API structure and data organisation in the tools to execute access and erasure requests effectively.
Sometimes the data is spread across different columns/tables, and that’s why it’s necessary to create different API calls/requests.
If there is an error response, after 3 times, you would have to create a new DSR or do the task manually.
Notes:
- Use carefully (especially for erasure requests; no going back).
- It only accepts JSON responses.
- There is no support for file responses in the API at the moment, and any future implementation will depend on the specifications provided by clients.