Customisations

Prerequisites

What? why?

Web Trust for the Document APIs allows some level of customisation. This customisation is regarding:

  • The logo used in the signing environment

  • Some texts in the signing environment

  • Font used to generate the signature (if signatureType = "fullname_date")

  • OTP message content

  • Outcome message plus redirection link at the end of the singing process.

These customisations allow you to do some branding of the signing environment, making it more yours.

Whithin the signature

There are two ways to customise the signature environment: the first is directly while creating the signature and the second using archetypes.

Let’s dive into the first one directly with an example that shows a fragment of the payload used to create a signature:

...

"signatureCustomisations": {
    "customLogoUrl": "https://www.deathstar.com/static/mylogo.png",
    "fullNameSignatureFont": "LeagueScript",
    "signPage": {
        "title": "If you want to welcome the Dark Force sign this",
        "showLogo": true
    },
    "otpSmsPage": {
        "title": "Verify your communication device",
        "subtitle": "Please insert here the verification code we will send you to your communication device",
        "showLogo": true
    },
    "outcomePage": {
        "title": "Welcome to the Dark Force",
        "titleRejected": "Maybe be you are afraid of being cool",
        "subtitle": "The signature procedure was completed correctly",
        "subtitleRejected": "The signature procedure was rejected",
        "showLogo": true,
        "customLink": {
            "title": "Click here to go to the Death Star website",
            "url": "https://www.deathstar.com/controlPanel",
            "redirectInSecs": 5
        }
    }
},
...

By adding signatureCustomisations to your signature creation payload, you can personalise the signing environment as follows:

  • customLogoUrl allows you to specify a public link to an image that can be used as the logo in the signing environment.

  • fullNameSignatureFont is the font to be used when signatureType is fullname_date, meaning that the signature will be generated automatically from signerFullname. These are the fonts available:

  • signPage.title overrides the default title of the signing page.

  • signPage.showLogo allows you to decide if the custom logo has to be shown on the signing page (customLogoUrl must be provided).

  • optSmsPage.title overrides the default title of the OTP page.

  • optSmsPage.subtitle overrides the default subtitle of the OTP page.

  • optSmsPage.showLogo allows you to decide if the custom logo has to be shown on the OTP page (customLogoUrl must be provided).

  • outcomePage.title overrides the default title of the outcome page.

  • outcomePage.subtitle overrides the default subtitle of the outcome page.

  • outcomePage.titleRejected overrides the default title of the outcome page when the signature is rejected.

  • outcomePage.subtitleRejected overrides the default subtitle of the outcome page when the signature is rejected.

  • outcomePage.showLogo allows you to decide if the custom logo has to be shown on the outcome page (customLogoUrl must be provided).

  • outcomePage.customLink.title is the text of the link to be added to the outcome page.

  • outcomePage.customLink.url is the URL of the link to be added to the outcome page.

  • outcomePage.customLink.redirectInSecs, if specified, sets the number of seconds to wait for an automatic redirect to the specified URL.

Archetypes

In the previous section, we saw how to use signatureCustomisations inside the singature creation payload to personalise the signing environment.

Another way to do so is to define an archetype. Archetypes describe the tag schema that a set of your interactions/signatures must adhere to, in order to be created. For example, if you want to split all of your interactions into 2 partitions (one for privacy policies and one for contracts), you can define two different archetypes. In the first one, you will specify all the meaningful tags for privacy policies (e.g., an identifier of the signer and the version of your privacy policy), and in the second one, you will specify all the meaningful tags for contracts (e.g., an identifier of the signer, the version of the contract, and your company's associate that signed the contract on its behalf).

Later on, when you create interactions/signatures, you could specify the relevant archetypeId in the body of the creation payload, and the system will prevent you from creating an interaction associated with an archetype if its tags do not respect the schema indicated in the archetype.

Let’s see an example:

Example
const res = await fetch("https://api.webtrust.kopjra.com/v1/archetypes", {
    headers: {
        "Content-Type": "application/json",
        "Accept": "application/json",
        "Authorization": "Basic NjhiOTkxMjEtYWIxNC00YzUwLWFlMzItNDgzZmQ4MWVkNWJkOnlBRG1YTDZ6IzNjVm4tWURPNmJsTWkybGY0MEpNMEdUcFpLVH5+Ujc1eUNEN3ZZVGU2fmJTdTJEOUZwNHFEVjl4RWhtVmRZSw==",
    },
    method: "POST",
    body: JSON.stringify({
      "name": "Archetype 1",
      "signatureCustomisations": {
           "customLogoUrl": "https://www.deathstar.com/static/mylogo.png",
           "fullNameSignatureFont": "LeagueScript",
           "signPage": {
               "title": "If you want to welcome the Dark Force sign this",
               "showLogo": true
           },
           "otpSmsPage": {
               "title": "Verify your communication device",
               "subtitle": "Please insert here the verification code we will send you to your communication device",
               "showLogo": true
           },
           "outcomePage": {
               "title": "Welcome to the Dark Force",
               "titleRejected": "Maybe you are afraid of being cool",
               "subtitle": "The signature procedure was completed correctly",
               "subtitleRejected": "The signature procedure was rejected",
               "showLogo": true,
               "customLink": {
                   "title": "Click here to go to the Death Star website",
                   "url": "https://www.deathstar.com/controlPanel",
                   "redirectInSecs": 5
               }
           }
        },
        "mandatoryTags": {
            "signerIdentifier": null,
            "policyVersion": null,
        }
    }),
});
console.log(await res.json());

In this example, we created a full archetype that also customises the signatures that use it; you can note the signatureCustomisations property, already explained in the previous section.

However, there are other properties:

  • name is just a friendly name for your archetype.

  • mandatoryTags defines which tags must be specified when you create a signature using this archetype. In the future you will be able to specify a regular expression to validate such tags, but for now null is the only accepted value. The key must contain only US-ASCII letters and/or numbers.

To use the archetype while creating a signature, you just need to specify property archetypeId in the signature creation payload, like:

...
"archetypeId": 2
...

OTP SMS message customisation

One thing you can do only via archetypes is the OTP message customisation. Since SMS messages are a little delicate due to provider and legal restrictions, this customisation must be moderated by one of our administrators.

How does it work? You just need to add this to the archetype creation payload:

...
"smsCustomMessage": "OTP: {{CODE}} - Enter the above code to sign your document",
...

Notice here, the use of the placeholder {{CODE}} to indicate where the OTP code will appear inside the message.

Once you create this archetype, you need to create a support ticket indicating the archetype ID and that you are trying to customise the OTP message as motivation. One of our administrators will take it in charge and respond to you accordingly.

In case of a positive response, you will see "smsCustomMessageModeratedOn": APPROVAL_DATE inside the response of the archetype GET. If it is still pending or rejected, you should see "smsCustomMessageModeratedOn": null . The rejection management is done via the same support ticket you opened.

A support ticket can be created using this link or by sending an email to support@kopjra.com.

OTP Email customisation

By using the emailCustomisation property (see here for definition), we can customise the OTP email messages.

...
"emailCustomisation": {....}
...