GDPR API Reference

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

 

GDPR Endpoints

Endpoint Method URL Description
Discovery GET https://gdpr.singular.net/gdpr/discovery Returns all currently supported request types that Singular can process through the GDPR API.
Requests POST https://gdpr.singular.net/gdpr/requests Use this endpoint to send new GDPR requests, sent through an HTTP POST request while specifying the Device IDs for the requested data subjects.
Status GET https://gdpr.singular.net/gdpr/requests/request_id Returns the current status for a previously sent request, identified by its Request ID.
Cancellation DELETE https://gdpr.singular.net/gdpr/requests/request_id Use this endpoint to cancel a previous request. This is possible as long as the request is in "pending" status.

Discovery Endpoint

GET https://gdpr.singular.net/api/gdpr/discovery

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.request("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": "md5","identity_type": "android_advertising_id"},
    {"identity_format": "sha1","identity_type": "android_advertising_id"},
    {"identity_format": "raw","identity_type": "android_id"},
    {"identity_format": "md5","identity_type": "android_id"},
    {"identity_format": "sha1","identity_type": "android_id"},
    {"identity_format": "raw","identity_type": "ios_advertising_id"},
    {"identity_format": "md5","identity_type": "ios_advertising_id"},
    {"identity_format": "sha1","identity_type": "ios_advertising_id"},
    {"identity_format": "raw","identity_type": "ios_vendor_id"},
    {"identity_format": "md5","identity_type": "ios_vendor_id"},
    {"identity_format": "sha1","identity_type": "ios_vendor_id"}
  ],
  "supported_subject_request_types": [
      "erasure",
      "access"
  ]
}

Requests Endpoint

POST https://gdpr.singular.net/api/gdpr/requests

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.

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.request("POST", url, data=payload, headers=headers, params=querystring)
print(response.text)

Query Parameters

Parameter Format Description Example
subject_request_id String UUID v4 string  
subject_request_type String String value representing the type of OpenGDPR Request. Singular currently supports the values: "erasure", "portability", "access"  
subject_identities Array A list of identity objects describing the type, value and format for each Device ID to fulfill the request for. A request can contain up to 100 Device IDs.
[
{
  "identity_type":
"android_advertising_id", "identity_value":
"38400-8cf0-11bd-b23e-1000d", "identity_format": "raw" } ]
submitted_time   RFC 3339 date string representing the time of the original request by the data subject 2010-05-25T10:00:00Z
property_id String The [platform]:[longname] pair to specify the relevant app. ios:com.myapp.xyz

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

GET https://gdpr.singular.net/api/gdpr/requests/<REQUEST_ID>

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.request("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

DELETE https://gdpr.singular.net/gdpr/requests/<REQUEST_ID>

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.request("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"
}
Was this article helpful?