Integration guide — Web

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.

With this integration 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 has three main steps:
• Create a session using the Session API. Provide a callback URL to receive the updates for this session.
• Using the web 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 APPROVED, use the Session API to retrieve the passport and ID data.

Each step is outlined in more detail below.

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 are given free credit to be used for this.

Always start by creating a new session from your backend system:
# request curl http://localhost:4000/api/v1/session.create \ -u PUBLIC_KEY:SECRET \ -d @- << EOF { "callback_url": "..." } EOF # response { "id": 123, "token": "i_dI5hs7m...", ... } Optional properties;
• callback_url — set a callback url to receive session updates. Must be a valid public URL where your backend system handles the session updates.
• 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.

Include the javascript SDK.
<script src="http://localhost:4000/client/v1.js"></script> Next, import the SDK and set up a session using the token from the previous step.
// integration example in javascript var iris = new Iris(token); iris.start( "#selector", // element where the client should be rendered function() { // session was successful }, function() { // handle error, e.g. retry by calling start again } ); On success, you will receive a callback to the URL provided in the previous step.

When you receive a callback with session state APPROVED, use the Session API to retreive the passport and ID data in your backend system.
# request curl http://localhost:4000/api/v1/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": "Department of State, U.S. Government", "portrait": "dGVzdHRlc3R0ZXN0...", ... } If face verification was required, an additional property will be available; face — containing and image of the user's face.

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

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", "session_reference": "" } 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 FAILED — The session failed, e.g. because of an NFC read error
• State ABORTED — The session was aborted by the user
• State COMPLETED — The session completed successfully
• State REJECTED — The session was rejected, e.g. because the document could not be verified
• State APPROVED — The session has been verified and approved