Knowledge Base

LiveIntent Privacy Management API

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.

 

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

Type

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.

Target

Callback URL to signal that the request was fully processed (see Callbacks section below).
This is a required field.

Identifiers

A JSON array of identifier types and values. Usage differs by service endpoint.

 

dsr.type

The dsr.type 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.

OBJECT

Alias for restrict.

ACCESS

Retrieve information and data that LiveIntent maintains on behalf of the Issuer for the requested user.

 

dsr.scope

The dsr.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.



dsr.identifiers

The dsr.identifiers field is a JSON array of objects. Each object specifies an identifier type and an array of identifier values. 

Please Note 

If multiple identifiers are included in a request, they should all refer to the same Data Subject.

 "identifiers": [ 
    {
      "type": "IDENTIFIER_TYPE_1",
      "values": [ 
        "identifier_1a",
        "identifier_1b"
      ]
    },
    {
      "type": "IDENTIFIER_TYPE_2",
      "values": [ 
        "identifier_2a",
        "identifier_2b",
        "identifier_2c"
      ]
    }    
  ]

 

Below is a list of identifier types currently supported (additional types may be supported in the future):

Identifier Type

Description

EMAIL_HASH

MD5, SHA1, or SHA256 hash of the user’s email address. 

The email address should be trimmed of leading/trailing spaces and translated to lower-case before hashing.

 

DSR Example

{
  "type":"ERASURE",
  "scope": "US_PRIVACY",
  "target":"https://example.com/callback",
  "identifiers": [ 
    {
      "type": "EMAIL_HASH",
      "values": [ 
        "b2796b8582ffbb8e7a5419f41544da9e",
        "10b5449edce5d623d979592bea3050b4af30a4b8",
      "34d31be18022626de6b311d6a76e791176d2691b6eef406f524d8f56364c187a"
      ]
    } 
  ]
}

 

 

JSON Web Tokens

The LiveIntent Privacy Management API makes use of RSA-signed JSON Web Tokens (JWT) to authenticate and encode DSR requests. 

JWT is an open, industry-standard RFC 7519 method for securely representing claims between two parties. JWT allows the sending party to generate and sign a JSON-based message and then encode the message for easy transport. The receiving party can verify the authenticity of the JWT message using the embedded signature before processing the contents of the message. For more information about JWT, please reference this site.

 

Supported claims

The following JWT claims are in use:

Claim

Description

Example

iss

Issuer (publisher/advertiser/data partner) formatted asn.1 DN string. 

CN=Daily Planet, L=Gotham City, C=US

iat

Issue timestamp (unix epoch format).

1514761200

exp

Expire timestamp (unix epoch format).

1514847600

aud

Intended audience.

An optional field that the Issuer can use to identify the LiveIntent service.

privacy.liadm.com

jti

JWT Identifier: Optional ID, which Issuer can use to identify this token.

22323423

cnf.kid

Signing key ID (see below).

key1

dsr

Data Service Request to be processed.

See the above example.

 

JWT Payload Example

Using the DSR Example from above.

{  
  "iss": "CN=dailyplanet.com",
  "iat": 1514761200,
  "exp": 1609459200,
  "jti": "35c087f5-7386-4eca-8a1f-6f65a0357612",
  "cnf": {
    "kid": "key1"
  },
  "dsr": {
    "type": "ERASURE",
    "scope": "US_PRIVACY",
    "target": "http://dailyplanet.com/callback",
    "identifiers": [ 
      {
        "type": "EMAIL_HASH",
        "values": [ 
          "b2796b8582ffbb8e7a5419f41544da9e",
          "10b5449edce5d623d979592bea3050b4af30a4b8",
      "34d31be18022626de6b311d6a76e791176d2691b6eef406f524d8f56364c187a" 
        ]
      } 
    ]
  }
}

 

Signing Keys

Each publisher must submit to LiveIntent one or more RSA public keys and the corresponding key identifiers to be used when verifying messages sent by the publisher. The cnf.kid field in the JWT indicates which key the publisher has used to sign the message. LiveIntent will use the common name (CN=) segment from the iss claim combined with the cnk.kid to identify which previously exchanged RSA public key should be used to validate the message signature before processing the request.

 

JWT Signature Example

The following is the calculated JWT Signature when signing the JWT Payload Example from above, using the signing key in Appendix A: Staging Environment Example Publisher.

eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJDTj1kYWlseXBsYW5ldC5jb20iLCJpYXQiOjE1MTQ3NjEyMDAsImV4cCI6MTYwOTQ1OTIwMCwianRpIjoiMzVjMDg3ZjUtNzM4Ni00ZWNhLThhMWYtNmY2NWEwMzU3NjEyIiwiY25mIjp7ImtpZCI6ImtleTEifSwiZHNyIjp7InR5cGUiOiJFUkFTVVJFIiwic2NvcGUiOiJVU19QUklWQUNZIiwidGFyZ2V0IjoiaHR0cDovL2RhaWx5cGxhbmV0LmNvbS9jYWxsYmFjayIsImlkZW50aWZpZXJzIjpbeyJ0eXBlIjoiRU1BSUxfSEFTSCIsInZhbHVlcyI6WyJiMjc5NmI4NTgyZmZiYjhlN2E1NDE5ZjQxNTQ0ZGE5ZSIsIjEwYjU0NDllZGNlNWQ2MjNkOTc5NTkyYmVhMzA1MGI0YWYzMGE0YjgiLCIzNGQzMWJlMTgwMjI2MjZkZTZiMzExZDZhNzZlNzkxMTc2ZDI2OTFiNmVlZjQwNmY1MjRkOGY1NjM2NGMxODdhIl19XX19.d2mWbxgRsjJXZZxKIy2cmcUNxpsVIyOPGtRKwEHHu3FfvOCJ8KbNwlr5V2DZuPWEhpS7b66t3wR4tR7ayfslJnqdk8r1sv8B47fH5ZOtKCyr7xzaRhFNGx3Coojbn61kaiKDnKc4gXZRUWUaCNBQQ4f6_ORYxs9uf4RjWvdjqis

Colors indicate the JWT header, payload, and signature. See this on jwt.io.


Service Endpoints

The following service endpoints are available for use by Issuers.

 

GET /submit

URL

/submit?dsr={JWT Encoded DSR Request}

Method

GET

Headers

Cookie: "lidid=..." 

This is required.

Description

This endpoint is designed to be called directly from the Data Subject’s browser via an embedded image pixel. The endpoint uses LiveIntent’s third-party cookie to identify the Data Subject. For this reason, the dsr.identifier field should not be included when calling this endpoint.

Response

Image/gif (a 1x1 transparent pixel).

 

Please Note

If the incoming request does not contain a "lidid" cookie, the service will return an error.

 

POST /dsr

URL

/dsr

Method

POST

Content-Type

application/json

Body

{ "jwt": "JWT Encoded DSR Request" }

Description

This endpoint is designed to be called as a server-to-server JSON based API and requires the publisher to submit the list of known user-identifying values in the dsr.identifiers claim.

Response

application/json

 

Example Request

curl https://gdpr-test.cph.liveintent.com/dsr -H "Content-type: application/json" -d '{"jwt":"eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJDTj1kYWlseXBsYW5ldC5jb20iLCJpYXQiOjE1MTQ3NjEyMDAsImV4cCI6MTYwOTQ1OTIwMCwianRpIjoiMzVjMDg3ZjUtNzM4Ni00ZWNhLThhMWYtNmY2NWEwMzU3NjEyIiwiY25mIjp7ImtpZCI6ImtleTEifSwiZHNyIjp7InR5cGUiOiJFUkFTVVJFIiwic2NvcGUiOiJVU19QUklWQUNZIiwidGFyZ2V0IjoiaHR0cDovL2RhaWx5cGxhbmV0LmNvbS9jYWxsYmFjayIsImlkZW50aWZpZXJzIjpbeyJ0eXBlIjoiRU1BSUxfSEFTSCIsInZhbHVlcyI6WyJiMjc5NmI4NTgyZmZiYjhlN2E1NDE5ZjQxNTQ0ZGE5ZSIsIjEwYjU0NDllZGNlNWQ2MjNkOTc5NTkyYmVhMzA1MGI0YWYzMGE0YjgiLCIzNGQzMWJlMTgwMjI2MjZkZTZiMzExZDZhNzZlNzkxMTc2ZDI2OTFiNmVlZjQwNmY1MjRkOGY1NjM2NGMxODdhIl19XX19.d2mWbxgRsjJXZZxKIy2cmcUNxpsVIyOPGtRKwEHHu3FfvOCJ8KbNwlr5V2DZuPWEhpS7b66t3wR4tR7ayfslJnqdk8r1sv8B47fH5ZOtKCyr7xzaRhFNGx3Coojbn61kaiKDnKc4gXZRUWUaCNBQQ4f6_ORYxs9uf4RjWvdjqis"}'

Colors indicate the JWT header, payload, and signature. See this on jwt.io.


Callbacks

When LiveIntent has successfully completed the processing of a Data Service Request that contains a callback URL in the dsr.target property, a POST request will be made to the specified callback target. The authorization header for the request will contain the original JWT Web Token that the Issuer used to submit the request. In the case of ACCESS request types, the body of the request will also contain the available information about the Data Subject.

 

Environments and URLs

Staging Environment

API Base URL: https://gdpr-test.cph.liveintent.com/

LiveIntent provides a staging environment that may be used to validate the proper message and protocol formats. This environment is intended to be used for testing and integration purposes only. The staging environment 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.

 

Production Environment

API Base URL: https://privacy.liadm.com/

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

 

Appendix A: 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 cnf.kid: key1

Sample Publisher RSA Key:

-----BEGIN RSA PRIVATE KEY-----

MIICWwIBAAKBgQCXetR4Wz3YxxEZxArubSXHtkACZ9CIPvc7r9AqmfCR4UM+xG5G

7VMU8KRDZrmEaKUzHWVmRSolDIGPFGXjv+csAzBA2aASI4PkxbeYov7xYFD1lQ4k

TTeg+bj0UaivNOChFUHMWwe5I/sVh7wcwIA1kJfQ15lJOgwBfz5fP8URKwIDAQAB

AoGALj0jQD3xygsx8CCEibUtlCHQtitEX2KBC2oma+qjoZQWd8F0PBhThQ/TxHNF

6+IZk1nEywwPylFf9vHuDDBW+wMg9oErNd6C/KlsVaPth/cQxWU5E5IlaANg5rKA

4VbisjXDkc0H/UXc+Dka4CGwfbdHm7ZylCXgYKNtlLtqcRECQQDFqBe6rz/B3vsU

nxyIxPo6BkrVtKhZHoyy+O69qAfy+VpDBnaA3kUWXwvVpvu1QGkdOYMeKJ1j0jYb

2Ayj3tQpAkEAxDFj5RcLnL3dSVORGUBt3uOOqJc+g2JQMZkbElM+9CZMtvOqghWQ

LrLuJKaqADkjnNNrhwRZ+49ivRBnJdwFMwJAVFN6jDLoSJYRGKMpUVB4UPkORE5m

5F6cOF7rvA5MFeU8FQxU0nYBk6HJMsWi7ZklP0qiHePGAihU3Vw3SFJwwQJATKhb

ttyNTf4lo4wCatJw26EgUaFe7KkSWn7PRBbAx1bbrLSCj/dq8cQ6Jpn0XMf2sUUu

g3/gxNkepG7vTqysXwJAE23D11+RZW4hM92TC8zohTw/jgEXR/klWMWykMuidc+M

t1n7m+87k1K1LL11cfK3X4jbdfv0am1EDOtsPIhvzQ==

-----END RSA PRIVATE KEY-----

 

Sample Publisher RSA Public Key:

-----BEGIN PUBLIC KEY-----

MIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQCXetR4Wz3YxxEZxArubSXHtkAC

Z9CIPvc7r9AqmfCR4UM+xG5G7VMU8KRDZrmEaKUzHWVmRSolDIGPFGXjv+csAzBA

2aASI4PkxbeYov7xYFD1lQ4kTTeg+bj0UaivNOChFUHMWwe5I/sVh7wcwIA1kJfQ

15lJOgwBfz5fP8URKwIDAQAB

-----END PUBLIC KEY-----

 

Was this article helpful?
1 out of 1 found this helpful
Powered by Zendesk