There are two ways to trigger your IT system to call the web service to download a file:
- Use the notification email as the trigger. Emails containing the file name are sent automatically whenever a new file is posted.
- Look for new files using the web service to get a file directory listing periodically.
In both cases, the web service uses your credentials (the same credentials you use to sign in to the reporting portal) and the data file name to return the presigned URL. The presigned URL enables the transfer of the file to your IT system.
If you are implementing a solution based on Option #1, we recommend requesting the presigned URL by passing both login credentials and file name through the web service in one step.
However, if you prefer or are implementing a solution based on Option #2 or downloading more than one file, you can obtain the presigned URL by first using your username and password to request an access token and then using the access token and file name to request the presigned URL.
Since electronic score report data files will be posted in both comma-delimited and fixed-width formats, you'll receive a separate email for each file. If you have an automatic file download service based on the score report email you receive (Option #1), your download script may be triggered two times (once for each format of the file). You may need to update your download script to ignore one of the email events based on the file extension (.csv, .txt).
The API references—and code samples—needed for both approaches are available.
- The presigned URL is active for only 15 seconds.
- The transporting encryption is accomplished by SSL/TLS/HTTPS.
- There is no client-side encryption enforced once the file is downloaded, so take any and all necessary steps to secure this file appropriately and meet your institution's security standards.
Note: The notification email has embedded html span tags. These tags can be used to identify and extract the file name from the email notification. Span tags use this format: <span id="fileName"> filename.txt </span>.