Prerequisites
Sign up for an account — It's free.
Sign in to your account and generate a public key and secret. For security purposes, the secret is only shown once, so make sure to save it and keep it in a safe place. If you lose your secret you can generate a new one.
Integration at a glance
On a high level, this integration has four main steps:
• Create a session using the
Session API.
• Open the hosted verification flow with the returned token and a redirect URL.
• Let the redirect bring the user back to your frontend when the flow completes.
• Retrieve identity data from your backend after the redirect.
Note that there is no sandbox environment for testing, instead, integration and testing is done in production.
When you sign up for an account you can use the Developer plan for this.
Step 1 — Create a session
Start by creating a new session from your backend system:
curl http://localhost:4000/api/v2/session.create \
-u PUBLIC_KEY:SECRET \
-d @- << EOF
{
"face_verification": false,
"passport_only": false
}
EOF
{
"id": 123,
"token": "i_dI5hs7m...",
...
} Optional properties:
• reference — set a reference to connect the session to any arbitrary identifier, such as a user id or a session id from your own system.
• face_verification — set whether face verification is required or not (false by default).
• passport_only — set whether only passports should be accepted, excluding national ID cards (false by default).
Note that a session is intended to be used for a short period of time to handle a single user. Once a session has been used, it should not be used again.
Step 2 — Open the hosted flow
Open this URL with the token from the previous step and a redirect URL where the user will be sent after the verification flow completes:
http://localhost:4000/open?token=TOKEN&redirect_url=https%3A%2F%2Fexample.com%2Fdone The session will open in the most appropriate way depending on the user's device, always ensuring the best possible user experience.
If you omit
redirect_url, the user will stay on the Iris hosted completion screen instead.
Native iOS or Android integrations can also redirect in the same way. Open the URL in a web view or in the device's web browser. The redirect URL can be a web URL, or a deeplink or universal link pointing to a native app.
Step 3 — Handle the redirect
When the verification flow completes, the user's browser will be redirected back to your redirect_url.
Use this frontend redirect as the completion signal. Your frontend should call your own backend, and your backend should use the session id it stored in Step 1 to retrieve the result. Step 4 — Retrieve identity data
After the frontend redirect, use the
Session API to retrieve the identity data in your backend system.
curl http://localhost:4000/api/v2/session.get \
-u PUBLIC_KEY:SECRET \
-d @- << EOF
{
"id": 123
}
EOF
{
"state": "COMPLETED",
...
"given_names": "John",
"surname": "Doe",
"nationality": "US",
"sex": "MALE",
"date_of_birth": "1988-01-01",
"personal_number": "...",
"place_of_birth": "...",
"optional_data": "...",
"optional_data2": "...",
"document_type": "PASSPORT",
"document_number": "31195855",
"expiry_date": "2031-01-01",
"issuing_country": "US",
"issuer": "Department of State, U.S. Government",
"portrait": "dGVzdHRlc3R0ZXN0...",
"document_integrity_verified": true,
"active_authentication": true,
"chip_authentication": true,
...
} If face verification was required, an additional property will be available; face — containing an image of the user's face.
Available data and metadata
Data and metadata returned by the
Session API, available for you to use in your application:
• Created — Timestamp for when the session was created
• Expires — Timestamp for when the session expires
• State — Current session state
• Reference — Your own optional reference for the session
• User IP — IP address observed when the user initiated the verification
• User agent — User agent observed when the user initiated the verification
• Given names — Given names as stated on the passport or ID
• Surname — Surname as stated on the passport or ID
• Nationality — Two-letter ISO 3166 code (e.g. “US”)
• Sex — “MALE”, “FEMALE” or “UNSPECIFIED”
• Date of birth — Formatted as YYYY-MM-DD
• Personal number — Personal number, if present in the document
• Place of birth — Place of birth, if present in the document
• Optional data — Additional personal data, if present in the document
• Optional data 2 — Additional personal data, if present in the document
• Document type — The document type (e.g. “PASSPORT”)
• Document number — Document number as stated on the passport or ID
• Expiry date — Formatted as YYYY-MM-DD
• Issuing country — Two-letter ISO 3166 code (e.g. “US”)
• Issuer — Name of the issuing authority
• Portrait image — High resolution digital image from the passport or ID, base64 encoded PNG
• Document integrity verified — Whether passive authentication verified the document data
• Active authentication — Whether active authentication was supported and verified
• Chip authentication — Whether chip authentication was supported and verified
• DSC — Document signer certificate used to verify the document
• CSCA certificate fingerprint — Fingerprint of the trusted country signing certificate authority certificate
• Face — Image of the user's face (if face verification was required), base64 encoded PNG
Session lifecycle
Possible lifecycle states for a session:
• State CREATED — The session is created
• State INITIATED — The session has been initiated by the user
• State FAILED — The session failed, e.g. because of an NFC read error
• State CANCELLED — The session was cancelled by the user
• State COMPLETED — The session completed successfully