Product Settings

What you can decide when implementing Fortface​

General settings (via API)​

These decisions come from the API and apply regardless of the platform used to capture the selfie or the document. They are the same for Android, iOS, and Web.

Which action or endpoint to use at each moment of the journey​

Fortface offers a set of actions and endpoints, each designed for a different moment in the user's journey. Choosing the right one for each step is the most structural decision of all, since it defines what the API will process and what it returns:

  • enroll: registers the user's selfie in the biometric database (e.g., during sign-up/account opening)
  • identify: compares the selfie with the already registered photo (e.g., login, authentication of a sensitive action)
  • search: compares the selfie against the entire registered database (1:N), useful for detecting duplicate identities/fraud
  • capture: verifies the selfie by cross-checking it with the CPF (the only case where the CPF is mandatory)
  • liveness: only confirms that it's a real person, without comparing against anything
  • /document: analyzes an identity document (photo or PDF), with the option to extract data via OCR and/or compare the document with the user's selfie

These actions are available via direct call through SDK/Backoffice (handshake).

See the "Resources" section for the full breakdown of each action and endpoint.

Approval and rejection rules​

Match Level (1:1 facial match score)

The API never decides on its own whether to approve or reject: it returns a number from 0 to 16 (matchLevel) indicating how well the selfie matches the registered photo. Your company defines the cutoff point. Fortface recommends using 13 or higher as a reference for low risk of false positives/negatives.

See the full table of error rates per level in the "Security Best Practices" section.

Identity risk score (selfie + CPF, via Hubface)

When using the capture action, the API cross-checks the selfie with the CPF and returns a score from 1 to 5 (plus the NULL and 0 cases). This defines your decision policy:

  • 5 → very low risk → can be approved automatically
  • 4 → low risk → approve with monitoring
  • 3 → neutral → flag for manual review
  • 2 → medium risk → preemptively reject (with possibility of appeal)
  • 1 → high risk → reject automatically
  • 0 / NULL → not enough information → request a new capture or complement with another source

In the test environment (sandbox), this score can be simulated using the last digit of the CPF sent, which is useful for testing all scenarios without relying on real data.

Learn more in the "Hubface: Face and Document Validation" section before defining your approval policy.

Covered/obstructed face detection (Face Occlusion)

Flags whether sunglasses, hands, objects, or the eye region are covering the face in the selfie. It's an additional data point; it doesn't block the result on its own, but it can be used in your rule to request a new photo. Regular prescription glasses usually don't count as occlusion.

How to enable it: via account configuration or by sending analysis.faceOcclusion in the request.

Inappropriate content detection (NSFW)

Checks whether the submitted image is an appropriate photo, preventing improper content from being sent instead of the selfie. Enabled via analysis.nsfw: true.

Liveness check strictness (Liveness Calibration)

Lets you calibrate the sensitivity of the facial liveness check. Three levels available: optimal, enhanced, and supreme (API default). The stricter the level, the greater the security against fraud, but also the higher the chance a legitimate user will need to repeat the capture. Fortface uses passive liveness: the user doesn't need to blink, smile, or turn their head.

How to configure it: analysis.livenessCalibration field (values optimal, enhanced, or supreme) in the handshake (SDK) or directly in the request (Backoffice).

What your company can decide about user data​

Beyond the approval rules, there are a few decisions about which data to collect/receive back during verification and what to do with it. This list covers only what is actually configurable by your company; it is not an inventory of everything the API processes internally.

  • Document data extraction (OCR): decides whether, when analyzing the document, the API also returns the extracted data (name, document number, date of birth, expiration date, nationality, sex). Enabled via ocr: true in the document analysis call.

  • Geolocation: decides whether your application will request the user's location during the session, as an additional antifraud signal. The actual configuration happens in the "User permissions" topic of this same section, via SessionDetails.getGeolocation.

  • Return of the captured photo itself (returnPhoto): decides whether your company wants to receive the selfie image back in the API response (to store it on your own) or let Fortface store it.

Correlation IDs​

externalTransactionId and externalUserId: fields you define to be able to cross-reference the result received in the direct call response with your internal transaction and user. Strongly recommended to always use them, for traceability and support.

It's also worth reinforcing the role of externalTransactionId in retries: when the user fails and tries again, the app should reuse the same externalTransactionId instead of opening a new transaction, in order to correctly measure the success rate per transaction (and not per individual attempt). This practice is also detailed in the "Error handling and retry behavior" topic of this same section.

Account settings​

  • Sandbox vs. Production: separate environments; sandbox has relaxed rules to make testing easier.
  • Permissions per API key: which actions (enroll, identify, search, etc.) your key can perform depend on the contracted commercial plan.
  • Galleries: allow separating registrations by business context (e.g., by product/business line); currently configured via the commercial team, not self-service.
  • Photo storage (savePhoto): an architecture/compliance decision: does Fortface store the captured photos, or does your company prefer to store them on its own? Impacts LGPD compliance and storage cost.
  • mTLS certificate: mandatory connection security prerequisite; generated by your company and validated by Fortface (10-year validity). Impacts the implementation timeline.
  • Response signing (Response Signature): optional feature that guarantees API responses haven't been tampered with; must be requested and enabled with the Fortface team.
  • User removal / data deletion: DELETE /backoffice/v1/enroll endpoint, available only via Backoffice (not self-service through the SDK), to delete a user's biometric registration. Relevant for handling data subject requests (LGPD).

Android SDK​

The Android SDK controls the entire visual capture experience (selfie and document) within your app. There are two ways to customize it: via code (FortfaceCustomizer, being phased out) or via JSON file (recommended for new integrations); the two cannot be combined in the same implementation.

Colors, theme, and branding​

Practically every screen in the flow is customizable: background color, button color, text color, icons, font, and (on the camera screen) your brand's logo (if you don't configure one, no logo appears).

The camera status colors (success/warning/brightness) follow a convention recommended by Fortface: green for success, orange/yellow for warning, blue for brightness. This is because usability tests showed that users trust color more than text to know whether everything is fine. It's worth keeping this convention even when customizing the colors.

The full list of parameters (camera background color, accept/reject button colors on upload, document frame color, etc.) is in the "SDK Customizations" section.

→ Recommendation: if your company chooses colors, fonts, or texts different from the defaults already provided by Fortface, read the "Usability Guide" page before finalizing your brand guide. It brings guidelines tested with real users (color-by-status convention, minimum contrast, message tone) that directly impact capture success rate.

Instruction screen (before the selfie)​

Can be turned on or off entirely (instructionScreen). When active, it shows 4 default tips before opening the camera (remove glasses/cap, find a well-lit place, neutral expression, phone position): title, texts, icons, colors, and the "Continue" button are all customizable.

Fortface recommendation: keep the screen active. It reduces rework and increases the success rate on the first capture attempt.

There is no equivalent instruction screen before document capture: that flow goes straight to the camera.

User permissions​

  • Camera: mandatory. Without it, the SDK doesn't work.
  • Geolocation: optional, enabled per session (SessionDetails.getGeolocation). If the user denies it, capture proceeds normally. It's a business decision: one more antifraud signal vs. one more permission requested from the user (which can create friction).

Document capture and upload​

  • Capture mode: automatic (default) with manual button fallback, unlike the selfie, which is automatic only.
  • File upload: can open the photo gallery or the phone's file manager (openPhotoGalery), which determines whether the user can send PDFs or only images.
  • Size limit: files above 4MB are automatically rejected (fixed rule, not configurable; worth considering when guiding the user).
  • Post-capture review screen: asks whether the document is sharp/legible, with the option to confirm or redo it.

Display mode​

  • Fullscreen (default) or modal: modal only works on tablets; on smartphones, it always opens fullscreen.
  • Orientation: automatic, portrait, or landscape (also only configurable on tablets; smartphones are always portrait).

Error handling and retry behavior​

When the user fails and tries again, the app should reuse the same externalTransactionId instead of opening a new transaction: this is what allows correctly measuring the success rate per transaction (and not per individual attempt).

iOS SDK​

Colors, theme, and branding​

The iOS customization logic is equivalent to Android's: two approaches (Swift code, being phased out, or JSON file, recommended), which cannot be combined.

Same coverage as Android: background color, button color/text, icons, logo (selfie camera), and font, across each screen of the flow (instruction, selfie camera, document camera, upload).

Important iOS difference: when using the JSON file, only the font family is applied: font size and weight (font.size, font.weight) defined in the JSON have no effect on iOS. Worth aligning this limitation with the design team when putting together the brand guide.

→ Recommendation: if your company chooses colors, fonts, or texts different from the defaults already provided by Fortface, it's worth reading the "Usability Guide" page before finalizing your brand guide. It brings guidelines tested with real users (color-by-status convention, minimum contrast, message tone) that directly impact capture success rate.

Instruction screen​

Same behavior as Android: can be enabled/disabled, with title, 4 tips, icons, and "Continue" button all customizable. Fortface recommends keeping it active: it reduces rework and increases the success rate on the first attempt. There is also no equivalent screen before document capture (only a post-capture review screen).

User permissions​

  • Camera: mandatory. The text shown to the user explaining why access is needed is free-form; it's up to your product team to write this message (configured in the app, not in the SDK).
  • Geolocation: optional, per session, same rationale as Android (antifraud signal vs. friction).
  • Photo/file gallery: requested only if the document upload flow is enabled.

Document capture and upload​

  • Automatic capture with manual fallback, 4MB file limit, and the same post-capture review screen as Android.
  • Document capture orientation is always portrait, with no option to configure it differently (unlike the selfie, which allows portrait/landscape on tablets).

Display mode​

Same options as Android: fullscreen (default) or modal (tablets only), automatic/portrait/landscape orientation (tablets only).

Error handling and retry behavior​

The SDK doesn't have a built-in error screen; it's up to the app to decide the experience for each scenario (camera denied, timeout, technical error, cancellation). Fortface recommends also logging cancellation and timeout events (not just success) to get real funnel metrics, and reusing the same externalTransactionId on new attempts.

Web SDK​

Colors, theme, and branding​

The Web SDK follows the same customization philosophy via a theme object (theme/components), with a few options exclusive to the web version (embedded mode, use in iframe/WebView). This section is also the only one that covers decisions about Fortlink (remote capture link), since it's a browser-hosted flow.

Coverage equivalent to the mobile SDKs: font, background color, logo, buttons, and status colors per screen (overall theme, instruction screen, selfie camera, ready screen, document camera, upload).

The full list of customization parameters is in the "SDK Customizations" section.

→ Recommendation: if your company chooses colors, fonts, or texts different from the defaults already provided by Fortface, it's worth reading the "Usability Guide" page before finalizing your brand guide. It brings guidelines tested with real users (color-by-status convention, minimum contrast, message tone) that directly impact capture success rate.

Instruction screen​

Can be enabled/disabled (face_recognition.instructions_screen.visible), with the same set of customizable texts, icons, and button as the other platforms. The recommendation to keep it active applies here too: it reduces rework and increases the success rate on the first attempt.

→ CTA: to be validated with the technical team: the source documentation shows a possible key duplication between two instruction screen texts (the "neutral expression" tip and "remove glasses/cap" tip using the same reference); worth confirming which one prevails before translating this into a customization guide for the client.

As with the mobile SDKs, there is no equivalent instruction screen before document capture.

Display modes (Web exclusive)​

Three options, more flexible than mobile:

  • Fullscreen: default.
  • Modal: with customizable overlay (color/opacity); automatically activated from a configurable minimum screen width (designed for desktop).
  • Embedded: the SDK runs inside a space on your own page, without opening over everything. Requires a minimum area size (400x650px).

This is a relevant product architecture decision (e.g., embedding verification within an onboarding form vs. opening over the whole screen); see the "Modal or Fullscreen Mode" section for technical details.

User permissions​

  • Camera: mandatory; if denied, browsers don't automatically reopen the request, so Fortface recommends not retrying in a loop and guiding the user to manually grant permission and reload the page.
  • Geolocation: optional, per session, same rationale as the mobile SDKs.
  • Use in iframe/WebView: requires additional configuration (allow="camera") for the camera to work; without it, the flow fails before it even starts. Relevant if the product is integrated within a partner's app.

Camera used for selfie capture​

By default, the Web SDK opens the front camera for the selfie. It's possible to configure the use of the back camera instead (useBackCamera parameter, available from Web SDK version 2.3.0), useful in assisted capture scenarios, such as an attendant photographing the user. This option is exclusive to the Web SDK; no equivalent documentation was found for Android or iOS.

How to configure it: useBackCamera: true when starting the facial biometrics session.

Document capture and upload​

Same logic as the mobile SDKs: live capture with manual fallback, file upload, post-capture review screen.

Error handling and retry behavior​

The SDK ends each session with one of these actions, which the app needs to handle with its own experience: capture (success), cancel (user canceled), timeout (capture time expired), timeout_ready (loading/ready time expired), and error (failure, with a specific code). Fortface recommends keeping a log of these events (not just the success one) to get real funnel metrics, avoiding retrying in a loop when camera permission is denied, and reusing the same externalTransactionId on new attempts.

Experience metrics (Web exclusive)​

By enabling returnMetrics: true, the session returns the time spent on each step (asset download, camera opening, instruction screen, capture). This is a product tool: it lets you measure, for example, whether it's worth keeping the instruction screen by comparing its time against the success rate.

Browser compatibility​

Defines who can complete the flow: it requires, for example, Chrome 112+, Safari 15.4+, Firefox 110+ (varies by operating system). Worth considering when sizing conversion: users on older browsers receive an incompatibility error.

Fortlink is a remote capture link generated by the API. Your company creates the link and decides how to send it to the user (SMS, email, WhatsApp); Fortface doesn't send anything, it only generates the link. The end user opens the link in the browser and completes verification without needing to install anything, which is an alternative to embedding the Web SDK directly on your site or app. That's why these decisions appear only here, in the Web section.

Via Fortlink, the set of actions available today is enroll, identify, capture, and liveness; search and /document are exclusive to the direct call via SDK/Backoffice (see topic 1).

See the "Fortlink: Available actions" section to design the full flow for each use case.

Every Fortlink ends in one of these statuses, and it's up to your company to decide what to do in each case:

  • PENDING: user hasn't completed it yet
  • EXPIRED: link expired before use
  • APPROVED: approved (liveness and/or Hubface score positive)
  • REJECTED: liveness rejected more than 5 times, or Hubface score 1 or 2
  • INCONCLUSIVE: Hubface score 0 or 3 (nothing can be confirmed)

See the "Fortlink: Possible statuses" section for the details of each rule.

Your company decides how and when it receives the verification result. Three available mechanisms, which can be combined:

Fortlink webhook: when creating a remote capture link, you provide a URL that automatically receives the result as soon as the user finishes (or the link expires). It's the recommended channel, more reliable than manually polling.

Manual polling: an alternative to the webhook: check the link's status at any time via your own call.

Post-flow redirect (redirectURL): takes the user back to your app/site after the final screen. It's navigation only; it doesn't replace the webhook as the source of the result.

Since Fortlink is asynchronous (the result arrives later, via webhook or manual polling, and not immediately as in a direct call), the externalTransactionId and externalUserId fields (see the "Correlation IDs" topic above) are essential for cross-referencing the received result with your internal transaction and user. Strongly recommended to always generate and send these IDs when creating the Fortlink.

Last updated on