Consent forms

These set of APIs deal with building consent form HTML pages using defined templates. Here is a more detailed explanation of how this works.

New consent form for a subject

These APIs create a new consent form and return the HTML content for a data subject. These forms are not initialized with the current consent status of the data subject.

POST https://api.consentgrid.io"/v1/consentforms/web/{templateName}/subjects/{subjectType}/{subjectId}?locale=en&subjectOption=option&ok=ok_uri&err=err_uri&by.id=id&by.type=user
Authorization: Bearer apiKey
Content-Type: application/json
Accept: application/json | text/html
GET https://api.consentgrid.io"/v1/consentforms/web/{templateName}/subjects/{subjectType}/{subjectId}?locale=en&subjectOption=option&ok=ok_uri&err=err_uri&by.id=id&by.type=user
Authorization: Bearer apiKey
Accept: application/json | text/html
POST https://api.consentgrid.io/v1/my/consentforms/{acct}/web/{templateName}?locale=en&subjectOption=option&ok=ok_uri&err=err_uri&by.id=id&by.type=user
cookie cgs_{accountURL}: session
Content-Type: application/json
Accept: application/json | text/html
GET https://api.consentgrid.io/v1/my/consentforms/{acct}/web/{templateName}?locale=en&subjectOption=option&ok=ok_uri&err=err_uri&by.id=id&by.type=user
cookie cgs_{accountURL}: session
Accept: application/json | text/html

Consent form initialized based on the latest consent status

These APIs create a new consent form, intialize it using the current consent status of the data subject, and return the HTML content for the form.

POST https://api.consentgrid.io"/v1/consentforms/web/{templateName}/subjects/{subjectType}/{subjectId}/latest?locale=en&subjectOption=option&ok=ok_uri&err=err_uri&by.id=id&by.type=user
Authorization: Bearer apiKey
Content-Type: application/json
Accept: application/json | text/html
GET https://api.consentgrid.io"/v1/consentforms/web/{templateName}/subjects/{subjectType}/{subjectId}/latest?locale=en&subjectOption=option&ok=ok_uri&err=err_uri&by.id=id&by.type=user
Authorization: Bearer apiKey
Accept: application/json | text/html
POST https://api.consentgrid.io/v1/my/consentforms/{acct}/web/{templateName}/latest?locale=en&subjectOption=option&ok=ok_uri&err=err_uri&by.id=id&by.type=user
cookie cgs_{accountURL}: session
Content-Type: application/json
Accept: application/json | text/html
GET https://api.consentgrid.io/v1/my/consentforms/{acct}/web/{templateName}/latest?locale=en&subjectOption=option&ok=ok_uri&err=err_uri&by.id=id&by.type=user
cookie cgs_{accountURL}: session
Accept: application/json | text/html

The templateName, along with the optional locale query parameter, will be used to select the consent form with the given specific locale. If a consent form template for this locale is not available, the form template for the default locale will be used.

The subjectId specifies the data subject for which the form is being instantiated. If there is a data subject with this id is in the database, it will be loaded, and combined with the data subject information submitted in the request body. This means if you uploaded your subject information before, then by providing the subjectId in the request document you can load the subject information from the database. The subjectOption query parameter determines how to process the subject information in the document. Possible values are:

merge or unspecified
Merge the given subject information with the subject information in the database, and use it to build the consent form template.
rewrite
Overwrite the subject information as given in the request body.
id
Only store the subject id in the database. The form template can still use any subject information submitted in the request body.

If no Accept header values are given or if Accept: text/html, this API returns the form as an HTML document. If Accept: application/json, then the API returns the JSON-encoded form as follows:

{ 
 "text": "htmlForm..."
}

The ok and err query parameters will be appended to the form action URL. If the ok=ok_uri query parameter is given, an HTTP redirect response to this URI will be returned upon successful submission of the form. If the err=err_uri query parameter is given, errors during submission will be redirected to this URI. If the error URI is not given, errors will be redirected to the ok_uri, with an additional query parameter err=msg containing the error message.

The request body optionally contains subject information. The subject data must validate with the data subject schema.

{
  "subject": {
    Subject fields
  }
}

by is an optional field that specifies the user identifier for the user saving the consent on behalf of the data subject. If omitted or empty, it is assumed that the data subject is recording the consent himself/herself.

Response

If successful, the return value will depend on Accept header in the request. If Accept: application/json, then the return value is the following document:

 { 
 "text": "templateData..."
}

Otherwise, the return document is an HTML document or fragment as defined by form template.