Consent Integration

Integrate your existing forms by adding an API POST /citizens/consent endpoint.

The following fields are available:

  1. Email Address: (required) this is the main identifier in 4Comply. The expected name form the JSON is email_address.
  2. Consent Code: (required) this field will contain whether the Digital Citizen consented to receive communications from you. The accepted values are yes, no, or unsubscribed. In the case of the unsubscribed, this is a special value that will only be sent when a contact unsubscribes from your system. And, the expected name is consent_code.
  3. Processing Purpose: (required) the processing purpose element helps determine the Time-To-Live (TTL) of the permission obtained from the Digital Citizen. For example, if a Digital Citizen submits a contact us form with consent, then the processing purpose is Form Submission with consent. The actual values and names can be customized and be found in the UI, under the Configuration section, on the Regulations menu item. The expected name for this field is processing_purpose. For a list of default processing purposes, please refer to Processing Purpose list in the 4Comply Defaults section.
  4. Consent Type: (required) for most cases, the consent type will be Communicate Electronically. This is a direct reference to the Master Permission Types section under the Regulations menu or the list of default values in the 4Comply Defaults section. These permissions are used in the regulations and determine what type of communication can be used with the Digital Citizen. The expected name for this field is consent_type.
  5. Standard Country: (required) this is the field that determines the country a contact comes from. There is also an option for Standard State however that field is optional.

Also, there are some optional fields that you have at your disposal:

  1. Business Unit: (optional) usually this field refers to where the consent was triggered, like Marketing or Sales. The expected name for this field is business_unit.
  2. Standard State: (optional) this is the field that determines the state a contact comes from. This will have priority over Standard Country assuming there is a Regulation associated with the Standard State.
  3. System Name: (optional) this is the name of the external system as added in 4Comply. If there are no Systems then the system fields can be ignored and 4Comply will use “default” as the value. You may add or remove systems under Configuration in the 4Comply Dashboard or take a look at the list of default values in the 4Comply Defaults section. The expected name for this field is system.
  4. System Id: (optional) this is the internal Id of the system in 4Comply. If you have it at hand, it can be used instead of the System name. The expected name for this field is system_id.
  5. System Record Type: (optional) depending on the system, this could have multiple values or just one. For example, if the information comes from SFDC, the Record Type could be Lead, Contact, or any custom object you have that stores customer information. You have the option to identify the type of record this consent submission is sending. The expected name for this field is system_record_type.
  6. System Record Id: (optional) this setting is linked to the previous one. Usually, in other systems, the records have a unique identifier, so this is the field to store that unique Id. The expected name for this field is system_record_id.

Once you’ve identified the fields that you have available in your forms, the rest is just creating a JSON and sending it to 4Comply. Here’s an example on how accomplish this using jQuery:

$(function () {
    $('form').submit(e => {
        $.ajax({
            type: "POST",
            beforeSend: function (request) {
                request.setRequestHeader("Content-type", "application/json");
                request.setRequestHeader("Accept", "application/json");
                //Set your tenant_id
                request.setRequestHeader("tenant_id", "Your-Tenant-Id");
                //Get the country field value
                request.setRequestHeader("standard_country", $('select[name="country"]').val());
            },
            url: "https://api.4comply.io/v1/citizens/consent",
            data: JSON.stringify({
                //Get all the form data using jQuery
                'email_address': $('input[name="email_address"]').val(),
                'consent_code': $('input[name="consent_code"]:checked').val(),
                'processing_purpose': $('input[name="processing_purpose"]').val(),
                'consent_type': $('input[name="consent_type"]').val(),
                'business_unit': $('input[name="business_unit"]').val()
            }),
            success: function (data) {
                console.log("Response: " + data);
            },
            error: function (xhr, status, error) {
                console.error("Error: " + error);
            }
        });
    });
});

The Processing Purpose, Consent Type, and Business Unit can be static values, so you could use hidden fields in the form, as the example above, or update the code to use static values.

Once the submission is accepted by 4Comply, there is an internal process that will match the processing purpose with the respective regulation and TTL and will create a consent entry and a permission entry. The permission entry will contain the expiration date of the record (calculated with the processing purpose TTL).


List Upload

You can also add Consent or Permissions through an upload. The file needs to be a JSON in a flat key-value pair format. The required fields change a bit, but the end result is the same.

These are the fields available for a consent upload:

  • email_address (required)
  • consent_code (required)
  • geo_code (required, instead of geo_override)
  • processing_purpose (required and need for the country regulation)
  • consent_type (required)
  • geo_type (optional, not required when using a country code)
  • business_unit (optional)
  • system (optional)
  • system_record_type (optional)