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 three main steps:
• Create a session using the
Session API.
• Redirect the user and wait for the session to complete.
• Use the
Session API to retrieve the passport and ID data.
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.
Step 1 — Create a session
Always start by creating a new session from your backend system:
curl http://localhost:4000/api/v1/session.create \
-u PUBLIC_KEY:SECRET
{
"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).
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 — Redirect the user
Redirect the user to this URL with the token from the previous step included:
http://localhost:4000/open?token=TOKEN Optionally provide a redirect URL where the user will be redirected once the session is completed:
http://localhost:4000/open?token=TOKEN&redirect_url=REDIRECT_URL The session will open in the most appropriate way depending on the user's device, always ensuring the best possible user experience.
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 — Retreive passport and ID data
Use the
Session API to retreive the passport and ID data in your backend system.
Check that the session state is APPROVED before using the data.
curl http://localhost:4000/api/v1/session.get \
-u PUBLIC_KEY:SECRET \
-d @- << EOF
{
"id": 123
}
EOF
{
"state": "APPROVED",
...
"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.
Available data points
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
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 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