Swrve Privacy API
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.
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 that must contain a key opengdpr.swrve.com, with a JSON object value that contains the key swrve_ids or external_user_ids with a value of an array of strings, each one being a Swrve user ID or external 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": [
"3c996335-1619-4375-869f-437c672d9535"
],
"external_user_ids": [
"fa3d4a05-058d-4d4b-859a-1d804b673621"
]
}
}
}
Response
The response is a JSON document (with Content-Type “application/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:
|
| 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 that must contain a key opengdpr.swrve.com, with a JSON object value that contains the key swrve_ids or external_user_ids with a value of an array of strings, each one being a Swrve user ID or external 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"
],
"external_user_ids": [
"fa3d4a05-058d-4d4b-859a-1d804b673621"
]
}
}
}
Response
The response is a JSON document (with Content-Type “application/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. |