Resources

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.
Minimum target iOS 11.0 or Android 5.0 (API level 21)

Integration guide

There are three steps to verifying a passport:
• Create a new session token using the Session API
• Start the client using the session token. Once the passport is successfully scanned by the user, the client will return a client token
• Use the client token with the Verification API to verify the passport and to retrieve the passport data
Always start a verification flow by creating a new session from your backend system:
# request curl http://localhost:4000/api/session.create \ -u PUBLIC_KEY:SECRET # response { "id": "agZmTrqZx...", "token": "i_dI5hs7m..." }
Send the session token to your application.
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.
The API accepts an optional reference property that can be used to connect the session to any arbitrary identifier, such as a user id or a session id from your own system.
Download the client (Iris framework) for iOS and add it to your Xcode project. Both Swift and Objective-C is supported.
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 client and set it up using the session token from the previous step.
Start the client and wait for the success callback.
// client integration example in Swift // import client import Iris // set up the client var client: Iris = Iris(sessionToken: sessionToken) // start the client client.start( successHandler: { (response) in // client token is available in the response }, errorHandler: { // handle error, e.g. retry by calling start again } )
On success, send the client token to your backend system.
Download the client (Iris library) for Android and add it to your Android Studio project. Both Kotlin and Java is supported.
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 client and set it up using the session token from the previous step.
Start the client and wait for the success callback.
// client integration example in Kotlin // import client import app.iris.library.Iris // set up the client val client = Iris(this, sessionToken) // start the client client.start(object: Iris.StartHandler { override fun onSuccess(response: Iris.SuccessResponse) { // client token is available in the response } override fun onError() { // handle error, e.g. retry by calling start again } })
On success, send the client token to your backend system.
Use the Verification API to verify the passport and retreive the passport data in your backend system.
# request curl http://localhost:4000/api/verification.create \ -u PUBLIC_KEY:SECRET \ -d @- << EOF { "client_token": "i_dI5hs7m..." } EOF # response { "state": "COMPLETED", "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.
Upon successful verification, all passport data points are returned. For data privacy reasons, no data is stored, instead, retrieve the data and store it safely in your own systems. The same API request (using the same client token) can be repeated and will return the same data.
Data points returned by the Verification API, available for you to use in your application:
• Given names — Given names as stated on the passport
• Surname — Surname as stated on the passport
• 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
• 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 portrait image, base64 encoded
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 client directly, without the need to first verify the passport:
• Given names
• Surname
• Nationality
• 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 verify the passport and use only the verified data from the Verification API for any real operations such as creating user accounts.
The SDK on iOS and Android does not require a network connection, which makes it possible to e.g. onboard a user even if they are offline.
However, the SDK still needs a session token in order to operate. Therefore one must be created ahead of time at some point when the device is online, and stored in the application so that it is available when needed even if the device is offline. Once a session token has been used, it should not be used again (instead, generate a new one). This requires extra care when creating and storing tokens ahead of time.
The passport verification works in a similar way, the client token must be stored in the application and used at some point later when the device is online again.
There are no time restrictions for these events, but we recommend not trying to use tokens (both session tokens and client tokens) that are older than a day.

Support

If you have questions or need help with your integration, contact us at support@passportreader.app