Prerequisites

Sign up for an account — It’s free
Sign in to your account and generate a new 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 guide — Iris ID

This guide covers how to integrate with Iris ID. With this option you don’t need an app of your own, instead, your users will use the Iris ID app to verify their identity.
On a high level, this integration as three main steps:
• Create a session using the Session API. You must provide a callback URL where you will receive the updates for this session.
• Inform the user to download the Iris ID app, and display a QR code or deeplink. The user has to scan the QR code or click on the deeplink to launch the session in Iris ID. Once the passport or ID is successfully scanned by the user, you will receive a callback to the URL provided in the previous step.
• When you receive a callback with session state COMPLETED, use the Session API to retrieve the passport and ID data.
Each step is outlined in more detail below.
Always start by creating a new session from your backend system:
# request curl http://localhost:4000/api/session.create \ -u PUBLIC_KEY:SECRET \ -d @- << EOF { "callback_url": "..." } EOF # response { "id": 123, "token": "i_dI5hs7m...", ... }
A callback URL must always be provided. It must be a valid URL where your backend system handles the session updates.
Two additional properties are optional;
• 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).
Note that a session is intended to be used for a short period of time to handle one user (one document). Once a session has been used successfully, it should not be used again.
Inform your user to download the Iris ID app in the App Store or Google Play.
Using the token received in the previous step, generate a QR code with the following data (the format is the same for iOS and Android):
iris:///?token=TOKEN
Display the QR code to the user so that they can scan it with their device. Scanning the QR code will open the Iris ID app and start the session.
Once the user has completed the session, you will receive a callback to the URL provided in the previous step.
Inform your user to download the Iris ID app in the App Store or Google Play.
Using the token received in the previous step, generate a link or a button with the following href (the format is the same for iOS and Android):
iris:///?token=TOKEN
Display the link or button to the user, or automatically redirect to the href. Clicking on the link or button, or being automatically redirected, will open the Iris ID app and start the session.
Once the user has completed the session, you will receive a callback to the URL provided in the previous step.
The Iris ID app can also automatically redirect the user at the end of the flow.
To enable this behavior, append a redirect URL to the href:
iris:///?token=TOKEN&redirect_url=REDIRECT_URL
Where REDIRECT_URL is a valid URL in URI encoded format. This URL can be e.g. a web address but it could also be a deeplink to another app.
When you receive a callback with session state COMPLETED, use the Session API to retreive the passport and ID data in your backend system.
# request curl http://localhost:4000/api/session.get \ -u PUBLIC_KEY:SECRET \ -d @- << EOF { "id": 123 } EOF # response { "given_names": "John", "surname": "Doe", "nationality": "US", "sex": "MALE", "date_of_birth": "1988-01-01", "document_type": "PASSPORT", "document_number": "31195855", "expiry_date": "2031-01-01", "issuing_country": "US", "issuer": "U.S. Department of State", "portrait": "dGVzdHRlc3R0ZXN0...", "current": true, "valid": true, ... }
Make sure to check the current and valid properties before using the data. If any of the properties are false, the data should be discarded and the user should try again.
If face verification was required, an additional property will be available; face — containing and image of the user’s face.

Integration guide — SDK

This guide covers how to fully integrate our solution into your own application. Our UX components blends with yours and the user will go through the necessary steps without leaving your app.
On a high level, this integration as three main steps:
• Create a session using the Session API. You must provide a callback URL where you will receive the updates for this session.
• Using the SDK start the session with the token created in the previous step. Once the passport or ID is successfully scanned by the user, you will receive a callback to the URL provided in the previous step.
• When you receive a callback with session state COMPLETED, use the Session API to retrieve the passport and ID data.
Each step is outlined in more detail below.
Always start by creating a new session from your backend system:
# request curl http://localhost:4000/api/session.create \ -u PUBLIC_KEY:SECRET \ -d @- << EOF { "callback_url": "..." } EOF # response { "id": 123, "token": "i_dI5hs7m...", ... }
A callback URL must always be provided. It must be a valid URL where your backend system handles the session updates.
Two additional properties are optional;
• 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).
Send the token to your application.
Note that a session is intended to be used for a short period of time to handle one user (one document). Once a session has been used successfully, it should not be used again.
Download the SDK (Iris framework) for iOS and add it to your Xcode project. Both Swift and Objective-C is supported. Minimum target iOS 11.0.
To add a framework to an iOS application, follow these steps:
• Open the app’s Xcode project or workspace.
• Go to the app target’s General configuration page.
• Add the framework target to the Embedded Binaries section by clicking the Add icon.
• Select the framework from the list of binaries that can be embedded.
Next, import the SDK and set up a session using the token from the previous step.
Start the session.
// integration example in Swift import Iris var iris: Iris = Iris(token: token) iris.start( successHandler: { (response) in // session was successful }, errorHandler: { // handle error, e.g. retry by calling start again } )
On success, you will receive a callback to the URL provided in the previous step. Some data points are also available directly in the response.
Download the SDK (Iris library) for Android and add it to your Android Studio project. Both Kotlin and Java is supported. Minimum target API level 21.
To add a library to an Android application, follow these steps:
• Open the app’s Android Studio project.
• Go to File > New > New Module and select Import .JAR/.AAR Package.
• Provide the path to the library and click Finish to add it.
• Go to File > Project Structure > Dependencies and select your app.
• Under Declared Dependencies, click the + button and select Module Dependency.
• Select the library from the list.
Next, import the SDK and set up a session using the token from the previous step.
Start the session.
// integration example in Kotlin import iris.Iris val iris = Iris(this, token) iris.start(object: Iris.StartHandler { override fun onSuccess(response: Iris.SuccessResponse) { // session was successful } override fun onError() { // handle error, e.g. retry by calling start again } })
On success, you will receive a callback to the URL provided in the previous step. Some data points are also available directly in the response.
When you receive a callback with session state COMPLETED, use the Session API to retreive the passport and ID data in your backend system.
# request curl http://localhost:4000/api/session.get \ -u PUBLIC_KEY:SECRET \ -d @- << EOF { "id": 123 } EOF # response { "given_names": "John", "surname": "Doe", "nationality": "US", "sex": "MALE", "date_of_birth": "1988-01-01", "document_type": "PASSPORT", "document_number": "31195855", "expiry_date": "2031-01-01", "issuing_country": "US", "issuer": "U.S. Department of State", "portrait": "dGVzdHRlc3R0ZXN0...", "current": true, "valid": true, ... }
Make sure to check the current and valid properties before using the data. If any of the properties are false, the data should be discarded and the user should try again.
If face verification was required, an additional property will be available; face — containing and image of the user’s face.

Additional resources

During the lifecycle of a session we will send a callback when the session state changes. These callbacks are sent to the URL provided when the session is created.
Callbacks are sent as JSON encoded POST requests and contain the session id and session state in the request body. All callbacks are re-tried up to 5 times in case of errors on the receiving end.
# callback example curl CALLBACK_URL \ -H "Content-Type: application/json" \ -d @- << EOF { "session_id": 123, "session_state": "INITIATED" } EOF
Below is a list of possible lifecycle states for a session. All state changes after CREATED are sent as callbacks to the URL provided when the session was created.
If the flow ends with state ABORTED or FAILED, a new session must be created and the user must start over from the beginning.
• State CREATED — The session is created
• State INITIATED — The session has been initiated by the user
• State ABORTED — The session was aborted by the user
• State FAILED — The session failed, e.g. because of an NFC read error
• State COMPLETED — The session completed successfully
Data points returned by the Session API, available for you to use in your application:
• 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 — If applicable, subject to country-specific formats
• 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
• Face — Image of the user’s face (if face verification was required), base64 encoded PNG
Validity checks:
• Current — Boolean indicating if the document is current (not expired or rejected by the issuer)
• Valid — Boolean indicating if the document is valid (chip verification was successful)
Certain data points are available in the SDK directly, without using the Session API:
• Given names
• Surname
• Nationality
• Document type
• Document number
• Expiry date
• Issuing country
• Issuer
• Portrait image
These data points are unverified and unsecure, and should not be used for purposes other than providing a smooth user experience, such as greeting the user by their real name as they progress in the application flow.
Always use only the verified data from the Session API for any real operations such as creating user accounts.
Sales & support
sales@passportreader.app
Passport Reader is a solution for touchless onboarding and identity verification on global scale. Through an SDK businesses can add biometric passport and id card processing, facial recognition, liveness detection, KYC and AML compliance as an integral part of their existing customer experience. Built by developers, for developers.

© Iris 2018-2021Kungsgatan 60, 111 22 Stockholm, SwedenTerms & conditionsPrivacy