Address verification on user onboarding

In this how-to, you will learn how to integrate the Incognia Onboarding API to add frictionless address verification to your mobile application. With this information, you may choose to automatically approve new signups and send suspicious ones to manual review.

Requirements

  • An Incognia account. Sign up here if you don't have an account.

  • An app with the Incognia SDK initialized. Follow SDK getting started guide for this.

  • API credentials to be able to make requests to Incognia APIs.

Step-by-step

Forwarding the device's Installation ID to your server

The Incognia SDK collects location and device data to build a behavioral profile for mobile users. This data is tagged with an identifier called Installation ID, which is automatically generated by the SDK.

To verify a new signup, Incognia needs to receive an Installation ID to identify the device from which the signup originates. Since your server will request the Incognia API to assess the risk of this new signup, it needs to receive this information from your mobile application.

The installation ID can be forwarded to your server in two ways.

Option 1: Sending the Installation ID as a header

Before sending a signup request from your mobile application to your server, call Incognia.getInstallationId and set its value as a header of the request. We encourage you to choose a clear name for this header, like Incognia-Installation-ID, so you can easily identify it on the server-side.

This option has a clear benefit if your application will use more than one Incognia solution because you won't need to change each request's properties, like signup, login, payment, password change, etc.

Kotlin
Java
Swift
Objective-C
Kotlin
Incognia.getInstallationId(context) { result ->
if (result.isSuccessful) {
val installationId = result.result
// HttpURLConnection
httpUrlConnection.setRequestProperty("Incognia-Installation-ID", installationId)
}
// Send the request with the installationId to your backend server
}
Java
Incognia.getInstallationId(context, new IncogniaListener<String>() {
@Override
public void onResult(final Result<String> result) {
if (result.isSuccessful()) {
String installationId = result.getResult();
// HttpURLConnection
httpUrlConnection.setRequestProperty("Incognia-Installation-ID", installationId);
}
// Send the request with the installationId to your backend server
}
});
Swift
ICGIncognia.getInstallationId({ installationId in
if installationId != nil {
// NSURLRequest
request.setValue(
installationId,
forHTTPHeaderField: "Incognia-Installation-ID"
)
}
// Send the request with the installationId to your backend server
})
Objective-C
[ICGIncognia getInstallationId:^(NSString *installationId) {
if (installationId != nil) {
// NSURLRequest
[request setValue:installationId forHTTPHeaderField:@"Incognia-Installation-ID"];
}
// Send the request with the installationId to your backend server
}];

Option 2: Sending the Installation ID in the body of the request

Before sending the signup request from your mobile application to your server, call Incognia.getInstallationId and send it as additional information about this new registration. We suggest that you choose a clear name for this property like Incognia-Installation-ID, so you can easily identify it on the server-side.

Handling the user's signup request

When your server receives a signup request, you can use Incognia intelligence to assess the risk of this new registration inside this request/response cycle or after it (if you don't need an immediate response in order to advance with the registration).

To evaluate this new signup risk, your server will request the Onboarding API informing that a new registration was made alongside its Installation ID and the address that the user claimed to be theirs (even though the declared address is an optional parameter, the risk assessment quality is greatly enhanced by its addition).

A sample implementation of a controller/handler

Let's consider a toy example as back-end with the controller below:

Ruby/Rails
Ruby/Rails
# signup_controller.rb
class SignupController < ApplicationController
def create
@user_form = CreateUserForm.new(params)
if @user_form.submit
redirect_to @user_form, notice: "Welcome to your account!"
else
render action: :new
end
end
end
# create_user_form.rb
class CreateUserForm < BaseForm
attr_accessor :name, :email, :address
validates :name, :email, :address, presence: true
# Other validations...
def submit
return nil if invalid?
User.create(
name: name,
email: email,
address: address,
# Assuming that you don't have a way to validate and all new signups
# need manual review (for simplicity sake).
needs_manual_review: true
)
end
end

You are required to authenticate when using the Incognia API. For authentication details, see Authenticating in Incognia APIs.

Considering that the authentication logic is implemented, you can add risk assessment requests to your signup handler:

Ruby/Rails
Ruby/Rails
# create_user_form.rb
class CreateUserForm < BaseForm
attr_accessor :name, :email, :address, :incognia_installation_id
validates :name, :email, :address, presence: true
def submit
return nil if invalid?
User.create(
name: name,
email: email,
address: address,
needs_manual_review: needs_manual_review?
)
end
private
def needs_manual_review?
api = Incognia::Api.instance
risk_assessment = api.register_signup(
installation_id: incognia_installation_id,
structured_address: build_address_for_incognia
)
# Automatically approved if Incognia gives low risk! :D
return false if risk_assessment == 'low_risk'
end
end
# incognia/api.rb
require 'faraday'
require 'json'
module Incognia
class Api
include Singleton
API_HOST = 'https://api.us.incognia.com/api/'.freeze
def register_signup(installation_id:, structured_address:)
signup_endpoint = 'v2/onboarding/signups'
params = {
installation_id: installation_id,
structured_address: structured_address
}
response = Faraday.post(
"#{API_HOST}#{signup_endpoint}",
params.to_json,
headers
)
if response.status == 200
parsed_body = JSON.parse(response.body)
parsed_body['risk_assessment']
else
# Error handling
end
end
private
def headers
{
'Content-Type': 'application/json',
# Read more about how to generate a fresh token at our
# Authenticating in Incognia APIs section.
Authorization: "Bearer #{fresh_token}"
}
end
end
end

Using the Incognia risk assessment

When your server makes a request to the Register new signup endpoint, it will receive a response like the following:

{
"id": "5e76a7ca-577c-4f47-a752-9e1e0cee9e49",
"request_id": "8afc84a7-f1d4-488d-bd69-36d9a37168b7",
"risk_assessment": "low_risk",
"evidence": {
"device_model": "Moto Z2 Play",
"geocode_quality": "good",
"address_quality": "good",
"location_events_near_address": 38,
"location_events_quantity": 288,
"location_services": {
"location_permission_enabled": true,
"location_sensors_enabled": true
},
"device_integrity": {
"probable_root": false,
"emulator": false,
"gps_spoofing": false,
"from_official_store": true
}
}
}

The response contains the id of the created entity (in this case a signup), the risk_assessment provided by Incognia based on device behavior, and evidence that supports this assessment. You can learn more about all returned data in this article: Understanding risk assessments.

The returned assessment can be used with other risk-related data, in a risk engine, to decide if this signup should be accepted.

Incognia's risk assessments include:

  • high_risk: the signup may be fraudulent and we advise you to take preventive actions in these scenarios, such as moving that signup to manual review;

  • low_risk: this signup seems to be safe to accept;

  • unknown_risk: we are unable to provide a precise assessment at the time of the request. Your server can request it again later for an updated risk assessment within 48 hours.

It is necessary to store the id in order to request an updated risk assessment in cases of unknown_risk and to send feedback to the Incognia API with the final decision about this signup.

Wrapping Up

After these steps, your application is ready to frictionlessly verify addresses to improve your user onboarding process.