Backend API
Please ensure that you have followed all steps as described under the Get Started section.
If you're using the separate UI hosting structure, it is recommended that the backend API is set up, configured and hosted before starting with the UI, as the backend API is essential for the UI portion to function correctly.
The UI communicates with the backend API every step of the way. The service can be configured to execute integration API requests to any endpoint(s) in order to sync data of the onboarding case, either on a per-step basis or as a single request at the end of the onboarding journey.
Multi-Tenancy
Multi-tenancy refers to the capability of the onboarding application to support multiple configuration sets hosted from a single instance.
This configuration split is achieved via folder structure. The "Tenants" folder name and location may be configured. Each subfolder, however, must be named to match the corresponding tenant ID and each subfolder must contain the following:
Assets - Folder containing all assets for the tenant.
background.png - Background image file.
custom.css - CSS file containing the tenant's custom styling.
logo.png - Logo image file
Languages - Folder containing JSON files with the metadata of all languages supported by the tenant.
JSON files for each language supported by the tenant. Example: en-us.json for US English.
Privacy - Folder containing HTML files with the tenant’s privacy policy in each language supported by the tenant.
HTML files. Example: en-us.html for the privacy policy in US English.
Terms - Folder containing the tenant’s terms and conditions in each language supported by the tenant.
HTML files. Example: en-us.html for the terms and conditions in US English.
Translations - Folder containing XLIFF translation files for each language supported by the tenant.
XLIFF files. Example: en-us.xliff for translations in US English.
config.release.json - Configuration JSON file dictating flow, business logic and behaviour of the onboarding application for the tenant.
Base Service Configuration
Base service configuration is configured in the appsettings.release.json file:
Property Details
AllowedHosts: Configure CORS.
DataLifetimeMinutes: The global amount of time (in minutes) that data will be cached in Redis for. This property applies to Redis caching not specific to any tenant. Default 30
Logging: Configure log4net logging.
Redis: Connection settings for Redis.
TenantsDirectory: Configures the physical path location to the "tenants" directory on the system.
Configuration Options
Each tenant may be configured separately. The following properties are exposed as configuration options in the config.release.json file for each tenant:
Property Details
AuthSecret: Authorization secret used to secure the API with. Recommended to be set to a GUID that is not used anywhere else. No default
AutomaticRedirectDelay: The amount of time, in milliseconds, that must pass after onboarding journey completion before the UI automatically redirects the user if the RedirectMode property value is set to 2. Default 5000
BiometricsApiKey: The API key used to connect to the biometrics backend service. Please contact Sybrin to request this. No default
BiometricsAuthorizationEndpoint: Endpoint used by the onboarding API to authorize against the biometrics backend service. No default
BiometricsCameraDirectionPriority: This property is used to determine which camera direction the SDK should try to prioritize while running liveness. 0 is none, meaning it will always prompt device selection. 1 is front, meaning it will default to the front camera if only one front device is found. 2 is back, meaning it will default to the rear camera if only one rear device is found. Default 1
BiometricsIncludeVideo: Whether or not a video should be recorded during liveness capture. Default false.
BiometricsOverexposedThreshold: The percentage of overexposed pixels that should be present for an image to be considered overexposed during biometrics operations. Default 50.
BiometricsOverexposedValue: The grayscale RGB value (0-255) that a pixel's color must be larger than in order to be considered overexposed during biometrics operations. Default 220.
BiometricsTokenLifetimeMinutes: How long the internal biometrics token must be used for before a new token is requested. Default 60
BiometricsUnderexposedThreshold: The percentage of underexposed pixels that should be present for an image to be considered underexposed during biometrics operations. Default 40.
BiometricsUnderexposedValue: The grayscale RGB value (0-255) that a pixel's color must be smaller than in order to be considered underexposed during biometrics operations. Default 30.
BiometricsVideoDuration: The time, in seconds, that the UI should record a video for when BiometricsIncludeVideo is set to true. Default 3
ClientID: A unique client identifier to help the onboarding application track usage of a particular tenant. This can be any GUID. If the separate UI hosting structure is used, the UI instance appsettings file for the UI tenant must contain the same client ID. No default
ConversionApiKey: The API key used to connect to the conversion service for converting images from PDF to PNG or JPEG. Please contact Sybrin to request this. No default
ConversionAuthorizationEndpoint: Endpoint used by the onboarding API to authorize against the PDF conversion backend service. No default
CorrelationDuplicateMode: Sets how duplicate correlation IDs should be handled. 0 = Exception, and means an exception will be thrown on duplicate correlation IDs. 1 = Flag, and means the case will be flagged as high risk with a message detailing that it has a duplicate correlation ID. Default 0
CorrelationIDRequired: Whether or not a correlation ID must be provided from the UI. If this value is true and no ID is provided, an exception is thrown. If this value is false and no ID is provided, a correlation ID is automatically generated for the case. Default false
DataExtractionEndpoint: Endpoint of the identity backend service request used to run ID document OCR and data extraction. No default
DataExtractionFieldEditMode: Sets the mode in which the fields defined in the DataExtractionFieldList property should be applied. 0 = include, and means that only the fields defined in the list should be editable. 1 = exclude, and means that all fields except for the ones defined in the list should be editable. Default 0
DataExtractionFieldList: List of fields that should be editable or not editable depending on the DataExtractionFieldEditMode property value. Blank by default
DataExtractionForceWebEditing: Sets whether or not identity mobile capture should navigate the original session to the result page for editing before proceeding. Default true
DataExtractionHeaders: Sets the headers that should be provided to the identity service while running ID document OCR.
DataExtractionIsLowConfidenceBlocking: Sets whether or not the "Next" button should be disabled if there are any unaddressed fields with a low confidence rating. Default true.
DataExtractionIsLowConfidenceConfirmable: Sets whether or not the user will be able to click on the warning icon of a low confidence field to mark it as "Confirmed". Default true.
DataExtractionIsLowConfidenceEditable: Sets whether or not low confidence fields will become editable so that the user can amend them. Default true.
DataExtractionMobileIsLowConfidenceBlocking: For mobile, sets whether or not the "Next" button should be disabled if there are any unaddressed fields with a low confidence rating. Default true.
DataExtractionMobileIsLowConfidenceConfirmable: For mobile, sets whether or not the user will be able to click on the warning icon of a low confidence field to mark it as "Confirmed". Default true.
DataExtractionMobileIsLowConfidenceEditable: For mobile, sets whether or not low confidence fields will become editable so that the user can amend them. Default true.
DataExtractionReturnCroppedImages: Whether or not to return cropped document images to the UI after Identity OCR. Default true
DataExtractionWordConfidenceThreshold: Sets the threshold for a field to be considered low confidence. Any value lower than configured here will be considered low confidence. Default 90.
DataLifetimeMinutes: The amount of time (in minutes) that data for the tenant will be cached in Redis for. This property affects how long the user would need to be inactive for before onboarding data for their case is discarded entirely. Default 30
DocumentTypeOverrides: This array may be used to disable specific document types. For details, please see document type overrides below.
DisableLiveness: this property enables functionallity to takes a selfie without running liveness on the image/video.
EnableFaceFeatureExtraction: Whether or not the service should run face feature extraction. Default false
EnableFidoDeviceScreening: Whether or not the service should run Fido device screening. Default false
EnableFraudDetection: Whether or not the service should run fraud checks. Default false
EnableReverseGeolocationExtraction: Whether or not the service should run reverse geolocation lookup. Default false
EnablePiplPhoneScreening: Whether or not the service should run Pipl phone number screening. Default false
EnableMobileCaptureSms: Whether or not the "Send SMS" button should appear during mobile capture states. Default false
ExtractImageFromPdfEndpoint: Endpoint of the backend service request used to extract PNG images from PDF files. No default
ExtractionBackParamName: The parameter name of the data extraction back image passed to the service that handles ID document OCR. Default "BackImage"
ExtractionFrontParamName: The parameter name of the data extraction front image passed to the service that handles ID document OCR. Default "FrontImage"
EyeDetectionScale: Scale adjustment to be applied while running eye detection. 1.2 is the default value used internally, however a value of 0 indicates "default" and will also translate to 1.2 internally. Default 0
EyeDetectionThreshold: Threshold adjustment to be applied while running eye detection. 3 is the default value used internally, however a value of 0 indicates "default" and will also translate to 3 internally. Default 0
FaceDetectionScale: Scale adjustment to be applied while running face detection. 1.1 is the default value used internally, however a value of 0 indicates "default" and will also translate to 1.1 internally. Default 0
FaceFeatureApiKey: The API key used to connect to face feacture extraction backend service. No default
FaceFeatureExtractionAuthorizationEndpoint: Endpoint used by the onboarding API to authorize against the face feature extraction backend service. No default
FidoApiKey: The API key used to connect to Fidos backend services. No default
FinalizeImmediateCompletion: When set to true, this flag will result in the onboarding process automatically firing the onCompletion event and configured callback once onboarding completes fully.
FraudApiKey: The API key used to connect to the fraud backend service. Please contact Sybrin to request this. No default.
FraudAuthorizationEndpoint: Endpoint used by the onboarding API to authorize against the fraud backend service. No default
FraudDetectionAuthToken: The authorization token used to connect to the fraud detection backend service. Please contact Sybrin to request this. No default
FraudDetectionEndpoint: Endpoint of the backend service request used to run fraud detection. No default
GeolocationApiKey: The API key used to connect to geolocation backend service. No default
GeolocationAuthorizationEndpoint: Endpoint used by the onboarding API to authorize against the geolocation backend service. No default
GoogleMapApiKey: The API key used to connect to Google map backend services. No default
IdentityApiKey: The API key used to connect to the identity backend service. Please contact Sybrin to request this. No default
IdentityAuthorizationEndpoint: Endpoint used by the onboarding API to authorize against the identity backend service. No default
IdentityCameraDirectionPriority: This property is used to determine which camera direction the SDK should try to prioritize while running ID document OCR. 0 is none, meaning it will always prompt device selection. 1 is front, meaning it will default to the front camera if only one front device is found. 2 is back, meaning it will default to the rear camera if only one rear device is found. Default 2
IdentityCaptureMode: This property is used to determine the capture mode to use while on the ID document OCR step. 0 is auto. 1 is manual. Default 0
IdentityMaxUploadFileSize: Sets the maximum size (in bytes) that a file picked for uploaded for Identity OCR may be. Default 5242880
IdentityOverexposedThreshold: The percentage of overexposed pixels that should be present for an image to be considered overexposed during identity operations. Default 50.
IdentityOverexposedValue: The grayscale RGB value (0-255) that a pixel's color must be larger than in order to be considered overexposed during identity operations. Default 220.
IdentityTokenLifetimeMinutes: How long the internal identity token must be used for before a new token is requested. Default 60
IdentityUnderexposedThreshold: The percentage of underexposed pixels that should be present for an image to be considered underexposed during identity operations. Default 40.
IdentityUnderexposedValue: The grayscale RGB value (0-255) that a pixel's color must be smaller than in order to be considered underexposed during identity operations. Default 30.
IntegrationIncludeDocumentCroppedImages: Whether or not to include cropped document images on the integration request. Default true
IntegrationIncludeDocumentRawImages: Whether or not to include raw document images on the integration request. Default true
LicenseKey: Your internal license key. Please contact Sybrin to request this. No default
LivenessHeaders: Sets the headers that should be passed to the biometrics service while running liveness. No default
LivenessMediaType: Sets the kind of media that should be used for liveness. 0 = Image, and means that the selfie image will be used for liveness detection. 1 = Video, and means that the selfie video will be used for liveness detection. Default 0
LivenessProviderType: Sets what kind of liveness provider must be used. 1 is Sybrin's provider. 2 is for third party usage. Default 1
LockMobileCountry: Whether or not the mobile number entered during verification must be locked to the country that the user is in. Default false
MediaStreamRetryCount: The number of times that onboarding will retry gaining access to the camera if it fails the first time. Default 5
MediaStreamRetryDelay: The amount of time (in milliseconds) that onboarding will wait before attempting to access the camera again after failure. Default 1000
NestApiKey: Sets the API key (matching the provided username) used to log onto the Sybrin Nest service if Nest integration is being used. No default
NestBaseUrl: Sets the base URL for the Sybrin Nest service if Nest integration is being used. No default
NestTokenLifetimeMinutes: Time, in minutes, that the internal Nest token should remain cached for (if used). Default 60
NestUsername: Sets the username used to log onto the Sybrin Nest service if Nest integration is being used. No default
NitroBaseUrl: Sets the base URL for the Sybrin Nitro service if Nitro integration is being used. No default
OtpBypass: This is a development/debug property and sets an OTP value that may be used to bypass verification. No default
OtpCountdownSeconds: How long the user must wait before being able to request a new OTP. Default 60
OtpLength: The amount of digits in the OTP that gets generated during the mobile verification step. Default 4
OtpLifetimeMinutes: The amount of time (in minutes) that the OTP generated during mobile verification remains valid for. Default 5
OtpSmsBypassNumber: This is a development/debug property and sets a mobile number value that may be used to bypass verification. No default
PassiveLivenessEnableSkipFailureCount: The number of liveness failures required before allowing the user to skip. If set to 0, liveness is never skippable. Default 0
PassiveLivenessEndpoint: Endpoint of the biometrics backend service call used to run passive liveness. No default
PassiveLivenessParamName: The parameter name of the passive liveness selfie image provided to the service that handles liveness processing. Default "media"
PrivacyPolicyPresentationMode: Sets the presentation mode for the privacy policy. 0 is embedded and requires privacy policy file configuration within the service. 1 is external and requires privacy policy URL configuration within the service appsettings. Default 0
PrivacyPolicyUrl: Sets the URL to direct the new window to if the user clicks any "View Privacy Policy" button while presentation mode is set to "1 - External". No default.
RedirectMode: This value can be 0 (None), 1 (Manual) or 2 (Automatic) and determines how redirection is handled at the end of the onboarding journey. If this value is 0, no redirection occurs. If this value is 1, the user must click the "Complete" button on the UI before redirection occurs. If this value is 2, the UI will automatically redirect the user after the amount of time specified in the AutomaticRedirectDelay property. Use the StaticRedirectUrl property to set the URL that must be redirected to. Default 0
RemoteCorrelationIDVerification: Section to configure remote correlation ID verification parameters.
IntegrationMode: The payload format. This value can be 0 (None - No integration happens), 1 (JSON), 2 (Form) or 3 (Nest). Default 0
Endpoint: The URL that should be hit for correlation ID verification.
NestProcessID - The Nest process ID to use for correlation ID verification when the IntegrationMode property value is set to 3.
NestMicroflowName - The Nest microflow name to use for correlation ID verification when the IntegrationMode property value is set to 3.
Salt: The salt (usually a GUID) that accompanied the onboarding API as it was generated.
ScreeningApiKey: The API key used to connect to the screening backend service. Please contact Sybrin to request this. No default
ScreeningAuthorizationEndpoint: Endpoint used by the onboarding API to authorize against the screening backend service. No default
ScreeningEndpoint: Endpoint of the screening backend service call used to run screenings. No default
SendAuditTrail: Whether or not the audit trail should be included in any integration requests that the service makes. Default true
ShowBanner: Toggles whether or not the onboarding banner should be shown. Default true
FilteredFields: filter out specific result fields, so they don't display on the Result component. Default []
ShowLanguageDropdown: Toggles whether or not the button that expands the languages dropdown should be shown. Default true
SmsEndpoint: The endpoint of the service used to send SMSes. No default
SmsPassword: The password used to log into the service that sends SMSes. No default
SmsSeparator: No default
SmsUsername: The username used to log into the service that sends SMSes. No default
StaticRedirectUrl: The URL that the UI must redirect the user to after journey completion if the RedirectMode property is set to 1 or 2. "Crocodile bracket notation" may be used for expression parsing certain values. Only "<#correlationid#>" or "<#onboardingid#>" are considered valid values for expression parsing and will be replaced with the correlation ID or the onboarding ID of the case respectively, upon execution. No default
Steps: Used to configure which steps should be available and how they should behave. See step configuration section below for details.
StrictOrderStepEnforcement: Whether or not the API must strictly prevent the user from running steps out of their assigned order. Default true
SuppressSpoofSelfies: Whether or not spoof results must be silently suppressed and used to flag the case instead of throwing an error visible on the front end. Default true
TargetImageType: Sets the target format that captured images should be converted to for data sync. 0 = Original, and means the original image will be sent. 1 = JPEG, and means that the image will be converted to JPEG before being sent. Default 0
TenantEnabled: Sets whether or not the tenant should be enabled and accessible.
TermsPresentationMode: Sets the presentation mode for the terms of use. 0 is embedded and requires terms file configuration within the service. 1 is external and requires terms URL configuration within the service appsettings. Default 0
TermsUrl: Sets the URL to direct the new window to if the user clicks any "View Terms of Service" button while presentation mode is set to "1 - External". No default.
TokenValidityDays: How long (in days) a token provided by the backend service should be valid for. This amount gets added to the minute value. Default 1
TokenValidityMinutes: How long (in minutes) a token provided by the backend service should be valid for. This amount gets added to the days value. Default 0
TrackIdentityHashes: Whether or not the backend should keep track of identity numbers that have already been used and mark a case as high risk when one is reused. Default true
WebApiKeyID: Individual API key ID as provided by Sybrin. No default
Document Type Overrides
You may use the DocumentTypeOverrides configuration option in appsettings if you wish to disable specific document types. For example, if you want to disable South African ID cards and South African greenbook IDs, use the following:
Supported document types are:
ghapassport: Ghana passport
kenpassport: Kenya passport
kenidcard: Kenya ID card
kenmilitary: Kenya military ID card
mwipassport: Malawi passport
mozpassport: Mozambique passport
mozidcard: Mozambique ID card
zafpassport: South African passport
zafidcard: South African ID card
zafgreenbook: South African green book ID
ugapassport: Uganda passport
ugaidcard: Uganda ID card
usacadriverslicense: USA California driver's license
zwepassport: Zimbabwe passport
phlpassport: Philippines passport
phlidcard: Philippines ID card
phldriverslicense: Philippines driver's license
phlseamansbook: Philippines seaman's book
phlsid: Philippines seaman's ID card
phlpostalid: Philippines postal ID
phlsocialsecurity: Philippines social security ID
phlunifiedmultipurpose: Philippines unified multi purpose ID
phlfirearmslicense: Philippines firearms license
phlprofessionalregulationsblue: Philippines professional regulations ID (old)
phlprofessionalregulations: Philippines professional regulations ID (new)
phlintegratedbar: Philippines integrated bar ID
phlinsurancecard: Philippines insurance card
phlhealthinsurancecard: Philippines health insurance card
usacaldriverslicense: USA California Driver's License
genpassport: Generic passport
passport: All passports
idcard: All ID cards
greenbook: All greenbook IDs
driverslicense: All driver's licenses
seamansbook: All seaman's books
sid: All seaman's ID cards
postalid: All postal IDs
socialsecurity: All social security IDs
unifiedmultipurpose: All unified multi purpose IDs
firearmslicense: All firearms licenses
professionalregulations: All professional regulations IDs
integratedbar: All integrated bar IDs
insurancecard: All insurance cards
healthinsurancecard: All health insurance cards
military: All military ID cards
Step Configuration
The following steps are available for configuration:
Terms - An introductory step to present instructions and allow the user to accept terms and conditions.
SubmitMobile - For submitting mobile number for verification.
VerifyOTP - For submitting an OTP once mobile number has been submitted.
PassiveLiveness - For running passive liveness detection.
AcceptPassiveLivenessResult - For showing and then allowing the user to either retry or accept the passive liveness result.
SelectCountry - For selecting the country that the ID document (that will be scanned in the data extraction step) belongs to.
SelectDocumentType - For selecting the type of ID document that will be scanned in the data extraction step.
DataExtraction - For running ID document OCR and data extraction.
AcceptDataExtractionResult - For showing and then allowing the user to either retry or accept the data extraction result.
Finalize - For syncing the final onboarding data and presenting the completion message once done, or to give the user the opportunity to retry upload if something goes wrong.
Dynamic - A special step that is expected to be an array, and allows the configuration of multiple dynamic steps with customizable data fields for entry/capture.
Available Properties
The following properties are available for configuration in each individual step:
Enabled - Whether or not the step should be included in the onboarding journey.
Order - The order of the step within the onboarding journey.
TimesRepeatable - The amount of times that the Onboarding product will allow a user to repeat a step. Use -1 for infinite.
HighRiskRepeatCount - The amount of times that a step must be repeated for before the Onboarding product flags the case as high risk. Use -1 for infinite.
NestProcessID - The Nest process ID to use for Nest integration when the IntegrationMode property value is set to 3.
NestMicroflowName - The Nest microflow name to use for Nest integration when the IntegrationMode property value is set to 3.
IntegrationMode - How the integration call should be handled for the given step. The options are 0 (None - no integration), 1 (Json), 2 (FormData), 3 (Nest).
None - No integration call occurs.
Json - An integration call occurs and the data is passed as Json.
FormData - An integration call occurs and the data is passed as Form Data.
Nest - An integration call occurs and the data is passed as an object that a Sybrin Nest service can interpret.
IntegrationEndpoint - The endpoint that the integration call should be made to if IntegrationMode is not 0.
Please see Integration section for details on how to achieve backend integration with onboarding result.
Dynamic Step Properties
Dynamic steps allow for additional configuration options to set the dynamic page up with. In addition to the properties defined in the section above, dynamic steps also provide these properties:
Title - The title of the dynamic page.
Subtitle - The subtitle of the dynamic page.
ButtonText - The caption of the button to complete/post the step with.
Fields - A collection of field objects that allow for individual field configuration:
ID - Identity of the field. Should be globally unique.
Order - The display order of the field.
Label - The caption of the field.
Type - The type of field. Can be 0 (Text), 1 (Number), 2 (Decimal) or 3 (Checkbox).
Required - Whether or not the field must be completed.
Pattern - Regex pattern used to validate the value entered into the field.
Minimum - The minimum length (for text) or value (for number or decimal) of the field.
Maximum - The maximum length (for text) or value (for number or decimal) of the field.
Last updated