Onfido logo home page
Watch a demo
Get in touch
Arrow back Back to guides

Migration guide: Onfido privacy notices and consent (US)

Start here

The following guide is designed to help you migrate to the new process of collecting US end user consent for completing checks with Onfido. These changes are necessary in order to be compliant with biometric laws in the US and enable the verification of end users located in the US with Onfido.

We recommend updating your integration as soon as possible. Starting in Q3 2022, if you have not complied with these requirements, we may be unable to continue to support your IDV checks.

Please contact client support if you would like to find out more or require additional assistance.

You may also wish to read our Onfido privacy notices and consent guide to find out more about the requirements for collecting US end user consent.

Version upgrades

In order to update your integration to use the new 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

Summary of differences - API parameters

API location parameter

Location is a new concept introduced for API v3.4. The current location of an end user determines the necessary consent required in order to process a verification. As a result, it is now mandatory to specify the location of each applicant before creating a 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 as part of your API request 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:

...
"location": {
        "ip_address": "219.44.17.31",
        "country_of_residence": "USA"
    }
...

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.

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.

Onfido has created a new mandatory API 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 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 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:

...
"consents": [
         {
            "name": "privacy_notices_read",
            "granted": true
        }
    ]
...

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 checks will fail with a validation error.

The parameter is not returned in the applicant object.


Implementation

You can no longer implement the SDK consent screen directly in your SDK configuration during initialization. Instead, it is controlled by the Onfido backend.

Before

The SDK screen could be optionally implemented by initiating the SDK with or without the additional consent step included.

iOS example:

let config = try! OnfidoConfig.builder()
    ...
    .withUserConsentStep()
    ...
    .build()

Android example:

final FlowStep[] defaultStepsWithWelcomeScreen = new FlowStep[]{FlowStep.USER_CONSENT,};

Web example:

Onfido.init({
  …
  steps: ['welcome', 'userConsent', 'document', 'face', 'complete'],
})

After

The SDK consent screen is now controlled by the Onfido backend. There is no action required on your side to implement the consent screen. The user consent step should be removed from your integration.

Please contact us if you would like to find out more.

Note: The option to specify the 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 consent screen is now mandatory for end users located in the US and is only shown to end users located in the US.

Before

The SDK consent screen was optional.

The 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 consent screen is mandatory for all end users located in the US.

The SDK 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 consent screen accordingly. As a result, not all end users will see the consent screen. If the end user’s location is not the US the consent screen will not be shown.

Screen

The contents of the SDK screen has not changed.

The 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 consent screen unless they click the "Accept" button.

API requirements

You no longer need to submit API parameters when using the Onfido SDK 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 consent screen.

After

There are no requirements to manually provide API parameters when using the Onfido SDK consent screen. The Onfido SDK collects the location and consent status of the end user directly and provides this to the Onfido backend.


Screen

There is no change to the requirements for the consent screen if you have built your own consent stage into your application. You can continue to use the same screen.

API requirements

You must now provide the new API parameters, in addition to showing the 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 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 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 check creation requests for the end user will fail with a validation error.

Onfido

Our solutions

Onfido uses 256-bit SSL encryption 100% of the time on every device.

BSI ISO/IEC27001

Onfido has been certified by BSI to ISO 27001 under certificate number IS 660122.

© Onfido™, 2022. All rights reserved.
Company Registration Number: 07479524.