Prepare a consent form, and return a token you can use to serve the form on ConsentGrid™ or retrieve its contents. This API is best suited for situations where the backend of your application submits the request the build the form, passes the token to your frontend, which then uses the token to retrieve form contents using AJAX calls to embed into your application.

POST https://aws.consentgrid.io/v1/consentforms/web/{templateName}/subjects/{subjectType}/{subjectId}/{type}/token?locale=en&subjectOption=option&ok=ok_uri&err=err_uri&by.id=id&by.type=user
Content-Type: application/json

This API is similar to the build consent form API. It instantiates a consent form template, but instead of returning the template, it returns a token that can be used to serve the form on ConsentGrid™ or retrieve the form contents to embed into your own user interface.

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.

The type path parameter is either new that means no existing consent information is loaded to initialize the form, or current that means existing consent information is loaded and used to initialize the form. This only works for SmartConsents with at most one active consent record (that is, consent cancels existing active consents when user saves a new consent record).

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 must be an instance of the JSON schema specified when the consent form template is defined.

{
  "subject": {
    Subject fields
  },
  "data": {
    Data fields to be stored with consent  
  },
  "uiData" {
    Fields available for form display, but will not be stored
  }
}

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

200 Ok

The response is a JSON document containing the token.

{
  "token": "w982384374923e45..."
}