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.

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.

Go to https://www.getpostman.com/apps.
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 of GIPS 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 and apikey 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. See getIdentityFromCorrelationId 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 and identityId 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, and identityId 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, and identityId 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, and identityId 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, and identityId 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, and identityId 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 and apikey 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, and identityId, 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, and identityId 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, and identityId 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, and identityId 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, and identityId 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:

JSON
1{
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": 0
13}

Click Send.

Note: With a RELYING_SERVICE apikey, a score up to 5 can be provided if the attributes are already on your side. In this case, “verified” shall be set to true for the attributes you already know (at least given names, surname, and date of birth otherwise the score will be ignored). If the score is 5 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 evidence ATTRIBUTES. However, if the score is 1 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 level 2) 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, and identityId 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, and identityId 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, and identityId 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, and identityId 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:

JSON
1{
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 for GET and DELETE operations.

getAddressStatus

Objective: Retrieve the address status based on its unique identifier.

Environment:

If you use an IDEMIA private cloud:

url, apikey, and identityId 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, and identityId 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, and identityId 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, and identityId 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, and identityId 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”

JSON
1{
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, and identityId 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, and identityId 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, and identityId 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, and identityId 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:

HTTP
1*--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, and identityId 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, and identityId 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, and identityId 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, and identityId 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 delivery submitPassport.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

JSON
1{
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 enumeration LIVE_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 and DELETE 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, and identityId 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:

JSON
1{
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 and DELETE 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, and identityId 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, and identityId 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, and identityId 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, and identityId 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:

HTTP
1*--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, and identityId 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, and identityId 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, and identityId 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, and identityId 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.

$C:\Users\afakchich\Documents\WORK\stories\Nouveau dossier\getCrop.png$

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:

HTTP
1*--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, and identityId 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:

HTTP
1*--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: