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

For how data subject requests fit into a broader consent architecture — and why erasure is not the same as stopping tracking — see Consent Management with the Singular SDK: A Decision Framework .

GDPR Endpoints

Discovery Endpoint

Usage

The OpenDSR 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 OpenDSR 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 OpenDSR 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 OpenDSR 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
• `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"
  }

Scope of deletion

Erasure removes the user-level records — logs and attribution detail — that Singular holds for the identifier. Aggregated data (for example, cohort rollups) is not device-addressable once aggregated and is unaffected by erasure. Describe this distinction in your own privacy documentation.

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"
  }