Postman Integration Guide
The purpose of this document is to explain how to setup a Postman project to use and test GIPS service APIs.
This Postman project contains requests examples that can be executed against the real service to ease the integration of the service into your application.
Postman Presentation
Postman is a tool for API development. It is used as a REST and SOAP client.
It offers an intuitive user interface allowing you to:
-
Send SOAP and REST requests
-
Save requests and responses
-
Add tests
-
Create test scenarios
Important Note:
You may have a status with error 415 – Unsupported Media Type. These errors are due to the Postman version you are using, not the ID&V engine itself. For example:
Some Postman versions do not support empty Multi part request:
Some Postman versions do not support an empty content type in the GET requests:
An important fix was made by the Postman team. Please use version 7.0.6 or later.
Prerequisites
-
Postman Documentation
-
GIPS API Guide
GIPS is composed of one REST API with multiple resources necessary to conduct an identity verification:
-
Identities
-
ID Documents
-
Identity attributes
-
Identity evaluation results
-
Biometrics
The full API is described in API documentation section in the portal.
Sequence Management
There is no imposed sequence to verify an identity with GIPS. However, it's not possible to process sensitive data without having previously notified that the user has consented to it, or make a comparison when there is not reference data submitted yet.
Here is a typical sequence:
Example with an error:
GET Proof
As a reminder, GIPS allows the relying service to decide when a process shall be stopped. When a process is done, the relying service should request the proof in order to keep the details on the user, as once the proof is retrieved or the transaction times out, data on the user will no longer be available on the IDEMIA server (except the proof ciphered if requested by the customer).
The proof comes in the form of a zip file. See proof specifications for more details.
Data Retention
Data on the user (images and personal details for instance) are kept for the time of the ongoing transaction. As soon as the proof is requested, or as soon as the time to live of the transaction is reached, then data from the user are no longer available on the GIPS server. The time to live of the transaction (and therefore the time to live of the data) is configurable per tenant. When the time to live is reached, neither the relying service nor the user will be able to access the transaction. (The request will return a specific HTTP error code, 404, meaning the transaction is no longer available).
Since there is no data retention on the GIPS side, the relying service is in charge of keeping the complete proof locally.
Exceptions:
-
GIPS allows a specific configuration per tenant (Activated? Retention time? Ciphered with GIPS certificate?), to keep the proof for screening and investigation reasons. When activated, the proof will be stored if:
-
A
get proof
is performed by the relying service. -
The transaction reaches its time to live.
-
-
GIPS allows a specific configuration per tenant (Activated? Retention time? Ciphered with tenant certificate?), to keep the proof for the tenant in case transaction reaches its time to live. For example:
-
User starts a new process and submits a passport and a portrait.
-
User exits the mobile application or the browser without informing the relying service (so without informing GIPS).
-
After a configurable time to live, GIPS will close the transaction and can keep the proof.
-
-
If ciphered, only the relying service will be able to decipher it.
- To retrieve a proof, the relying service has to perform a
get Proof
as if the transaction was still available.
- To retrieve a proof, the relying service has to perform a
Postman Installation
Note: Do not use the Postman chrome extension because it is no longer maintained and does not support some functionalities such as multipart. A standalone Postman application is required.
-
Select the Postman version associated with your platform OS.
-
Download the latest version (at least 7.0.6).
-
Click Execute. The installation is done automatically.
- Launch Postman by double clicking on:
Import Helper Project
To import the provided Postman project:
-
Unzip GIPS Postman delivery morpho-ipv-gips-postman-3.20.0.tar.gz in a folder on your computer.
-
In Postman, click Import.
- Click Choose Files.
- Select project file
gips.postman_collection.json
in the unzipped GIPS postman delivery and click Open.
The project is now imported in the Collections section:
Access Configuration
Import Environment and Configuration
Before testing the GIPS service, the Postman project must be configured.
-
Click Environment option.
-
Click Manage Environments.
- Click Import.
- Click Select files. Select the environment file present in delivery in
env
folder ofGIPS env.postman_environment.json
.
The environment is then imported successfully.
- Click the arrow to the right of No Environment (1) and select GIPS env (2).
- Click the eye icon called Environment quick look (1) and click Edit in GIPS env (2).
- Fill in the following fields, paying close attention.
If you use an IDEMIA private cloud:
Note: Be careful, keys are case-sensitive.
Update key “url”: type in the "value" field the URL of the GIPS server that has been provided to you. Example: https://myservice-intg.com/gips
Update key “apikey”: type in the "value" field your apikey Example: 22a79d15-3430-46c6-a21c-c266e30fbe8f
- Click Update and then close the environment window. Other values will be filled automatically during the performed tests.
Testing : Using API Key
-
Objective: Explain how to set the apikey in a Postman environment.
-
Environment:
-
The apikey is used as a header in all requests.
-
The value is taken from configuration parameters.
-
-
Usage:
-
Open environment quick look.
-
Click Edit.
-
Edit the apikey value to the desired one.
-
Note: The apikey generated for users having a
USER_AGENT
role has no access to blocking indicator information.
GIPS Tests
Now that your Postman environment is configured, you can try the sample requests.
This chapter describes each request present in the Postman project.
Identity
The objective of this test is to:
- create a new identity and initiate the verification process with ID&V
- retrieve the identity status and details
- retrieve identity status and all indicator details
- retrieve the identity status and details
- set a new context
- delete an identity
createIdentity
This creates a new identity. This step is required before next steps.
Environment:
If you use an IDEMIA private cloud:
url
andapikey
are used from the Postman environment
Usage:
-
Open the folder called
Identity
. -
Click createIdentity.
-
Optional: Add a multipart “context” metadata (key/values). The keys/values will be associated with the identity but has no impact on identity scoring or verification.
-
Optional: In the headers you can set a
correlation-id
. This identifier shall be unique per identity or per transaction. It gives the ability to make the link between the GIPS internal identity identifier and a customer unique identifier. SeegetIdentityFromCorrelationId
for more details.
-
-
Click Send.
Response:
-
Status shall be 200 OK to confirm the identity has been created.
-
The response contains a JSON with identity details such as the identity identifier and the score.
-
The identity identifier is automatically filled in the Postman environment variable
identityId
and will be used on subsequent calls. -
The response body contains a status of the created identity.
Note: Some Postman versions do not allow optional multipart (Postman issue). Please make sure you are using version 7.0.6 or later.
getIdentity
Objective: Retrieve the identity status and details based on its unique identifier.
Environment:
If you use an IDEMIA private cloud:
url
,apikey
andidentityId
are provided from the Postman environment.
Usage:
-
Open the folder
Identity
and click getIdentity. -
Click Send.
Response:
-
Status shall be 200 OK.
-
The response contains a JSON with all the identity details linked to the provided identity identifier such as evidence, adjudication status, and scoring.
-
The identity identifier is automatically filled in the Postman environment variable
identityId
and will be used on subsequent calls.
Get Identity with Indicators Details
Objective: Retrieve the identity status and all indicator details based on its unique Identifier.
Environment:
If you use an IDEMIA private cloud
url
,apikey
, andidentityId
are provided from the Postman environment.
Usage:
-
Open the folder
Identity
and click getIdentityWithIndicatorsDetails. -
Click Send.
Response:
-
Status shall be 200 OK.
-
The response contains a JSON with all the identity details linked to the provided identity identifier, such as evidence, adjudication status, and scoring.
-
The identity identifier is automatically filled in the Postman environment variable
identityId
and will be used on subsequent calls. -
Indicators details.
getIdentityFromCorrelationId
Objective: Retrieve the identity status and details based on its unique identifier.
Environment:
If you use an IDEMIA private cloud:
url
,apikey
, andidentityId
are provided from the Postman environment.
Usage:
-
Open the folder
Identity
. -
Click getIdentityFromCorrelationId.
-
Type in the URL the correlation identifier from which you want to retrieve the identity status and identifier (meaning the one set in headers during the
createIdentity
step.) -
Click Send.
Response:
-
Status shall be 200 OK.
-
The response contains a JSON with all the identity details linked to the provided correlation identifier.
getStatus
Objective: Retrieve the status associated with the requested identity and discards data on the server.
Environment:
If you use an IDEMIA private cloud:
url
,apikey
, andidentityId
are provided from the Postman environment.
Usage:
-
Open the folder called
Identity
and click getStatus. -
Click Send.
Response:
-
Status shall be 200 OK.
-
The response contains a JSON with a light view of the identity global status (status and creation date) and for each document, the type previously submitted, the identifier, and status.
putContext
Objective: Set a new context (previous context was provided during identity creation or another putContext
will be lost).
Environment:
If you use an IDEMIA private cloud:
url
,apikey
, andidentityId
are provided from the Postman environment.
Usage:
-
Open the folder
Identity
. -
Click putContext.
-
Click Body.
-
Modify the content if needed.
Example:
Example of context where the key BUSINESS_ID will be set to value CONTEXT1:
[ { "key": “BUSINESS_ID”, "value": "CONTEXT1" } ]
- Click Send.
Response:
Status shall be: 204 No Content to confirm the context has been replaced.
deleteIdentity
Objective: Delete an identity based on its unique identifier.
Environment:
If you use an IDEMIA private cloud:
url
,apikey
, andidentityId
are provided from the Postman environment.
Usage:
-
Open the folder
Identity
. -
Click deleteIdentity.
-
Click Send.
Response:
- Status shall be 204 No Content meaning the identity has been deleted.
Adjudication Details
- getAdjudicationServerAvailability
-
Objective: Retrieve the status of the adjudication service.
-
Environment:
If you use an IDEMIA private cloud:
url
andapikey
are provided from the Postman environment.
-
Usage:
-
Open the folder
Adjudication details
. -
Click getAdjudicationServerAvailability.
-
Click Send.
-
-
Response:
-
Status shall be 200 OK.
-
Response contains a JSON with details on the adjudication service availability (if the server available, if available when it will close, if closed when it will open next.)
-
- getAdjudicationsStatus
-
Objective: Retrieve the status of all adjudications linked to an identity.
-
Environment:
If you use an IDEMIA private cloud:
url
,apikey
, andidentityId
, are provided from the Postman environment.
-
Usage:
-
Open the folder Adjudication details.
-
Click getAdjudicationsStatus.
-
Edit the URL if you want to set a different status.
- By default it will retrieve adjudications with the status of PROCESSING.
-
Click Send.
-
-
Response:
-
Status shall be 200 OK.
-
The response contains a JSON with details on the adjudication service availability (if the server available, if available when it will close, if closed when it will open next.)
-
Consents
The objective of this test is to:
- send notification that the end user consents to their identity evidence being processed by ID&V
- retrieve list of previous submitted consents
- delete a previously submitted consent
submitConsents
Objective: Submit a list of consents. The consent allows you to define whether a consent is needed before a submit in order to perform verification. For example, if the consent is activated in configuration as mandatory for the portrait, then GIPS will request first an approval consent for the portrait, then GIPS will submit the portrait itself. If the portrait is sent before the approval consent is obtained, an error 3001 will be given back synchronously.
By default, consent is mandatory for PORTRAIT evidences. For example, consent on portraits shall be sent before the portrait itself, otherwise GIPS will not process it for identity evaluation.
Environment:
If you use an IDEMIA private cloud:
url
,apikey
, andidentityId
are provided from the Postman environment.
Usage:
-
Open the folder
Consents
. -
Click submitConsents.
-
Click Body.
-
Modify the content if needed.
-
Click Send.
Response:
-
Status shall be 200 OK to confirm the consent has been associated with the identity.
-
The response body contains a JSON with consent details like a consent identifier per submitted consent.
getConsents
Objective: Retrieve list of previously submitted consents.
Environment:
If you use an IDEMIA private cloud:
url
,apikey
, andidentityId
are provided from the Postman environment.
Usage:
-
Open the folder “Consents” (1)
-
Click “getConsents” (2)
- Click Send.
Response:
-
Status shall be 200 OK.
-
The response body contains a JSON with consent details like a consent identifier for each consents that were previously submitted.
deleteConsent
Objective: Delete a previously submitted consent based on its identifier.
Environment:
If you use an IDEMIA private cloud:
url
,apikey
, andidentityId
are provided from the Postman environment.
Usage:
-
Open the folder
Consents
. -
Click deleteConsent.
-
In the URL set the identifier of the consent you want to delete.
-
Click Send.
Response:
- Status shall be 204 No Content meaning the consent has been deleted.
Personal Details
The objective of this test is to:
- submit identity attributes to be processed for an identity (surname, given names, date of birth, etc.).
- retrieve the evidence attributes details and status
submitAttributes
Objective: Submit attributes for an identity such as surname, given names, and date of birth.
Environment:
If you use an IDEMIA private cloud:
url
,apikey
, andidentityId
are provided from the Postman environment.
Usage:
-
Open the folder called
Personal Details
. -
Click submitAttributes.
-
Click Body.
-
Make sure you are in raw mode.
-
Update the data if needed.
-
Example:
JSON1{2 "attributesData": [3 {4 "givenNames": [{ "value": "CHRISTOPHE", "verified": false }],5 "surname": { "value": "ULYSSE", "verified": false },6 "dateOfBirth": { "value": "1960-04-10", "verified": false },7 "placeOfBirth": "Paris",8 "gender": { "value": "M", "verified": false },9 "nationality": { "value": "FRA", "verified": false }10 }11 ],12 "score": 013}
- Click Send.
Note: With a
RELYING_SERVICE
apikey, a score up to5
can be provided if the attributes are already on your side. In this case, “verified” shall be set totrue
for the attributes you already know (at least given names, surname, and date of birth otherwise the score will be ignored). If the score is5
and the given names, surname, and date of birth are at least verified, then then user will have to provide only an evidence where the name matches the evidenceATTRIBUTES
. However, if the score is1
and the given names, surname, and date of birth at least are verified then, if the user provides an evidence with an higher score (for example a passport verified at level2
) then this evidence will become the reference and, if the attributes does not match, the attributes will be rejected (INVALID
).
Response:
-
Status shall be 200 OK to confirm the evidence has been associated with an identity.
-
The response body contains a JSON with the identity status and the attributes’ evidence details containing things like the status, the score, and the evidence unique identifier.
getAttributesStatus
Objective: Retrieve the evidence ATTRIBUTES
based on the identity unique identifier.
Environment:
If you use an IDEMIA private cloud:
url
,apikey
, andidentityId
are provided from the Postman environment.
Usage:
-
Open the folder
Personal Details
. -
Click getAttributesStatus.
-
Click Send.
Response:
-
Status shall be 200 OK.
-
The response body contains the global status of the requested evidences
ATTRIBUTES
.
getAttributes
Objective: Retrieve the evidence ATTRIBUTES
based on the identity unique identifier.
Environment:
If you use an IDEMIA private cloud:
url
,apikey
, andidentityId
are provided from the Postman environment.
Usage:
-
Open the folder
Personal Details
. -
Click getAttributes.
-
Click Send.
Response:
-
Status shall be 200 OK.
-
The response body contains details of the global status and evidence
ATTRIBUTES
details.
Get Attributes with Indicators Details
Objective: Retrieve the evidence ATTRIBUTES and all the indicator details based on the identity unique identifier.
Environment:
If you use an IDEMIA private cloud:
url
,apikey
, andidentityId
are provided from the Postman environment.
Usage:
-
Open the folder
Personal Details
. -
Click getAttributesWithIndicatorsDetails.
-
Click Send.
Response:
-
Status shall be 200 OK.
-
The response body contains details the global status and the evidence
ATTRIBUTES
details. -
Indicators details.
Address
The objective of this test is to:
- send the address for verification of the identity attributes
- retrieve the address details and status
submitAddress
Objective: Send the address for verification of the identity attributes.
Environment:
If you use an IDEMIA private cloud:
url
,apikey
, andidentityId
are provided from the Postman environment.
Usage:
-
Open the folder
Address
. -
Click submitAddress.
-
Click Body” and replace the parameter.
-
Make sure you are in raw mode.
-
Update the data if needed.
-
Example:
JSON1{2 "addressesData": [3 {4 "streetDetails": { "streetLines": ["8840 w russell road"] },5 "postcode": "89148",6 "city": "LAS VEGAS",7 "state": "NV",8 "country": "USA"9 }10 ]11}
- Click Send.
Response:
-
Status shall be 200 OK to confirm that the evidence has been associated with an identity.
-
The response body contains the address status.
-
An environment variable
addressId
is set and will be used forGET
andDELETE
operations.
getAddressStatus
Objective: Retrieve the address status based on its unique identifier.
Environment:
If you use an IDEMIA private cloud:
url
,apikey
, andidentityId
are provided from the Postman environment.
Usage:
-
Open the folder
Address
. -
Click getAddressStatus.
-
Click Send.
Response:
-
Status shall be 200 OK.
-
The response body contains the status of the requested
ADDRESS
evidence.
getAddress
Objective: Retrieve the details of a specific address based on its unique identifier.
Environment:
If you use an IDEMIA private cloud:
url
,apikey
, andidentityId
are provided from the Postman environment.
Usage:
-
Open the folder Address.
-
Click getAddress.
-
Click Send.
Response:
-
Status shall be 200 OK.
-
The response body contains the global status of identity and details on the
ADDRESS
evidence associated with a given identifier like status and score.
Get Address with Indicators Details
Objective: Retrieve details and all the indicators of a specific address based on its unique identifier.
Environment:
If you use an IDEMIA private cloud:
url
,apikey
, andidentityId
are provided from the Postman environment.
Usage:
-
Open the folder
Address
. -
Click getAddressWithIndicatorsDetails.
-
Click Send.
Response:
-
Status shall be 200 OK.
-
The response body contains the global status of identity and details on the
ADDRESS
evidence associated with a given identifier such as status and score. -
Indicators details.
getAddresses
Objective: Retrieve details for all addresses.
Environment:
If you use an IDEMIA private cloud:
url
,apikey
, andidentityId
are provided from the Postman environment.
Usage:
-
Open the folder Address.
-
Click getAddresses.
-
Click Send.
Response:
-
Status shall be 200 OK.
-
The response body contains the global status of identity and the details on all address evidence such as status and score.
Portrait Identification
The objective of this test is to:
- submit the portrait of the person for verification against a document photograph
- retrieve the portrait identification details and status
submitPortrait
Objective: Submit the portrait of the person for verification (matching against an identity document’s photograph if any already provided and verified). The identity document can be sent before or after the portrait
Reminder: Consent is required by default for a portrait.
Environment:
If you use an IDEMIA private cloud:
url
,apikey
, andidentityId
are provided from the Postman environment.
Usage:
-
Open the folder
Portrait Identification
. -
Click submitPortrait.
-
Click Body and replace the parameters:
-
Portrait
: the portrait capture image, a selfie for example. -
PortraitInformation
: known details on the portrait capture like the source used to take the picture and the metadata. See provided example in Postman delivery:submitPortrait.json
.
-
Example:
source
: from enumeration "LIVE_CAPTURE_IMAGE", “LIVE_CAPTURE_VIDEO”, “SCAN”, “DOCUMENT_CROP”, “OTHER”
JSON1{2 "source": "LIVE_CAPTURE_IMAGE",3 "metadata": [4 {5 "key": "KEY1",6 "value": "value1"7 },8 {9 "key": "KEY2",10 "value": "value2"11 }12 ]13}
metadata
: a list of metadata
- Click Send.
Response:
-
Status shall be 200 OK to confirm the evidence has been associated with the identity.
-
The response body contains the identity global status and evidence
PORTRAIT
details like the evidence unique identifier, the status, and score. -
On response, the environment variable
portraitId
is set in Postman with the portrait evidence identifier.
getPortraitStatus
Objective: Retrieve the status of the portrait evidence. This allows polling the evidence status. As soon as a status is finished PROCESSING
, you can perform a getPortraitDetails
(see next section) to get the status and score for example.
Environment:
If you use an IDEMIA private cloud:
-
url
,apikey
, andidentityId
are provided from the Postman environment. -
The evidence unique identifier,
portraitId
, is also used.
Usage:
-
Open the folder
Portrait Identification
. -
Click getPortraitStatus.
-
Click Send.
Response:
-
Status shall be 200 OK.
-
The response contains the status of the portrait. As soon as status is finished
PROCESSING
, you can get the portrait details.
getPortraitDetails
Objective: Retrieve the portrait details based on its unique identifier.
Environment:
If you use an IDEMIA private cloud:
-
url
,apikey
, andidentityId
are provided from the Postman environment. -
The evidence unique identifier,
portraitId
, is also used.
Usage:
-
Open the folder
Portrait Identification
. -
Click getPortraitDetails.
-
Click Send.
Response:
-
Status shall be 200 OK.
-
The response body contains the global status of identity and details on the portrait evidence such as status and score.
Get Portrait with Indicators Details
Objective: Retrieve the portrait details and all the indicators based on its unique identifier.
Environment:
If you use an IDEMIA private cloud:
-
url
,apikey
, andidentityId
are provided from the Postman environment. -
The evidence unique identifier,
portraitId
, is also used.
Usage:
-
Open the folder
Portrait Identification
. -
Click getPortraitWithIndicatorsDetails.
-
Click Send.
Response:
-
Status shall be 200 OK.
-
The response body contains a global status of identity and details on the portrait evidence such as status and score.
-
Indicators details.
getPortraitCapture
Objective: Retrieve the portrait image sent previously.
Environment:
If you use an IDEMIA private cloud:
url
,apikey
, andidentityId
are provided from the Postman environment.
Usage:
-
Open the folder
Portrait Identification
. -
Click getPortrait.
-
Click the arrow to the right of the Send button.
-
Choose Send and Download. When the popup appears, choose a directory and a name to save the returned part to a file.
Response:
- Status shall be 200 OK.
- The saved content is a multipart response: the file shall be edited to remove the multipart header and footer.
-
Edit the saved file in a file editor (Notepad++ for example).
-
At the beginning of the file, delete the multipart header:
HTTP1*--1b817195-cbe4-485f-90fd-4ed6f27f54a8*2*Content-Disposition: form-data; name="Portrait"*3*Content-Type: application/octet-stream*4At the end of the file, delete multipart footer:5*--1b817195-cbe4-485f-90fd-4ed6f27f54a8--*
- Save your modifications and open the file with a photo editor.
deletePortrait
Objective: Delete a portrait sent previously.
Environment:
If you use an IDEMIA private cloud:
url
,apikey
, andidentityId
are provided from the Postman environment.
Usage:
-
Open the folder
Portrait Identification
. -
Click: “deletePortrait.
-
Click Send.
Response:
- Status shall be: 204 No Content to confirm that the portrait has been deleted.
sendPortraitToAdjudication
Objective: Send the portrait to manual adjudication. The facial adjudication shall have been activated for your tenant. A portrait can be sent to adjudication only if the flag isAdjudicable
is set to true
and if adjudication is available, otherwise you'll receive an error.
Environment:
If you use an IDEMIA private cloud:
-
url
,apikey
, andidentityId
are provided from the Postman environment. -
The evidence unique identifier,
portraitId
, is also used.
Usage:
-
Open the folder
Portrait Identification
. -
Click sendPortraitToAdjudication.
-
Click Send.
Response:
-
Status shall be 200 OK in order to confirm that portrait has been sent to adjudication.
-
The response contains the adjudication details confirming that
FACIAL
adjudication has been sent (PROCESSING
) and the expiration date and time of the adjudication request.
getPortraitAdjudicationStatus
Objective: Retrieve the adjudication status of the portrait (operator decision).
Environment:
If you use an IDEMIA private cloud:
-
url
,apikey
, andidentityId
are provided from the Postman environment. -
The evidence unique identifier,
portraitId
, is also used.
Usage:
-
Open the folder
Portrait Identification
. -
Click getPortraitAdjudicationStatus.
-
Click Send.
Response:
-
Status shall be 200 OK.
-
The response contains the adjudication details confirming if the
FACIAL
adjudication is still in progress (PROCESSING
), if the timeout was reached (TIME_OUT
), or if it was accepted or rejected by the operator.
Identity Documents
To send the identity documents, the same URL is used for:
-
Passports
-
Identity Cards
-
Resident Cards
-
Driver's Licenses
In the Postman project, one folder has been created for each document type and each folder is associated with a unique environment variable in order to facilitate the tests (so that when a passport is submitted, Postman fills a
variable passportId
or when a driver's license is submitted then drivingLicenseId
is used).
Submit Identity Document Capture
Objective: Send an identity document image for verification of identity attributes and a portrait.
Environment:
If you use an IDEMIA private cloud:
url
,apikey
, andidentityId
are provided from the Postman environment.
Usage (example for passport):
-
Open the folder
Passport
. -
Click submitPassportCapture.
-
Click Body and replace the parameters.
-
DocumentCaptureDetails
: known details on the identity document like type and country. See the provided example in deliverysubmitPassport.json
. This field is optional. If it is not sent, the classification will be done by GIPS.Example: mrz: a list of string containing MRZ details
-
JSON1{2 "jurisdiction": "FRA",3 "documentType": "PASSPORT",4 "source": "LIVE_CAPTURE_IMAGE",5 "metadata": [6 {7 "key": "KEY1",8 "value": "value1"9 },10 {11 "key": "KEY2",12 "value": "value2"13 }14 ]15}
-
jurisdiction
: document issuing country -
documentType
: document Type -
source
: from enumerationLIVE_CAPTURE_IMAGE
,LIVE_CAPTURE_VIDEO
,SCAN
,DOCUMENT_CROP
,OTHER
-
metadata
: a list of metadata -
DocumentFront
: front image document -
DocumentBack
: back image document
- Click Send.
Response:
-
Status shall be 200 OK to confirm evidence has been associated with the identity.
-
The response body contains the evidence
IDDOCUMENT
details such as the unique evidence identifier, the evidence type, and status. -
As described previously, based on the chosen Postman folder, an environment variable is set and will be used for
GET
andDELETE
operations on this evidence.
Note:
For identity cards, both the front and back are required, except for France, Italy, and Romania where the back is optional.
For passports, the back is forbidden.
For French Resident cards, if the MRZ of resident card starts with “IR” then both the front and back are mandatory, otherwise (“TS”), only the front is required.
For driver's licenses, only the front is required except for USA, UK, and Canada, where both sides are mandatory.
Submit Identity Document
Objective: Send an identity document for verification of the identity attributes.
Environment:
If you use an IDEMIA private cloud:
url
,apikey
, andidentityId
are provided from the Postman environment.
Usage (example for passport):
-
Open the folder
Passport
. -
Click submitPassport.
-
Click Body.
-
Make sure you are in raw mode.
-
Update the data if needed.
Example:
-
JSON1{2 "idDocumentType": "PASSPORT",3 "idDocumentNumber": "AB1234567",4 "issuingCountry": "AUS",5 "personalAttributes": {6 "givenNames": [{ "value": "CHRISTOPHE", "verified": false }],7 "surname": { "value": "ULYSSE", "verified": false },8 "dateOfBirth": { "value": "1960-04-10", "verified": false }9 },10 "metadata": [{ "key": "GENDER", "value": "M" }]11}
- Click Send.
Response:
-
Status shall be 200 OK to confirm that the evidence has been associated with the identity.
-
The response body contains the evidence
IDDOCUMENT
details like the unique evidence identifier, the evidence type, and status. -
As described previously, based on the chosen Postman folder, an environment variable is set and will be used for
GET
andDELETE
operations on this evidence.
Retrieve Status for a Specific Identity Document
Objective: Retrieve the status for a specific identity document. This allows the ability to perform polling on the evidence. As soon as the status is not PROCESSING
, you can perform a getIdentityDocumentDetails
to retrieve all of the evidence details.
Environment:
If you use an IDEMIA private cloud:
-
url
,apikey
, andidentityId
are provided from the Postman environment. -
The evidence unique identifier is also used (for example, for a passport:
passportId
)
Usage (example with Passport):
-
Open the folder
Passport
. -
Click getPassportStatus.
-
Click Send.
Response:
-
Status shall be 200 OK.
-
Response contains the status of the identity document. As soon as the status is finished
PROCESSING
, you can get all of the document details.
Get Identity Document Details
Objective: Retrieve the identity document details, based on its unique identifier.
Environment:
If you use an IDEMIA private cloud:
-
url
,apikey
, andidentityId
are provided from the Postman environment. -
The evidence unique identifier is also used (for example, for a passport:
passportId
).
Usage (example with Passport):
-
Open the folder
Passport
. -
Click getPassportDetails.
-
Click Send.
Response:
-
Status shall be 200 OK.
-
The response body contains the global status of the identity and details on the evidence(s) associated with the given identifier such as status and score.
Get Identity Document with Indicators Details
Objective: Retrieve the identity document data and all the indicator details, based on its unique identifier.
Environment:
If you use an IDEMIA private cloud:
-
url
,apikey
, andidentityId
are provided from the Postman environment. -
The evidence unique identifier is also used (for example, for a passport:
passportId
).
Usage (example with Passport):
-
Open the folder
Passport
. -
Click getDrivingLicenseDetails.
-
Click Send.
Response:
-
Status shall be 200 OK.
-
The response body contains the global status of identity and details on the evidence associated with a given identifier like status and score.
-
Indicators details.
Get Identity Document Capture
Objective: Retrieve the identity document captured image, based on its unique identifier.
Environment:
If you use an IDEMIA private cloud:
-
url
,apikey
, andidentityId
are provided from the Postman environment. -
The evidence unique identifier is also used (for example, for a passport:
passportId
).
Usage (example with Passport):
-
Open the folder
Passport
. -
Click getPassportCapture.
-
Click the arrow on the right of the Send button.
-
Choose Send and Download. When the popup is displayed, choose a directory and a name to save the returned part to a file.
Response:
- Status shall be 200 OK.
- The saved content is a multipart response: file shall be edited to remove the multipart header and footer.
-
Edit saved file with file editor (notepad++ for example).
-
At beginning of the file, delete multipart header:
HTTP1*--1b817195-cbe4-485f-90fd-4ed6f27f54a8*2*Content-Disposition: form-data; name="DocumentBack"*3*Content-Type: application/octet-stream*
At the end of the file, delete multipart footer: *--1b817195-cbe4-485f-90fd-4ed6f27f54a8--*
.
- Save the modifications brought and open the file with a photo editor.
Note: when you send a document with a front and back, the multipart gives back a saved response in two parts: the first part is the front of the document and second part is the back of the document.
Delete Identity Document
Objective: Delete an identity document sent previously, based on its unique identifier.
Environment:
If you use an IDEMIA private cloud:
-
url
,apikey
, andidentityId
are provided from the Postman environment. -
The evidence unique identifier is also used (for example for passport:
passportId
).
Usage (example with Passport):
-
Open the folder
Passport
. -
Click deletePassport.
-
Click Send.
Response:
- Status shall be 204 No Content in order to confirm that passport has been deleted.
Send Identity Document to Adjudication
Objective: Send the document to manual adjudication. The adjudication shall have been activated for your tenant. An evidence can be sent to adjudication only if the flag isAdjudicable is
set to true
and if adjudication is available, otherwise an error will be given back.
Environment:
If you use an IDEMIA private cloud:
-
url
,apikey
, andidentityId
are provided from the Postman environment. -
The evidence unique identifier is also used (for example for passport:
passportId
).
Usage (example with Passport):
-
Open the folder
Passport
. -
Click sendPassportToAdjudication.
-
Click Send.
Response:
-
Status shall be 200 OK in order to confirm that passport has been well sent to adjudication.
-
Response contains the adjudication details confirming that DOCUMENT adjudication has been sent (PROCESSING) and the expiration date time of adjudication request.
Retrieve Adjudication Status for a Specific Identity Document
Objective: Retrieve the adjudication status for a specific identity document.
Environment:
If you use an IDEMIA private cloud:
-
url
,apikey
, andidentityId
are provided from the Postman environment. -
The evidence unique identifier is also used (for example for passport
passportId
).
Usage (example with Passport):
-
Open the folder
Passport
. -
Click getPassportAdjudicationStatus.
-
Click Send.
Response:
-
Status shall be 200 OK.
-
The response contains the adjudication details confirming if the
DOCUMENT
adjudication is still in progress (PROCESSING
) or if the timeout was reached (TIME_OUT
) or if it was accepted or rejected by the operator.
Get Identity Document Portrait Crop
Objective: Retrieve the portrait crop extracted from the identity document sent previously.
Environment:
If you use an IDEMIA private cloud:
url
,apikey
, andidentityId
are provided from the Postman environment.
Usage (example with Passport):
-
Open the folder
Passport
. -
Click getPassportCapture.
-
Click the arrow on the right of the Send button.
-
Choose Send and Download. When the popup is displayed, choose a directory and a name to save the returned part to a file.
Response:
- Status shall be 200 OK.
- The saved content is a multipart response: file shall be edited to remove the multipart header and footer.
-
Edit the saved file with file editor (notepad++ for example).
-
At beginning of the file, delete the multipart header:
HTTP1*--1b817195-cbe4-485f-90fd-4ed6f27f54a8*2*Content-Disposition: form-data; name="Portrait"*3*Content-Type: application/octet-stream*
At the end of the file, delete multipart footer: *--1b817195-cbe4-485f-90fd-4ed6f27f54a8--*
.
- Save the modifications brought and open the file with a photo editor.
Get Proof
Objective: Retrieve proof associated with the requested identity and discards the data on the server.
Environment:
If you use an IDEMIA private cloud:
url
,apikey
, andidentityId
are provided from the Postman environment.
Usage:
-
Open the folder
Proof
. -
Click getProof.
-
Click the arrow to the right of the Send button.
-
Choose Send and Download. When the popup is displayed, chose a directory and a name to save the returned part to a file.
Response:
- Status shall be 200 OK to confirm that proof has been correctly generated.
- The saved content is a multipart response: 7-Zip software can directly extract the content without editing the file. If you use another zip extractor you may have to edit the file to remove the multipart header and footer.
-
Edit the saved file with a file editor (Notepad++ for example).
-
At the beginning of the file, delete the multipart header:
HTTP1*--1b817195-cbe4-485f-90fd-4ed6f27f54a8*2*Content-Disposition: form-data; name=”ef…1729.zip"*3*Content-Type: application/octet-stream*
At the end of the file, delete the multipart footer: *--1b817195-cbe4-485f-90fd-4ed6f27f54a8--*
.
-
Save the file.
-
Open the file with a zip extractor: it contains the proof as described in the proof documentation:
And folder image: