Introduction

Travel Use Case

The CommonCheck QR Verifier is an API that allows customers to verify digital COVID-19 test, vaccination and recovery credentials both for authenticity, ownership and compliance with the destination’s entry requirements. By integrating this API into existing systems, airlines, governments and other organizations that need to verify COVID-19 credentials can automatically verify the health status of their travelers or customers. With the API, supported health certificates/documents can be checked for authenticity and evaluated against country-specific health-related entry requirements.

Non-travel Use Case

The Verifier API can also be used for non-travel use cases, for instance, for verifying the health certificates of a concert or sporting event attendees. It can also be used in domestic verification apps within a particular country. For domestic verification, the same endpoints can be invoked with a slight variation in the request body(more on this below).

How it works?

The QR Verifier API takes in a QR content (the string that a QR code represents) and performs the following services:

  • Normalization of payload: Extracts and normalizes the information contained in dozens of different COVID-19 digital cert standards into standard schemas.
  • Checking of certificate authenticity: Checks if the digital signature on the credential(tests, vaccines and recovery certificates) is valid including validity checks of the Document Signing Certificates used to sign the credential. This functionality can be turned on/off in the API request.
  • Checking of certificate revocation: Checks whether the certificate has been revoked by the Issuer (when the Issuer provides a dedicated revocation check service). This functionality can be turned on/off in the API request.
  • Checking of certificate data against pre-specified rules: Evaluates the health related data contained in the certificate against pre-specified rules. This is useful in helping enforce business decisions such as permitting only a specific set of vaccinations. This functionality can be turned on/off in the API request.
  • Checking of certificate data against personal details: Matches the details within the certs against the personal details provided by the customer. This functionality can be turned on/off in the API request.

Sample Non-Travel Request

List of Recognized Issuers

Below is the list of issuers that the Verifier API supports

Issuer
Standard
Type
Countries
AOK Pass
Non-National Standard
Covid test
France, USA
3DCerts
Non-National Standard
Covid test
Singapore, Indonesia
Collinsons
Non-National Standard
Covid test
Singapore, Hong Kong, Indonesia, United Kingdom
Accredify
Non-National Standard
Covid test
Singapore, Hong Kong
NextID
Non-National Standard
Covid test
Singapore
BP Labs
Non-National Standard
Covid test
Malaysia
Riverr
Non-National Standard
Covid test
Singapore, Philippines, Taiwan
Convergence.Tech(Trybe.ID)
Non-National Standard
Covid test
Singapore
PAH(Gribbles)
Non-National Standard
Covid test
Malaysia
Jebhealth
Non-National Standard
Covid test
Singapore, Malaysia
Immunitee
Non-National Standard
Covid test
Malaysia
CommonPass
Non-National Standard
Covid test
USA
Hi-Precision
Non-National Standard
Covid test
Philippines
Healius
Non-National Standard
Covid test
Austrailia
PADL
Non-National Standard
Covid test
Austrailia
MYEG
Non-National Standard
Covid test
Malaysia
Agriya Analitika
Non-National Standard
Covid test
Indonesia
Kuwait Mosafer
Non-National Standard
Covid test
Bangladesh, Egypt, India, Lebanon, Nepal, Pakistan, Philippines, Kuwait, France, Sri Lanka, Turkey, UAE, Jordan, Oman, Qatar, Saudi Arabia, Bahrain, USA
AMOSUP
Non-National Standard
Covid test
Philippines
EKA Hospital
Non-National Standard
Covid test
Indonesia
Aventus
Non-National Standard
Covid test
Philippines
Bangladesh Government
Non-National Standard
Covid test
Bangladesh
USCI University Lab
Non-National Standard
Covid test
Malaysia
Agaram Diagnostics
Non-National Standard
Covid test
India
Hospital Penawar
Non-National Standard
Covid test
Malaysia
Gnosis Laboratories
Non-National Standard
Covid test
Malaysia
JSS Medical Lab
Non-National Standard
Covid test
Malaysia
Dr. Lal Pathlabs
Non-National Standard
Covid test
India
Supercare Lab
Non-National Standard
Covid test
Philippines
Consentry
Non-National Standard
Covid test
United Kingdom
C Lab
Non-National Standard
Covid test
Egypt
Prime Speed Medical
Non-National Standard
Covid test
Egypt
Ermita Molecular Diagnostic Laboratory
Non-National Standard
Covid test
Philippines
AL Molecular Diagnostic Laboratory Inc
Non-National Standard
Covid test
Philippines
Mediflex Laboratories
Non-National Standard
Covid test
Maldives
Al Shams
Non-National Standard
Covid test
Egypt
Swabaja
Non-National Standard
Covid test
Indonesia
Rsud Bali Manadra
Non-National Standard
Covid test
Indonesia
Bahrain Ministry of Health
Non-National Standard
Covid test
Bahrain
Elroi Medical Clinic
Non-National Standard
Covid test
Philippines
Supreme Council of University Hospital
Non-National Standard
Covid test
Egypt
Thyrocare
Non-National Standard
Covid test
Bahrain
TracVirus
Non-National Standard
Covid test
Malaysia
Histopath
Non-National Standard
Covid test
Australia
Chinese Government Hospital and Medical Centre
Non-National Standard
Covid test
Philippines
Knowledge Catalyst
Non-National Standard
Covid test
Singapore
DuniaLab
Non-National Standard
Covid test
Malaysia
VIDA - Unifier Integration
Non-National Standard
Covid test
Indonesia
GovDigital-Ubirch (Germany)
Non-National Standard
Covid test
Germany
Pathlab
Non-National Standard
Covid test
Malaysia
Metropolis/Scal
Non-National Standard
Covid test
India
Filpass(Edufield)
Non-National Standard
Covid test
Philippines
RakoScience
Non-National Standard
Covid test
New Zeland
Paradigm Lab
Non-National Standard
Covid test
USA
Israel Green Pass
National Stanadard
Covid Vaccination
Israel
DIVOC
National Stanadard
Covid Vaccination
India, Sri Lanka, Indonesia, Philippines
Hong Kong Health Code
National Stanadard
Covid Vaccination & Covid test
Hong Kong
Singapore HealthCerts
National Stanadard
Covid Vaccination & Covid test
Singapore
MySejahtera
National Stanadard
Covid Vaccination & Covid test
Malaysia
UK NHS
National Stanadard
Covid Vaccination & Covid test
United Kingdom
ICAO VDS
National Stanadard
Covid Vaccination & Covid test
Australia, Japan
Smart Health Card
Non-National Standard
Covid Vaccination
Japan, Canada, USA, Cayman Island
EU DCC
National Stanadard
Covid Vaccination, Covid test & Covid Recovery
Albania, Austria, Bulgaria, Belgium, Bulgaria, Croatia, Czechia, Denmark, Estonia, Finland, France, Germany, Greece, Hungary, Iceland, Ireland, Israel, Italy, Latvia, Lithuania, Luxembourg, Malta, Netherlands, New Zealand, Norway, Poland, Portugal, Romania, Singapore, Slovakia, Slovenia, Spain, Sweden, Switzerland, Turkey, United Arab Emirates
thailand-dcc
National Stanadard
Covid Vaccination
Thailand
COOV
National Stanadard
Covid Vaccination
South Korea
Tawtheeq
National Stanadard
Covid Vaccination
Qatar

Authentication

To get access to the API, you must have API keys provided by CommonCheck team. Please reach out using the form above if you require assistance.

HTTP Errors

This section covers the possible HTTP errors

Type of status code
Description
HTTP 400
The server could not understand the request due to invalid syntax.
HTTP 401
the client must authenticate itself to get the requested response. this case the api-key is required
HTTP 500
Interal server error raised a support ticket for this error
HTTP 502
This error response means that the server, while working as a gateway to get a response needed to handle the request, got an invalid response.
HTTP 503
The server is not ready to handle the request. Common causes are servers being overloaded or down for maintenance.

QR Verifier Status Code

This section covers the status codes that the Verifier API will respond

Status code
Description
1000
Successful QR identification, verification, extraction and valid entry requirement request Definition: received 2000 + 2010 + 3000
1010
Unavailability of Plugin Identifier Service
1011
Unavailability of Plugin fetch credential service
1012
Unavailability of Plugin fetch credential service
1013
Unavailability of Timatic Service
1014
Unavailability of Timatic Service
1015
Unavailability of Allowlist Service
1016
Invalid License key with timatic feature
1017
Unavailability of rules orchestrator service
1018
Invalid License key with traveldoc feature
1050
CheckPersonalDetails checked true but personal details data not provided
1051
Vaccine QR cannot be used with Timatic
1052
Itinerary, localDateTimeWithTimezone and transportType must be provided when entryRequirements.check is set to true and airTravel is true
1053
entryRequirement is true but engine is not provided
1054
Qr Content Type does not match requested document type
1055
dynamicdate and rulesetId must be provided when entryRequirements.check is set to true and domesticTravel is true
1056
arrivalDatetime and departureDatetime cannot be blank when entryRequirements.check is set to true and transportType is air or land
1080
License key used is blocked from verifying this issuer's certs
1081
License key used is blocked from verifying this HTTP issuer's certs
2000
Successful QR identification
2001
Scanned license key not QR code
2002
Known unsupported issuer
2003
Unknown QR code
2004
Unknown Issuer
2005
Failed to download issuer public keys
2006
Issuer is missing
2007
Unsupported document type (not at vaccine or covid test)
2010
Sucessfully read the QR and verify the QR
2100
Unable to retrieve credentials
2101
Unavailability of downstream issuer servers
2102
Expired certificate
2103
Unavailability of Timatic Service
2104
Type not recognised
2105
Unable to verify signature
2200
Change of issuer’s implementation in signature
2201
Invalid health credential
2202
Unable to Verify Credential
2300
Change of issuer’s implementation in schema, unable to parse any data
3000
rules engine passed
3010
Country code should be ISO Alpha-3 string
3011
Ruleset not found
3012
No rules found in the ruleset
3013
No covid test rules found in ruleset
3014
No vaccine rules found in ruleset
3100
Unable to reach timatic server
3101
Missing input parameters
3102
Invalid XML Request
3200
Unable to reach V2 rules engine
3201
Missing input parameters
3202
Invalid input parameters
3203
Country code should be ISO Alpha-3 string
3204
Country rule does not exist
3205
Unable to reach specific country rule
3206
Exception error occuring at country rule
5000
Internal Server Error

Verify Options Schema

checkCertValidity
required
boolean
Enable or disable certificate validity check. This enforces a check to verify if the certificate has a valid signature and was generated by the claimed issuer.
checkCertRevocation
required
boolean
Enable or disable certificate revocation check. This enforces a check to verify if the certificate has been revoked by the issuer.
checkPersonalDetails
boolean
Enable or disable personal details check from certificate
checkEntityInAllowList
boolean
Enable or disable checks if the healthcare institution that conducted the COVID test is accepted by the destination country
entryRequirements
Arrow pointing down
required
object (QrVerifyEntryRequirementsInput)

Rules Engine Options

check
required
boolean
Enable or disable entry requirements check. This checks the certificate contents against entry requirements as specified by the destination, based on origin and flight data.
engine
string (RulesEngine)
Enum:
"affinidi"
"travelDoc"
"timatic"
"affinidiv2"
Selected engine to perform entry requirement check with. Valid options are "affinidi","affinidiv2","travelDoc" and "timatic". To use Timatic, a customer is required to liaise directly with Timatic and share with Affinidi their Timatic account details
type
string (TravelEntryType)
Enum:
"airTravel"
"landTravel"
"domesticTravel"
Select the mode of travel. Valid options are "airTravel","landTravel" and "domesticTravel"

Personal Details Schema

passport
required
string
Traveller's passport number
name
required
string
Traveller's full name
dateOfBirth
required
string
Traveller's date of birth
nationality
required
string
Traveller's nationality
nationalId
string
Traveller's National identification number
gender
string
Traveller's gender

Itinerary Schema

departure
Arrow pointing down
required
object (ItineraryObject)
arrival
Arrow pointing down
required
object (ItineraryObject)
flightNumber
string
Traveler's flight number
transit
required
boolean
check is there transit

QR Verifier API

This section covers the full API request that should be used as payload.

VerifyV1.1

HEADER PARAMETERS
Api-Key
required
string
The api-key that is issued
X-Forwarded-Host
string
standard header for identifying the original host requested by the client in the Host HTTP request header
uber-trace-id
string
used for internal tracing not required
REQUEST BODY SCHEMA:
application/json
qrContent
required
string
the qrContent after scanning the qr code
verifyOptions
Arrow pointing down
required
object (QrVerifyOptions)
An object with configuration options for verification of the certificate.
data
Arrow pointing down
required
object (QrVerifyData)
Enum:
data
containes the additional information that can be verified through this API, like
personalDetails
,
itinerary
, etc. The
data
field could be kept as a blank if the consumer does not want to verify any additional information in the cert. If the consumer wants to verify only authenticity of the cert, they can put the data field as a blank object like
{}
.

Responses

Request samples

Payload
Content type
application/json

Response samples

200
Content type
application/json

QR Reader API

We understand that there are many libraries and tools that can be used to read QR content. For the ease of your integration we have also included a QR code reader API to read and return the qrContent

ReadFile

The Api-Key must be provided in the request header for authorization.

The input file must be provided in the form-data and must be below 1 MB.

Accepted file types:

  • PNG
  • JPEG
  • Single page PDF

The output will be the QR content of the respective input file.

HEADER PARAMETERS
Api-Key
required
string
api key that is issued
REQUEST BODY SCHEMA:
application/json
file
required
string <binary>
the input file that should be less than 1 MB

Responses

400
Bad Request
401
Unauthorized

DISCLAIMER: THE COMMONS PROJECT FOUNDATION (“TCP”) DOES NOT PROVIDE MEDICAL ADVICE OR ADMINISTER ANY DIAGNOSTIC MEDICAL TESTS, VACCINES OR OTHER HEALTHCARE INTERVENTIONS. TCP MAKES NO ENDORSEMENT OR REPRESENTATION AS TO THE ACCREDITATION, LICENSING OR GOOD-STANDING OF ANY HEALTHCARE PROVIDER UNDER APPLICABLE STATE, FEDERAL, NATIONAL OR SUPRANATIONAL LAWS AND REGULATIONS. TCP EXPRESSLY DISCLAIMS ANY AND ALL LIABILITY FOR ANY CONSEQUENTIAL, INDIRECT, INCIDENTAL, SPECIAL OR EXEMPLARY DAMAGES, INCLUDING WITHOUT LIMITATION ANY LOSS OF REVENUES OR PROFITS OR ANY LOSS OF USE OF DATA, ARISING OUT OF OR CONNECTED IN ANY WAY WITH ANY DIAGNOSTIC TESTING, MEDICAL TREATMENT, VACCINATION OR OTHER HEALTHCARE INTERVENTION OR OTHERWISE PROVIDED, SPONSORED, OR PROMOTED BY ANY CTN MEMBER, WHETHER PROVIDED BY THE MEMBER ITSELF OR BY ITS AFFILIATES, REPRESENTATIVES, AGENTS OR SUBCONTRACTORS.