Signicat PictureID
Signicat PictureID is Signicat's own eIDV service for secure online customer onboarding. This service enables you to verify your user identity through an identity document check and a likeness verification.
Supported features
PictureID supports the following features:
- ID document check
- Face match between ID document and selfie
The PictureID service is available as a provider in the Assure API.
User flow
With the PictureID service, your end-users can identify themselves by taking a photo of their ID document and a selfie. Once the image data is analysed and approved, they can access your service.
The selfie step is optional. You can either request a photo of the ID document only, or both the ID document and a selfie.
With a default configuration, the end-user goes through the following steps:
- Read tips before they start (have ID document ready, good lighting, stable internet and camera/microphone access).
- Select device, either phone or desktop. Phone is recommended, since it gives a better user experience when capturing images of the ID document.
- Scan QR code with their mobile (if "Use phone" is selected).
- Select the issuing country for the ID document.
- Select the ID document type (passport, identity card, driving license).
- Choose to take a photo or upload a photo.
- Take a photo of the ID document. This is usually the photo ID page. Some ID documents also have a backside and the end-user might be asked to take a photo of the backside as well.
- Take a selfie (if you require this).
- Verify the quality of the photo(s).
In the following screen example, the end-user starts on a desktop and switches to their mobile. Also, they are only asked to take a photo of their ID document (no selfie):
Integration use case (web only)
I want to allow an end-user to verify their identity using the PictureID service in my website.
I want the required ID images to be captured and uploaded using the Assure Capture flow.
I also want to be able to retrieve the information 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 applications.
In this use case, you integrate only with the Assure API. The Web SDK is embedded in the Assure API Start capture flow service.
Integration steps
The guide assumes you already have done the initial integration steps with the Assure API, see Set up an API integration.
Here is an overview of the main integration steps:
Create a dossier
Use the Create dossier endpoint to create a placeholder for all of your end-user's data:
curl -X POST \
<ENVIRONMENT>/assure/dossiers \
-H 'Accept: application/json' \
-H 'Authorization: Bearer <OIDC_ACCESS_TOKEN>' \
-H 'Content-Type: application/json' \
Save the dossierId from the response body to use in the next requests.
After creating a dossier, you can see all of its contents anytime you want to. To do that, use the Get dossier endpoint giving it the dossierId.
Start Capture flow
Use the Start Capture flow service to create an identity verification process in a web context. From the end-user's perspective, this service helps them capture and upload ID images.
Request
To start the flow, send a POST request to https://api.signicat.com/assure/dossiers/{dossierId}/capture
In the Start capture flow request, ensure you:
- Use the
dossierIdfrom the "Create dossier" response. - Specify the
redirectUrlto redirect the user to the required page after the verification is finished.
Here is an example of a basic request:
curl --location 'https://api.signicat.com/assure/dossiers/<DOSSIER_ID>/capture' \
--header 'Authorization: Bearer <OIDC_TOKEN>' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--data '{
"providers":
[
{
"provider": "signicatpictureid",
"processType": "document"
}
],
"redirectUrl": "<REDIRECT_URL>"
}'
This example is for the "document only" case. If you require the end-user to take a picture of both their ID document and a selfie, processType should contain documentSelfie instead.
For other optional parameters in this request, see the API Reference > Start capture flow.
Redirect the end-user to the identity verification
In the "Start capture flow" response, you will receive a URL, for example:
{
"url": "https://assure-demo.sandbox.signicat.com/capture/#/artifact=4f24sdq2pcs1m5dymx8zfvdft8g1ns3getdx41ar222e3smkoh"
}
- You must use this URL to redirect the end-user to the identity verification UI (on desktop or mobile), where they can perform their identification.
- After the end-user has identified themselves, they will be redirected to the specified
redirectURLyou sent in the request. - Then wait for the notification to arrive before you proceed to the Get the result step (see below).
It is recommended to subscribe to Assure Events to be notified when the result is available (either successfully or not). For more information, see Assure Events.
User experience tips to improve the onboarding
Consider to include the following tips in the UI before the end-user starts the identity verification. They should have the following ready:
- Their identity document.
- Their mobile phone. It is recommended to switch from desktop to mobile to ensure better image quality and a smoother user experience.
- A stable and good internet connection.
- Good lighting to capture the images.
- Allow camera and microphone access.
Get the result
After the user has finished all the necessary steps in the identity verification UI, the images/videos will be analysed and the result sent back to the Assure API.
When the verification result is ready, you can call the Get process endpoint to see the detailed result information:
curl -X GET \
<ENVIRONMENT>/assure/dossiers/<DOSSIER_ID>/processes/<PROCESS_ID> \
-H 'Authorization: Bearer <OIDC_ACCESS_TOKEN>' \
-H 'Accept: application/json' \
You will get all the process and result information in the response body.
Example result
This is a response example of an accepted process for “processType”:”document” (no selfie):
{
"processId": "46385ffb-4485-44ce-be71-b0aaef466338",
"provider": "signicatpictureid",
"processType": "document",
"status": "accepted",
"finalResult": {
"firstName": "WILLEKE LISELOTTE",
"lastName": "DE BRUIJN",
"dateOfExpiry": "2031-08-30",
"dateOfBirth": "1965-03-10",
"gender": "F",
"nationality": "NLD",
"documentNumber": "SPECI2021",
"issuingCountry": "NLD",
"personalIdentificationNumber": "999999990"
},
"providerSpecific": {
"document": {
"issuingCountry": "NLD",
"dateOfExpiry": "2031-08-30",
"documentNumber": "SPECI2021",
"subject": {
"firstName": "WILLEKE LISELOTTE",
"lastName": "DE BRUIJN",
"dateOfBirth": "1965-03-10",
"gender": "F",
"nationality": "NLD",
"personalIdentificationNumber": "999999990",
"photo": {
"x": 295,
"y": 764,
"width": 629,
"height": 868
},
"signature": {
"x": 2660,
"y": 1562,
"width": 610,
"height": 118
}
},
"securityChecks": {
"notTamperedDocument": {
"name": "Not tampered document",
"passed": true
},
"nonExpired": {
"name": "Document not expired",
"passed": true
},
"notUnderage": {
"name": "Not underage",
"passed": true
},
"notBlackAndWhite": {
"name": "Not black & white copy",
"passed": true
},
"dataIntegrity": {
"name": "Data integrity",
"passed": true
}
}
}
},
"createdAt": "2024-11-14T12:27:01Z",
"updatedAt": "2024-11-14T12:27:28Z"
}
In this example, true is passed as value in the security checks, meaning all the underlying verifications have passed and the status is accepted.
See also an accepted example for “processType”:”documentSelfie”and other response statuses like rejected, failed in the Final result status section.
Delete dossier
After you have finished the end-user verification, you can delete the dossier with the Delete dossier endpoint.
SDKs
The PictureID service is only available via a web browser. There are no native SDKs available. If needed, please contact us by creating a support ticket in the Signicat Dashboard.
Service details for PictureID
This section goes more into detail about some useful endpoints when integrating with PictureID:
Get process
This section describes the final result status that you receive in the Get process response for PictureID.
Final result status
PictureID always performs security checks of the captured ID document (“processType”:”document”). If you also require a selfie (“processType”:”documentSelfie”), the service will perform a face match between the photo in the ID document and the selfie.
Based on the security check results, the Assure API returns the following final statuses for the two process types:
accepted
The status is accepted when all underlying verification checks have passed. This means there are no
indications the document is fraudulent.
This is a response example of an accepted process for “processType”:”documentSelfie”:
{
"processId": "27e15a7a-c720-4052-b384-f6f541b12514",
"provider": "signicatpictureid",
"processType": "documentSelfie",
"status": "accepted",
"finalResult": {
"firstName": "WILLEKE LISELOTTE",
"lastName": "DE BRUIJN",
"dateOfExpiry": "2031-08-30",
"dateOfBirth": "1965-03-10",
"gender": "F",
"nationality": "NLD",
"documentNumber": "SPECI2021",
"issuingCountry": "NLD",
"similarityScore": "high",
"personalIdentificationNumber": "999999990"
},
"providerSpecific": {
"document": {
"issuingCountry": "NLD",
"dateOfExpiry": "2031-08-30",
"documentNumber": "SPECI2021",
"subject": {
"firstName": "WILLEKE LISELOTTE",
"lastName": "DE BRUIJN",
"dateOfBirth": "1965-03-10",
"gender": "F",
"nationality": "NLD",
"personalIdentificationNumber": "999999990",
"photo": {
"x": 187,
"y": 456,
"width": 376,
"height": 539
},
"signature": {
"x": 1511,
"y": 948,
"width": 598,
"height": 156
}
},
"securityChecks": {
"notTamperedDocument": {
"name": "Not tampered document",
"passed": true
},
"nonExpired": {
"name": "Document not expired",
"passed": true
},
"notUnderage": {
"name": "Not underage",
"passed": true
},
"notBlackAndWhite": {
"name": "Not black & white copy",
"passed": true
},
"dataIntegrity": {
"name": "Data integrity",
"passed": true
},
"selfieAndDocumentMatch": {
"name": "Selfie and photo in the document match",
"similarityLevel": "high"
}
}
},
"selfie": {
"status": "SUCCESS",
"x": 349,
"y": 333,
"width": 417,
"height": 702
}
},
"createdAt": "2024-12-17T00:12:12Z",
"updatedAt": "2024-12-17T00:13:38Z"
}
In this example, true is passed as value in the security checks, and highis passed as the similarity level on the selfie and ID document comparison check. This means all the underlying verifications have passed and the status is accepted.
rejected
The verification cannot be processed further. This may occur due to poor image quality, making crucial information unreadable (for example documentNumber ), low similarityLevel on the comparison check between the selfie and the ID document or the end-user is below the minimum accepted age (notUnderage).
This is a response example of a process that was rejected due to poor image quality. In this case the documentNumber field is missing in the providerSpecific area:
{
"processId": "130d9871-4426-4f6c-95bd-f632875ed6e8",
"provider": "signicatpictureid",
"processType": "document",
"status": "rejected",
"providerSpecific": {
"document": {
"subject": {
"photo": {
"x": 41,
"y": 171,
"width": 82,
"height": 110
},
"signature": {
"x": 388,
"y": 268,
"width": 232,
"height": 27
}
},
"securityChecks": {
"notTamperedDocument": {
"name": "Not tampered document",
"passed": false
},
"notBlackAndWhite": {
"name": "Not black & white copy",
"passed": true
},
"dataIntegrity": {
"name": "Data integrity",
"passed": false
}
}
}
},
"createdAt": "2024-12-16T23:53:02Z",
"updatedAt": "2024-12-16T23:53:19Z"
}
This is a response example of process that was rejected because of a very low facial similarityLevel. This could happen if the selfie is from a different person than in the ID document:
{
"processId": "589ab89e-75e8-47db-b43a-5b38ec93972c",
"provider": "signicatpictureid",
"processType": "documentSelfie",
"status": "rejected",
"providerSpecific": {
"document": {
"issuingCountry": "NLD",
"dateOfExpiry": "2031-08-30",
"documentNumber": "SPECI2021",
"subject": {
"firstName": "WILLEKE LISELOTTE",
"lastName": "DE BRUIJN",
"dateOfBirth": "1965-03-10",
"gender": "F",
"nationality": "NLD",
"personalIdentificationNumber": "999999990",
"photo": {
"x": 188,
"y": 457,
"width": 376,
"height": 538
},
"signature": {
"x": 1511,
"y": 948,
"width": 598,
"height": 156
}
},
"securityChecks": {
"notTamperedDocument": {
"name": "Not tampered document",
"passed": true
},
"nonExpired": {
"name": "Document not expired",
"passed": true
},
"notUnderage": {
"name": "Not underage",
"passed": true
},
"notBlackAndWhite": {
"name": "Not black & white copy",
"passed": true
},
"dataIntegrity": {
"name": "Data integrity",
"passed": true
},
"selfieAndDocumentMatch": {
"name": "Selfie and photo in the document match",
"similarityLevel": "veryLow"
}
}
},
"selfie": {
"status": "SUCCESS",
"x": 372,
"y": 819,
"width": 352,
"height": 556
}
},
"createdAt": "2024-12-17T00:16:55Z",
"updatedAt": "2024-12-17T00:18:43Z"
}
inconclusive
Status is returned as inconclusive in the following cases:
- A security check has failed.
- The facial similarity level score is medium.
The notUnderage security check is not included in the inconclusive status. If a person is below legal age, the status will be rejected.
securityChecks
This is a response example of a process that was inconclusive since the security checks for notTampered and dataIntegrity did not pass.
{
"processId": "6aff2abb-bd88-436c-bc81-9086c32a2e2a",
"provider": "signicatpictureid",
"processType": "document",
"status": "inconclusive",
"providerSpecific": {
"document": {
"issuingCountry": "NLD",
"dateOfExpiry": "2031-08-30",
"documentNumber": "SPECI2021",
"subject": {
"firstName": "WILLEKE LISELOTTE",
"lastName": "DE BRUIJN",
"dateOfBirth": "1965-03-10",
"gender": "F",
"nationality": "NLD",
"personalIdentificationNumber": "999999990",
"photo": {
"x": 90,
"y": 171,
"width": 167,
"height": 235
},
"signature": {
"x": 336,
"y": 425,
"width": 298,
"height": 108
}
},
"securityChecks": {
"notTamperedDocument": {
"name": "Not tampered document",
"passed": false
},
"nonExpired": {
"name": "Document not expired",
"passed": true
},
"notUnderage": {
"name": "Not underage",
"passed": true
},
"notBlackAndWhite": {
"name": "Not black & white copy",
"passed": true
},
"dataIntegrity": {
"name": "Data integrity",
"passed": false
}
}
}
},
"createdAt": "2024-12-16T23:35:52Z",
"updatedAt": "2024-12-16T23:36:15Z"
}
similarityLevel
This is a response example of a process that was inconclusive since the facial similarityLevelscore is medium:
{
"processId": "589ab89e-75e8-47db-b43a-5b38ec93972c",
"provider": "signicatpictureid",
"processType": "documentSelfie",
"status": "inconclusive",
"providerSpecific": {
"document": {
"issuingCountry": "NLD",
"dateOfExpiry": "2031-08-30",
"documentNumber": "SPECI2021",
"subject": {
"firstName": "WILLEKE LISELOTTE",
"lastName": "DE BRUIJN",
"dateOfBirth": "1965-03-10",
"gender": "F",
"nationality": "NLD",
"personalIdentificationNumber": "999999990",
"photo": {
"x": 188,
"y": 457,
"width": 376,
"height": 538
},
"signature": {
"x": 1511,
"y": 948,
"width": 598,
"height": 156
}
},
"securityChecks": {
"notTamperedDocument": {
"name": "Not tampered document",
"passed": true
},
"nonExpired": {
"name": "Document not expired",
"passed": true
},
"notUnderage": {
"name": "Not underage",
"passed": true
},
"notBlackAndWhite": {
"name": "Not black & white copy",
"passed": true
},
"dataIntegrity": {
"name": "Data integrity",
"passed": true
},
"selfieAndDocumentMatch": {
"name": "Selfie and photo in the document match",
"similarityLevel": "medium"
}
}
},
"selfie": {
"status": "SUCCESS",
"x": 372,
"y": 819,
"width": 352,
"height": 556
}
},
"createdAt": "2024-12-17T00:16:55Z",
"updatedAt": "2024-12-17T00:18:43Z"
}
failed
In this example the process failed due to an expired transaction. This might happen if the end-user spends too long time on the verification process. The end-user has 15 minutes to complete the process after uploading the first image.
{
"processId": "8fba52bb-1734-4cec-b327-2470fd6f29bd",
"provider": "signicatpictureid",
"processType": "document",
"status": "failed",
"failReason": {
"detail": "Transaction time expired."
},
"depictions": [
"front"
],
"createdAt": "2025-01-08T15:41:59Z",
"updatedAt": "2025-01-08T16:05:18Z"
}
canceled
The identity verification process was cancelled by the end-user.
{
"processId": "e1bba176-5dff-4acc-ba4d-5dafe4d66ca3",
"provider": "signicatpictureid",
"processType": "document",
"status": "canceled",
"createdAt": "2024-12-16T23:32:01Z",
"updatedAt": "2024-12-16T23:32:28Z"
}
Download full result
In the "Get process" response, you get the results for PictureID in the provider-specific area, normalised by Assure API. To get the raw results, as they were obtained from the provider, use the Download full result service. The result is returned in a zip file.
You can always get a zip file for PictureID processes that have been completed with success.
File example
The name of the zip file is based on field values in the process, consisting of "dossierId_processId_downloadDate.zip", for example fe4cda65-bb97-477b-acc4-7ee2af64914c_46385ffb-4485-44ce-be71-b0aaef466338_20241204T224400.zip.
Here is a screen example of a zip file from a PictureID process:
PictureID zip file
File content
The main content is as follows:
- ID document image(s) (front and back if available) in JPG format.
- The full result in JSON format.
- Selfie image in JPG format if the process type is
documentSelfie.