Home / Issuing / Generate Reports
Using Reports
For security purposes and to ensure up-to-date data, generated reports have a limited lifespan of one day. After one day has passed, they will no longer be valid or usable.
Highnote provides on-demand reports that empower you with data to drive your critical business decisions. This guide is provides on overview on using the Highnote GraphQL API to list and generate reports, check report statuses, and download reports.
You can use the ReportUsage query to retrieve the following data:
reportType: Displays the type of report.limit: Displays your report usage limit. The default daily limit is three.limitRemaining: Displays how many reports are remaining from your usage limit. For example, if you have generated one report from your limit, this line would display 2 as your remaining limit.periodEnd: The date and time when your usage limit resets.
Use the following query to retrieve report usage data:
You can generate up to three reports per day. The reportUsage allowance resets daily at 12 AM Eastern Time (ET).
You can generate a report using the InitiateReport mutation. When generating a report, you must provide the reportType, and all required or optional parameters. If required parameters are missing, a validation message is sent indicating which fields are missing.
Use the following mutation to generate a report:
Using a report ID, you can query for the Report node to get report details for a single report. Important details to note include the download {url} and status.
If you’d like to list all existing reports and their details, you can use ListReports. You can filter the query by reportType and status to narrow down results if necessary.
Use the following query to list reports:
The Report Download Service (RDS) provides a secure and authenticated way to download reports. To use the RDS, you must provide your API key and the reportId that you received from either a notification or from using the ListReports API. With a reportId provided, RDS will provide a data stream of your report that you can use to download all report data.
The Report Download Service (RDS) supports a base64 encoded API key for authorization.
| Authorization Type | Description | Type |
|---|---|---|
| base64 encoded API Key | Provided in the header of the request as Basic auth: Basic <base64EncodedApiKey> | String |
Request
Endpoint: /reports/{reportId}
| Field Name | Description | Type |
|---|---|---|
reportId | The identified of the report the client wants to download | String |
Header
| Header Name | Value | Description |
|---|---|---|
Authorization | Basic <base64EncodedApiKey> | N/A |
x-request-id | Optional client provided unique request id | Helps with tracing the operation |
Body: N/A
Response
Header
| Header Name | Value | Description |
|---|---|---|
x-response-id | Client provided unique request id | Same value provided in x-request-id |
Content-Type | application/octet-stream | Server supplied report content type |
Body: Stream of bytes
Response Status: HTTP status codes returned in case of errors
| HTTP Status Code | Description |
|---|---|
400 | Bad request. Usually occurs if the report id is invalid or user doesn’t own the given report. |
401 | Authentication error. Occurs if the token is invalid or expired. |
404 | Occurs if report is not found for the given reportId. |
500 | Internal server error. |
Usage
The URL used to download reports differs whether you are using the Test or Live Environment.
The following example requests represent use cases for downloading reports using either a specific name or reportId in the Live Environment:
- Download a File with a Specific Name
export TOKEN=<base64EncodedApiKey> curl https://download.us.highnote.com/reports/<reportId> -H "Authorization: Basic ${TOKEN}" -H "x-request-id: <requestId>" -v --output output.csv- Download a File with the Filename Equal to the reportId
export TOKEN=<base64EncodedApiKey> curl https://download.us.highnote.com/reports/<reportId> -H "Authorization: Basic ${TOKEN}" -H "x-request-id: <requestId>" -O