# Integration use cases

This page presents some of the most common use cases 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 (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 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](/docs/identification/about.html#supported-eidv-providers). For more details about using third-party providers’ SDK, please contact Signicat support.
  • If you need guidance for use cases that are not detailed here, please contact Signicat support.

# 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

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

click-to-zoom

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

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

click-to-zoom

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 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 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). Please contact Signicat support for information 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 (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.

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.

click-to-zoom

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 Signicat Support.

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

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 (for more details about the process structure, see Response structure).
  • 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 the Electronic IDentification provider in my website.

I want the required ID images to be captured and uploaded using Electronic ID’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 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 Capture Flow service.

click-to-zoom

Step A: Create dossier

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

Step G: Start Capture flow

  • Use that dossierId to start the service embedded in the Assure API that will use Electronic ID’s JS 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 use 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).

  • Get video
    • Use the Get video endpoint to get a video of the end-user capturing images of the identity document.
  • Get All Dossiers
    • Use the Get all dossiers endpoint to check information about all dossiers that have been created so far.
  • Delete Process
  • Delete Dossier

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

click-to-zoom

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

Last updated: 2/19/2021, 4:22:43 PM