# Integration use cases

This page presents some of the most common use cases for electronic verification of ID documents (eIDV), using Signicat's Assure API.


Page contents

# 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 (Use case 1). Relevant for usage with Onfido and Signicat Paper providers.
  • You use the Signicat Capture app for capturing images or video (Use case 4). Relevant for usage with ElectronicID and Onfido providers.
  • You host the third-party SDK to capture the image or video (Use case 2, 3 and 5). Relevant for usage with ElectronicID, Onfido and ReadID providers.

Tip

If you are unsure about which alternative fits you best, see Integration guide > Recommended paths.

# Additional information

# UC 1: Use Onfido and integrate only with 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.

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

click-to-zoom

The color codes illustrate the flow decision:

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

# 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 (opens new window)

  • Extra optional step: Check the images that were uploaded using the Get Image (opens new window) 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 (for more information, see Get process > Response structure).

# UC 2: Use Onfido and integrate 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.

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

click-to-zoom

The color codes illustrate the flow decision:

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

In this case, you will perform the same steps as in Use Case 1, except from some differences in step C and D.

# Step C: Create process

  • For web apps: Indicate the URL of the web page where the Capture app 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 processIdto be used in 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). Please contact Signicat support for information on how to do that.

# UC 3: Use Electronic IDentification (EID) and integrate 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 (opens new window) (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.

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

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

click-to-zoom

The color codes illustrate the flow decision:

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

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

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

# Step B: Get document types

When integrating with EID’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 IDentification on your environment.

Tip: EID 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 Signicat Support at support@signicat.com.

# 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 in 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 Supporat at support@signicat.com.

# Step E: Start verification

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

  • Access EID’s Registration Authority App. If you don’t have the link to that app, use the Get Manual Approval URL (opens new window) 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 (for more details about the process structure, see Response structure).
  • All information is normalized and 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 (opens new window) endpoint.

# UC 4: Use Electronic IDentification and integrate only with Assure API (web usage only)

I want to allow an end-user to verify their identity using the Electronic IDentification (EID) provider in my website.

I want the required ID images to be captured and uploaded using EID’s SDK but I don’t want to integrate with it.

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

In the end, I want to see all the information regarding the verification process. Afterwards, I want to delete the dossier (including all the end-user information).

Note: This use case only fits web (JS) applications.

In this use case, you integrate only with the Assure API. However, the end-user experience is the same as in Use Case 3, since EID’s Web (JS) SDK is embedded in the Assure API’s Capture Flow service.

click-to-zoom

The color codes illustrate the flow decision:

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

# Step A: Create dossier

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

# Step G: Start Capture flow

  • Use that dossierId in the Start Capture flow (opens new window) request.
  • In the request, you must also indicate the redirectUrl to redirect the user to the required page after the verification is finished.
  • It is recommended to send a notificationUrl to receive a callback after the process is finished.

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

{
    "providers": [
        {
            "provider": "eid"
        }
    ],
    "notificationUrl": "https://labs.signicat.com/proxy?target=<SERVER_URL>",
    "redirectUrl": "https://my-redirect-url.com/"
}
{
    "url": "https://preprod.signicat.com/capture/#/artifact=4pwgyft1874rqzt8ww9z3v0r5xmqeodro3wy2nin3hgcdvy96g"
}
  • You must use this URL to redirect the end-user to the web page where they will be asked to verify their identity.

  • After the end-user has identified themselves, they will be redirected to the specified redirectURLyou sent in the request.

  • Then you should wait for the callback notification to arrive before you proceed to the Get process step (see below).

# Step F: Get process

After you get the notification in the URL you provided in step G (above), you know that the verification result is ready. You can then use the following requests to get information about the process:

After you have finished the end-user verification, you can delete the dossier:

# UC 5: Use ReadID and integrate 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.

Note: 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.

click-to-zoom

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

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

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 be used in the next step.

# Step D1: Launch provider’s SDK

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

Last updated: 6/1/2021, 10:28:36 AM