Skip to main content
Version: v6

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#

Step-by-step#

Forwarding the device's Installation ID to your server#

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.

//It is not advised to call Incognia.getInstallationId() on the main thread. If you call this method on the main thread, the installationId will be returned only if it is already available.val installationId = Incognia.getInstallationId()
// HttpURLConnectionhttpUrlConnection.setRequestProperty("Incognia-Installation-ID", installationId)
// 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:

// SignupController.java@Controller("/signup")public class SignupController {  private final DatabaseFacade dbFacade;    @Post  public HttpResponse<User> postSignup(@Valid @Body PostSignUpRequest request) {    boolean needsManualReview = true;    User u = new User(request.getUsername(), request.getUserAddress(), request.getIncogniaInstallationId(), needsManualReview);    dbFacade.save(u);    return HttpResponse.ok(u);  }}
important
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:

// SignupController.java@Controller("/signup")public class SignupController {  private final DatabaseFacade dbFacade;  // read how to use Incognia's Java Wrapper: https://github.com/inloco/incognia-api-java  private final IncogniaAPI incogniaAPI;    @Post  public HttpResponse<User> postSignup(@Valid @Body PostSignUpRequest request) {    boolean needsManualReview = true;    var incogniaAddress = convertToIncogniaAddress(request.getUserAddress());    var riskAssessment = incogniaAPI.registerSignup(request.getIncogniaInstallationId(), incogniaAddress).getRiskAssessment();    if (riskAssessment.equals(Assessment.LOW_RISK)) {      // Automatically approved if Incognia gives low risk! :D      needsManualReview = false;    }    User u = new User(request.getUsername(), request.getUserAddress(), request.getIncogniaInstallationId(), needsManualReview);    dbFacade.save(u);    return HttpResponse.ok(u);  }}

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.
Attention
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.