API Reference

Using the Privacy API

Overview

Use the Privacy API to create data subject requests (DSR) for GDPR and CCPA compliance.

This API is based on the OpenDSR framework and adheres to the OpenDSR specification.

Authentication

See the Authentication section of the Management API for information on how to authenticate against this API.

Endpoint

The base URL for the OpenDSR Privacy API is: https://opendsr.pushly.com/v2

Creating a Request

Use the Create Subject Request endpoint to create a new DSR.

Each request must include:

  1. A UUIDv4 subject_request_id that identifies the individual DSR.
  2. The subject_request_type that determines if the DSR is an erasure or access request.
  3. A subject_identities array or extensions object.
    1. subject_identities: An array of a single object that represents your customer ID for the data subject.
    2. extensions: An object using the opendsr.pushly.com extension that includes the Pushly ID associated to the data subject's device.

Customer ID Example (Access)

If the DSR is based off of your own customer ID that you provide to Pushly via an SDK then the request could be structured as follows:

POST /v2/domains/1/subject_requests HTTP/1.1
Host: opendsr.pushly.com
Content-Type: application/json

{
  "subject_request_id": "8e12a087-e096-4de2-9c42-0423f45c464e",
  "regulation": "ccpa",
  "subject_request_type": "access",
  "submitted_time": "2024-04-25T15:00:00Z",
  "subject_identities": [
    {
      "identity_type": "controller_customer_id",
      "identity_value": "ABCD123",
      "identity_format": "raw"
    }
  ],
  "status_callback_urls": [
    "https://www.example.com/opendsr/callback"
  ]
}

Pushly ID Example (Erasure)

If the DSR is based off of the Pushly ID that you retrieve via the SDK then the request could be structured as follows:

POST /v2/domains/1/subject_requests HTTP/1.1
Host: opendsr.pushly.com
Content-Type: application/json

{
    "subject_request_id": "8e12a087-e096-4de2-9c42-0423f45c464e",
    "regulation": "ccpa",
    "subject_request_type": "erasure",
    "submitted_time": "2024-04-25T15:00:00Z",
    "extensions": {
        "opendsr.pushly.com": {
            "pushly_ids": ["Ar4gsIHynxXMu22dR1wOQXYYVRhVh23a"]
        }
    },
    "status_callback_urls": [
        "https://www.example.com/opendsr/callback"
    ]
}

Request Validation

All responses and callbacks from this API should be validated for authenticity using the processor certificate as described in the Discovery API

Each response or callback from this API include two headers that should be used along with the certificate:

  • X-OpenDSR-Processor-Domain: Represents the domain for which the signing certificate is issued. The domain name MUST match the domain on which OpenDSR requests are received.
  • X-OpenDSR-Signature: Base64 encoded SHA-256 signature generated by the certificate matching the domain in the X-OpenDSR-Processor-Domain header.

The process of validating the request is:

  1. Base64 encode the full response body
  2. Sign the request using the public key from the processor certificate
  3. Compare the signature to the value provided in the X-OpenDSR-Signature header.

📘

Use your preferred cryptography library to perform validation

Status Update Callbacks

New Data Subject Requests can include a list of Callback URLs that will be invoked when the status of the request changes. These callbacks can be used as an alternative to polling the DSR Status Endpoint to check for updates.

Requests to these callback URLs represent the updated status of the DSR and will include the validation headers reference in the previous section of this document.

An example callback would look like:

POST /opendsr/callbacks HTTP/1.1
Host: opendsr.pushly.com
Content-Type: application/json
X-OpenDSR-Processor-Domain: opendsr.pushly.com
X-OpenDSR-Signature: [Signature]

{
    "controller_id": "1234",
    "expected_completion_time": "2024-05-11T15:00:01Z",
    "status_callback_url": "https://yourcallbackurl.com/opendsr/callbacks",
    "subject_request_id": "a7551968-d5d6-44b2-9831-815ac9017798",
    "request_status": "pending",
    "results_url": "https://opendsr.pushly.com/v2/domains/1234/d188d4ba-12db-48a0-898c-cd0f8ba7b345/report",
    "results_count" : 340
}

Response File Format

When a Access/Portability DSR has completed and results were found a results_url will be present in the DSR status response.

This URL will return a JSON Lines formatted file where each line represents an event that is attached to the data subject. Each line will contain a schema with properties that represent the data points that were attached to the event that was logged.

Additional Information

More information about the available endpoints and request/response bodies can be found by navigating to the appropriate endpoint for which you want to learn more about.

If you would like to discuss implementation of this API please contact your account manager and they connect you with an implementation engineer.