Introduction

The CheckedID API by JanusID allows you to integrate a comprehensive and secure identity verification service into your processes and systems. It works together with an Invitation API and a ReportData API to cover parts of the process.

  • The CheckedID app verifies the identity of your user for you.
  • Import all relevant verification data and pictures for further processing.
  • Create and send invitations to use the CheckedID app to your users, customers or employees. You can also integrate the sending of invitations into your own environment, such as a CRM or HR system.

The CheckedID API is designed for privacy. You will be able to avoid any issues with purpose and proportionality of data processing and/or data leakage. The parameters to ensure the CheckedID service best fits your needs are initially set by KPN and can be adjusted if and when required.


Conceptual model

Conceptual model

  1. Agent calls the Invitation API.
  2. Agent sends invitation to user.
  3. User starts CheckedID app.
  4. App retrieves and validates user setttings.
  5. App guides user to capture ID data and live selfie.
  6. App sends data to CheckedID verifications service.
  7. CheckedID signals agent that verification has finished.
  8. Agent calls ReportData API to collect verification data.


Definitions

Agent

A natural person or automated service working for an organization.

User

  1. A natural person who is in process of becoming an identified relation of an organization.
  2. An agent who is (also) entitled to use the CheckedID app for identifying relations of their organization.

Organization

A legal person that:

  1. Is a CheckedID and KPN API Store customer, and
  2. Has a legitimate purpose for verifying the identities of natural persons who are (future) relations of them.

CheckedID App

The CheckedID app is published by JanusID B.V. in the Google Play Store for Android and App Store for iOS.

ID document

A formal government issued, ICAO 9303 conformant document to be used for international personal travel and/or identification. E.g. passport, identity card, residence permit, in some cases also driving licences.


API workflow

Workflow diagram


Features and constraints

Features

  • Secure identity verification of persons.
  • Self-scanning by persons using the CheckedID app.
  • Callback functionality upon user submitting data.
  • Processes all ID documents from any country worldwide.
  • Select the personal data you need and are legally allowed to receive. E.g. receive the data with or without personal number, ID document and/or holder pictures.
  • Receive the data in an encrypted report via e-mail, download it from the portal and/or as JSON through the API.
  • App users don't need to fill in any data, just tap-and-go. A simple and fully automated flow.

Constraints

  • Your agent needs:

    • Browser access to the CheckedID portal with pc (preferred), tablet or smartphone.
    • Knowledge of relevant laws and regulations for identity verification.
  • Your customer (invited or authorized) needs:

    • A smartphone which has:

      • Android or iOS.
      • A camera.
      • NFC reading capability (optional).
      • Adequate internet connection, minimum 3G or wifi.
      • CheckedID app installed from either Google Play Store or Apple App Store.
    • Possession of a valid identity document.


How to...

Create an invitation

An invitation provides an invitee of a CheckedID registered customer access to the app for 1 transaction during a limited period of time.

Field name Type Value
CustomerCode integer As registered with CheckedID.
EmployeeCode integer As registered with CheckedID.
InviteeEmail string Unique identifier for invitations.
InviteeFirstName string Used for personally addressing the invitee.
CustomerReference string [OPTIONAL] Used by customers for identifying this invitation in their own environment.
AppFlow string Possible values 10 or 20. This relates to the type of user:
10 - invitee / one-time user flow,
20 - employee / registered user flow.
Validity integer Number of hours the invitation is valid after being generated.

Invitations as requested are generated with new – or renewed – InvitationCode and InvitedTime. These will be provided with the response.


Invitation output

Field name Type Value
CustomerCode integer As registered with CheckedID.
Invitations array A list of invitations, see model below.


Invitation model

Field name Type Value
EmployeeCode integer Employee code.
InviteeEmail string Invitee e-mail address.
InvitationCode string Invitation code.
InviteeFirstName string First name of invitee.
CustomerReference string Customer reference.
AppFlow string App Flow. Possible values 10 or 20. This relates to the type of user:
10 - invitee / one-time user flow,
20 - employee / registered user flow.
Validity integer Number of hours the invitation is valid after being generated.
InvitedTime string Invitation date time (UTC - ISO-8601).

Get report details based on dossier number and scope

The API allows for receiving verified data per dossier. The request takes DossierNumber as input parameter. You will obtain the value of this DossierNumber once the user has submitted their data with the CheckedID app, then the URL value of the Result callback is called. You can point the webhook to any URL, by giving a value to the callback parameter in the CheckedID portal.

Use the DossierNumber, from the Result callback, together with the Scope as input parameters for this request.

Note: Reports are accessible during the retention period set for the customer’s data. This can be for a maximum of 28 days after data creation. However, a period of 7 days is default and advised. After the retention period all personal data is deleted or anonymized and can no longer be retrieved from CheckedID.

Result callback output

Field name Type Value
CustomerCode integer Customer code.
EmployeeCode integer Employee code.
InviteeEmail string Invitee e-mail address.
CustomerReference string Customer reference.
InvitationCode string Invitation code.
DossierNumber string Dossier number of the report.
ReportDateTime string Report date time (UTC - ISO-8601).
ReportResult string Result.
Details string Details.
DetailsMessageCode string Possible values 00 to 79. See table below.


Details message codes

MessageID Description
00 NFC chip: reading NOT SUPPORTED on device.
01 NFC chip: APPROVED.
02 NFC chip: reading SKIPPED by user.
03 NFC chip: REJECTED.
09 ID uploaded from portal.
10 FACE match: REJECTED - no ID photo.
11 FACE match: employee APPROVED.
12 FACE match: biometrically APPROVED.
13 FACE match: biometrically REJECTED.
14 FACE match: visually APPROVED.
15 FACE match: visually REJECTED.
20 [original Mitek reported error/warning].
21 OCR error(s) possible for some data.
22 ID validation error.
23 Expired document.
50 Document and chip data have NO MATCH.
51 [ID document type] is not allowed for identification by [Customer].
52 Additional document is MISSING for [ID document type].
70 Manually processed dossier.
71 INVITATION used: [InvitationCode].
72 INVITATION used: [InvitationCode] + Ref: [CustomerReference].
79 Revised by CheckedID.


Report details output

Field name Type Value
CustomerName string Customer name.
DossierNumber string Dossier number of the report.
Scope string Possible values 01 (PDF report unencryted), 10 (data only), 12 (pictures from report), 13 (pictures with originals).
EmployeeInvolved string Name of employee involved.
ReportDateTime string Report date time (UTC - ISO-8601).
ExecutedBy string Executed by.
ReportResult string Result. Possible values approved and rejected.
Details string Details.
DetailsMessageCode string Details message code.
DocumentType string Document type.
DocumentTypeCode string Document code, conform ICAO-9303.
DocumentCountry string Document country.
DocumentNumber string Document number.
DateOfIssue string Date of issue.
DateOfExpiry string Date of expiry.
Authority string Authority.
FirstName string First name.
Name string Name.
Sex string Gender. male, female or "" (empty string).
DateOfBirth string Date of birth.
PlaceOfBirth string Place of birth.
PersonalNumber string Personal number.
Nationality string Nationality.
PhotoIdChip array Photo ID chip (Base64).
PhotoHolder array Photo holder (Base64).
IdDocumentFront array Front document (Base64).
IdDocumentBack array Back document (Base64).
OtherDocument array Other document (Base64).
ReportPDF string Unencrypted version of the PDF report (Base64).


Return codes

Code   Description
200   Success.
201   Created.
202   Accepted.
302   Found. Link in location header.
400   Bad request.
401   Unauthorized.
403   Forbidden.
404   Not found.
405   Method not allowed.
412   Precondition failed.
429   Too many requests.
500   Internal server error.
502   Bad gateway.
503   Service unavailable.