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.


API specification

Test the API on SwaggerHub


Base URL

https://api-prd.kpn.com/identity/janusid/checkedid


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 licenses.


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.

Send a POST request to /api/invitations


Request

^^Request body^^
{
  "CustomerCode": 1001,
  "Invitations": [
    {
      "EmployeeCode": 1,
      "InviteeEmail": "example@example.com",
      "InviteeFirstName": "Jack",
      "InviteeLastName": "Jones",
      "InvitationCode": "EVA4XK",
      "CustomerReference": "Example 2603",
      "AppFlow": 10,
      "Validity": 36
    }
  ]
}


Field name Type Value
CustomerCode integer As registered with CheckedID. Mandatory.
EmployeeCode integer As registered with CheckedID. Mandatory.
InviteeEmail string Duplicate e-mail addresses allowed. Duplicate e-mail addresses result in multiple invitations. Mandatory.
InviteeFirstName string Used for personally addressing the invitee. Mandatory.
InviteeLastName string Used for personally addressing the invitee.
InvitationCode string Invitation Code.
CustomerReference string Used by customers for identifying this invitation in their own environment. Optional.
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. Mandatory.
Validity integer Number of hours the invitation is valid after being generated. Mandatory.

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


Response

^^Status 200 Response^^
{
  "CustomerCode": 10001,
  "Invitations": [
    {
      "EmployeeCode": 1,
      "InviteeEmail": "example@example.com",
      "InvitationCode": "EVA4XK",
      "InviteeFirstName": "Jack",
      "InviteeLastName": "Jones",
      "CustomerReference": "Example 2603",
      "AppFlow": 10,
      "Validity": 36,
      "InvitedTime": "2020-03-11T14:29:31.9100000+00:00"
    }
  ]
}


Field name Type Value
CustomerCode integer As registered with CheckedID.
Invitations array A list of invitations.
EmployeeCode integer Employee code as registered with CheckedID.
InviteeEmail string Invitee e-mail address.
InvitationCode string Invitation code.
InviteeFirstName string First name of invitee.
InviteeLastName string Last name of the 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).


Update an invitation

To update an existing invitation send a POST request to /api/invitations.

Note: The initial InvitedTime remains the same when you update an invitation.


Request

^^Request body^^
{
  "CustomerCode": 1001,
  "Invitations": [
    {
      "EmployeeCode": 1,
      "InviteeEmail": "example@example.com",
      "InviteeFirstName": "Jack",
      "InviteeLastName": "Jones",
      "InvitationCode": "EVA4XK",
      "CustomerReference": "Example 2603",
      "AppFlow": 10,
      "Validity": 36
    }
  ]
}


Field name Type Value
CustomerCode integer As registered with CheckedID. Mandatory.
EmployeeCode integer As registered with CheckedID. Mandatory.
InviteeEmail string Duplicate e-mail addresses allowed. Duplicate e-mail addresses result in multiple invitations. Mandatory.
InviteeFirstName string Used for personally addressing the invitee. Mandatory.
InviteeLastName string Used for personally addressing the invitee.
InvitationCode string Invitation Code.
CustomerReference string Used by customers for identifying this invitation in their own environment. Optional.
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. Mandatory.
Validity integer Number of hours the invitation is valid after being generated. Mandatory.


Response

^^Status 200 Response^^
{
  "CustomerCode": 10001,
  "Invitations": [
    {
      "EmployeeCode": 1,
      "InviteeEmail": "example@example.com",
      "InvitationCode": "EVA4XK",
      "InviteeFirstName": "Jack",
      "InviteeLastName": "Jones",
      "CustomerReference": "Example 2603",
      "AppFlow": 10,
      "Validity": 36,
    }
  ]
}


Field name Type Value
CustomerCode integer As registered with CheckedID.
Invitations array A list of invitations.
EmployeeCode integer Employee code as registered with CheckedID.
InviteeEmail string Invitee e-mail address.
InvitationCode string Invitation code.
InviteeFirstName string First name of invitee.
InviteeLastName string Last name of the 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.


Retrieve report data

You can retrieve verified data per dossier. Send a POST request to /api/getreportdata

Send the DossierNumber, from the Result callback of the CheckedID report, together with the Scope as input parameters for this request.

Request

^^Request body^^
{
  "DossierNumber": null,
  "Scope": null
}
Field name Type Value
DossierNumber string The DossierNumber of the CheckedID report.
Scope string Possible values: 01, 10, 11, 12, and 13.
Scope 10 retrieves all pictures, scope 13 retrieves only the photo on the chip, if available.

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.

Response

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 81. See table Details message codes 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.
24 Copied ID document used.
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].
53 [ID document type] from [Country] is not allowed for identification by [Customer].
54 Right‐to‐Work is REJECTED.
70 Manually processed dossier.
71 INVITATION used: [InvitationCode].
72 INVITATION used: [InvitationCode] + Ref: [CustomerReference].
79 Revised by CheckedID.
80 Right‐to‐Work needs to be approved.
81 Right‐to‐Work is APPROVED.


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.

Mopinion feedback