Home / Basics / Highnote API
Highnote Query Language
The Highnote Query Language (HQL) lets you quickly search across Highnote API entities.
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_0001' |
!= | Not Equal to | accountId != 'ac_0001' |
> | 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_0001', 'ac_0002) |
NOT IN | Returns entities that do not match any value in list | accountId NOT IN ('ac_0001', 'ac_0002) |
AND | Both sides of expression are valid | transactionAmount > USD 100 AND accountId = ‘ac_0001’ |
OR | Either side of expression is valid | accountId = ‘ac_0001’ OR accountId = ‘ac_0002’ |
( ) | Groups search terms together | last4 = 1234 AND (accountId = ‘ac_0001’ OR accountId = ‘ac_0002’) |
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 Financial Account features | activeFeatures='DIRECT_DEPOSIT' |
| primaryAccountHolder | Primary account holder of the Financial Account | ps_ah01 |
| primaryAccountAccountHolder | Account Id of the primary user | ac_0002 |
| primaryAccountHolderAccount | If authorized user, Account Id of the primary user account; else Account Id of the primary user | ps_ah02 |
| customField | Custom fields linked to Financial Account. Must be an exact match. | customField='myCustomField:myCustomValue' |
| accountStatus | Status of a Financial Account | |
| 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 |
Returns TransactionSearchResult, which is a Union of:
AuthorizationAndClearEvent | AuthorizationEvent | BalanceInquiryEvent | CheckPayment | ClearingEvent | CreditFunds | CreditFundsACHTransferEvent | DebitFunds | DebitFundsACHTransferEvent | DisbursementTransferEvent | EnhancedDataEvent | ExternallyInitiatedWireTransfer | IntegratorInitiatedFundsDepositACHTransfer | IntegratorInitiatedFundsDepositACHTransferEvent | IntegratorInitiatedFundsWithdrawalACHTransfer | IntegratorInitiatedFundsWithdrawalACHTransferEvent | InterFinancialAccountTransfer | InterFinancialAccountTransferEvent | IssuerPreliminaryAuthorizationEvent | ManualAdjustmentEvent | NonOriginatedAchTransfer | OriginatedAchTransfer | PayrollACHTransferEvent | PayrollTransfer | ReversalEvent | SecureCardBalanceRepaymentACHTransfer | SecureCardBalanceRepaymentACHTransferEvent | SecureDeposit | SecureDepositACHTransfer | SecureDepositACHTransferEvent | SecureDepositTransferEvent | Transfer | VerificationEvent | WireTransfer
| 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, acquiringPayment | 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 | 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 | Merchant Category Code | 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 mutation to list card product accounts, and then search by createdAt date.