Home / Basics / Highnote API
Highnote Query Language
The Highnote Query Language (HQL) v.1.0.0 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:
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.
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'.
| 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') |
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 |
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 | |
| contractId | Optional contract ID for this transaction. If not provided, the default contract ID is used. | |
| transferId | Unique ID of the transfer |
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 internalAccountTransfer, wireTransfer, manualAdjustment, achTransfer, cardTransaction, checkPayment, disbursement, aquiringPayment | 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 values 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 |
Use the following query to list card product accounts, and then search by createdAt date.