Data Privacy API
The SessionM Platform provides functions that support the following data privacy requests directly within the platform:
- Rights to Data Access and Rectification: When asked, a company must be able to confirm whether it is collecting personal data and provide it in a readable format. Errors in customer data must be able to be rectified if requested.
- Right to Be Forgotten: A company must be able to quickly remove all data about a known consumer and confirm this removal.
- Right to Object or Restrict Processing: A company must restrict or block the processing of personal data by freezing data subject records.
The Data Privacy API supports the creation and maintenance of requests on behalf of customers to forget or export privacy data. In addition, the API can be used to create requests that restrict or reinstate a customer's access to marketing programs as well as to app or web portal access - if using SessionM’s identity services product. These data privacy features are available to all clients committed to fulfilling customer requests seeking to safeguard or review their own personal data.
Note that not all of the Data Privacy functionality is available via platform APIs. In some cases, such as data exports, the API supports the submission of export requests, but not the retrieval of the exported data file. For that, the SessionM Platform operator must retrieve the customer’s data files via the customer profile UI for that specific customer. For more information, see the article that details the implementation of Data Privacy in the SessionM Platform UI and any dependencies between the UI and the APIs.
This API provides the following methods:
- Retrieve All Privacy Requests
- Create Request to Forget Customer Data
- Create Request to Export Customer Data
- Retrieve All Requests to Export Customer Data
- Create Request to Restrict or Reinstate Customer
Retrieve All Privacy Requests
Gets all data privacy requests initiated by all platform users on behalf of customers.
Endpoints
This method offers the following endpoints:
GET /priv/v1/apps/:api_key/users/:user_id/privacy
GET /priv/v1/apps/:api_key/external/users/:external_id/privacy For more information on how to specify an endpoint as part of an actual URL, see Before You Begin. The procedure in this section includes a sample URL for a customer transaction.
Endpoint Parameters
The following parameters are available when specifying the endpoint for this method:
| Endpoint Parameter | Description |
|---|---|
| api_key | Supplied by the SessionM Platform, the API key is necessary to authenticate any HTTP request to a SessionM API. This key is associated to an API secret, which ties the authentication to a specific application or web site within the organization. The platform maintains each application or site as a digital property, something that can be configured using the SessionM UI. |
| user_id | Internal identifier for the customer within the SessionM Platform. |
| external_id | Identifier for a customer in an external system integrating with the SessionM Platform. |
Request Object
Not applicable.
Response Object
In addition to a status key-value pair, the response object returned by the method contains a privacy_response array, populated with one or more privacy requests, as shown below:
{
status: ok,
privacy_requests:
[
{
"user_id": "4f5b82c0-07c8-11e6-8d84-624132d14633",
"status": "completed",
"export_data_status": "completed"
}
]
}This object is documented in the following table:
Response Attributes for Privacy
| Attribute | Type | Description |
|---|---|---|
| user_id | string | Internal identifier for the customer within the SessionM Platform. |
| status | string | Status of any privacy request. Possible values include: completed and in_progress. |
| export_data_status | string | Status of job being run to export data for a customer. Possible values include: completed and in_progress. Passed as a parameter only if privacy request has type. |
Statuses and Errors
When this method makes a successful call to the platform, it returns a 200-level status code. When the string returned with a 200-level status code is ok, the transaction did process. But, if the string returned is error, you need to discover what type of error occurred.
Keep in mind the following error conditions:
- Any request that is restricted throws a 403.
- With respect to export data, if Marmot is not set up correctly, a "service not available" message is returned.
For more information on generic errors, see the associated section in Generic Statuses and Errors.
Create Request to Forget Customer Data
Creates request to forget any customer information, such as an email address or a physical address as well as any loyalty data about available offers and earned achievements. Once implemented, the customer account and all associated data is removed from any loyalty or marketing programs.
Before executing the request, it is recommended that a check is performed to confirm the customer’s identity and that they do, in fact, want to proceed with the erasure request. This action cannot be undone.
Endpoints
This method offers the following endpoints:
POST /priv/v1/apps/:api_key/users/:user_id/privacy/forget
POST /priv/v1/apps/:api_key/external/users/:external_id/privacy/forget For more information on how to specify an endpoint as part of an actual URL, see Before You Begin. The procedure in this section includes a sample URL for a customer transaction.
Endpoint Parameters
The following parameters are available when specifying the endpoint for this method:
| Endpoint Parameter | Description |
|---|---|
| api_key | Supplied by the SessionM Platform, the API key is necessary to authenticate any HTTP request to a SessionM API. This key is associated to an API secret, which ties the authentication to a specific application or web site within the organization. The platform maintains each application or site as a digital property, something that can be configured using the SessionM UI. |
| user_id | Internal identifier for the customer within the SessionM Platform. |
| external_id | Identifier for a customer in an external system integrating with the SessionM Platform. |
Request Object
Not applicable.
Response Object
The response object contains only a status key-value pair as shown below:
Statuses and Error
When this method makes a successful call to the platform, it returns a 200-level status code. When the string returned with a 200-level status code is ok, the transaction did process. But, if the string returned is error, you need to discover what type of error occurred.
Keep in mind the following error conditions:
- Any request that is restricted throws a 403.
- With respect to export data, if Marmot is not set up correctly, a "service not available" message is returned.
For more information on generic errors, see the associated section in Generic Statuses and Errors.
Create Request to Export Customer Data
Creates an export data request which generates a CSV file of the customer’s data. The exported CSV file contains data from a customer profile as well as any data derived from calculated metrics, purchases, marketing and loyalty program-related events, and application sessions.
The exported CSV files contain data from a customer profile as well as any data derived from calculated metrics, purchases, marketing and loyalty program-related events, and application sessions. Specifically, the following data is provided to the client:
- Standard customer profile
- Appended data
- Calculated metrics
- Transaction data
- Loyalty points, tiers, offers data
- Tag data
Bear in mind that this API currently allows for the submission of requests, but the SessionM Platform operator can only get the customer’s data files from the customer profile UI for that specific customer. For more information, see this article's discussion on turnaround expectations for the export file delivery.
Endpoints
This method offers the following endpoints:
POST /priv/v1/apps/:api_key/users/:user_id/privacy/export
POST /priv/v1/apps/:api_key/external/users/:external_id/privacy/export For more information on how to specify an endpoint as part of an actual URL, see Before You Begin. The procedure in this section includes a sample URL for a customer transaction.
Endpoint Parameters
The following parameters are available when specifying the endpoint for this method:
| Endpoint Parameter | Description |
|---|---|
| api_key | Supplied by the SessionM Platform, the API key is necessary to authenticate any HTTP request to a SessionM API. This key is associated to an API secret, which ties the authentication to a specific application or web site within the organization. The platform maintains each application or site as a digital property, something that can be configured using the SessionM UI. |
| user_id | Internal identifier for the customer within the SessionM Platform. |
| external_id | Identifier for a customer in an external system integrating with the SessionM Platform. |
Request Object
Not applicable.
Response Object
In addition to a status key-value pair, the response object returned by the method contains a message string, which indicates that the export is being processed and is shown below:
Statuses and Errors
When this method makes a successful call to the platform, it returns a 200-level status code. When the string returned with a 200-level status code is ok, the transaction did process. But, if the string returned is error, you need to discover what type of error occurred.
Keep in mind the following error conditions:
- Any request that is restricted throws a 403.
- With respect to export data, if Marmot is not set up correctly, a "service not available" message is returned.
For more information on generic errors, see the associated section in Generic Statuses and Errors.
Retrieve All Requests to Export Customer Data
Gets all data requests initiated by all platform users to export privacy data.
Endpoints
This method offers the following endpoints:
GET /priv/v1/apps/:api_key/users/:user_id/privacy/export
GET /priv/v1/apps/:api_key/external/users/:external_id/privacy/export For more information on how to specify an endpoint as part of an actual URL, see Before You Begin. The procedure in this section includes a sample URL for a customer transaction.
Endpoint Parameters
The following parameters are available when specifying the endpoint for this method:
| Endpoint Parameter | Description |
|---|---|
| api_key | Supplied by the SessionM Platform, the API key is necessary to authenticate any HTTP request to a SessionM API. This key is associated to an API secret, which ties the authentication to a specific application or web site within the organization. The platform maintains each application or site as a digital property, something that can be configured using the SessionM UI. |
| user_id | Internal identifier for the customer within the SessionM Platform. |
| external_id | Identifier for a customer in an external system integrating with the SessionM Platform. |
Request Object
Not applicable.
Response Object
In addition to a status key-value pair, the response object returned by the method contains a gdpr_user_data array, populated with one or more export requests, as shown below:
{
"status": "ok",
"gdpr_user_data": [
{
"user_id": "4f5b82c0-07c8-11e6-8d84-624132d14633",
"export_data_status": "completed"
}
]
}This object is documented in the following table:
Response Attributes for GDPR User Data
| Attribute | Type | Description |
|---|---|---|
| user_id | string | Internal identifier for the customer within the SessionM Platform. |
| export_data_status | string | Status of job being run to export data for a customer. Possible values include: completed and in_progress. Passed as a parameter only if privacy request has type. |
Statuses and Errors
When this method makes a successful call to the platform, it returns a 200-level status code. When the string returned with a 200-level status code is ok, the transaction did process. But, if the string returned is error, you need to discover what type of error occurred.
Keep in mind the following error conditions:
- Any request that is restricted throws a 403.
- With respect to export data, if Marmot is not set up correctly, a "service not available" message is returned.
For more information on generic errors, see the associated section in Generic Statuses and Errors.
Create Request to Restrict or Reinstate Customer
Creates a request that toggles a user between a status of "Restrict" and "Reinstate". Restricting a customer removes their ability to participate in marketing campaigns and audience inclusion, as managed by SessionM’s Campaigns and Audiences Modules. Doing so also removes their ability to log into an app or web portal experience, if SessionM’s identity services product is used.
It's important to note that the data is NOT removed; only access to the data is temporarily paused. Reinstating a customer re-establishes their ability to take the actions mentioned above that had restricted processing. If a restrict request is in progress, the reinstate route will not work and visa versa.
Endpoints
This method offers the following endpoints:
POST /priv/v1/apps/:api_key/users/:user_id/privacy/restrict
POST /priv/v1/apps/:api_key/external/users/:external_id/privacy/restrict For more information on how to specify an endpoint as part of an actual URL, see Before You Begin. The procedure in this section includes a sample URL for a customer transaction.
Endpoint Parameters
The following parameters are available when specifying the endpoint for this method:
| Endpoint Parameter | Description |
|---|---|
| api_key | Supplied by the SessionM Platform, the API key is necessary to authenticate any HTTP request to a SessionM API. This key is associated to an API secret, which ties the authentication to a specific application or web site within the organization. The platform maintains each application or site as a digital property, something that can be configured using the SessionM UI. |
| user_id | Internal identifier for the customer within the SessionM Platform. |
| external_id | Identifier for a customer in an external system integrating with the SessionM Platform. |
Request Object
Not applicable.
Response Object
The response object contains only a status key-value pair as shown below:
Statuses and Errors
When this method makes a successful call to the platform, it returns a 200-level status code. When the string returned with a 200-level status code is ok, the transaction did process. But, if the string returned is error, you need to discover what type of error occurred.
Keep in mind the following error conditions:
- Any request that is restricted throws a 403.
- With respect to export data, if Marmot is not set up correctly, a "service not available" message is returned.
For more information on generic errors, see the associated section in Generic Statuses and Errors.