Verify a New Zealand COVID Pass

Overview

The New Zealand government has started issuing a type of digital health certificate known as a 'My Vaccine Pass' using the New Zealand COVID Pass (NZCP) specification, this credential contains a limited set of personal information and provides a way for the holder to prove they meet certain health policy requirements in regards to COVID-19 such as being vaccinated against the virus.

This guide will step through how to verify a New Zealand Covid Pass (NZCP), which can be presented as either an encoded string from a QR code or a file upload of a document containing a QR code.

Prerequisites

You need the following in order to proceed with this tutorial:

  • Access to MATTR VII APIs

  • A signed New Zealand COVID Pass issued by the New Zealand Ministry of Health

If you’re experiencing any difficulties, please contact us.

The NZCP Verify API is available as a Technical Preview to sandbox users, this allows you to try the API with non-production workloads however you may encounter unexpected issues. In particular, for this API the image processing capabilities are complex and may result in 5xx errors that have not yet been mapped to descriptions. In general, processing the official NZ COVID Pass JSON and PDF payloads are more stable.

If you wish to use the API to start verifying holders with NZ COVID Passes please get in touch to discuss.

Document types

NZ COVID Pass certificates may be presented to a verifier in the following formats:

  • PDF generated by NZ MoH containing the NZCP QR code

  • Photograph/scanned image of the PDF

  • Screenshot of the NZCP QR code

The MATTR VII platform can accept PDF, images (png or jpeg of sufficient quality and resolution) or the encoded string represented in the QR code.

Eligibility

The MATTR VII NZCP Verify API only checks for technical verification of the New Zealand COVID Pass payload and will return the contents of the data subject for which the pass has been created.

  • There is no provision in the API to confirm the eligibility of the holder, i.e. if the subject of the certificate should or should not have been issued the pass. This is determined by the New Zealand Ministry of Health.

  • There is no way for the API to determine if the document presented pertains to the same person that presents the document to the verifier. This will have to be determined by the verifier, e.g. by checking other forms of identity.

Use of the NZ COVID Pass to identify individuals requires adherence to a set of published terms. How you use the MATTR APIs to conduct activities related to individual data subjects is governed by these laws. We may remove your access to these APIs if these terms are not being followed.

Verify an NZCP by invoking the API as follows.

Request by encoded string

NZCP QR codes use the format specified in ISO/IEC 18004:2015 and are constructed as:

http
Copy to clipboard.
1NZCP:/<version-identifier>/<base32-encoded-CWT> 

Using a QR code scanning application to extract the entire QR encoded string and can be sent to the MATTR VII NZCP Verify API as follows:

http
Copy to clipboard.
1POST 
2https://YOUR_TENANT_SUBDOMAIN.vii.mattr.global/ext/nzcp/v1/verify
3Header: Content-Type: application/json

Request

json
Copy to clipboard.
1{
2  "payload": "NZCP:/1/2KCEVIQEIVVWK6JNGEASNICZAEP2KALYDZSGSZB2O5SWEOTOPJRXALTDN53GSZBRHEXGQZLBNR2GQLTOPICRUYMBTIFAIGTUKBAAUYTWMOSGQQDDN5XHIZLYOSBHQJTIOR2HA4Z2F4XXO53XFZ3TGLTPOJTS6MRQGE4C6Y3SMVSGK3TUNFQWY4ZPOYYXQKTIOR2HA4Z2F4XW46TDOAXGG33WNFSDCOJONBSWC3DUNAXG46RPMNXW45DFPB2HGL3WGFTXMZLSONUW63TFGEXDALRQMR2HS4DFQJ2FMZLSNFTGSYLCNRSUG4TFMRSW45DJMFWG6UDVMJWGSY2DN53GSZCQMFZXG4LDOJSWIZLOORUWC3CTOVRGUZLDOSRWSZ3JOZSW4TTBNVSWISTBMNVWUZTBNVUWY6KOMFWWKZ2TOBQXE4TPO5RWI33CNIYTSNRQFUYDILJRGYDVAYFE6VGU4MCDGK7DHLLYWHVPUS2YIDJOA6Y524TD3AZRM263WTY2BE4DPKIF27WKF3UDNNVSVWRDYIYVJ65IRJJJ6Z25M2DO4YZLBHWFQGVQR5ZLIWEQJOZTS3IQ7JTNCFDX"
3}

The payload in the request is the NZCP represented as a string.

Note: The example shown here won't be successfully verified as it is not an official NZCP issued by the New Zealand Ministry of Health.

Response

json
Copy to clipboard.
1{
2  "verified": true,
3  "payload": {
4    "givenName": "Jack",
5    "familyName": "Sparrow",
6    "dob": "1960-04-16"
7  },
8  "metadata": {
9    "notBefore": "2021-11-02T20:05:30.000Z",
10    "expiry": "2031-11-02T20:05:30.000Z",
11    "issuer": "did:web:nzcp.covid19.health.nz",
12    "type": "PublicCovidPass",
13    "id": "urn:uuid:60a4f54d-4e30-4332-be33-ad78b1eafa4b"
14  }
15}

The response includes a verified boolean, which indicates the outcome of the verification. Also returned is the associated payload and metadata from the certificate.

The data handled during the verification is not stored at any stage on the MATTR platform. The information is held temporarily in memory to allow the processing of the request and discarded once presented back in the response.

See our privacy policy for the platform for more details.

Request by PDF or Image

It is possible to capture the entire PDF or image of a document and send it to the MATTR VII NZCP Verify API by specifying the Content-Type header as follows:

  • application/pdf

  • image/png

  • image/jpeg

Request

http
Copy to clipboard.
1POST 
2https://YOUR_TENANT_SUBDOMAIN.vii.mattr.global/ext/nzcp/v1/verify
3Header: Content-Type: application/pdf

In the request include the binary PDF or image file.

The MATTR VII NZCP Verify API will process the file by:

  • Determining the file size, a maximum 1MB file is permitted to be uploaded, larger files will be rejected with a 413 error.

  • For PDF files, only the 1st page of the PDF is processed

  • Images must contain an NZCP QR code of sufficient quality and resolution, this depends on many factors just as the size of the QR relative to the image, and if any other pre-processing has occurred on the image.

  • The server will scan the file looking for a QR code, this is deterministic but the order cannot be overridden, try to ensure that only a single QR code is present on the file.

  • The QR code is then read and the contents processed as an NZ COVID Pass.

Response

The same response is returned as if the encoded string had been sent directly to the server.

json
Copy to clipboard.
1{
2  "verified": true,
3  "payload": {
4    "givenName": "Jack",
5    "familyName": "Sparrow",
6    "dob": "1960-04-16"
7  },
8  "metadata": {
9    "notBefore": "2021-11-02T20:05:30.000Z",
10    "expiry": "2031-11-02T20:05:30.000Z",
11    "issuer": "did:web:nzcp.covid19.health.nz",
12    "type": "PublicCovidPass",
13    "id": "urn:uuid:60a4f54d-4e30-4332-be33-ad78b1eafa4b"
14  }
15}

Not verified and errors 

In general, if the payload of the NZCP can be read and decoded the API will return a 200 HTTP status and specify if the NZCP is verified using the Boolean flag.  

For responses that show the verified status to be false, a further error body is returned with more details about the error, examples include: 

  • NZCP not issued by a trusted issuer 

  • NZCP is expired, current time is greater than expiry 

  • COSE signature verification failed 

Payloads that fail to decode or that are too large will return 4xx HTTP status responses, examples include: 

  • 400 Failed to decode base32 payload

  • 400 Unsupported payload version '1' 

  • 415 Unsupported media type

  • 413 Payload Too Large