Implementing OpenGDPR API

GDPR request flow

The GDPR request types, access, portability, erasure, and rectification, have the same flow:

1. App User submits a request.
2. The App Owner constructs the GDPR request (see below) and sends it to AppsFlyer.
3. AppsFlyer receives the request and responds with a "201 OK" for valid requests.
4. During the following 48 hours, the request is queued and has a pending status. The App User may cancel the request. 
5. After 48 hours, the request status changes to in_progress. AppsFlyer sends a ‘status change’ postback. The request can't be canceled. 
6. a) Within 28-days AppsFlyer fulfills the request.
   In the case of erasure or rectification, the App User's data is deleted.
   In the case of portability or access, the App User's data can be accessed in the AppsFlyer dashboard under GDPR, or via the Request API (see below).
   b) The request status updates to completed. AppsFlyer sends a status change postback.

GDPR request format

A GDPR Request API can be submitted via HTTP POST to the following endpoint -

https://hq1.appsflyer.com/gdpr/opengdpr_requests?api_token=[api token]

The API token is the same API token used for Pull API. The Admin retrieves the Pull API token from the API token page in the Dashboard.

Example GDPR erasure request 

curl --location --request POST 'https://hq1.appsflyer.com/gdpr/opengdpr_requests?api_token=[api_token]' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--data-raw '{ 
 "subject_request_id":"f4e5a271-f25e-4107-b681-************",
 "subject_request_type":"erasure",
 "submitted_time":"2020-07-05T10:00:00Z",
 "subject_identities":[ 
  { 
   "identity_type":"android_advertising_id",
   "identity_value":"55*****-****-****-************",
   "identity_format":"raw"
  }
 ],
 "api_version":"0.1",
 "property_id":"com.*********.*******.********",
 "status_callback_urls":[ 
  "https://examplecontroller.com/opengdpr_callbacks"
 ]
}'
 

GDPR erasure request code example

/* 
using the okhttp package install from maven
https://mvnrepository.com/artifact/com.squareup.okhttp3/okhttp
 */

import okhttp3.*;
import java.io.IOException;

public class GdprSendRequest {
 public static void main(String[] args){

  OkHttpClient client = new OkHttpClient();
  RequestBody body = RequestBody.create(null, "" +
  "{\r\n\"subject_request_id\": \"<SUBJECT_ID>\"," +
  "\r\n\"subject_request_type\": \"erasure\"," +
  "\r\n\"submitted_time\": \"2018-11-02T15:00:00Z\"," +
  "\r\n\"subject_identities\": [\r\n" +
  "{\r\n\"identity_type\": \"android_advertising_id\"," +
  "\r\n\"identity_value\": \"<ADVERTISING_ID>\"," +
  "\r\n\"identity_format\": \"raw\"\r\n}" +
   "\r\n]," +
   "\r\n\"property_id\": \"com.example.application\"}");

  Request request = new Request.Builder()
  .url("https://hq1.appsflyer.com/gdpr/opengdpr_requests?api_token=<API_TOKEN>")
  .post(body)
  .addHeader("Content-Type", "application/json")
   .addHeader("Accept", "application/json")
  .build();

  try {
   Response response = client.newCall(request).execute();
   System.out.println(response.code());
   System.out.println(response.body().string());
   System.exit(0);
  } catch (IOException e) {
   e.printStackTrace();
   System.exit(1);
  }
 }
}

""" using the requests python package, 
install using pip install requests """

import requests
import json
headers = {
 "Content-Type": "application/json",
 "Accept": "application/json"
}
params = {
 "api_token": ""
}
body = {
 "subject_request_id": "", 
 "subject_request_type": "erasure", 
 "submitted_time": "2018-10-02T15:00:00Z", 
 "subject_identities": [
  { "identity_type": "android_advertising_id", 
   "identity_value": "", 
   "identity_format": "raw" }
  ], 
 "property_id": "com.example.application" 
} 
body = json.dumps(body) 
res = requests.request("POST", 
"https://hq1.appsflyer.com/gdpr/opengdpr_requests", 
headers=headers, data=body, params=params) 
print(res.text) 
 

/* using the request npm package, 
install using npm install request */

var request = require("request");
var options = { method: 'POST',
 url: 'https://hq1.appsflyer.com/gdpr/opengdpr_requests',
 qs: { api_token: '' },
 headers: 
 { Accept: 'application/json',
  'Content-Type': 'application/json' },
 body:
 { subject_request_id: '<SUBJECT_ID>',
  subject_request_type: 'erasure',
  submitted_time: '2018-10-02T15:00:00Z',
  subject_identities: 
  [ { identity_type: 'android_advertising_id',
   identity_value: '<ADVERTISING_ID>',
   identity_format: 'raw' } ],
 property_id: 'com.example.application'
 },
 json: true };
request(options, function (error, response, body) {
 if (error) throw new Error(error);

 console.log(body);
});

using System;
using RestSharp;
namespace CS
{
 class Gdpr
 {
  static void Main(string[] args)
  {
		var url = "https://hq1.appsflyer.com/gdpr/opengdpr_requests";
		var apiToken = "?api_token=<API_TOKEN>";
  var client = new RestClient(url + apiToken);
  var request = new RestRequest(Method.POST);
  request.AddHeader("Content-Type", "application/json");
  Request.AddHeader("Accept", "application/json");
  var body = "{\r\n\"subject_request_id\": \"<SUBJECT_ID>\"," + 
   "\r\n \"subject_request_type\": \"erasure\"," + 
   "\r\n \"submitted_time\": \"2018-11-02T15:00:00Z\"," +
   "\r\n \"subject_identities\": [\r\n" +
   "{ \r\n \"identity_type\": \"android_advertising_id\"," +
   "\r\n \"identity_value\": \"<ADVERTISING_ID>\"," + 
   "\r\n \"identity_format\": \"raw\"\r\n }" + 
   "\r\n ]," + 
   "\r\n \"property_id\": \"com.example.application\"}";
		 
   request.AddParameter("undefined", body,ParameterType.RequestBody);
   IRestResponse response = client.Execute(request);
   // handle response by reading response.StatusCode
   Console.WriteLine(response.Content);
  }
 }
}

Every submitted GDPR request can be later queried for its status, by specifying the subject_request_id. There are four supported status types:

1. pending - A correct request has been received and is currently in the queue
2. in_progress - A request is currently being acted on
3. completed - A request has been fulfilled
4. canceled - A request has been canceled

Status request format

A status request can be submitted via HTTP GET to the following endpoint:

https://hq1.appsflyer.com/gdpr/opengdpr_requests/[subject_request_id]?api_token=[api token]

Status response example

HTTP/1.1 200 OK
Content-Type: application/json
X-OpenGDPR-Processor Domain: example processor.com
X-OpenGDPR-Signature:
kiGlog3PdQx+FQmB8wYwFC1fekbJG7Dm9WdqgmXc9uKkFRSM4uPzylLi7j083461xLZ+mUloo3tpsmyIZpt5eMfgo7ejXPh6lqB4ZgCnN6+1b6Q3NoNcn/+11UOrvmDj772wvg6uIAFzsSVSjMQxRs8LAmHqFO4cF2pbuoPuK2diHOixxLj6+t97q0nZM7u3wmgkwF9EHIo3C6G1SI04/odvyY/VdMZgj3H1fLnz+X5rc42/wU4974u3iBrKgUnv0fcB4YB+L6Q3GsMbmYzuAbe0HpVA17ud/bVoyQZAkrW2yoSy1x4Ts6XKba6pLifIHf446Bubsf5r7x1kg6Eo7B8zur666NyWOYrglkOzU4IYO8ifJFRZZXazOgk7ggn9obEd78GBc3kjKKZdwaCrLx7WV5y9TMDCf+2FILOJM/MwTUy1dLZiaFHhGdzld2AjbjK1CfVzyPssch0iQYYtbR49GhumvkYl11S4oDfu0c3t/xUCZWg0hoR3XL3B7NjcrlrQinB1KbyTNZccKR0F4Lk9fDgwTVkrAg152UqPyzXxpdzXjfkDkSEgAevXQwVJWBNf18bMIEgdH2usF/XauQoyrne7rcMIWBISPgtBPj3mhcrwscjGVsxqJva8KCVCKD/4Axmo9DISib5/7A6uczJxQG2Bcrdj++vQqK2succ=
{
 "controller_id":"example_controller_id",
 "expected_completion_time":"2018-11-01T15:00:01Z",
 "subject_request_id":"a7551968-d5d6-44b2-9831-815ac9017798",
 "request_status":"pending",
 "api_version":"0.1"
}

Status postbacks

As described in the GDPR Request Flow above, when the status of a GDPR request changes, from pending to in_progress to completed, AppsFlyer sends a GDPR postback to the requesting endpoints, specified with the status_callback_urls property.

Status Postback Example:

POST /opengdpr_callbacks HTTP/1.1
Host: examplecontroller.com
Content-Type: application/json
X-OpenGDPR-Processor Domain: appsflyer.com
X-OpenGDPR-Signature: kiGlog3PdQx+FQmB8wYwFC1fekbJG7Dm9WdqgmXc9uKkFRSM4uPzylLi7j083461xLZ+mUloo3tpsmyIZpt5eMfgo7ejXPh6lqB4ZgCnN6+1b6Q3NoNcn/+11UOrvmDj772wvg6uIAFzsSVSjMQxRs8LAmHqFO4cF2pbuoPuK2diHOixxLj6+t97q0nZM7u3wmgkwF9EHIo3C6G1SI04/odvyY/VdMZgj3H1fLnz+X5rc42/wU4974u3iBrKgUnv0fcB4YB+L6Q3GsMbmYzuAbe0HpVA17ud/bVoyQZAkrW2yoSy1x4Ts6XKba6pLifIHf446Bubsf5r7x1kg6Eo7B8zur666NyWOYrglkOzU4IYO8ifJFRZZXazOgk7ggn9obEd78GBc3kjKKZdwaCrLx7WV5y9TMDCf+2FILOJM/MwTUy1dLZiaFHhGdzld2AjbjK1CfVzyPssch0iQYYtbR49GhumvkYl11S4oDfu0c3t/xUCZWg0hoR3XL3B7NjcrlrQinB1KbyTNZccKR0F4Lk9fDgwTVkrAg152UqPyzXxpdzXjfkDkSEgAevXQwVJWBNf18bMIEgdH2usF/XauQoyrne7rcMIWBISPgtBPj3mhcrwscjGVsxqJva8KCVCKD/4Axmo9DISib5/7A6uczJxQG2Bcrdj++vQqK2succ=

{
"controller_id":"example controller id at the processor",
"expected_completion_time":"2018-11-01T15:00:01Z",
"status_callback_url":"https://examplecontroller.com/opengdpr_callbacks",
"Subject_request_id":"a7551968-d5d6-44b2-9831-815ac9017798",
"Request_status":"pending"
}

Once an Access Request or Portability Request has been completed, you can download the report via HTTP GET to the following endpoint:

https://hq1.appsflyer.com/gdpr/download/[REQUEST_ID]?api_token=[TOKEN]

The generated report is available for fourteen days from the time of completion.

To learn about the formats supported by AppsFlyer, a discovery request can be submitted via HTTP GET to the following endpoint:

https://hq1.appsflyer.com/gdpr/discovery?api_token=[api token]

Discovery response example

HTTP/1.1 200 OK
Content-Type: application/json
{
 "api_version": "0.1",
 "supported_identities": [
 {
  "identity_type": "android_advertising_id",
  "identity_format": "raw"
 },
 ],
 "supported_subject_request_types": [
 "erasure", "access", "portability", "rectification"
 ],
 "processor_certificate": "https://exampleprocessor.com/cert.pem"
}

It is possible to cancel a GDPR request, based on its subject_request_id, but only during the pending phase.

To so submit an HTTP DELETE with subject_request_id to:

https://hq1.appsflyer.com/gdpr/opengdpr_requests/[subject_request_id]?api_token=[api token]

Cancellation response

When a GDPR cancellation request is received, AppsFlyer returns an HTTP response with status code 202 and several other parameters. 

Once the cancellation of the request takes place AppsFlyer sends a postback with canceled status.

This AppsFlyer’s API is a test API for the AppsFlyer’s GDPR Requests API.

How does it work?

The test API works as follows:

1. Once a GDPR request has been made, the request is immediately placed in ‘Pending’ status. For testing purposes, the status changes every 30 seconds.

2. If an endpoint for a status postback has been inserted in the GDPR request, a first postback is sent right after the request and two more status postbacks are sent in 30-second intervals.

GDPR Request Test Endpoint:

https://hq1.appsflyer.com/gdpr/stub?api_token=[api token]

Status Request Test Endpoint:

https://hq1.appsflyer.com/gdpr/stub/[request id]?api_token=[api token]

Discovery Request Test Endpoint:

https://hq1.appsflyer.com/gdpr/stub/discovery?api_token=[api token]

Cancellation Request Test Endpoint:

https://hq1.appsflyer.com/gdpr/stub/[request id]?api_token=[api token]

The account admin can access the GDPR requests submitted in the Logs Dashboard.

For completed access and portability requests, it is also possible to download the report from within this dashboard.

To access the Logs Dashboard:

1. Go to the main dashboard and click your user name.
2. Click Logs and the following window opens:

The GDPR API HTTP return codes and error messages are detailed in this section. 

HTTP return code 400 - bad request

Messages having return code 400 contain a JSON with the error code and message.

{ "error": { "code":400, "af_gdpr_code": "%AF error code%", "message":"%error message text%" } }