Learn how to use the Singular API to support GDPR requests.

GDPR Endpoints

Discovery Endpoint

Usage

The OpenGDPR Discovery endpoint returns all currently supported request types that Singular can process through the GDPR API.

Sample Query

import requests
  response = requests.get("https://gdpr.singular.net/api/gdpr/discovery")
  print(response.text)

Sample Output

{
    "api_version": "0.1.4",
    "supported_identities": [
      {"identity_format": "raw","identity_type": "android_advertising_id"},
      {"identity_format": "raw","identity_type": "android_id"},
      {"identity_format": "raw","identity_type": "ios_advertising_id"},
      {"identity_format": "raw","identity_type": "ios_vendor_id"},
      {"identity_format": "raw","identity_type": "user_id"}
    ],
    "supported_subject_request_types": [
        "erasure",
        "access"
    ]
  }

Requests Endpoint

Usage

The OpenGDPR Requests endpoint handles new GDPR requests, sent through an HTTP POST request while specifying the Device IDs for the requested data subjects.

Supported Requests

The OpenGDPR Requests endpoint supports the following types of requests, corresponding to different GDPR rights:

• `erasure` - supporting user requests for data erasure as part of the GDPR's Article 17, Right to erasure
• `access` - supporting user requests for data access as part of the GDPR's Article 15, Right to access

Supported IDs

The OpenGDPR Requests endpoint supports the following types of IDs:

• `android_advertising_id` - requests made by providing the Google Advertising ID, which is also known as GAID or AIFA
• `android_id` - requests made by providing the Android ID, which is also known as ANDI
• `ios_advertising_id` - requests made by providing IDFA, which is the iOS Advertising ID.  Note that requests for "limit-ad-tracking or ATT AuthorizationStatus denied" devices containing zeroed IDFAs ("00000000-0000-0000-0000-000000000000") will be ignored, and the API will not return with an error.  `ios_vendor_id` should be used instead.
• `ios_vendor_id` - requests made by providing IDFV, which is the iOS ID for Vendors
• `user_id` - requests made by providing the Custom User ID

Sample Query

import requests
  
  url = "https://gdpr.singular.net/api/gdpr/requests"
  
  payload = {
    "subject_request_id": "1c8b23f4-12eb-4fe8-af1c-0f72807dfec2",
    "subject_request_type": "access",
    "submitted_time": "2018-05-25T10:00:00Z",
    "subject_identities": [
      {
        "identity_type": "android_advertising_id",
        "identity_value": "38400000-8cf0-11bd-b23e-10b96e40000d",
        "identity_format": "raw"
      }
    ],
    "property_id": "Android:com.myapp.xyz",
  }
  
  headers = {
    "content-type": "application/json",
    "Authorization": "[API_KEY]"
  }
  
  response = requests.post(url, json=payload, headers=headers)
  print(response.text)

Query Parameters

[
  {
    "identity_type":
    "android_advertising_id",
    "identity_value": 
    "38400-8cf0-11bd-b23e-1000d",
    "identity_format": "raw"
  }
  ]

Sample Output

{
    "controller_id":"example_controller_id",
    "received_time":"2018-05-25T10:00:01Z",
    "expected_completion_time": "2018-06-24T10:00:01Z",
    "encoded_request":"<BASE64 ENCODED REQUEST>",
    "subject_request_id":"1c8b23f4-12eb-4fe8-af1c-0f72807dfec2",
    "results_url": "https://url-to-results-in-json-format",
    "api_version": "0.1.4"
  }

Status Endpoint

Usage

Returns the current status for a previously sent request, identified by its Request ID.

Sample Query

import requests
  url = "https://gdpr.singular.net/api/gdpr/requests/"
  subject_request_id = "1c8b23f4-12eb-4fe8-af1c-0f72807dfec2"
  headers = {"Authorization": "<API KEY>"}
  response = requests.get(url+subject_request_id, headers=headers)
  print(response.text)

Sample Output

{
      "controller_id": "example_controller_id",
      "request_status": "completed",
      "expected_completion_time": "2018-06-24T10:00:01Z",
      "subject_request_id": "1c8b23f4-12eb-4fe8-af1c-0f72807dfec2",
      "api_version": "0.1.4"
  }

Cancellation Endpoint

Usage

Use this endpoint to cancel a previous request. This is possible as long as the request is in "pending" status.

Sample Query

import requests
  url = "https://gdpr.singular.net/api/gdpr/requests/"
  subject_request_id = "1c8b23f4-12eb-4fe8-af1c-0f72807dfec2"
  headers = {"Authorization": "<API KEY>"}
  response = requests.delete(url+subject_request_id, headers=headers)
  print(response.text)

Sample Output

{
    "controller_id":"example_controller_id",
    "subject_request_id":"1c8b23f4-12eb-4fe8-af1c-0f72807dfec2",
    "received_time":"2018-05-25T10:00:01Z",
    "api_version":"0.1"
  }