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

info

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

Searches on normalized values related to all Issuing Transaction Types as well as attributes specific to individual Issuing Transaction Types.

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, aquiringPayment, instantNetworkTransfer	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
completeDate	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, completeDate 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
                }
              }
            }
          }
        }
      }
    }
  }
}