Developer Pages

# Signicat Electronic IDentification


Page contents

# Supported features

Electronic IDentification (opens new window) is Signicat's own eIDV service integrated with Assure API. This service offers the following features:

  • ID document check
  • Face match between ID document and selfie
  • Liveness check of live video recording
  • Manual review or live interview by a support agent

# Integration use cases

This section assumes you already have done the initial integration steps with the Assure API, i.e. set up client credentials and access token.

# UC 1: Use EID and integrate only with Assure API (web usage only)

I want to allow an end-user to verify their identity using the Electronic IDentification (opens new window) (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. EID’s Web (JS) SDK is embedded in the Assure API Start capture flow (opens new window) service.

Use case 4 flow click-to-zoom

The colour codes illustrate the flow decision:

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

# Step A: Create dossier

  • Use the Create dossier (opens new window) endpoint to create a placeholder for all of your end-user’s data.
  • Save the dossierId you get in the response to be used in the next requests.

Note:

Ensure you use one dossier per end-user.

# Step G: Start capture flow

  • Use the dossierId from step A 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 subscribe to Assure events to be notified when the result is available.

Code example:

{
    "providers": [
        {
            "provider": "eid"
        }
    ],
    "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.

  • It is recommended to subscribe to Assure events to be notified when the result is available. Then wait for the notification to arrive before you proceed to the Get process step (see below).

# Step F: Get process

If you subscribe to Assure events, you will get notified when the verification result is ready. You can then use the following requests to get information about the process:

  • Get process: Use the dossierId and processId in the event notification. The process now contains data about the process final result (for more information, see Final result status).
  • Get video: Use the Get video (opens new window) endpoint to get a video of the end-user capturing images of the identity document.
  • Download full result: Use the Download full result (opens new window) endpoint to download all the information regarding the process.

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

# UC 2: Use 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's (opens new window) SDK.

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. Use case 3 flow click-to-zoom

The colour 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, 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 Create process (opens new window) endpoint to create an identity verification process in that dossier. Ensure you give it the dossierId you got in the Create dossier response. Enter the EID provider in the request body:
{
  "provider": "eid"
}
  • At this point, you can also request to receive a notification of when the verification is finished (see 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 do this, please contact us 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.
  • 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 Assure event 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, see Final result status).
  • All information is normalised 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.

# SDKs

To get help with using the SDKs from Electronic IDentification, please contact us at support@signicat.com.

# Service details for Electronic IDentification

This section goes more into detail about some useful endpoints when integrating with EID:

# Start Capture flow

# Capture SDK

More information will follow later.

# Electronic IDentification native JS SDK configuration

The Capture configuration also includes specific configuration fields when using the Electronic IDentification native SDK. This configuration applies when the sdk field in the "Start Capture flow" request is set to native and provider to eid.

For more details, see the eidConfig element in the API Reference for either Create (opens new window) or Update capture configuration (opens new window).

# Get process

This section describes the final result statuses for ElectronicIDentification. For a more general description of how the "Get process" endpoint works, see Service details > Get process and the API Reference (opens new window).

# Final result status

Electronic IDentification returns information about whether the verification was accepted, rejected, inconclusive or failed. Assure API simply maps those values directly to the process' final status. Reasons for the process to be rejected is part of the response.

Electronic IDentification responses will always have an ocr element (see the code example below). For unattended and attended process types (respectively without or with an agent present), it will also have a manualApproval element. For more details about process types, see API Reference > Get process > processType (opens new window).

# accepted

This is a response example of an Electronic IDentification process that was accepted:


    {
    "status": "accepted",
    "processId": "e0dea380-4219-4388-81bb-61a56ed73ef3",
    "provider": "eid",
    "providerSpecific": {
        "ocr": {
            "similarityScore": "high",
            "livenessDetected": "true",
            "features": [
                {
                    "name": "Header",
                    "found": true,
                    "bbox": {
                        "x": 84,
                        "y": 28,
                        "width": 248,
                        "height": 32
                    },
                    "side": "data"
                },
                {
                    "name": "OVI 2",
                    "found": true,
                    "bbox": {
                        "x": 596,
                        "y": 44,
                        "width": 32,
                        "height": 24
                    },
                    "side": "data"
                },
                {
                    "name": "Signature",
                    "found": true,
                    "bbox": {
                        "x": 402,
                        "y": 273,
                        "width": 217,
                        "height": 60
                    },
                    "side": "data"
                },
                {
                    "name": "Photo",
                    "found": true,
                    "bbox": {
                        "x": 32,
                        "y": 168,
                        "width": 141,
                        "height": 141
                    },
                    "side": "data"
                },
                {
                    "name": "OVI 1",
                    "found": true,
                    "bbox": {
                        "x": 12,
                        "y": 44,
                        "width": 72,
                        "height": 80
                    },
                    "side": "data"
                }
            ],
            "securityChecks": {
                "nonExpired": {
                    "valid": true
                },
                "notUnderage": {
                    "valid": true
                },
                "dataIntegrity": {
                    "valid": true
                },
                "livenessDetected": {
                    "valid": true
                },
                "notFaceSpoofing": {
                    "valid": true
                },
                "notBWCopy": {
                    "valid": true
                }
            },
            "documentNumber": "1234567890",
            "dateOfExpiry": "2025-10-05",
            "firstName": "MARIA PAULA",
            "lastName": "SANTOS MENDES",
            "documentType": "passport",
            "dateOfBirth": "2002-04-29",
            "gender": "F",
            "nationality": "PRT",
            "personalIdentificationNumber": "FANTASYBANK1234567890",
            "issuingCountry": "PRT"
        }
    },
    "processType": "substantial",
    "createdAt": "2021-06-09T10:04:42Z",
    "updatedAt": "2021-06-09T10:05:41Z"
}

For field descriptions, see the Open API documentation > Get process (opens new window).

# rejected

The process gets the rejected status if one or more security checks are not valid. In this example, the reason is that the document has expired:















 











































    {
    "status": "rejected",
    "processId": "1cc14545-0396-4cbe-8501-8f2461a91dfe",
    "provider": "eid",
    "providerSpecific": {
        "ocr": {
            "features": [
                {
                    ...
                },
                ...
            ],
            "securityChecks": {
                "nonExpired": {
                    "valid": false
                },
                "notUnderage": {
                    "valid": true
                },
                "dataIntegrity": {
                    "valid": true
                },
                "livenessDetected": {
                    "valid": true
                },
                "notFaceSpoofing": {
                    "valid": true
                },
                "sidesMatch": {
                    "valid": true
                },
                "notBWCopy": {
                    "valid": true
                }
            },
            "socialSecurityNumber": "11926318740",
            "healthNumber": "1234567890",
            "taxNumber": "199693803",
            "similarityScore": "high",
            "livenessDetected": "true",
            "documentNumber": "1234567890",
            "dateOfExpiry": "2020-07-08",
            "firstName": "MARIA PAULA",
            "lastName": "SANTOS MENDES",
            "documentType": "identityCard",
            "dateOfBirth": "2002-04-29",
            "gender": "F",
            "nationality": "PRT",
            "personalIdentificationNumber": "FANTASYBANK1234567890",
            "issuingCountry": "PRT"
        }
    },
    "processType": "substantial",
    "createdAt": "2021-06-09T10:37:10Z",
    "updatedAt": "2021-06-09T10:38:04Z"
}

For field descriptions, see the Open API documentation > Get process (opens new window).

# inconclusive

A process gets the inconclusive status in the following cases:

If you get an inconclusive status, you should inspect the process response to find the reason.

In this example the status is inconclusive since both similarityScore is too low (verylow) and two features are missing (OVI 1 and OVI 2 = false).







 















 


























 








































{
    "status": "inconclusive",
    "processId": "e0dea380-4219-4388-81bb-61a56ed73ef3",
    "provider": "eid",
    "providerSpecific": {
        "ocr": {
            "similarityScore": "verylow",
            "livenessDetected": "true",
            "features": [
                {
                    "name": "Header",
                    "found": true,
                    "bbox": {
                        "x": 85,
                        "y": 37,
                        "width": 249,
                        "height": 33
                    },
                    "side": "data"
                },
                {
                    "name": "OVI 2",
                    "found": false,
                    "side": "data"
                },
                {
                    "name": "Signature",
                    "found": true,
                    "bbox": {
                        "x": 392,
                        "y": 281,
                        "width": 202,
                        "height": 65
                    },
                    "side": "data"
                },
                {
                    "name": "Photo",
                    "found": true,
                    "bbox": {
                        "x": 44,
                        "y": 178,
                        "width": 141,
                        "height": 141
                    },
                    "side": "data"
                },
                {
                    "name": "OVI 1",
                    "found": false,
                    "side": "data"
                }
            ],
            "securityChecks": {
                "nonExpired": {
                    "valid": true
                },
                "notUnderage": {
                    "valid": true
                },
                "dataIntegrity": {
                    "valid": true
                },
                "livenessDetected": {
                    "valid": true
                },
                "notFaceSpoofing": {
                    "valid": true
                },
                "notBWCopy": {
                    "valid": true
                }
            },
            "documentNumber": "1234567890",
            "dateOfExpiry": "2025-10-05",
            "firstName": "MARIA PAULA",
            "lastName": "SANTOS MENDES",
            "documentType": "passport",
            "dateOfBirth": "2002-04-29",
            "gender": "F",
            "nationality": "PRT",
            "personalIdentificationNumber": "FANTASYBANK1234567890",
            "issuingCountry": "PRT"
        }
    },
    "processType": "substantial",
    "createdAt": "2021-06-09T10:04:42Z",
    "updatedAt": "2021-06-09T10:05:41Z"
}
# failed

A process gets the failed status if an error prevented the verification from completing. Examples could be that the microphone access is denied by the end-user or that the process times out due to inactivity on the end-user side (usually after 3 minutes).

This is a response example of an Electronic IDentification process that failed:











 



{
    "status": "failed",
    "processId": "4644c061-e229-449a-b4db-643c7403bbdc",
    "provider": "eid",
    "processType": "substantial",
    "createdAt": "2021-04-15T08:25:04Z",
    "updatedAt": "2021-04-15T08:28:57Z",
    "failReason": {
        "id": "8ea0e55f-385f-47b7-a401-ef1db467a625",
        "type": "InactiveUser.Aborted",
        "message": "There has been no interaction with the video"
    }
}

In this case, you can find more information about why it failed in the failReason field. For more information, see the OpenAPI documentation (opens new window).

# Download full result

In the Get process response, you get the results for Electronic ID in the provider-specific area (for example similarityScore). For full information as obtained from the provider, use the Download full result service. This service returns a zip file containing data and media files about the verification.

# Data files

# ocr.json

This "raw" file contains all information about the OCR capture and automatic verification performed by EID.

# manual_approval.json

This "raw" file contains all information about the manual verification performed by the support agent.

# Media files

Type File name/format Comment
front front.jpeg
back back.jpeg Only retrieved if the ID document has a backside.
selfie selfie.jpeg
portrait portrait.jpeg
video video.mp4
Last updated: 03/05/2024 07:03 UTC

← FaceTec →