Migration guide: Onfido US Biometric Privacy Laws notices and consent (US)
Start here
The following guide is designed to help you migrate to the new process of collecting US Biometric Privacy Laws end user consent for completing checks with Onfido. These changes necessitated by Onfido’s mandatory biometric controls which apply to any Document, Facial Similarity or Known Faces checks for any user located in the US at the time of the check.
US state biometric privacy laws, including but not limited to Section 14 of Title 740 of the Illinois Compiled Statutes (BIPA), Chapter 503 of Title 11 of the Texas Business and Commerce Code (CUBI), and Chapter 19.375 of Title 19 of the Revised Code of Washington (“US Biometric Privacy Laws”), may regulate the collection and use of biometric identifiers, biometric information, or biometric data (“Biometric Data“). Onfido’s mandatory US biometric controls require customers with end users located in the US at the time Onfido processes a Document, Motion or Facial Similarity Check to:
- incorporate Onfido privacy notices and US Biometric Privacy Laws consent language into their interface; and,
- submit an API consent parameter which confirms that consent has been granted to collect biometric data. We recommend updating your integration as soon as possible. If you have not complied with these requirements, we may be unable to continue to support your IDV checks.
Please contact client support to find out more or require additional assistance.
You can also read our Onfido privacy notices and consent guide to find out more about the requirements for collecting US end user consent.
Customers remain responsible for complying with US Biometric Privacy Laws and other applicable privacy laws, including any requirements to collect consent or give notice under laws such as GDPR, or US State Privacy laws. This guide is intended as guidance only and does not constitute legal advice. Clients should seek their own legal advice if using Onfido’s products in the US.
Version upgrades
In order to update your integration to use the new US Biometric Privacy Laws consent features you must upgrade to at least the following versions of the API and SDKs.
- API v3.4
- SDKs
- iOS 25.0.0
- Android 12.0.0
- Web 8.0.0
- React Native 5.4.0
- Flutter 1.0.0
Summary of differences - API parameters
This section describes changes to the Onfido API regarding US Biometric Privacy Laws consents.
If using one of the Onfido SDKs on a version equal or above the ones listed, you may ignore this section. See Onfido privacy notices and consent guide and/or changes for SDKs.
API location parameter
Location is a new concept introduced for API v3.4. The current location of an end user determines the necessary US Biometric Privacy Laws consent required in order to process a Document, Facial Similarity or Known Faces check. As a result, it is now mandatory to specify the location of each applicant before creating a Document, Facial Similarity or Known Faces check with Onfido.
Onfido provides the following parameter in the applicant and documents resource for specifying the location of an applicant:
| Name | Description |
|---|---|
location | optional The location of the applicant. |
You must provide location before attempting to create a Document, Facial Similarity or Known Faces check. This can be done when creating an applicant, updating an applicant or uploading a document. You can input the IP address and the country of residence (3 character ISO country code) of the applicant.
Example:
1...2"location": {3 "ip_address": "219.44.17.31",4 "country_of_residence": "USA"5 }6...
The location parameter is mandatory for all applicants in order to create a check with a Facial Similarity report. If you do not provide the location parameter, all checks will fail with a validation error due to missing applicant location.
If you submit location information during applicant creation, this will be returned in the applicant object. If you submit location information during document upload, this will not be returned in the applicant object.
Note: If the location of the applicant is the US, then it is mandatory to also provide the consents parameter.
API US Biometric Privacy Laws consent parameter
Onfido has created a new mandatory API US Biometric Privacy Laws consent parameter consents in API v3.4, which replaces the existing consent parameter privacy_notices_read_consent_given.
Before
Onfido provided the following optional parameter in the check resource for confirming end user US Biometric Privacy Laws consent:
| Name | Description |
|---|---|
privacy_notices_read_consent_given | optional Boolean to indicate that the privacy notices and terms of service have been read and, where specific laws require, that consent has been given for Onfido. |
You could submit the parameter during check creation as true or false. If set to false, the request would fail with a validation error.
As an optional parameter, it could be omitted and the check would still process.
In API v3 the parameter was not returned in the check object. From API v3.1 onwards the parameter was returned in the check object. Returned a value of true if specified during check creation, otherwise returned null.
Note: This parameter is deprecated from API v3.4 onwards.
After
Onfido now provides the following parameter in API v3.4 in the applicant resource for confirming end user US Biomentric Privacy Laws consent for applicants located in the US:
| Name | Description |
|---|---|
consents | optional Indicates whether consent has been given by the applicant. |
You can include consents as part of your API request when creating or updating an applicant.
Example:
1...2"consents": [3 {4 "name": "privacy_notices_read",5 "granted": true6 }7 ]8...
granted should be set to true where the user is located in the US (as specified in the location parameter) and the end user has viewed and accepted the Onfido privacy notices and consent language.
If it's set to false, check creation requests will fail with a validation error.
The consents parameter is mandatory for any applicant who is located in the US. If you do not provide the consents parameter and the location of the applicant is the US, all Document, Facial Similarity and Known Faces checks will fail with a validation error due to either missing applicant location or missing consents.
The parameter is not returned in the applicant object.
Summary of differences - SDK US Biometric Privacy Laws consent screen
Implementation
You can no longer implement the SDK US Biometric Privacy Laws consent screen directly in your SDK configuration during initialization. Instead, it is controlled by the Onfido backend.
Before
The SDK US Biometric Privacy Laws screen could be optionally implemented by initiating the SDK with or without the additional US Biometric Privacy Laws consent step included.
iOS example:
1let config = try! OnfidoConfig.builder()2 ...3 .withUserConsentStep()4 ...5 .build()
Android example:
1final FlowStep[] defaultStepsWithWelcomeScreen = new FlowStep[]{2 …3 FlowStep.USER_CONSENT,4 …5};
Web example:
1Onfido.init({2 …3 steps: ['welcome', 'userConsent', 'document', 'face', 'complete'],4})
After
The SDK US Biometric Privacy Laws consent screen is now controlled by the Onfido backend. There is no action required on your side to implement the US Biometric Privacy Laws consent screen.
Customers remain responsible for complying with US Biometric Privacy Laws and other applicable privacy laws, including any requirements to collect consent or give notice under laws such as GDPR, or US State Privacy laws.
Please contact us to find out more.
Note: The option to specify the US Biometric Privacy Laws consent screen during SDK initialization is deprecated from iOS 25.0.0, Android 12.0.0 and Web 8.0.0. This is a breaking change. If you try to initialise the SDK with this optional step, you will receive an error.
Logic
The US Biometric Privacy Laws consent screen is now mandatory for end users located in the US and is only shown to end users located in the US or when we cannot determine end user location.
Before
The SDK US Biometric Privacy Laws consent screen was optional.
The US Biometric Privacy Laws consent screen could be implemented for all end users, no end users or a subsection of end users depending on your implementation.
After
The SDK US Biometric Privacy Laws consent screen is mandatory for all end users located in the US.
The SDK US Biometric Privacy Laws screen is only shown to end users located in the US. The SDK uses IP address information to approximate the end user’s location at a city and country level, and shows the US Biometric Privacy Laws consent screen accordingly. As a result, not all end users will see the US Biometric Privacy Laws consent screen. If the end user’s location is not the US, or both location and consent are provided to Onfido before the user enters the SDK capture flow, the US Biometric Privacy Laws consent screen will not be shown.
US Biometric Privacy Laws Screen
The US Biometric Privacy Laws consent screen will still be shown to the end user at the beginning of the SDK flow (if applicable), before they are asked to enter any personal information or upload media. The end user will not be able to continue past the US Biometric Privacy Laws consent screen unless they click the "Accept" button.
API requirements
You no longer need to submit API parameters when using the Onfido SDK US Biometric Privacy Laws consent screen.
Before
You were required to set the API parameter privacy_notices_read_consent_given outside of the SDK flow when creating a check, in addition to showing the SDK US Biometric Privacy Laws consent screen.
After
There are no requirements to manually provide API parameters when using the Onfido SDK US Biometric Privacy Laws consent screen. The Onfido SDK collects the location and US Biometric Privacy Laws consent status of the end user directly and provides this to the Onfido backend.
Summary of differences - Building an Onfido US Biometric Privacy Laws notices and consent stage into your own application
US Biometric Privacy Laws Screen
There is no change to the requirements for the US Biometric Privacy Laws consent screen if you have built your own US Biometric Privacy Laws consent stage into your application. You can continue to use the same screen.
Customers remain responsible for complying with US Biometric Privacy Laws and other applicable privacy laws, including any requirements to collect consent or give notice under laws such as GDPR, or US State Privacy laws.
API requirements
You must now provide the new API parameters, in addition to showing the US Biometric Privacy Laws consent screen in your application.
Before
You were required to set the API parameter privacy_notices_read_consent_given outside of your application when creating a check, in addition to showing your US Biometric Privacy Laws consent screen.
Note: This API parameter is deprecated from API v3.4 onwards.
After
You must provide the location parameter outside of your application before creating a check, in addition to showing your US Biometric Privacy Laws consent screen. If you do not provide location, all check creation requests for all end users will fail with a validation error.
If the end user’s location is the US, after the end user has viewed and accepted the Onfido privacy notices and consent language, you must also provide the consents parameter outside of your application before creating a check. If you do not provide consents, or it is set to false, all Document, Facial Similarity and Known Faces check creation requests for the end user will fail with a validation error.
