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):
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.
Photo instructions
PictureID requires the user to capture the entire document page and gives the following instructions in the Photo instructions screen: "Make sure document edges and surroundings are visible".
Recommended
Here are some examples of good photos, where the edges and some surroundings are shown (photo page and back page of a Dutch passport):
OK: Shows the whole passport photo page with edges and some surroundings
OK: Shows the whole passport back page with edges and some surroundings
Not recommended
However, the following images will not work well with PictureID, since they are cropped too much:
Not OK: Edges and surroundings are less visible
Not OK: Edges and surroundings are less visible
Integration use cases for PictureID
This section assumes you already have done the initial integration steps with the Assure API, see set up client credentials and access token.
In the following, we present the two most common use cases for PictureID:
- Use case 1: Use Assure API Capture service to capture and upload the images (web only)
- Use case 2: Send existing images via direct upload to Assure API (web or native mobile)
Both options can be used either in a web or in a native (mobile) context. The steps in the two flows are quite similar, except for some smaller differences in the Create process and Upload images steps.
UC 1: Use Assure API Capture service to capture and upload the images (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.
PictureID with Start Capture flow (Use case 1)
The cyan colour indicates the path you should take for this use case.
This use case path is described in more detail below, using the same step numbers as in the diagram.
Step A: Create 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.
Step G: Start Capture flow
Use the Start Capture flow endpoint to create an identity verification process in a web context. The Capture service helps capturing and uploading ID images from the identity verification process.
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 process step to get the result (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.
Step F: Get process
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.
After you have finished the end-user verification, it is recommended to delete the dossier. This deletes all the information about this end-user.
See also the General usage recommendations section.
UC 2: Send existing images via direct API upload (web or native mobile)
I want to use PictureID 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 because I already have the images or a UI that captures the images.
I want to be notified when a final result has been obtained (either successfully or not).
Note: This use case seamlessly fits both web (JS) and native mobile (Android/iOS) applications.
PictureID with direct upload using setImage (Use case 2)
The cyan colour indicates the path you should take for this use case.
This use case path is described in more detail below, using the same step numbers as in the diagram.
Step A: Create dossier
- Use the Create dossier endpoint to create a placeholder for all of your end-user's data.
- Save the
dossierIdyou get in the response to be used in the next requests.
Ensure you use one dossier per end-user.
Step B: Get document types (optional)
This step is not required, but you may want to get the list of documents accepted by PictureID so you know which documentType PictureID supports (to be passed on to the next request).
In this use case, the document type is a passport (see example code in the next step).
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
signicatpictureid. - Set the
documentIdto decide the document type, for example "137" for a Dutch passport (see the previous step, Get document types, to see which document types are valid for PictureID).
Here is an example JSON request body:
{
"provider": "signicatpictureid",
"processType": "document",
"documentId": 137
}
- In this example, you ask the end-user to perform an identity verification using their Dutch passport (137).
- You must save the
processIdfrom the response to use in the next steps.
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.
Step D2: Upload images (direct upload)
- Use the setImages endpoint to upload the images the end-user captured during the identity verification. This JSON example file contains specimen images of a Norwegian passport and a selfie: NOR_passport-specimen_and_selfie.json
- 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 PictureID.
Step E: Start verification
- Use the startVerification endpoint to perform a verification of the identity document that was uploaded.
- 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 ”signicatpicureid”
- The status is “pending”
Step F: Get process
If you have subscribed to Assure Events as recommended in the Create process step, you know when the verification result is ready.
- Call the Get process endpoint: Then use the
dossierIdandprocessIdreceived in the Assure Events notification.
The process now contains data about the process' final result. For more details about this, see Service details for PictureID > Get process.
After you have finished the end-user verification, it is recommended to delete the dossier. This deletes all the information about this end-user.
See also the General usage recommendations section.
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).
Here is an example of a "document" process that was rejected since the notUnderage security check is missing:
{
"processId": "3b1dc433-a46c-4473-bab6-d0f7c8a44341",
"provider": "signicatpictureid",
"processType": "document",
"status": "rejected",
"statusReasons":
[
{
"type": "Document",
"category": "Security",
"subCategory": "NotUnderage",
"message": "Security check 'notUnderage' failed or was not found."
}
],
"depictions": [
"front"
],
"providerSpecific": {
"document": {
"subject": {
"signature": {
"x": 260,
"y": 447,
"width": 278,
"height": 107
}
},
"securityChecks": {
"notTamperedDocument": {
"name": "Not tampered document",
"passed": true
},
"notBlackAndWhite": {
"name": "Not black & white copy",
"passed": true
},
"dataIntegrity": {
"name": "Data integrity",
"passed": false
}
}
}
},
"createdAt": "2025-05-13T08:18:28Z",
"updatedAt": "2025-05-13T08:19:47Z"
}
Here is an example of a "document" process that was rejected since the document quality is not good enough to extract the documentNumber:
{
"processId": "4aefbbf2-3c6a-44fb-9838-69ee62fadd64",
"provider": "signicatpictureid",
"processType": "document",
"status": "rejected",
"statusReasons":
[
{
"type": "Document",
"category": "ImageQuality",
"message": "Document image does not have enough quality or is not an image of an ID document (documentNumber could not be extracted)."
}
],
"depictions": [
"front"
],
"providerSpecific": {
"document": {
"subject": {
"photo": {
"x": 45,
"y": 172,
"width": 84,
"height": 108
},
"signature": {
"x": 391,
"y": 283,
"width": 210,
"height": 51
}
},
"securityChecks": {
"notTamperedDocument": {
"name": "Not tampered document",
"passed": false
},
"notBlackAndWhite": {
"name": "Not black & white copy",
"passed": true
},
"dataIntegrity": {
"name": "Data integrity",
"passed": false
}
}
}
},
"createdAt": "2025-05-14T08:02:48Z",
"updatedAt": "2025-05-14T08:03:47Z"
}
This is a response example of "documentSelfie" 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",
"statusReasons": [
{
"type": "Biometrics",
"category": "SimilarityLevel",
"message": "Similarity level is 'veryLow'."
}
],
"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
notUnderagesecurity check is not included in the inconclusive status. If a person is below legal age, the status will be rejected. - If a user has laminated their paper identity document (such as an ESP 2007 residence permit), the system may mistakenly flag the document as tampered. The lamination can cause the algorithm to misinterpret the image, sometimes identifying it as a photo of a screen rather than an original physical document.
securityChecks
This is a response example of a process that was inconclusive since the nonExpired security check did not pass.
{
"processId": "6aff2abb-bd88-436c-bc81-9086c32a2e2a",
"provider": "signicatpictureid",
"processType": "document",
"status": "inconclusive",
"statusReasons": [
{
"type": "Document",
"category": "SecurityCheckFailed",
"subCategory": "NonExpired",
"message": "Security check 'nonExpired' failed."
}
],
"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": true
},
"nonExpired": {
"name": "Document not expired",
"passed": false
},
"notUnderage": {
"name": "Not underage",
"passed": true
},
"notBlackAndWhite": {
"name": "Not black & white copy",
"passed": true
},
"dataIntegrity": {
"name": "Data integrity",
"passed": true
}
}
}
},
"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",
"statusReasons": [
{
"type": "Biometrics",
"category": "SimilarityLevel",
"message": "Similarity level is 'medium'."
}
],
"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.