Highnote Query Language
Overview
The Highnote Query Language (HQL) provides programmatic search capabilities across Highnote entities using SQL-like syntax through the GraphQL API.
Specifically, HQL enables complex searches that would normally require multiple standard GraphQL requests:
| Search Type | Example |
|---|---|
| Cross-field conditions | transactionAmount > USD 500 AND createdAt >= '2024-01-01' |
| List operations | accountId IN ('ac_ba22446a041287274d81af25bb83eeba46b1', 'ac_c022126bc2bb629545a988564e267d8982a5') |
| Custom metadata | customField='riskLevel:high' |
| Logical grouping | (accountStatus = 'ACTIVE' OR accountStatus = 'PENDING') AND productId = 'pd_4644868cd7b749fa82a4149d46d9827d' |
The API processes HQL queries through three main search contexts: Financial Accounts, Payment Transactions (acquiring), and Universal Transactions (issuing), each exposing context-specific searchable fields alongside common attributes.
HQL operates through the searchQueryLanguage field within GraphQL filterBy inputs:
{
filterBy: {
searchQueryLanguage: {
query: "transactionAmount > USD 100 AND accountStatus = 'ACTIVE'",
version: "VERSION_1"
}
}
}
Limitations
HQL takes precedence
HQL is a standalone filter system that uses the searchQueryLanguage field within filterBy inputs.
If provided with other standard filters, HQL takes precedence and the other filters are ignored.
Minimum API version: The minimum supported Search API version is VERSION_1.
Rate limits: See API Rate Limiting for details.
Search latency: Highnote’s Search API has a latency period of up to two minutes.
HQL Conventions
The Highnote Query Language uses the following conventions:
- A term is a keyword used to search on attributes related to an entity.
- An expression is
<term><operator><value>. For example,transactionAmount > USD 100. - A value with special characters must be escaped with single quotes. For example, Highnote identifiers include an underscore and should be represented as
'ac_c022b9c66de3299c4f06a03293106c65234b'.
Operators
| Operator | Description | Example |
|---|---|---|
= | Equal to | accountId != 'ac_ba22446a041287274d81af25bb83eeba46b1' |
!= | Not Equal to | accountId != 'ac_ba22446a041287274d81af25bb83eeba46b1' |
> | Greater Than | transactionAmount > USD 100 |
>= | Greater Than or Equal To | transactionAmount >= USD 100 |
< | Less Than | transactionAmount < USD 100 |
<= | Less Than or Equal To | transactionAmount <= USD 100 |
IN | Returns entities that match any value in list | accountId IN ('ac_ba22446a041287274d81af25bb83eeba46b1', 'ac_c022126bc2bb629545a988564e267d8982a5') |
NOT IN | Returns entities that do not match any value in list | accountId NOT IN ('ac_og2234f70e5e4e384f1ca1f52b26aab8e7b5', 'ac_og22d44c3eb6e6f14929954ba278ffcd84ec) |
AND | Both sides of expression are valid | transactionAmount > USD 100 AND accountId = 'ac_ba22446a041287274d81af25bb83eeba46b1' |
OR | Either side of expression is valid | accountId = 'ac_ba22446a041287274d81af25bb83eeba46b1' OR accountId = 'ac_c022126bc2bb629545a988564e267d8982a5' |
( ) | Groups search terms together | last4 = 1234 AND (accountId = ‘ac_ba22446a041287274d81af25bb83eeba46b1’ OR accountId = 'ac_c022126bc2bb629545a988564e267d8982a5') |
Account Search
An account search applies to FinancialAccount attributes.
Returns FinancialAccount.
| Field | Description | Example |
|---|---|---|
| id (or accountId) | FinancialAccount | |
| productId | The Card Product associated to the Financial Account | |
| activeFeatures | The list of active features. Valid enum values: FinancialAccountFeatureType | activeFeatures='DIRECT_DEPOSIT' |
| primaryAccountHolder | Primary account holder of the Financial Account | ps_ah01 |
| primaryAccountAccountHolder | Account Id of the primary user | ac_c022126bc2bb629545a988564e267d8982a5 |
| primaryAccountHolderAccount | If authorized user, Account Id of the primary user account; else Account Id of the primary user | ps_ap0135e1c47a453c4656bb8da5fb2a60f976, |
| customField | Custom fields linked to Financial Account. Must be an exact match. | customField='myCustomField:myCustomValue' |
| accountStatus | Status of a Financial Account. Valid enum values: FinancialAccountStatus | |
| application | Application used to issue the Financial Account | |
| createdAt | Datetime (ISO 8601) the Financial Account was created |
Acquiring Search
An acquiring search applies to attributes of the following: PaymentTransaction, PaymentTransactionLifecycleStep, and PaymentTransactionEvent.
Returns PaymentTransaction.
| Field | Description | Example |
|---|---|---|
| id | Identifier of the PaymentTransaction | |
| transactionAmount | Amount of the transaction | |
| accountId | Financial Accounts linked to the Payment Transaction and corresponding Steps and Events | |
| cardholderEmail | Email associated with the cardholder of a Payment Transaction. Must be an exact match. | |
| cardholderName | Name associated with the cardholder of a Payment Transaction. Must be an exact match. | |
| authorizationIdentifier | ID of the authorization response code provided by the processor for this PaymentTransaction on a successful authorization | |
| last4 | Last 4 digits of the card used for the Payment Transaction | |
| orderId | Originating Payment Order that this transaction was initiated from | |
| merchantAcceptorId | Optional ID of the merchant location or terminal accepting the payment for this transaction. If not provided, the default merchantAcceptorId is used. | |
| transferId | Unique ID of the transfer |
Universal Transaction Search
A universal transaction search applies to normalized values related to the transaction types listed under type below, as well as attributes specific to individual transaction types.
UTS searches span both issuing and acquiring transactions.
UTS coverage
Universal Transaction Search does not cover every Issuing Transaction Type. Fee transfers, credit card transfers, reward point transfers, and crypto funding transfers are not searchable from this context.
Returns TransactionSearchResult.
| Field | Description | Applies To |
|---|---|---|
| id | Identifier of the transaction | All |
| transactionSearchStatus | A normalized value across all transaction types that represents whether a transaction is COMPLETED, PENDING, or FAILED. Dependent on the lifecycle of each transaction type. | All |
| transactionAmount | A normalized value that searches across all transaction types' amount values.. Ex: WireTransfer.amount, TransactionEvent.approvedAmount | All |
| transactionAmountCurrencyCode | Currency that the transaction was initiated with | All |
| transactionId | The parent transaction id, if applicable | All |
| accountHolderId | The AccountHolder that may be associated with a transaction. Multiple AccountHolders may be associated with a transaction. | All |
| transactionSearchType | Narrows down the search to either a TRANSACTION or EVENT. | All |
| type | Narrows down the search to a specific transaction type. Allowed values are interFinancialAccountTransfer, wireTransfer, manualAdjustment, achTransfer, cardTransaction, checkPayment, disbursement, acquiringPayment, instantNetworkTransaction, instantSettlementTransaction, realtimePaymentTransaction, accountReceivable | All |
| accountId | A FinancialAccount that may be associated with a transaction. Multiple FinancialAccounts can be associated with 1 transaction. | All |
| createdAt | When the transaction was created | All |
| actionDate | A normalized timestamp field that searches on the last updated date for a transaction. For example, within the lifecycle of a Transaction, searches on the latest createdAt of a TransactionEvent | All |
| completedAt | A normalized timestamp field that searches on when a transaction was completed, if applicable. For example, if a Transaction has gone through the entire payment lifecycle, completedAt can be used to search when the final TransactionEvent occurred. | All |
| productId | The CardProduct that is associated with a transaction. Multiple CardProducts may be associated with a transaction | All |
| last4 | The last 4 digits of the card used in the transaction | TransactionEvent types |
| cardProcessingType | The method or channel used to process the transaction. Valid enum values: cardProcessingType | TransactionEvent types |
| cardAcceptorIdentificationCode | Highnote assigned Merchant ID | TransactionEvent types |
| merchantName | Name of the merchant | TransactionEvent types |
| institutionName | Name of the institution | TransactionEvent types |
| merchantCategoryCode or mcc | Human friendly enums representing 4-digit ISO-18245 merchant category codes. Valid enum values: MerchantCategory | TransactionEvent types |
| cardAcceptorLocation | Geographic/address info about where the transaction took place | TransactionEvent types |
| transactionCountryCode | Country code where the transaction took place | TransactionEvent types |
| postedAmount | Final settled transaction amount charged to the cardholder's account | TransactionEvent types |
HQL Examples
Use the following mutation to list card product accounts, and then search by createdAt date.
query ListCardProductAccounts(
$id: ID!
$first: Int
$after: String
$filterBy: AccountHolderFinancialAccountsFilterInput
) {
node(id: $id) {
id
__typename
... on Organization {
accounts(first: $first, after: $after, filterBy: $filterBy) {
__typename
pageInfo {
hasNextPage
hasPreviousPage
startCursor
endCursor
}
edges {
node {
id
name
createdAt
updatedAt
accountStatus
accountAttributes
cardProduct {
id
}
cardProductApplication {
... on AccountHolderCardProductApplication {
accountHolderSnapshot {
... on USPersonAccountHolderSnapshot {
accountHolderCurrent {
id
name {
familyName
givenName
middleName
suffix
title
}
}
}
... on USBusinessAccountHolderSnapshot {
accountHolderCurrent {
id
businessProfile {
name {
legalBusinessName
doingBusinessAsName
}
}
}
}
}
}
}
owner {
... on USPersonAccountHolder {
id
name {
familyName
givenName
middleName
suffix
title
}
}
... on USBusinessAccountHolder {
id
businessProfile {
name {
legalBusinessName
doingBusinessAsName
}
}
}
... on Organization {
id
profile {
displayName
}
}
}
ledgers(ledgerNames: AVAILABLE_CASH) {
id
name
normalBalance
creditBalance {
value
currencyCode
decimalPlaces
}
debitBalance {
value
currencyCode
decimalPlaces
}
}
features {
enabled
... on SecuredCreditPaymentCardFinancialAccountFeature {
creditLimit {
currencyCode
decimalPlaces
value
}
}
... on FleetCardAccountFeature {
creditLimit {
currencyCode
decimalPlaces
value
}
}
... on CommercialCreditPayInFullCardAccountFeature {
creditLimit {
currencyCode
decimalPlaces
value
}
}
... on CreditCardAccountFeature {
creditLimit {
currencyCode
decimalPlaces
value
}
}
... on OnDemandFundingFinancialAccountFeature {
sourceFinancialAccount {
id
}
}
}
}
}
}
}
... on CardProduct {
accounts(first: $first, after: $after, filterBy: $filterBy) {
__typename
pageInfo {
hasNextPage
hasPreviousPage
startCursor
endCursor
}
edges {
node {
id
name
createdAt
updatedAt
accountStatus
accountAttributes
cardProductApplication {
... on AccountHolderCardProductApplication {
accountHolderSnapshot {
... on USPersonAccountHolderSnapshot {
accountHolderCurrent {
id
name {
familyName
givenName
middleName
suffix
title
}
}
}
... on USBusinessAccountHolderSnapshot {
accountHolderCurrent {
id
businessProfile {
name {
legalBusinessName
doingBusinessAsName
}
}
}
}
}
}
}
owner {
... on USPersonAccountHolder {
id
name {
familyName
givenName
middleName
suffix
title
}
}
... on USBusinessAccountHolder {
id
businessProfile {
name {
legalBusinessName
doingBusinessAsName
}
}
}
... on Organization {
id
profile {
displayName
}
}
}
ledgers(ledgerNames: AVAILABLE_CASH) {
id
name
normalBalance
creditBalance {
value
currencyCode
decimalPlaces
}
debitBalance {
value
currencyCode
decimalPlaces
}
}
features {
enabled
... on SecuredCreditPaymentCardFinancialAccountFeature {
creditLimit {
currencyCode
decimalPlaces
value
}
}
... on FleetCardAccountFeature {
creditLimit {
currencyCode
decimalPlaces
value
}
}
... on CommercialCreditPayInFullCardAccountFeature {
creditLimit {
currencyCode
decimalPlaces
value
}
}
... on CreditCardAccountFeature {
creditLimit {
currencyCode
decimalPlaces
value
}
}
... on OnDemandFundingFinancialAccountFeature {
sourceFinancialAccount {
id
}
}
}
}
}
}
}
}
}