v1 Upload Flow

Overview

The goal of this document is to give an overview of API interactions that occur when a SafePaths mobile user uploads their data to the SafePlaces API within the context of a contact tracing interview.

Flow Overview

Case and Access Code Creation

Contact tracer creates a new case within the SafePaths web UI. After the new case has been created a new AccessCode record will be created and associated with the case. The accessCode value will be returned in the response payload of the create case endpoint. See this document (SPL Token Exchange | Access Code Exchange ) for information on creating access tokens.

• Endpoint: POST /organization/case (SPL API Specification v1 (For MVP1) | confirmed: POST /organization/case )

Access Code Validation

The user will input the accessCode into the SafePaths app. An API request will be made to this endpoint. The endpoint returns a boolean indicating whether or not the accessCode exists and is valid.

• Endpoint: GET /access-code/valid/{accessCode} (SPL API Specification v1 (For MVP1) | GET /access code/valid/{accessCode} )

User Consent

The user consents to the HA’s terms of service after the access code is confirmed to be valid. We record the user’s consent on the case record associated with the accessCode and invalidate the accessCode record (set invalidatedAt timestamp) if the user did not consent to the terms of service.

• Endpoint: POST /consent (SPL API Specification v1 (For MVP1) | POST /consent )

Data Upload

User data (points of concern) are posted to the endpoint along with the accessCode. Validation on the accessCode occurs once more and then we persist the provided user data.

• Endpoint: POST /upload (SPL API Specification v1 (For MVP1) | POST /upload )

Post Data Upload

The SafePlaces frontend application will be polling the GET /case/{caseId}/points (SPL API Specification v1 (For MVP1) | GET /case/{caseId}/points ). Once the upload process has concluded the endpoint will return the points of concern that were uploaded from the SafePaths app. The endpoint should check for the presence of an access code record associated with the case and take the following actions:

• Return an appropriate error message to the client if the accessCode record is no longer valid (invalidatedAt timestamp is not nil ) for any reason

• Return an appropriate error message to the client if the user has not consented to the HA’s terms of service

• Return an appropriate status code if there is a valid access code associated with the case and but no points of concern associated with the case (user has not uploaded data yet)

• Return all points of concern associated with the case if there are any

Open Questions

1. The SafePaths mobile app needs to know what HA’s are using SafePlaces. How are we serving up information about what HA’s are on using SafePlaces? What information do we expose about the HA’s and their organizations?