Available APIs: info for developers

Contact tracing APIs

Contact tracing is a critical part of New Zealand’s COVID-19 elimination strategy. The faster contact tracers can reach people who have been exposed to the virus, the faster we can stop the virus from spreading.

The Ministry has created a number of APIs, outlined below, enabling third-party vendors and developers to receive information about COVID-19 exposure events, and to transfer relevant contact tracing information to the Ministry.

Exposure event notifications

This feed allows authorised developers to receive a list of Exposure Events of Interest (EEOI). These events are instances where people may have come into contact with COVID-19. An EEOI will contain a location identified as a Global Location Number (GLN), a time window, and any other relevant data so that appropriate action can be taken. Depending on the type of solution, there will be two possible actions:

1. Contact alerts

A contact alert will be sent notifying an individual that they have potentially been in contact with COVID-19 by being in the same place around the same time as a person who has tested positive for the virus. The message will tell the person what to do.

2. Visitor register matching

Solutions that hold information about visitors at locations can use the GLN and time range in the EEOI to search their dataset for matching visitor entries.

Matching records can be sent to contact tracers electronically and linked to appropriate case records for investigation.

The solution will need to have authorisation to share the person’s name and contact details and adherence to Government privacy requirements.

The process for Exposure event notification and data upload for integrated partners is as follows:

  1. Exposure Event of Interest (EEOI)
    EEOI notification is published.
  2. Notify subscribers
    All subscribers receive the notification.
  3. Match subscriber’s data
    Within their own datasets, a subscriber looks for relevant records that match. For example, in a visitor register they will find names/numbers of people who were there within the exposure notification window at the given location (GLN).
  4. Match identified
    If a subscriber has matching data, they send it to the Ministry.
  5. Data collection endpoints
    Incoming data is tagged against the relevant case record in the National Contact Tracing System (NCTS).

Push events from a digital diary

When a person tests positive for COVID-19, they are identified as a ‘case’ and are called by their local Public Health Unit (PHU). During this call they are informed of their positive test result, and (in subsequent calls) asked for information about where they have been, and who they have been in contact with.

If they have kept a digital diary of their movements, they will be asked to share this electronically. If the person consents, a 6-digit alphanumeric one-time-password is generated in the National Contact Tracing Solution (NCTS) by the PHU. They then read out this one-time-password over the phone for the Case to enter this into their digital diary.

  1. User calls case
    PHU calls location representative.
  2. User asks for information
    PHU asks Case if they have used a diary phone app that is integrated with the NCTS – see Integrating other contact tracing apps with NZ COVID Tracer APIs.
  3. Generate code
    If the case has, the PHU generate a one-time-password in NCTS linked to Case Records.
  4. Enter code
    The case enters the one-time-password into their digital diary.
  5. Match data
    Data is uploaded to NCTS to allow for contact tracing.

Publish a visitor from a location

As part of a case investigation, a contact tracer will investigate locations of possible exposure events and may need to phone people at an affected location for more information. This could include requesting a copy of a visitor register for a particular time period.

If the location is using an integrated third-party solution for managing their visitor register, they will be given a 6 digit one-time-password and a time range over the phone. They will use this to send the relevant data to contact tracers electronically. This would require integrators to develop an interface for themselves or their customers to enter this code for the corresponding EEOI parameters, which would then use the API endpoint to upload this data to the Ministry.

  1. Phone call to location
    PHU calls a person at a location exposed to COVID-19.
  2. Request for information
    PHU asks the person if they are using a visitor register solution that is compatible with the NCTS – see Integrating other contact tracing apps with NZ COVID Tracer APIs.
  3. Generate code
    If the location is the PHU generate a one-time-password in the NCTS linked to Case Records.
  4. Enter code
    The person enters the one-time-password into their visitor register interface.
  5. Match data
    Data is uploaded to NCTS to allow for contact tracing.
Back to top