Vaccine Passport Data Feed

The AppArmor Vaccine Passport Feed allows you to pull down vaccine passport data from your AppArmor Dashboard. The Feed can be used by qualified developers to create integrations between third party systems and the AppArmor platform.

Please note that the API must be used by a qualified developer. AppArmor does not provide software development training, nor does our team know the details of implementing the API in all programming environments. Our support team is able to provide general support and troubleshooting help for the API, but they will be unable to assist with the unique implementation details of your systems.

Implementation Recommendations

Most commonly, this feed is used to integrate with Access Control systems. Based on our previous experience, we’ve noticed the most common issues are with client Internet connectivity, networking equipment, and other systems. Our goal is to have the most resilient solution possible so that access to buildings continues smoothly. With this in mind, our recommendation is to:

  1. Have a polling tool that downloads the complete list from the feed on a periodic basis (every 15 minutes) and saves it locally.

  2. Configure the access control system to query the local copy of the data.

This configuration has been the most resilient so far.  If an Internet outage occurs, building access should be unaffected because the access control system is querying the local cached copy of the data.

We discourage “live lookups” of the data because of the bandwidth overhead, and this approach could be impacted by a temporary Internet connectivity issue.

API Key

Access to the Feed requires a unique “API Key” provided by AppArmor. The API Key is a randomized string of text that is used as a parameter to all requests. Please contact AppArmor Support, or your AppArmor representative for information about licensing and obtaining an API Key.

Accessing the Feed

Each client has a unique hostname associated with their AppArmor Dashboard account. The Incident Reporting Feed is accessed by appending the path “/Passports/Feed/” and the “[KEY]” parameter to the Dashboard url. For instance, if your AppArmor Dashboard URL is clientname.apparmor.com, and your API key is “abcd-1234-abcd-1234” then the API can be accessed at the following URL:

https://clientname.apparmor.com/Passports/Feed/?[KEY]=abcd-1234-abcd-1234

Data Format

By default, the feed will show a table of the reports, but you can adjust the format of the feed by specifying the [format] attribute to one of "CSV", "XML", "JSON".  Here's an example:

https://clientname.apparmor.com/Passports/Feed/?[KEY]=abcd-1234-abcd-1234&[format]=XML

Additional Parameters

The Vaccine Passport feed url also support other parameters as outlined below.

UserID and SSOID

Although performing “live lookups” is not recommended, the feed also support the ability to query a single user’s vaccination status. To do this, you can specify either the "UserID" (typically email address) or "SSOID" (if SSO is implemented by the client) to do individual lookups on the data. Here are example URLs with these attributes added:

https://clientname.apparmor.com/Passports/Feed/?[KEY]=abcd-1234-abcd-1234&[format]=CSV&UserID=user@email.com

 

CustomStatus

By default, the feed tries to normalize the users' status to either “Approved” or “Not Approved”. We’ve found that as the pandemic has evolved, this approach has become non-optimal because there are numerous additional statuses being created for different scenarios (e.g.: Exempt, Tested, etc). For this reason, you can append “&CustomStatus=True” to the feed URL to “pass through” the custom statuses to the feed.

AdditionalFields

If you would like to return additional data fields from the Vaccine Passport, they can be specified in the “AdditionalFields” attribute. For instance, if you would like to also return the “Vaccine Dose 1” and “Vaccine Dose 2” fields, they can be requested by adding “&AdditionalFields=Vaccine Dose 1,Vaccine Dose 2”. Multiple additional fields can be listed using commas as separators.

Generally speaking we recommend URL encoding the parameters for best results. Typically a URL encoded set of parameters will have spaces replaced by “%20”. So the the url will end with “&AdditionalFields=Vaccine%20Dose%201,Vaccine%20Dose%202”

Here is a sample URL showing the AdditionalFields parameter added to the end:

PassportDate and ExpiryDate

Adding the “&PassportDate=True” and/or the “&ExpiryDate=True” parameters to the feed url will include the date the passport application was submitted (PassportDate) and/or the date of expiration for the passport (ExpiryDate). Please note that “&CustomStatus=True” must be included to use PassportDate or ExpiryDate parameters.

Feed Data Fields

There are only three fields being returned in the data feed, they are:

  • UserID: The user identifier, typically an email address

  • SSOID: If the client is using Single Sign On, then this will contain their SSO identifier.

  • Status: Either "Approved" or "Not Approved" (Unless the “CustomStatus=True” attribute is added to the URL. In that case, the custom status will be supplied.)