CIV identity verification (Scanovate BTR)

CIV lets the person filling a form verify their identity with Scanovate BTR without leaving the form. They click a CIV button in the form, complete the identification flow defined in Scanovate, and the verification results are written into fields of the form.

CIV is configured per project. A project can have more than one CIV integration, and each CIV field in a template selects the integration it uses.

Before you start

• CIV must be enabled for your project. Contact your Cellosign account team to enable it.
• Have the details of your Scanovate account ready: the token URL, client ID and client secret, the Scanovate BTR service address, and the BTR flow ID of the flow you want to run.
• Only project managers (and managers of the company that owns the project) can set up CIV integrations and select them in templates.

Setting up CIV takes three steps: create the credential, add the CIV integration, and add the CIV control to a template.

Step 1 — Create the Scanovate credential (Client Secret)

Under Client Secrets, click Add and fill in:

Field	What it’s for
Name	A name for the credential, e.g. Scanovate.
Type	Select Scanovate BTR v3.7.5.
url	The Scanovate token URL.
grant_type	Required by the form, but not used for Scanovate. Enter any value, e.g. client_credentials.
scope	Leave empty.
client_id	The client ID of your Scanovate account.
client_secret	The client secret of your Scanovate account.

Save the secret, then click Test to check that Cellosign can obtain a token from Scanovate. Cellosign requests a new token automatically when the current one expires.

Step 2 — Add the CIV integration

On the Integrations page, locate the CIV Integration pane and click Add.

Field	What it’s for
Name	A name for the integration. This is the name you select in the template editor.
Base URL	The Scanovate BTR service address. Must start with https://.
Scanovate credential	The credential from step 1. Only active Client Secrets of type Scanovate BTR in this project are listed.

Click Save.

The Base URL is checked when you save and again before every verification. It must use HTTPS, must not include a user name, password, query string or fragment, and its host name must resolve to a public internet address. If saving fails, the form shows the reason:

Message	What to do
CIV base URL must use HTTPS.	Use an address that starts with https://.
CIV base URL must not contain credentials, a query, or a fragment.	Remove the user name/password, the part after ?, or the part after #.
CIV base URL hostname could not be resolved.	Check the host name for typos.
CIV base URL resolves to a forbidden network address.	Use an address that is reachable on the public internet.
Select an active Scanovate Client Secret from this project.	Select another credential, or create one as described in step 1.

To change an integration, click its edit (pencil) button. To delete it, open it and click Delete. A verification that is already in progress can still complete. Templates that use a deleted integration show Unavailable integration in the CIV settings, and their CIV button does not start a verification until another integration is selected.

Creating, editing and deleting a CIV integration is recorded in the audit log.

Step 3 — Add CIV to a template

1. Open the template and add the CIV control from the palette. CIV is available in both the HTML and the PDF template editors.
2. On the Values & Display tab, set the Button text. The default is “Biometric identification”.
3. On the Developer tab (</>), configure the CIV Integration section:

Setting	What it’s for
Integration	Select the CIV integration from step 2. Required: until an integration is selected, the other CIV settings are hidden and the CIV button in the form does not start a verification.
BTR Flow ID	The ID of the Scanovate BTR flow to run, e.g. 3659. Without a flow ID the CIV button does not start a verification.
Source / Target	Map verification results (Source) to fields of the form (Target). Click Add Mapping to add a row.

Mapping rules:

• Each Source and each Target can be used only once.
• Text results can be mapped to text and number fields. Image results (img_*) can be mapped only to image and drawing fields.
• Images are resized to at most 1300 pixels and saved as JPEG. An image larger than 3 MB is not saved.
• If you clear the Integration, the flow ID and mappings are hidden but kept, and they return when you select an integration again.

Only project managers can change the CIV settings of a template. Other users see the message “CIV integration settings can be changed only by project managers when CIV is enabled for the project.”

Results you can map

The Source list shows the result names exactly as below.

Source	Description
internal_status	The result of the verification: success or error.
id_*	Data read from an ID card, e.g. id_firstName, id_lastName, id_idNumber, id_dateOfBirth, id_gender, id_issueDate, id_expiryDate, id_placeOfBirth, id_citizenship.
dl_*	Data read from a driving licence, e.g. dl_documentNumber, dl_address, dl_licenseCategory, dl_firstNameEnglish, dl_lastNameEnglish.
mrz_*	Data read from the machine-readable zone of a passport, e.g. mrz_firstName, mrz_lastName, mrz_idNumber, mrz_nationality, mrz_issuingCountry, mrz_expiryDate, mrz_mrzText.
ln_success, ln_message	The result of the liveness check.
bio_success, bio_score	The result and score of the biometric face match.
stt_*	Speech-to-text results, e.g. stt_text, stt_score, stt_language.
img_faceImage, img_frontImage, img_backImage, img_cardImage, img_backCardImage, img_croppedMrz, img_frameImage	Images captured during the verification.

Note: results with the same name in different groups (for example id_firstName, dl_firstName and mrz_firstName) return the same value: the first one available in the verification result.

What the client sees

1. The CIV control appears in the form as a button with the configured text.
2. When the client clicks it, the verification opens full screen inside the form. The browser may ask for permission to use the camera and microphone.
3. The client completes the Scanovate flow. When the verification succeeds, the window closes automatically and the mapped fields are filled in.
4. If the verification fails, the window closes and the mapped fields are not filled in.
5. The client can close the verification with the X button at any time and click the CIV button again to start over.

CIV works in the same way when an agent fills in the form on the agent screen.

Verification results in the archive and webhooks

The archive metadata and webhook payloads include a civ section with field_id, process_id, flow_id, status, transaction_id, session_id and completed_at. Of the images captured during the verification, only those mapped to a form field are stored.