Integration guide for PictureID
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.
Prerequisites
This guide assumes you already have done the initial integration steps with the Assure API, see set up client credentials and access token.
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 green 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 eyJh ... QifQ.eyJ ... hIOw' \
-H 'Content-Type: application/json' \
Save the dossierId from the response body to use in the next requests.
Ensure you use one dossier per end-user.
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 eyJh ... QifQ.eyJ ... hIOw' \
--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 eyJh ... QifQ.eyJ ... hIOw' \
-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).
This use case seamlessly fits both web (JS) and native mobile (Android/iOS) applications.
PictureID with direct upload using setImage (Use case 2)
The green 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.