Identity verification

Integration use cases

1446 views December 9, 2019 September 28, 2020 0

This page presents some of the most common use cases (UC) for Signicat Assure API:

General information about the use cases

You have three possibilities when integrating with Assure API and starting an eIDV process:

  • You collect the image of the identity document and then upload the image(s) through the Assure API relevant for Onfido and Signicat Paper (UC1).
  • You use the Signicat hosted third-party web SDKs for capturing images or video relevant for eID and Onfido (UC4).
  • You host the third-party SDK to capture the image or video relevant for eID, Onfido and ReadID (UC 2,3 and 5).

Tip: If you are unsure about which use case fits you best, see the Integration details page.

Additional information:

  • The description of each use case is based on the same flows and steps presented in Integration Details.
  • For more information about the third-party providers (Onfido, eID and ReadID) in the use cases, see  Supported providers (API documentation). For more details about using third-party providers’ SDK, please contact Signicat.
  • If you need guidance for use cases that are not detailed here, please contact Signicat.

Understanding the flow diagrams

The following color codes illustrate the flow decision in the use case diagrams below:

  • Green = Must
  • Grey = Optional
  • White = Not used

“Web SDK service” is an encapsulation of the providers’ Web SDKs into the Assure API.

Use case 1: Verify ID document using Onfido and integrating only with Signicat Assure API (web or mobile usage)

I want to use Onfido to verify the identity of an end-user using their identity document.

I want to be able to upload the ID images directly through the Assure API without having to integrate with Onfido’s SDK.

I want to be notified when a final result has been obtained.

This use case seamlessly fits both web (JS) and mobile (Android/iOS) applications.

If you need more details about each step below, please follow the links in the headings (e.g. Step A below) to the API integration details page.

Step A: Create dossier

Save the dossierId from the response body to use on the next requests.

Step B: Get document types (optional)

This step is not required, but you may want to get the list of documents accepted by Onfido so you know which documentType Onfido supports (to be passed on to the next request).

In this use case, the document type is a passport.

Step C: Create process

  • Use the following example JSON in the request body.
    {
      "provider": "onfido",
      "documentType": "passport",
      "notificationUrl": "https://labs.signicat.com/proxy?target=<SERVER_URL>",
    }​

This request example shows that:

    • A passport is used to perform identity verification.
    • You will get a notification (in the provided URL) when the process is completed.
      Note: In order to receive notifications in production, you must request Signicat to whitelist your URL. To perform tests in preproduction, we recommend using https://labs.signicat.com/proxy as suggested in the example above.
  • Save the processId from the response to use on the next steps.

Step D2: Upload images

This JSON example file contains specimen images of a Norwegian passport and a selfie: NOR_passport-specimen_and_selfie.json

  • Extra optional step: Check the images that were uploaded using the Get Image endpoint. You should only be able to retrieve “FRONT” and “SELFIE”. “BACK” will only be available if you used a 2-sided document and “PORTRAIT” is not made available by Onfido.

Step E: Start verification

  • Extra optional step: Before requesting the verification to start, you may want to call Get Process to get the following process info:
    • The provider is”onfido”
    • The status is “pending”
  • Wait for the callback notification

Step F: Get process

After you get the notification in the URL you provided in step C, you know that the verification result is ready.

  • Call the Get Process endpoint: Use the dossierId and processId in the callback notification.

Tip: The process now contains data about the process’ final result (see documentation about the process structure for more information).

Use case 2: Verify ID document using Onfido and integrating with Onfido’s SDK (web or mobile usage)

I want to use Onfido to verify the identity of an end-user using their identity document.

I want the required ID images to be captured and uploaded using Onfido’s iOS SDK.

This use case seamlessly fits both web (JS) and mobile (Android/iOS) applications.

In this case, you will perform the same steps as in Use Case 1, except for Step C and Step D. For more details about each step, follow the links to the API integration details page.

Step C: Create process

  • For web apps: Indicate the URL of the web page where the Web SDK will be used. Use the example JSON file in the request body:
    {
      "provider": "onfido",
      "processParameters": {
          "referrer": "https://*.myserver.com/*"
      }
    }​
  • For mobile (iOS/Android) apps: Indicate the unique ID of the mobile app that will integrate with the SDK (bundle ID for iOS, application ID for Android). Use the example JSON file in the request body
    {
      "provider": "onfido",
      "processParameters": {
          "mobileAppId": "com.example.mymobileapp"
      }
    }
  • Save the authorizationToken and the processId to use on the next step.

Step D1: Launch provider’s SDK

Here you launch Onfido’s SDK instead of uploading the images through the Assure API (Use Case 1). Check this page for a list of guides on how to do that.

Use case 3: Verify ID document using Electronic IDentification (eID) and integrating with eID’s SDK (web or mobile usage)

I want to allow the same end-user from the previous use case to verify their identity, but now using Electronic IDentification  (eID).

In the end, I want to receive a final result with the same structure as the one from the test case before (despite having used a different provider).

I also want to see the information about all processes from this end-user.

This use case seamlessly fits both web (JS) and mobile (Android/iOS) applications.

Remember that Electronic ID always requires that the ID images are captured and uploaded using their SDK.

Note: Do not create a new dossier. Since this is the same end-user, you should use the same dossierId as on the previous use cases.

  • Use dossierId from the previous use cases on the next steps.

Step B: Get document types

When integrating with Electronic ID’s SDK, you must specify the ID of the document that will be used to verify the identity. To get that document ID you must use this endpoint to get the list of documents supported by Electronic ID on your environment.

Tip: Electronic ID supports more documents than the ones shown on that list, but they must be explicitly enabled. If you need to enable more documents, please contact our support team.

Step C: Create process

  • Use the example JSON in the request body.
    {
      "provider": "eid"
    }​
  • At this point, you can also request to receive a notification of when the verification is finished – check Use Case 1 for details on how to do that.
  • Save the authorizationToken and the processId to be used on the next step.

Step D1: Launch provider’s SDK

Now you must launch Electronic’s SDK in your app. For more details about how to use the different providers’ SDKs, please contact Signicat.

Step E: Start verification

Electronic ID requires that a manual approval of each verification request is performed using their Registration Authority Application (RA App).

  • Access Electronic ID’s Registration Authority App. If you don’t have the link to that app, use the Get Manual Approval URL endpoint to get it.
  • Select Start to work.
  • Accept a verification request.
  • Go through the indicated steps and register the verification.  Note: It is important to register the verification since it marks the process as “accepted“. If you reject it, the process status in the next step will be returned as “rejected” and you will not get a finalResult element in the response body.

Step F: Get process

  • Use the dossierId and processId from the previous steps (or from the callback notification, in case you use it).
  • The process status is now “accepted” and the response body contains data about the process final result (see documentation about the process structure for more information).
  • All information is normalized and that the “finalResult” element contains the same fields of information as the final result of the accepted Onfido requests in the previous use cases.
  • Get Dossier: Finally, to check the information about all processes regarding this end-user, call the Get Dossier endpoint.

Use case 4: Verify ID document using Electronic IDentification and integrating only with Signicat Assure API (web usage only)

I want to allow an end-user to verify their identity using Electronic IDentification in my website.

I want the required ID images to be captured and uploaded using the provider’s JS (Web) SDK, but I don’t want to integrate with their SDK. I want to integrate only with the Assure API.

I also want to be able to retrieve the video of the verification process.

In the end, I want to see all the dossiers I have so far, to to delete a process in a dossier and also delete a dossier of my choice.

This use case fits only web (JS) applications.

In this use case, you will only have to integrate with the Assure API but the experience of the end-user will be the same as in Use Case 3 because Electronic ID’s Web (JS) SDK will be embedded by the Assure API’s “Start Web SDK Flow” service.

Step A: Create dossier

    • Save the dossierId from the response body to use on the next requests.

Step G: Start Web flow

    • Use that dossierId to start the service embedded in the Assure API that will use Electronic ID’s web SDK flow to perform the verification.
    • In the service request, you must indicate the URL to where the end-user will be redirected when the SDK is finished/cancelled/failed.
      {
        "provider": "eid",
        "redirectUrl": "https://my-redirect-url.com/"
      }​
    • There are other optional parameters in this request (e.g., to set a callback notification URL). Please read the info in the link above for details.
  • No need to Get Document Types, Create Process or Start Verification, as in Use Case 3 – the service will take care of all that for you.
  • Manual approval
    • When the flow is finished, you can go to Electronic ID’s RA App (see Use Case 3 for details) and manually review and approve the verification.

Step F: Get process

The process now contains data about the process final result (see documentation about the process structure for more information).

Use case 5: Verify ID document using ReadID and integrating with ReadID’s SDK (mobile usage only)

I want to integrate with ReadID in my mobile app to allow an end-user to verify their identity using a NFC readable identity document.

ReadID can only be integrated in mobile applications (Android/iOS).

In this use case, the integration flow will be exactly the same as in Use Case 2 and 3.

For this use case, you must follow the same steps as in Use Case 1, only changing the provider chosen during step C:

Step C: Create process

  • Specify ReadID as the provider in the request body.
    {
      "provider": "readid"
    }​
  • Save the authorizationToken and the processId to use on the next step.

Step D1: Launch provider’s SDK

Launch ReadID’s SDK in your app. For details, please contact Signicat.

 

Was this helpful?