Automate your vaccination checks with HealthCerts — powered by OpenAttestation X Notαrise

How to programmatically retrieve and verify an individual’s vaccination status in Singapore

With the updated workplace vaccination measures in place from 15 January 2022, only fully vaccinated employees can return to the office.

This is where employers or businesses might feel overwhelmed to manually check every returning employee to ensure that they are vaccinated. The ideal scenario would be to have an automated way to perform these checks. If this piqued your interest, we have the very solution for you in this article!

Getting proof of vaccination should be quick and easy

There may be various ways to check an individual’s vaccination status — whether through the TraceTogether or HealthHub app. However, they all rely on visual confirmation. The TraceTogether check-in screens that we are familiar with do not provide details like the name of the vaccinated individual and their date of vaccination. PDFs and screenshots taken from the HealthHub app would also not serve as a sure way to verify the authenticity of the document.

With the power of the OpenAttestation (OA) open-source framework, it now becomes quick and easy to create verifiable documents that can be issued and verified by anyone. In this case, it would be the issuance and verification of HealthCerts.

In this article, we will go through how to programmatically retrieve and verify an individual’s Vaccination HealthCert so that you can skip all the tedious manual checks.

1. Get the individual to retrieve their Vaccination HealthCert

The first step is for the individual to retrieve their Ministry of Health (MOH) endorsed Vaccination HealthCert via the Notαrise portal.

“Vaccination certificate” button highlighted on www.notarise.gov.sg

Vaccinated individuals would just need to click on the “Vaccination certificate” button and log in via Singpass¹. Simply follow through with the instructions presented and they would get hold of their endorsed HealthCert via email in no time!

¹Individuals who may not have a Singpass account may also retrieve their Vaccination HealthCert via their Passport Number by clicking on the “Login via Passport Number” link

2. Obtain the Verify URL

Sample email upon successful issuance of HealthCert

Upon receiving the success email with the endorsed Vaccination HealthCert, simply copy the Verify URL from the “View Certificate” button.

A full Verify URL should look something like this:

https://www.verify.gov.sg/verify?q=%7B%22type%22%3A%22DOCUMENT%22%2C%22payload%22%3A%7B%22uri%22%3A%22https%3A%2F%2Fapi-vaccine.storage.staging.notarise.io%2Fdocument%2F8e61852b-4842-46ae-af91-8dcb157681cc%22%2C%22permittedActions%22%3A%5B%22VIEW%22%2C%22STORE%22%5D%7D%7D#%7B%22key%22%3A%22cea9cfc2cd24e2a7f0841e22a9c2ca25342ee8f70c17e5840086a586c04425db%22%7D

Visiting the above URL will bring you to www.verify.gov.sg where verification checks will be performed before the HealthCert is beautifully rendered.

2a. Making sense of the Verify URL

The decoded query parameters should look something like is:

?q={"type":"DOCUMENT","payload":{"uri":"https://api-vaccine.storage.staging.notarise.io/document/8e61852b-4842-46ae-af91-8dcb157681cc","permittedActions":["VIEW","STORE"]}}

It is then followed by an anchor (URI fragment):

#{“key”:”cea9cfc2cd24e2a7f0841e22a9c2ca25342ee8f70c17e5840086a586c04425db”}

The query parameters and anchor provide important information on how to retrieve and decrypt the HealthCert. The structure of the query params and anchor is further explained in the Architectural Decision Records (ADRs) of OpenAttestation.

By making a HTTP GET request to the uri field: https://api-vaccine.storage.staging.notarise.io/document/8e61852b-4842-46ae-af91-8dcb157681cc, you would be presented with a JSON object with its content encrypted.

In order to decrypt this payload, you will need the corresponding key as provided in the anchor of the URL: cea9cfc2cd24e2a7f0841e22a9c2ca25342ee8f70c17e5840086a586c04425db.

With the oa-encryption library, you will be able to decrypt and obtain the final JSON object that represents the actual Vaccination HealthCert (usually expressed as a .OA file).

Quicktip: For a quick way to encrypt/decrypt an OA document, you can make use of this GUI toolkit: toolkit.openattestation.com/encrypt-decrypt

3. Verifying the HealthCert

3 verification checkmarks on www.verify.gov.sg

Verifying an OA document ensures that:

  1. The document has been issued (issuance status)
  2. The document has not been tampered
  3. The document’s issuer has been identified

These are the same 3 checkmarks you would see on www.verify.gov.sg as mentioned in step 2. For more information about OA verification, you may refer to the documentation here.

With the oa-verify library or our publically available API endpoint², you can easily verify OA documents.

²Do take note that the public API endpoint is currently whitelisted to only verify documents issued by domains ending with *.gov.sg (even though OA documents can be issued by any entity)

Quicktip: For a quick way to verify an OA document, you can make use of this GUI toolkit: toolkit.openattestation.com/verify (Select “Mainnet” to verify production HealthCerts)

4. Extracting details from the HealthCert

Extracting details from a HealthCert is easy because it is essentially a JSON object.

4a. Unwrapping an OA document

In its verifiable state, the OA document is considered “wrapped”. This is why you see salts prefixed to each of the fields in an OA document. To learn more about why documents have to be wrapped, you may refer to the documentation here.

In order to cleanly retrieve the original values and structure of the JSON object, you would have to unwrap the OA document first.

With the open-attestation library or the open-attestation-cli, you can easily wrap or unwrap OA documents.

Quicktip: For a quick way to wrap/unwrap an OA document, you can make use of this GUI toolkit: toolkit.openattestation.com/wrap

4b. The Vaccination HealthCert schema

The data structure of a Vaccination HealthCerts can be described using a JSON Schema which can be found in schemata.openattestation.com under the “VACCINATION-HEALTHCERT” section.

A quick glance at the Vaccination HealthCert Schema v1.0

The schema.json definition is valuable to understand where and how to retrieve patient details, test types, test results, etc. from a Vaccination HealthCert. Whereas the *-unwrapped.json and *-wrapped.json simply refers to sample Vaccination HealthCerts that are in their unwrapped/wrapped state.

Samples

Vaccination HealthCert samples on gallery.openattestation.com

If you would like to try out what was described in this article, simply head to gallery.openattestation.com/tag/health-certs and click on any of the Vaccination v1 samples. After you are directed to www.verify.gov.sg and the HealthCert is successfully verified, you can scan the Online QR to obtain the full Verify URL.

Alternatively, you may attempt to retrieve your very own Vaccination HealthCert from Notαrise to perform the 4 steps as mentioned in this article.

Conclusion

At last, you should now be able to programmatically verify (step 3) and extract details (step 4) from a Vaccination HealthCert.

If you have any further questions regarding HealthCerts, feel free to reach out to support@notarise.gov.sg.

Please be reminded that you will still need to comply with all applicable laws (such as the Personal Data Protection Act, where relevant).

--

--

--

Be Happy, Be Awesome! We deliver high-quality digital services to citizens and businesses in Singapore 😊

Recommended from Medium

Two MORE Weeks To Flatten The Curve

Ten Years from Now, What Will Be Written About the Pandemic?

READ/DOWNLOAD#@ Financial Accounting FULL BOOK PDF & FULL AUDIOBOOK

Project Kavach: Safety Protocols and Measures by Urban Company

Teens in Georgia can now get a driver’s license without taking a test — CBS News

A Global Pandemic Demands Global Responses in Everyones' Best Interests

Florida’s Covid-19 Catastrophe

How to STOP COVID-19

Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store
Kyle Huang Junyuan

Kyle Huang Junyuan

More from Medium

Book report on The Ride of a Lifetime

Fuse, enabling mass adoption of digital crypto payments & DeFi

mod.io ✕ GDC