Signicat Electronic IDentification

Supported features

Signicat Electronic IDentification 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 (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 service.

Use case 4 flow

The colour codes illustrate the flow decision:

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

Step A: Create dossier

• Use the Create dossier 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 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/"
}

• For other optional parameters in this request, see the OpenAPI documentation > Start capture flow.
• In the response, you will get a URL, e.g.

{
    "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 endpoint to get a video of the end-user capturing images of the identity document.
• Download full result: Use the Download full result endpoint to download all the information regarding the process.

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

• Use the Delete dossier endpoint to delete the dossier. Note: This will also delete all the information about this end-user.

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

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, you need to contact us by creating a support ticket in the Signicat Dashboard.

Step C: Create process

Use the Create process endpoint to create an identity verification process inside the dossier.

Ensure you:

• Use the dossierId from the "Create dossier" response.

• Set the provider to eid.

{
  "provider": "eid"
}

Save the authorizationToken and the processId from the response 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 information about how to do this, you can contact us by creating a support ticket in the Signicat Dashboard.

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

SDKs

To get help with using the SDKs from Electronic IDentification, you can contact us by creating a support ticket in the Signicat Dashboard.

Service details for Electronic IDentification

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

• Start Capture flow
• Get process
• Download full result

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 or Update capture configuration.

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.

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.

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.

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.

inconclusive

A process gets the inconclusive status in the following cases:

• When the similarityScore value in the OCR analysis is other than high (see description of possible values for similarityScore under OpenAPI docs > Get process > providerSpecific > ocr)
• When one or more features are not "found", e.g. if the end-user covers a visual element on the ID document while taking a photo of it.

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.

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