LiveIntent Privacy Management API

January 05, 2022 19:50

The LiveIntent Privacy Management API supports businesses that interact with LiveIntent in managing their obligations for user privacy under CCPA and GDPR. The API offers services that allow Issuers to request data-deletion, opt-out, or data access requests submitted to LiveIntent.

The API is intended to be invoked on a per-user basis in response to a request from the user to manage their privacy settings with the Issuer. Batch or bulk operations are not covered by this API.

Terms

Issuer

A publisher, advertiser, or data partner who interacts with LiveIntent’s services.

Data Subject

A user with whom the Issuer has a relationship.

Data Subject Request (DSR)

A JSON message requesting an action to be performed by LiveIntent with respect to data processing connected to the Data Subject that LiveIntent manages on behalf of the Issuer.

Environments and Base URLs

Staging Environment

API Base URL: https://privacy-auth.liveintenteng.com/

LiveIntent provides a staging environment that may be used to validate the proper message and protocol formats. This environment is intended for testing and integration purposes only - it does not access or provide any real user data. Access to this environment is protected by customer-specific keys, or alternatively, publishers may use the example publisher/key provided in Appendix A at the end of this article.

Production Environment

API Base URL: https://privacy-auth.liveintent.com/

The production environment is where user-request transactions are processed. Access to this environment is protected by customer-specific keys.

Service Endpoints

The following service endpoints are available for use by Issuers.

POST/dsr

URL	${API_BASE_URL}/dsr
method	POST
content-type	application/json or application/x-www-form-urlencoded
response	application/json

Data Subject Requests

Issuers may submit requests to LiveIntent to affect the processing of data for a Data Subject.

The following fields are available for a Data Subject Request (DSR).

Field	Description
domain	The predetermined value for the Issuer's domain name. This is a required field.
requestType	The request type of the message. This is a required field.
scope	The jurisdiction under which the privacy request is being submitted. This is a required field.
emailAddress	The raw or hashed email address of the data subject. This is a required field.
callbackURL	Callback URL to signal that the request was fully processed (see Callbacks section below). This is required when requestType='ACCESS'.

domain

The domain field is a fixed value that identifies the Issuer making the API call. This field is used in combination with the API key to authenticate the request and is set during the API Key provisioning process.

requestType

The requestType field describes the action to be taken on the Data Subject. The following actions are supported.

Request Type	Description
ERASURE	Delete the data that LiveIntent maintains on behalf of the Issuer for the requested user.
RESTRICT	Opt-out of future data-processing that LiveIntent manages on behalf of the Issuer for the requested user.
ACCESS	Retrieve information and data that LiveIntent maintains on behalf of the Issuer for the requested user.

scope

The scope field describes the legal jurisdiction covering the request.

Request Type	Description
EU_PRIVACY	The request is being submitted under the jurisdiction of GDPR.
US_PRIVACY	The request is being submitted under the jurisdiction of CCPA.

emailAddress

The emailAddress field contains the raw or hashed email address of the Data Subject. For hashed email addresses, the address should be trimmed of leading/trailing spaces and translated to lower-case before hashing. The supported hash algorithms include MD5, SHA1, and SHA256.

callbackURL

Data Subject Requests are processed in an asynchronous manner and are not immediately completed when received. The callbackURL field may contain the URL for an HTTPS endpoint that will be triggered upon the successful completion of the Data Subject Request. (See the Callbacks section after the example request below). The callbackURL field is required when requestType='ACCESS'.

Example request

curl "${API_BASE}/dsr" 
  -H "Content-Type: application/json" 
  -H "Authorization: bearer ${ACCESS_KEY}" 

  -d '{ 
    "domain": "dailyplanet.com",
    "requestType": "ERASURE",
    "scope": "US_PRIVACY",
    "emailAddress": "user@domain.com"
  }'

Callbacks

Whenever a data subject request is submitted to LiveIntent's privacy API, the callbackUrl parameter may be provided. If present, the value must specify an HTTPS endpoint. LiveIntent data processing systems will submit a POST request to the callback url once the Data Subject Request is successfully completed.

Callback notifications contain an Authorization header with a bearer token. The bearer token value is a signed JWT message containing the details of the dsr request and is signed using the issuer's ${ACCESS_KEY} via the RSA256 signing algorithm. (NOTE: When passing the private key as a header, strip the header/footer lines and concatenate all of the key lines together into a single string.)

The issuer may decode the JWT header and verify the signature using the corresponding public key before processing the notification. For more information about JWT tokens, see https://jwt.io

Example decoded JWT Authorization header payload:

{
  "iss": "CN=example.com",
  "iat": 1514761200,
  "exp": 1609459200,
  "jti": "35c087f5-7386-4eca-8a1f-6f65a0357612",
  "cnf": {
    "kid": "li-key"
  },
  "dsr": {
    "type": "ERASURE",
    "scope": "US_PRIVACY",
    "target": "https://example.com/dsr/notification",
    "identifiers": [ 
      {
        "type": "EMAIL_HASH",
        "values": [ 
          "cd2bfcffe5fee4a1149d101994d0987f",
          "c35f2956d804e01ef2dec392ef3adae36289123f",
      "f7ee5ec7312165148b69fcca1d29075b14b8aef0b5048a332b18b88d09069fb7" 
        ]
      } 
    ]
  }
}

For ACCESS requests, the body of the request will be a JSON message containing the URL and expiration of the requested downloadable data file.

Example ACCESS request callback message body:

{
  "url": "https://...URL to download the requested data file...",
  "expiration": "ISO-8601 formatted date"
}

Appendix

Staging environment example publisher

As mentioned above, Issuers must submit one or more signing keys to LiveIntent for use in the staging and production environments. To get started with the integration process, the following example publisher credentials are available for use in the staging environment. The staging environment does not have access to any user data and transactions are not actually processed.

Integrating developers may make use of these identifiers/keys while their submitted keys are being provisioned by LiveIntent.

Sample Publisher iss: CN=dailyplanet.com

Sample Publisher RSA Key:

Sample Publisher RSA Public Key: