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.
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
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%7DVisiting 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
Verifying an OA document ensures that:
- The document has been issued (issuance status)
- The document has not been tampered
- 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.
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
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).
