API Access for Analytics Extracts

Last updated
Save as PDF

This article provides guidance for admins on how to download and decrypt scheduled analytics extracts using API access.

Overview

API access enables you to download scheduled analytics reports containing customized data extracts that are typically not available through the standard user interface. This functionality is configured by the Customer Education (CE) team and becomes accessible only after setup. It is intended for advanced reporting use cases and restricted to users with appropriate administrative credentials.

Prerequisites

Before using this functionality, ensure the following:

Special API Key Access: A dedicated API key is required to access analytics extracts. This key is provisioned by the CE team after the extract service is configured for your organization.
Encryption Key: The Customer Education team also provides the encryption key needed to decrypt the downloaded files. This key is unique to each customer and securely shared.

Retrieve and Use Analytics Extracts

You can retrieve analytics extracts by using a specific sequence of API calls. These extracts are available only after the scheduled reports are configured for your organization. This configuration is initiated by your Customer Success Manager based on reporting requirements. Once confirmed, the CSM coordinates with the CE Analytics Team to enable the feature.

Use the Analytics Extracts API

Follow the sequence of API calls to access, retrieve, and download your configured analytics extracts.

Call the following endpoint to retrieve all extracts configured for the school: https://developers.northpass.com/reference/list-extracts
Using the extract ID, call one of the following endpoints:

To return all extract files: https://developers.northpass.com/reference/list-extract-files
To return only the most recent file: https://developers.northpass.com/reference/get-extracts-latest-file

Using both the extract ID and the file ID, call the following endpoint: https://developers.northpass.com/reference/get-extract-file-download-info
This returns a pre-signed URL to download the file and the initialization vector required to decrypt it.

Note

The download URL is valid for one hour.
Do not share pre-signed URLs, as they grant open access to the content until they expire.

Decrypt the Report File

All extract files are encrypted using the AES-256-CBC algorithm.

To decrypt the downloaded file, you need two values:

The encryption key is Base64-encoded.
The initialization vector (IV) is returned in the API response and is also Base64-encoded.

Both values must be converted to HEX before decryption.

Decryption Example

The following example shows how to decrypt files on macOS X. If you are unfamiliar with Terminal, refer to Apple’s official support guide for instructions on how to use it.

Make sure to convert the encryption key and IV from Base64 to HEX before decryption. For best results and security, it is recommended to use a reliable online Base64-to-HEX converter.
Open Terminal.
Run the following command:

openssl enc -aes-256-cbc -nosalt -d -in Encypted_File_Name.csv.gz -out Decrypted_File_Name.csv.gz -K 'REPLACE-WITH-HEX-ENCRYPTION-KEY' -iv 'REPLACE-WITH-HEX-IV'

Service Behavior and Rules

The Analytics Extract API follows specific operational guidelines that define how extracts are generated, stored, and managed:

Extracts are generated on a schedule defined by the Analytics team or Customer Success Manager, based on discussions with the customer.
Reports are stored for 30 days, after which they are permanently deleted.
No backups are retained; expired reports cannot be recovered.
Reports are provided in CSV format, compressed using GZip, and encrypted.

API Usage Limits

To maintain performance and reliability, API access to Analytics Extracts is subject to defined rate and usage limits:

Request Rate: 5 per second (burstable up to 10 per second).
Daily Quota: 500 requests.
Example: Checking every 15 minutes = ~100 requests per day