Consent Preference - API documentation

The Consent Preference API enables the functionality of the Consent Record, which records the consents provided by the domain users, who are referred to as ‘subjects’ within the functionality.

Base URL = https://api.primeconsent.com/api/v1

Headers

Authentication

To implement the Consent Preference, we provide the following key for the API.

Appid: an ID generated for your account on the Privacy Pillar Portal.

     See Generate your App ID to how to generate your App ID.

Content-Type

To send data to our HTTP API, the Content-Type header must be set as mentioned below.

Header['Appid'] = 'app_id' // your App IDHeader['Content-Type'] = 'application/json'

API for Consent Preference

To implement the Consent Preference module on your website the following three APIs are provided to you.

Get Consents Records (List) – Method: GET

The following API is to view the list of consent records for a specified period. 

/consent-preference/get-consent/:pid

The following is the accepted query parameters tabulation for each API, the parameters are customizable according to your website.

Parameters

The following is an example of the API response for the Consent Records list.

Response

{  "count": 1,  "response": [    {      "id": "57f1713d-b425-4021-b271-262a60c8e0ef",      "pid": "67a0d68e-94e0-492a-8221-1dabaacd375d",      "optout": false,      "country": "USA",      "owner_id": "01",      "email": "myemail@privacypillar.com",      "first_name": "Jason",      "last_name": "David",      "verified": true,      "ip_address": "59.96.171.179",      "data_source": "private", //either public or private       "additional_data":       {          "city":"Princeton",          "ZIP_Code":"400001"       },      "auth_id": "110",      "legal_notices": [        {          "id": "72f9d235-eb4f-4ee9-96ae-b6c9b2469824",          "pid": "67a0d68e-94e0-492a-8221-1dabaacd375d",          "owner_id": "01",          "consent_id": "57f1713d-b425-4021-b271-262a60c8e0ef",          "version": 1,          "identifier": "privacy_policy",          "content": "<script>",          "created_at": "2021-07-13T14:08:48.858115Z",          "updated_at": "2021-07-13T14:08:48.858115Z"        },        {          "id": "7302f00a-f174-469d-92e7-d92a50b8a83b",          "pid": "67a0d68e-94e0-492a-8221-1dabaacd375d",          "owner_id": "01",          "consent_id": "57f1713d-b425-4021-b271-262a60c8e0ef",          "version": 1,          "identifier": "terms_and_conditions",          "content": "<script>",          "created_at": "2021-07-13T14:08:48.752745Z",          "updated_at": "2021-07-13T14:08:48.752745Z"        }      ],      "proofs": [        {          "id": "3d18495f-fd1b-4ad0-8594-edfa10fe4025",          "pid": "67a0d68e-94e0-492a-8221-1dabaacd375d",          "consent_id": "57f1713d-b425-4021-b271-262a60c8e0ef",          "content": "{\"firstname\":\"Aditya\",\"lastname\":\"Mishra\",\"email\":\"gswfsadfsafe42athi@privacypillar.com\"}",          "form": "<form _ngcontent-wfc-c187=\"\" novalidate=\"\" id=\"registerForm\" ng-reflect-form=\"[object Object]\" class=\"ng-dirty ng-touched ng-valid</form>",          "created_at": "2021-07-13T14:08:48.872844Z",          "updated_at": "2021-07-13T14:08:48.872844Z"        }      ],      "preferences": [        {          "id": "f11d5c65-ab1a-4949-8ba7-c1692aa8dc30",          "pid": "67a0d68e-94e0-492a-8221-1dabaacd375d",          "consent_id": "57f1713d-b425-4021-b271-262a60c8e0ef",          "preference": "terms_and_conditions",          "allow": true,          "created_at": "2021-07-13T14:08:48.919956Z",          "updated_at": "2021-07-13T14:08:48.919956Z"        },        {          "id": "ff16fa2a-bab0-4c81-abe5-dca9d8a65e0a",          "pid": "67a0d68e-94e0-492a-8221-1dabaacd375d",          "consent_id": "57f1713d-b425-4021-b271-262a60c8e0ef",          "preference": "privacy_policy",          "allow": true,          "created_at": "2021-07-13T14:08:48.950719Z",          "updated_at": "2021-07-13T14:08:48.950719Z"        }      ],      "created_at": "2021-07-13T14:08:48.705921Z",      "updated_at": "2021-07-13T14:08:48.705921Z"    }  ],  "status": 200}

Create Consent – Method: POST

The following is the API when you create a manual consent record.

/consent-preference/create/:pid

User-info Parameters

Proof Parameters

Legal Notice Parameters

Preference Parameters

API Request Payload

{    "owner_id": "-owner-id-",    "email": "myemail@privacypillar.com",    "first_name": "Jason",    "last_name": "David",     "verified": true,    "optout": false,    "country": "USA",    "auth_id": "user-auth-id",    "data_source": "private", //'private' or 'public'    "additional_data":           {             "city":"mumbai",             "ZIP_Code":"400001"           },    "proofs": [    {           "content": "proof_1a",           "form": "form_1a"    }    ],    "legal_notices": [     {           identifier: "terms_and_conditions",           version: 1,           content: 'https://example.com/terms-and-conditions'      },     {            identifier: "privacy_policy",            version: 2,            content: 'https://example.com/privacy-policy'      }    ],    "preferences": [            { preference: 'terms_and_conditions', allow: true },            { preference: 'privacy_policy', allow: true },            { preference: 'others', allow: true },    ],  "ip_address": "127.0.0.1"}

Response

{    "consent_id": "bad07d89-4a15-4088-837b-40e4d3b2d6ee",    "message": "Record Created",    "status": 201,    "timestamp": "2021-07-27T16:38:54.873834124Z"}

Get Consent by ID – Method: GET

The Get Consent by ID function returns the details of a single consent that you select by the Consent ID.

/consent-preference/get-consent-by-id/:pid/:id

Parameters

Response

{    "id": "bad07d89-4a15-4088-837b-40e4d3b2d6ee" //Consent ID    "owner_id": "011",    "email": "myemail@privacypillar.com",    "first_name": "James",    "last_name": "David",       "verified": true,    "optout": false,    "country": "UAS",    "data_source": "Private",    "additional_data":          {            "city":"Princeton",            "ZIP_Code":"400001"           },      "proofs": [       {            "content": "content_1a",            "form": "form_1a"       },      ],      "legal_notices": [       {              identifier: "terms_and_condition",             version: 1,             content: 'https://example.com/term-and-condition'        },       {             identifier: "privacy_policy",             version: 2,             content: 'https://example.com/privacy-policy'        }       ],      "preferences": [        { preference: 'terms_and_conditions', allow: true },        { preference: 'privacy_policy', allow: true },        { preference: 'other_criteria', allow: false },       ],  "ip_address": "127.0.0.1"}

API for Legal Notices

The following are APIs to implement the Legal Notices functionality. A few examples of API request payload and the responses are provided.

Get Legal Notice Records (List) - Method: GET

The following is the API to get the list of Legal Notices shown on the Consent Details page. So, the values of pid and consent_ID are taken from that consent.

/consent-preference/legal-notices/:pid/:consentID

Header['Appid'] = // your appID

Since the Legal Notice list is shown within the Consent Details page, some values are taken from the respective consent.

Parameters

Response

{    "count": 2,    "response": [        {            "id": "0551623e-cb2d-4891-adcb-381963bb7a96",            "pid": "b41656d4-24a2-416e-9d58-1a06a0746ae7",            "owner_id": "0011",            "consent_id": "bf953fae-47d3-4e1e-865c-617908db241a",            "version": 1,            "identifier": "terms_and_conditions",            "content": "https://example.com/terms-and-conditions",            "created_at": "2021-06-21T12:58:50.256872Z",            "updated_at": "2021-06-21T22:08:11.256872Z"        },        {            "id": "05f4da35-24f1-4b54-b1b7-5e4518bc90b2",            "pid": "184176c8-2519-43ea-a019-8b3ba400fe17",            "owner_id": "0011",            "consent_id": "bf953fae-47d3-4e1e-865c-617908db241a",            "version": 2,            "identifier": "privacy_policy",            "content": "https://example.com/privacy-policy",            "created_at": "2021-06-24T09:48:17.135937Z",            "updated_at": "2021-06-24T09:48:17.135937Z"        }    ],    "status": 200}

Create Legal Noice - Method: POST

The legal notices opt-in or opt-out by the user is called create preference.

/consent-preference/legal-notices/:pid/:consentID

Header['Appid'] = // your AppID

Query Parameters

Request Payload

[      {        identifier: "terms_and_conditions",       version: 1,       content: 'https://example.com/terms-and-conditions' }, {       identifier: "privacy_policy",       version: 1,       content: 'https://example.com/privacy-policy'  }]

Response

{    "message": "Record Created",    "status": 201,}

Get Legal Notice by ID - Method: GET

The opt-in and opt-out details of the legal notices under each consent detail are shown using this API.

/consent-preference/legal-notice-by-id/:pid/:consentID/:id

Header['Appid'] = //appID

Parameters

Response

{ "response": {    "id": "07688650-a2a1-4e25-948a-59dd34a2c398",    "pid": "63208a7d-771b-4cfd-8859-b254ca5aae23",    "owner_id": "9900",    "consent_id": "a8acb22b-c548-45eb-948b-3cf23b9413d0",    "version": 1,    "identifier": "terms_and_conditions",    "content": "<content>",    "created_at": "2021-05-21T14:58:09.652965Z",    "updated_at": "2021-05-21T14:58:09.652965Z" }, "status": 200}

API for Proofs

The APIs for Proofs are given below, and a few examples of API request payload and the responses are provided.

Get Proofs Records (List) - Method: GET

The following is the API to get the list of Proofs shown on the Consent Details page. So, the values of pid and consent_id are taken from the particular consent.

/consent-preference/proofs-list/:pid/:consentID

Header['Appid'] = //appID

Parameters

Response

{  "count": 2,  "response": [    {       "id": "4bb1b901-7fa5-4d24-9ccb-ea3c75a3cfbe",       "pid": "083f0a2a-b70f-4132-ac8f-e326e6885b5d",       "consent_id": "ff827a25-756b-422d-90bf-620933e13e49",       "content": "sample_content1",       "form": "form_sample1",       "created_at": "2021-06-24T10:29:32.212923Z",       "updated_at": "2021-06-24T10:29:32.212923Z"    },    {       "id": "622f727b-93c1-4a97-8fed-5c84ff7995e7",       "pid": "083f0a2a-b70f-4132-ac8f-e326e6885b5d",       "consent_id": "ff827a25-756b-422d-90bf-620933e13e49",       "content": "sample_content2",       "form": "form_sample2",       "created_at": "2021-06-24T10:34:01.608246Z",       "updated_at": "2021-06-24T10:34:01.608246Z"    }  ],  "status": 200}

Create Proof - Method: POST

Submitting the proof details by the user is called create preference.

/consent-preference/proofs/:pid/:consentID

Header['Appid'] = // your appID

Query Parameters

Request Payload

[{"content": "sample_content","form": "sample_form"},{"content": "sample_content2","form": "sample_form2"}]

Response

{    "message": "Record Created",    "status": 201,}

Get Proof by ID - Method: GET

The proof details submitted by the user under each consent are shown using this API.

/consent-preference/proof-by-id/:pid/:consentID/:id

Header['Appid'] = //your appID

Parameters

Response

{    "response": {        "id": "ef4b83d2-ccd0-4f20-8d15-0efd2a6699e0",        "pid": "083f0a2a-b70f-4132-ac8f-e326e6885b5d",        "consent_id": "07b3757e-60d2-48d3-bb73-47dd8de8db99",        "content": "test",        "form": "test",        "created_at": "2021-06-24T10:11:59.190368Z",        "updated_at": "2021-06-24T10:11:59.190368Z"    },    "status": 200}

API for Preference

The APIs for Preference are given below, and a few examples of API request payload and the responses are provided.

Get Preference Records (List) - Method: GET

The following is the API to get the list of Preferences shown on the Consent Details page. So, the values of pid and consent_id are taken from the particular consent.

/consent-preference/preference/:pid/:consentID

Header['Appid'] = //appID

Parameters

Response

{    "count": 2,    "response": [        {            "id": "f4067ece-4978-414b-9ba3-60ac6d602260",            "pid": "67a0d68e-94e0-492a-8221-1dabaacd375d",            "consent_id": "0e8a7daf-fb9b-4927-b74e-1875676b3aae",            "preference": "terms_and_conditions",            "allow": true,            "created_at": "2021-07-21T07:45:52.940978Z",            "updated_at": "2021-07-21T07:45:52.940978Z"        },        {            "id": "l6167rfg-4978-546b-9rt3-23dg6d602260",            "pid": "67a0d68e-94e0-492a-8221-1dabaacd375d",            "consent_id": "0e8a7daf-fb9b-4927-b74e-1875676b3aae",            "preference": "privacy_policy",            "allow": true,            "created_at": "2021-07-21T07:45:52.940978Z",            "updated_at": "2021-07-21T07:45:52.940978Z"        }    ],    "status": 200}

Create Preference - Method: POST

The preference opt-in or opt-out by the user is called create preference.

/consent-preference/preference/:pid/:consentID

Header['Appid'] = //appID

Query Parameters

Request Payload

[    {    "allow": true,    "preference": "privacy_policy"    },    {    "allow": true,    "preference": "terms_and_conditions"    }]

Response

{"message": "Record Created","status": 201,}

Get Preference by ID - Method: GET

The opt-in and opt-out details of the preference under each consent detail are shown using this API.

/consent-preference/preference-by-id/:pid/:consentID/:id

Header['Appid'] = //appID

Parameters

Response

{    "response": {        "id": "f4067ece-4978-414b-9ba3-60ac6d602260",        "pid": "67a0d68e-94e0-492a-8221-1dabaacd375d",        "consent_id": "0e8a7daf-fb9b-4927-b74e-1875676b3aae",        "preference": "terms_and_conditions",        "allow": true,        "created_at": "2021-07-21T07:45:52.940978Z",        "updated_at": "2021-07-21T07:45:52.940978Z"    },    "status": 200}