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 users based on formal, government-issued ID documents such as passports, ID cards, residence permits.
  • 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.

To get customized data parameters, please contact KPN support


API specification

Test the API on SwaggerHub


Base URL

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


Conceptual model

  1. Agent calls the Invitation API.
  2. Agent sends an invitation to the user with the invitation code, QR code or quick link.
  3. User starts CheckedID app.
  4. App retrieves and validates user settings.
  5. App guides the 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 the ReportData API to collect verification data.


Definitions

Agent

A natural person or automated service working for an organization.

User

A user is a person who is invited (or: entitled) to use the app for identity verification.

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. For example: Passport, identity card, residence permit, in some cases also driving licenses.

QR code

A QR code (short for Quick Response code) is a type of matrix barcode (or two-dimensional barcode). Here it serves as a representation of the invitation code, which is 6 character alphanumeric string.

WebHook

A webhook − also called a web callback or HTTP push API − is an HTTP POST callback to your back-end service. For example, when the customer accepts a transaction request, an HTTPS POST request is sent to your specified callback URL.

Here it serves to get the response of the HTTPS POST request directly from CheckedID. If you need IP white-listing, please contact KPN support.


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.
      • Adequate internet connection, minimum 3G or Wi-Fi.
      • CheckedID app installed from either Google Play Store or Apple App Store.
    • Possession of a valid identity document.


Getting started

Make sure you've read What's in it for you for more info on how to register and start testing APIs.

Authentication

The API follows the KPN Store API Authentication Standard to secure the API. It includes the use of OAuth 2.0 client_id and client_secret to receive an access token.

Go to the Authentication tab on top of this page to find out how to:

  • Authenticate to an API using cURL.
  • Authenticate to an API on Swaggerhub.
  • Import Open API Specifications (OAS), also called Swagger files into Postman.


How to...

Run the endpoints on SwaggerHub

You can easily run this and other endpoints.

  1. Go to the API on SwaggerHub.
  2. Click Authorize.
    1. Enter your client_id and client_secret using your KPN API Store credentials (Client ID and Client secret).
    2. Click Authorize.
    3. Click Close.
  3. Click the endpoint.
    1. Click Try it out.
    2. Enter/select all required parameter values and any optional parameter values.
    3. At the bottom of the form, click Execute.
  4. Review the Response.

Manage Invitations

The following endpoints allow you to create new invitations, update existing ones, and delete invitations:

  • Creates invitations: POST ​/invitations
  • Updates invitations: PATCH ​/invitations
  • Deletes invitations. DELETE ​/invitation​/{customerCode}​/{invitationCode}

You can send the invitation code in the invitation as:

  1. Invitation code. Example: LLMY1R
  2. QR code. You can create it with any QR generator using the Invitation code.
  3. Quick link. Example: checkedid://janusid.com/?invitecode=LLMY1R

Manage Users

The following endpoints allow you to create, update and delete users, and to activate employees:

  • Creates employees: POST ​/users
  • Updates employees: PATCH ​/users
  • Deletes employees: DELETE ​/user​/{customerCode}​/{userCode}
  • Activates employees: PATCH ​/activateusers

Retrieve ReportData

The following endpoints allow you to retrieve report data:

  • Retrieves PDF report: GET ​/report​/{dossierNumber}
  • Retrieves report data: GET ​/reportdata​/{dossierNumber}​/{scope} This endpoint retrieves data from verification reports previously received by CheckedID customers. These – personal – data sets can be imported into the environment of the customer.

Reports are accessible for a maximum of seven days after they were created. After that period their data can no longer be retrieved.

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.


HTTP response headers

The following tables display the standard response headers that are returned with each API response:

Standard response field name Description
sunset This field will be populated with the deprecation details. By default the value is n/a.
api-version Indicates the API version you have used.
quota-interval Used to specify an integer (for example, 1, 2, 5, 60, and so on) that will be paired with the quota-time-unit you specify (minute, hour, day, week, or month) to determine a time period during which the quota use is calculated.
For example, an interval of 24 with a quota-time-unit of hour means that the quota will be calculated over the course of 24 hours.
quota-limit Number of API calls an user can make within a given time period.
If this limit is exceeded, the user will be throttled and API requests will fail.
quota-reset-UTC All quota times are set to the Coordinated Universal Time (UTC) time zone.
quota-time-unit Used to specify the unit of time applicable to the quota.
For example, an interval of 24 with a quota-time-unit of hour means that the quota will be calculated over the course of 24 hours.
quota-used Number of API calls made within the quota.
strict-transport-security The HTTP Strict-Transport-Security (HSTS) response header lets a website tell browsers that it should only be accessed using HTTPS, instead of using HTTP. All present and future subdomains will be HTTPS for a maximum of 1 year and access is blocked to pages or sub domains that can only be served over HTTP including HSTS preload lists of web browsers.
Strict-Transport-Security: max-age=31536000; includeSubDomains; preload.
Access control field name Description
access-control-allow-credentials Tells browsers whether to expose the response to frontend JavaScript when the request's credentials mode (Request.credentials) is include.
When a request's credentials mode (Request.credentials) is include, browsers will only expose the response to frontend JavaScript if the Access-Control-Allow-Credentials value is true. Boolean.
access-control-allow-origin Indicates whether the response can be shared with requesting code from the given origin.
access-control-allow-headers Used in response to a pre-flight request which includes the Access-Control-Request-Headers to indicate which HTTP headers can be used during the actual request.
access-control-max-age Indicates how long the results of a pre-flight request (that is the information contained in the Access-Control-Allow-Methods and Access-Control-Allow-Headers headers) can be cached.
access-control-allow-methods Indicates which HTTP methods are allowed on a particular endpoint for cross-origin requests.
For example: GET, PUT, POST, DELETE.
content-length The Content-Length entity header indicates the size of the entity-body, in bytes, sent to the recipient.
content-type The Content-Type entity header the client what the content type of the returned content actually is.

Mopinion feedback