About Highnote Reporting

Overview

Report schemas are subject to change

New columns may be introduced to existing reports as business or processing requirements evolve. Existing columns will not be removed or renamed without appropriate communication.

Subscribers are expected to design their data ingestion pipelines to tolerate the presence of new, previously undocumented fields. Implementations that rely on fixed column positions, strict column counts, or fail on unrecognized fields are not supported.

These additions are considered non-breaking changes. We recommend consuming report data by column name rather than ordinal position.

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.

List report usage

maximum per day

You can generate up to three reports per day. The reportUsage allowance resets daily at 12 AM Eastern Time (ET).

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:

ReportUsage

Query

query ReportUsage {
  reportUsage {
    ... on ReportUsage {
      reportType
      limit
      limitRemaining
      periodEnd
    }
  }
}

Variables

{
  "input": {
    "status": {
      "includes": [
        "COMPLETED"
      ]
    },
    "reportType": {
      "includes": [
        "CARD_TRANSACTION_ACTIVITY"
      ]
    }
  }
}

⚠️ Please login to execute queries. Visit the dashboard to authenticate.

Result

{
  "data": {
    "reportUsage": [
      {
        "reportType": "CARD_TRANSACTION_ACTIVITY",
        "limit": 3,
        "limitRemaining": 2,
        "periodEnd": "2023-06-21T04:00:00.000Z"
      }
    ]
  },
  "extensions": {
    "requestId": "REQUEST_ID"
  }
}

Generate a report

lifespan

Generated reports have a lifespan of 1 day, to enhance security and ensure data freshness. Afterward, they are no longer be valid or usable.

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:

InitiateReport

Query

mutation InitiateReport($input: InitiateOrganizationReportInput!) {
  initiateOrganizationReport(input: $input) {
    __typename
    ... on Report {
      __typename
      id
      status
      statusReason
      reportType
      createdAt
      updatedAt
    }
    ... on UserError {
      __typename
      errors {
        errorPath
        code
        description
      }
    }
  }
}

Variables

{
  "input": {
    "reportType": "CARD_TRANSACTION_ACTIVITY",
    "parameters": {
      "between": {
        "start": "2023-03-10T00:37:31+0000",
        "end": "2023-04-10T00:37:31+0000"
      }
    }
  }
}

⚠️ Please login to execute queries. Visit the dashboard to authenticate.

Result

{
  "data": {
    "initiateOrganizationReport": {
      "__typename": "Report",
      "id": "rptjb_01",
      "status": "IN_PROGRESS",
      "statusReason": null,
      "reportType": "CARD_TRANSACTION_ACTIVITY",
      "createdAt": "2023-06-21T17:30:07.196Z",
      "updatedAt": "2023-06-21T18:44:52.006Z"
    }
  },
  "extensions": {
    "requestId": "REQUEST_ID"
  }
}

Get report details

Using a report ID, you can query the Report node to get report details for a single report. Important details to note include the download {url} and status:

Report

Query

query Report($id: ID!) {
  node(id: $id) {
    ... on Report {
      __typename
      id
      status
      reportType
      download {
        url
      }
      createdAt
      updatedAt
    }
  }
}

Variables

{
  "id": "rptjb_02"
}

⚠️ Please login to execute queries. Visit the dashboard to authenticate.

Result

{
  "data": {
    "node": {
      "__typename": "Report",
      "id": "rptjb_02",
      "status": "COMPLETED",
      "reportType": "CARD_TRANSACTION_ACTIVITY",
      "download": {
        "url": "https://download.us.highnote.com/rptjb_b826e41aefc147b79be9c08f1f7952fa"
      },
      "createdAt": "2023-06-21T17:30:07.196Z",
      "updatedAt": "2023-06-21T17:30:49.348Z"
    }
  },
  "extensions": {
    "requestId": "REQUEST_ID"
  }
}

List reports

To list all existing reports and their details, query the Reports object. You can filter the query by reportType and status to narrow down results if necessary.

Use the following query to list reports:

Reports

Query

query Reports($first: Int, $after: String, $input: ReportFilterInput) {
  reports(first: $first, after: $after, filterBy: $input) {
    ... on ReportConnection {
      edges {
        ... on ReportEdge {
          node {
            __typename
            id
            status
            reportType
            download {
              url
            }
            createdAt
            updatedAt
          }
        }
      }
      pageInfo {
        hasNextPage
        hasPreviousPage
        startCursor
        endCursor
      }
    }
  }
}

Variables

{
  "input": {
    "status": {
      "includes": [
        "COMPLETED"
      ]
    },
    "reportType": {
      "includes": [
        "CARD_TRANSACTION_ACTIVITY"
      ]
    }
  }
}

⚠️ Please login to execute queries. Visit the dashboard to authenticate.

Result

{
  "data": {
    "reports": {
      "edges": [
        {
          "node": {
            "__typename": "Report",
            "id": "rptjb_02",
            "status": "COMPLETED",
            "reportType": "CARD_TRANSACTION_ACTIVITY",
            "download": {
              "url": "https://download.us.highnote.com/rptjb_105f3fc4683c4c74ab8f1ab009af4c26"
            },
            "createdAt": "2023-07-05T22:36:32.081Z",
            "updatedAt": "2023-07-05T22:36:52.894Z"
          }
        },
        {
          "node": {
            "__typename": "Report",
            "id": "rptjb_03",
            "status": "COMPLETED",
            "reportType": "CARD_TRANSACTION_ACTIVITY",
            "download": {
              "url": "https://download.us.highnote.com/rptjb_c390e0d3483b4f3697d57621dcf855fa"
            },
            "createdAt": "2023-07-05T22:55:34.899Z",
            "updatedAt": "2023-07-05T22:55:39.457Z"
          }
        }
      ],
      "pageInfo": {
        "hasNextPage": true,
        "hasPreviousPage": false,
        "startCursor": "dD0yMDIzLTA3LTA1VDIyJTNBMzYlM0E1Mi45MDc3OTYwMDBaJmk9cnB0amJfMTA1ZjNmYzQ2ODNjNGM3NGFiOGYxYWIwMDlhZjRjMjY",
        "endCursor": "dD0yMDIzLTA3LTA1VDIyJTNBNTUlM0EzOS40NjY3MzEwMDBaJmk9cnB0amJfYzM5MGUwZDM0ODNiNGYzNjk3ZDU3NjIxZGNmODU1ZmE"
      }
    }
  },
  "extensions": {
    "requestId": "REQUEST_ID"
  }
}

Download a report

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.

Authorization

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

Download report API

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