PII Opt-Out Request APIs
The Conviva pii-opt-out API provides a programmatic way to request that Conviva delete Personally Identiable Information (PII) data based on specified viewer IDs. Also, use this API to view lists of PII requests and the request status. Successful requests progress through the stages of ENQUEUED, STARTED, and FINISHED.
Note: When a user opt-out request is processed, the user's data is also removed from unique viewers and other related data. As a result, the related metric values will not include the anonymized user data.
An optional email address can be added to the request to receive email notification when the request status changes to FINISHED.
This API supports POST and GET requests.
-
Use the POST API to submit an opt-out request for PII data deletion. After submission, the request status is ENQUEUED. When Conviva begins work on the request, Conviva updates the status to either STARTED, indicating the data deletion is in-progress, or FINISHED, indicating the request process is complete.
Contact Conviva Support (support@conviva.com) about the rejected requests. -
Use the GET API to return a list of PII queued, started, and finished requests or the individual status of a specific request.
Data Sovereignty
To ensure complete data sovereignty, Conviva completely removes the PII data (viewer IDs and IP addresses) automatically within 30 days of receiving the PII data and stops collecting PII data immediately upon receiving an opt-out request.
Configure Conviva applications so as not to pass the Viewer ID to Conviva. Also, EU IP addresses can be encrypted or dropped, so they do not pass through the Conviva web gateway.
IP address processing options:
-
Obfuscated with MD5 encryption and a proprietary Conviva salt (irreversible).
-
Dropped at the Conviva web gateway.
Submit a PII Data Deletion Request
To submit a PII data deletion request, use the POST https://api.conviva.com/pii-opt-out API call with the requested viewer IDs in the API payload. Each API request accepts up to 100 identifers using viewer IDs.
For the API credentials, use the client or application-based credentials generated in Pulse from the API Management page, accessed from the Pulse Settings menu. For more details, see Pulse API Management page. Be sure to specify the API key associated with the account from which viewer’s request is sent.
Note: Using API credentials from a different account in the opt-out request will not block sending the PII request to Conviva, but may prevent the request from being processed.
Viewer IDs are available in the Pulse Viewer Module pages.
POST https://api.conviva.com/pii-opt-outSample Request
{
"viewer_id": ["viewer1", "viewer2", "viewer3", ...],
"@notification_email": ["email@company.com"]
}The API response returns the request id of the created opt-out request along with the number of viewer identifiers created in the request, and the number of previously submitted identifiers that were ignored. If all identifiers were previously submitted, the request is rejected.
Sample Response
{
"id": "00f49083-234d-4f52-8625-a2847eba7cf8",
"created": 100, ENQUEUED, STARTED, FINISHED. Example: status=ENQUEUED|
#### Sample GET Request with Optional Filters
```url
GET https://api.conviva.com/pii-opt-out?limit=2&start=2020-02-15&end=2020-03-15&status=STARTED,FINISHED
The API response returns a list of the matching PII request data.
{
"id": "829ccabb-9411-4094-a4d4-71b0acde14d1",
"status": "STARTED",
"@notification_email": [ "email@company.com" ],
"created_at": "2020-06-04 19:36:05 UTC",
"identifiers": { "viewer_id": ["viewer1", "viewer2"] }
}Retrieve Status for a PII Request
To retrieve the status of a specific PII request, use the GET https://api.conviva.com/pii-opt-out?id={id} API call with the request ID parameter in the API call.
Sample Request
GET https://api.conviva.com/pii-opt-out?id=477180be-52a0-44f8-b909-b2c40d48934aThe API response returns the status and data of the matching opt-out request.
{
"status": "ENQUEUED",
"creator": "user@conviva.com",
"created_at": "2020-02-06 19:24:14 PST",
"updated_at": "2020-02-06 19:24:14 PST",
"identifiers": {
"viewer_id": ["viewer_id1", "viewer_id2"]
},
"id": "477180be-52a0-44f8-b909-b2c40d48934a"
}Run Test PII Requests
It can be useful to run test pii-opt-out API calls to verify the API call syntax and response formats as well as prepare for the integration of Conviva's PII opt-out process with other PII tracking systems.
To run test pii-opt-out API calls, Conviva recommends making the API calls from the c3.-Test account. Also, email Conviva Support (support@conviva.com) so the Support Team can monitor the test requests and help verify the opt-out process.
Success Responses
A successful API response returns a 201 HTTP success code for PII data request creation, retrieval, or deletion.
Error Responses
If an error occurs while processing an opt-out request, the request is returned with a 400 or 500 series HTTP status code.
In most cases, wait several minutes and retry the request.