Last modified May 27, 2021 by Shelly Wolfe

Swrve Privacy API

The Swrve Privacy API is a series of REST calls for managing your Data Subject access and data erasure requests.

Swrve’s service ingests first-party data on behalf of our customers, giving you the opportunity to use sophisticated targeting techniques to contact your end users. To ensure compliance with data protection and privacy laws such as the General Data Protection Regulation (GDPR), California Consumer Privacy Act (CCPA), and other equivalent legislation, Swrve provides an API to initiate data and privacy-related requests and track their progress.

The Swrve Privacy API supports the following actions:

  • Subject access request – Subject access requests gather all the data Swrve holds about a particular app user, as identified by their Swrve user ID. If you have multiple apps in Swrve, you must submit a separate subject access request for each app, using the app-specific authentication key. Once Swrve processes the request, a ZIP file containing the user’s records from the Swrve user database is available to download, in CSV format.
  • Erasure request – An erasure request removes all information that Swrve has stored about a particular app user. Swrve permanently erases the data and does not collect any further data for that user.

Use the Swrve Privacy API to integrate with your in-house data processing system. To ensure there is some level of commonality between systems that process Data Subject requests like the above, Swrve has implemented the API according to the OpenDSR (formerly known as OpenGDPR) framework version 1.0.

OpenDSR roles

This article refers to the following roles as defined under the specific regulations and uses them interchangeably:

GDPR CCPA Description
Data Subject Consumers The end user of your app, as identified by their Swrve user ID.
Data Controller Businesses The organization who receives an access request from the Data Subject and validates it (in this instance, you, the Swrve customer). The Controller submits requests to the Data Processors.
Data Processor Service providers The Data Processor acts on behalf of the Controller and fulfills requests within the Controllers scope. In this instance, the Data Processor is Swrve.

Authentication

To use the Privacy API, you must create an app-specific GDPR key in Swrve. To view or manage this key, on the Settings menu, select Integration settings. For information about creating a new key, see Integrate your app.

The API Key Management section of the Integration Settings page, showing an app's various types of API keys, including GDPR.

Required URL parameters

All requests to the API must include the following two keys as part of the URL:

Key Description
api_key The GDPR key for your app. You must create a separate GDPR key—the Privacy API does not support using your default API key.
personal_key Your personal key, as displayed on the Integration settings page.

US vs. EU URL

The URL examples in this article reference Swrve’s URL for data and content stored in our US data center. If your app uses EU data storage and URL endpoints (that is, you log into the Swrve dashboard at https://eu-dashboard.swrve.com), use the EU-based URL for all API calls (for example, https://eu-privacy.swrve.com/gdpr_requests?api_key=gdpr-YourGDPRKey&personal_key=YourPersonalKey).


Send a Subject access request

This request searches the Swrve user database for the named user ID, extracts any related files, and combines them into a ZIP file. Once the search is complete, the ZIP file is available to download using a time-limited URL. To get the URL, you must submit a Status request to the API, with a code for the request.

Request method

POST

URL

https://privacy.swrve.com/gdpr_requests?api_key=<GDPR_key>&personal_key=<your_personal_key>

POST body parameters

The POST body must be a JSON document, with a Content-Type header of “application/json“, and contain the following fields:

Parameter Presence Description
subject_request_id Required UUID v4 string. The Controller must generate this when they submit the request to the Processor.
subject_request_type Required String value representing the OpenGDPR Request type of access.
submitted_time Required RFC 3339 date string representing the time the Data Subject submitted the original request.
extensions Required Used to hold a Swrve-specific OpenGDPR extension. This is mandatory in the Swrve API since we use it to determine the Swrve user IDs to search for. It is a JSON object, which must contain a key opengdpr.swrve.com, with a JSON object value, which in turn contains the key swrve_ids with a value of an array of strings, each one being a Swrve user ID.
api_version Optional Version string representing the implemented version of the OpenGDPR API (currently 1.0).

Example request

{
    "subject_request_id": "24b00ad-8718-146a-19d0-87c5059493007",
    "subject_request_type": "access",
    "api_version": "1.0",
    "submitted_time": "2020-12-09T00:00:00Z",
    "extensions": {
        "opengdpr.swrve.com": {
            "swrve_ids": [ "74c21995f577-3139-66d8-6c93-65333594" ]
        }
    }
}

Response

The response is a JSON document (with Content-Typeapplication/json“) containing the following fields:

Field Description
controller_id A string indicating the unique identity of the app in the Swrve system.
expected_completion_time RFC 3339 date string representing the time when Swrve expects to fulfill the request. This might be a matter of days, since the request itself might initiate a complex sequence of searching within the Swrve system. Larger or busier apps will require more time to process the request.
received_time
RFC 3339 date string representing the time when Swrve received the request.
encoded_request
Base64 encoding of the entire body of the OpenGDPR request.
subject_request_id
UUID v4 string from the originating OpenGDPR request. You will need this piece of information to get the status of the request, and to get the URL that you use to download the data associated with the user.

Example response

{
    "controller_id": 1,
    "expected_completion_time": "2021-01-13T11:06:45.119Z",
    "received_time": "2020-12-19T11:06:45.119Z",
    "encoded_request": "pCYaTMDUywVIVI5cTWXIgAvw0wd1dzW5iZgC0iVnsZmxmIYWBI1Z5tIQjMApjjHNVAWYzcdXfOgNRMsA3wJcBZsySlT5zz0eiYYNAcQlMf6Sg6dZCWIZ6OlyXttFTjNRp0J3OTiID1IYcLdIg1pZWAVc2VCmDChXmIM9BgNWgTdN3pdc4SHiAzgI2GM9gLYEOwzyukCMELDL0IwiSI20azFM9RLz5I0y4MYWTyxwY3OkCXAw10fIRC2TImAmIMTS4gLZHAxNtcO1a3ylHWgmznnCNI9O52jCInV3zIiLsISIQnjIWgR3cIf9FViblhZg3WbJlYdmAWzzYniHiYMMAwoMdTzIAMNNB6etOImhACgiAToIIAyY",
    "subject_request_id": "24b00ad-8718-146a-19d0-87c5059493007"
}

Check request status

The status API returns the processing status of a previously submitted subject access or data erasure request.

Request method

GET

URL

https://privacy.swrve.com/gdpr_requests/<subject_request_id>?api_key=<GDPR_key>&personal_key=<your_personal_key>

URL parameters

Parameter Presence Description
subject_request_id Required The subject_request_id the Controller provided to Swrve in the original Subject access request.
api_key
personal_key
Required The authentication keys described above.

Example request

GET http://privacy.swrve.com:2910/gdpr_requests/24b00ad-8718-146a-19d0-87c5059493007?api_key=gdpr-jjdpI89P5K4gr3v3YG&personal_key=KrXu4kX5tkPXXjdNQBL

Response

The response is a JSON document describing the request’s progress, with the following fields:

Field Description
controller_id A string indicating the identity of the app in the Swrve system.
expected_completion_time RFC 3339 date string representing the time when Swrve expects to fulfill the request. This might be a matter of days, since the request itself might initiate a complex sequence of searching and data erasure within the Swrve system. Larger or busier apps will require more time to process the request.
subject_request_id UUID v4 string matching the original OpenGDPR request.
request_status String indicating the status of the request:

  • pending – The request Swrve received was well formed and is ready to process.
  • in_progress – Swrve is currently processing the request.
  • completed – Swrve has finished processing the request.
  • cancelled – The request was cancelled and did not finish processing.
api_version Version string representing the implemented version of the OpenGDPR API (currently 1.0).
results_url
Once Swrve finishes processing the request and the status is completed, indicates the valid URL where the results of the request are available.

Example response without results URL

{
    "controller_id": 1,
    "expected_completion_time": "2020-01-01T00:00:00.000Z",
    "subject_request_id": "24b00ad-8718-146a-19d0-87c5059493007",
    "request_status": "in_progress",
    "api_version": "1.0"
}

Example response with results URL

{
    "controller_id": 1,
    "expected_completion_time": "2020-01-03T00:00:00.000Z",
    "subject_request_id": "e40118d43-9ec5-5e23-4b56-de04a13828e",
    "request_status": "completed",
    "api_version": "1.0",
    "results_url": "https://privacy.swrve.com/d/e40118d43-9ec5-5e23-4b56-de04a13828e"
}

Download Subject access request data

The results URL provided in the status response is protected. Swrve requires the app GDPR API key and your personal key to authenticate the request (see above).

Request method

GET

URL

https://privacy.swrve.com/d/<results_url>?api_key=<GDPR_key>&personal_key=<your_personal_key>

Swrve authenticates the API and personal keys, and then responds with an HTTP redirect to the location of the ZIP file that contains the access request’s results.

Example request

GET http://privacy.swrve.com/d/e40118d43-9ec5-5e23-4b56-de04a13828e?api_key=gdpr-jjdpI89P5K4gr3v3YG&personal_key=KrXu4kX5tkPXXjdNQBL


Send a data erasure request

This request deletes all data relating to the target users from the Swrve system. Once complete, Swrve discards and does not record any further data your app sends for that user ID.

Request method

POST

URL

https://privacy.swrve.com/gdpr_requests?api_key=<GDPR_key>&personal_key=<your_personal_key>

POST body parameters

The POST body must be a JSON document, with a Content-Type header of “application/json“, and contain the following fields:

Parameter Presence Description
subject_request_id Required UUID v4 string. The Controller must generate this when they submit the request to the Processor.
subject_request_type Required String value representing the OpenGDPR Request type of erasure.
submitted_time Required RFC 3339 date string representing the time the Data Subject submitted the original request.
api_version Optional Version string representing the desired version of the OpenGDPR API. Defaults to 1.0.
extensions Required Used to hold a Swrve-specific OpenGDPR extension. This is mandatory in the Swrve API since we use it to determine the Swrve user IDs to search for. It is a JSON object, which must contain a key opengdpr.swrve.com, with a JSON object value, which in turn contains the key swrve_ids with a value of an array of strings, each one being a Swrve user ID.

Example request

{
    "subject_request_id": "a7000004-d5d6-44b2-9831-815ac9017798",
    "subject_request_type": "erasure",
    "api_version": "1.0",
    "submitted_time": "2019-12-09T00:00:00Z",
    "extensions": {
        "opengdpr.swrve.com": {
            "swrve_ids": [ "3c996335-1619-4375-869f-437c672d9535" ]
        }
     }
}

Response

The response is a JSON document (with Content-Typeapplication/json“) containing the following fields:

Field Description
controller_id A string indicating the unique identity of the app in the Swrve system.
expected_completion_time RFC 3339 date string representing the time when Swrve expects to fulfill the request. This might be a matter of days, since the request itself might initiate a complex sequence of searching and data erasure within the Swrve system. Larger or busier apps will require more time to process the request.
received_time
RFC 3339 date string representing the time when Swrve received the request.
encoded_request
Base64 encoding of the entire body of the OpenGDPR request.
subject_request_id
UUID v4 string from the originating OpenGDPR request.

Example response

{
    "controller_id": 1,
    "expected_completion_time": "2020-01-13T11:06:45.119Z",
    "received_time": "2019-12-19T11:06:45.119Z",
    "encoded_request": "eyAgInN1YmplY3RfcmVxdWVzdF9pZCI6ICJhNzAwMDAwNS1kNWQ2LTQ0YjItOTgzMS04MTVhYzkwMTc3OTgiLCAgInN1YmplY3RfcmVxdWVzdF90eXBlIjogImFjY2VzcyIsICAiYXBpX3ZlcnNpb24iOiAiMS4wIiwgICJzdWJtaXR0ZWRfdGltZSI6ICIyMDE5LTEyLTA5VDAwOjAwOjAwWiIsICAiZXh0ZW5zaW9ucyI6IHsgICAgIm9wZW5nZHByLnN3cnZlLmNvbSI6IHsgICAgICAic3dydmVfaWRzIjogWyAiM2M5OTYzMzUtMTYxOS00Mzc1LTg2OWYtNDM3YzY3MmQ5NTM1IiBdICAgIH0gIH19",
    "subject_request_id": "a7000005-d5d6-44b2-9831-815ac9017798"
}

Error codes

Errors are returned in a JSON format with HTTP response code 400/404:

{
   "code": "Error message"
}

Some error samples are provided below:

Code Error message Description
404 Blank or missing ‘swrve_ids’ are invalid The request is missing the customer’s Swrve ID, or Swrve does not recognize the user IDs you provided. Check that you have the correct Swrve user IDs.
400 Invalid POST request message The request included an invalid parameter or an invalid JSON object, based on the specification.
400 This app does not support the GDPR API Your app has not been enabled for Privacy API requests. To have your app enabled, contact your CSM at support@swrve.com.
400 Request already exists Check that the subject_request_id is correct as Swrve has already received a subject access or data erasure request for that ID.
400 Invalid or non-GDPR-typed API key Check that your API key is correct and that it’s a GDPR-type key.
400 Invalid personal key Check that your personal key is correct.