Entity IDs and Object Types
Every Node in the Highnote API has a globally unique ID. Treat IDs as opaque strings you pass back to Highnote, not as structured data to parse.
Every entity ID starts with a short prefix that indicates its type, followed by a hash value. But prefixes can change, so you should not treat them as a stable contract.
Throughout this documentation set, angle-bracketed placeholder text in all caps stands in for real values. For example:
| Entity | Prefix | Placeholder in Docs |
|---|---|---|
| FinancialAccount | ac_a1b2c3... | <FINANCIAL_ACCOUNT_ID> |
| PaymentCard | cd_a1b2c3... | <PAYMENT_CARD_ID> |
| CardProduct | pd_a1b2c3... | <CARD_PRODUCT_ID> |
Identify types with __typename
For programmatic type identification, use the __typename field — it is available on every object in the Highnote API and matches the GraphQL type name exactly:
query {
node(id: "ac_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6") {
__typename
id
}
}
{
"data": {
"node": {
"__typename": "FinancialAccount",
"id": "ac_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6"
}
}
}
Documentation placeholders
Interactive examples throughout the documentation use angle-bracketed placeholders to stand in for real values. Anything wrapped in <...> is a placeholder you replace with your own data before sending a request, or a stand-in for the opaque value Highnote returns in a response.
{
"variables": {
"financialAccountId": "<FINANCIAL_ACCOUNT_ID>"
}
}
The placeholder naming follows a few consistent conventions.
Entity ID placeholders
Entity ID placeholders use the entity name in UPPER_SNAKE_CASE with an _ID suffix:
<FINANCIAL_ACCOUNT_ID>→ replace with a real FinancialAccount ID (e.g.,ac_...)<PAYMENT_CARD_ID>→ replace with a real PaymentCard ID (e.g.,cd_...)<CARD_PRODUCT_ID>→ replace with a real CardProduct ID (e.g.,pd_...)
When an example has multiple IDs of the same entity type, the placeholder gets a numeric suffix to distinguish them:
{
"edges": [
{ "node": { "id": "<FINANCIAL_ACCOUNT_ID_1>" } },
{ "node": { "id": "<FINANCIAL_ACCOUNT_ID_2>" } }
]
}
Values you provide
Customer-provided values — IDs you generate or assign in your own systems — use a YOUR_ prefix:
<YOUR_EXTERNAL_ID>— an external ID you set on a Highnote entity to reference it in your own system<YOUR_MERCHANT_ID>— an identifier you assign to a merchant in your system<YOUR_IDEMPOTENCY_KEY>— a UUID you generate for idempotency<YOUR_CUSTOMER_ID>— an identifier you assign to an end-user<YOUR_FINICITY_CUSTOMER_ID>— your Finicity partner-issued customer ID
Opaque tokens and generated values
Some values are opaque tokens or platform-generated identifiers that behave differently from entity IDs. These use descriptive names without the _ID suffix:
<DIGITAL_WALLET_TOKEN>— a digital wallet token (Apple Pay, Google Pay, etc.)<PAYMENT_METHOD_TOKEN>— a tokenized payment method<CURSOR>— a pagination cursor used withafter:andbefore:arguments<REQUEST_ID>— a Highnote-generated request trace ID returned in theextensionsfield of every response
Interfaces and unions
Some placeholders refer to GraphQL interfaces or unions with multiple concrete types. When an example includes the __typename field, the placeholder name matches the concrete type. When no __typename is shown, the placeholder uses the interface or umbrella name.
Country-specific prefixes like US are dropped from placeholder names because the placeholder convention should remain stable if Highnote expands to other regions. For example, USBusinessAuthorizedPerson becomes <BUSINESS_AUTHORIZED_PERSON_ID>, and USPersonAccountHolder becomes <PERSON_ACCOUNT_HOLDER_ID>.
For example, TransactionEvent is an interface with many concrete event types (AuthorizationEvent, ClearingEvent, AdjustmentEvent, etc.). An example that queries __typename might show <AUTHORIZATION_EVENT_ID>, while a response that omits __typename shows <TRANSACTION_EVENT_ID> to indicate "any event in the interface."
Placeholder reference
The table below maps each placeholder used in documentation examples to its underlying GraphQL type. Placeholders for interfaces and unions include the concrete subtypes in the Variations column.
| Placeholder | Entity | Variations |
|---|---|---|
<ACCOUNT_HOLDER_APPLICATION_DOCUMENT_ID> | AccountHolderApplicationDocument | |
<ACCOUNT_HOLDER_CARD_PRODUCT_APPLICATION_ID> | AccountHolderCardProductApplication | |
<ACCOUNT_HOLDER_CARD_PRODUCT_APPLICATION_OFFER_ID> | AccountHolderCardProductApplicationOffer | |
<ACCOUNT_HOLDER_PROVISIONING_ID> | AccountHolderProvisioning | |
<ACCOUNT_HOLDER_PROVISIONING_WORKFLOW_ACTION_ID> | AccountHolderProvisioningWorkflowAction | |
<ACCOUNT_HOLDER_RISK_SCORE_ID> | AccountHolderRiskScore | |
<ACH_TRANSFER_ID> | AchTransfer | OriginatedAchTransfer, NonOriginatedAchTransfer |
<APPLICATION_CONTRACT_ID> | ApplicationContract | |
<AUTHORIZED_PERSON_ID> | AuthorizedPerson (any subtype when __typename is not specified) | USBusinessAuthorizedPerson, USPersonAuthorizedUser |
<AUTHORIZED_USER_CARD_PRODUCT_APPLICATION_ID> | AuthorizedUserCardProductApplication | |
<BUSINESS_ACCOUNT_HOLDER_ID> | USBusinessAccountHolder | |
<BUSINESS_AUTHORIZED_PERSON_ID> | USBusinessAuthorizedPerson | |
<BUSINESS_PROFILE_ID> | USBusinessProfile | |
<BUSINESS_ULTIMATE_BENEFICIAL_OWNER_ID> | USBusinessUltimateBeneficialOwner | |
<CARD_PAYMENT_DISPUTE_ID> | CardPaymentDispute | |
<CARD_PRODUCT_APPLICATION_ID> | CardProductApplication (any subtype when __typename is not specified) | AccountHolderCardProductApplication, AuthorizedUserCardProductApplication |
<CARD_PRODUCT_ID> | CardProduct | |
<CARD_PROFILE_SET_ID> | CardProfileSet | |
<CATALOG_ITEM_ID> | CatalogItem | |
<CHECK_PAYMENT_EVENT_ID> | CheckPaymentEvent | |
<CHECK_PAYMENT_ID> | CheckPayment | |
<COLLABORATIVE_AUTHORIZATION_ENDPOINT_ID> | CollaborativeAuthorizationEndpoint | |
<CREDIT_CARD_TRANSFER_EVENT_ID> | CreditCardTransferEvent | |
<CREDIT_LIMIT_CHANGE_REQUEST_ID> | CreditLimitChangeRequest | |
<CREDIT_PLAN_ID> | CreditPlan | |
<CREDIT_PLAN_TEMPLATE_ID> | CreditPlanTemplate | |
<CURSOR> | Pagination cursor (opaque string) | |
<DIGITAL_CARD_PROFILE_ID> | DigitalCardProfile | |
<DIGITAL_WALLET_TOKEN> | CardDigitalWalletToken | |
<DIRECT_DEPOSIT_DETAIL_ID> | DirectDepositDetail | |
<DISBURSEMENT_TRANSFER_EVENT_ID> | DisbursementTransferEvent | |
<DOCUMENT_UPLOAD_LINK_ID> | DocumentUploadLink | |
<DOCUMENT_UPLOAD_SESSION_ID> | DocumentUploadSession | |
<ENHANCED_DATA_EVENT_ID> | EnhancedDataEvent | |
<EXTERNAL_FINANCIAL_BANK_ACCOUNT_ID> | ExternalFinancialBankAccount | |
<EXTERNAL_MONEY_MOVEMENT_TRANSACTION_EVENT_ID> | ExternalMoneyMovementTransactionEvent | |
<EXTERNAL_MONEY_MOVEMENT_TRANSACTION_ID> | ExternalMoneyMovementTransaction | |
<EXTERNAL_PHYSICAL_PAYMENT_CARD_ORDER_ID> | ExternalPhysicalPaymentCardOrder | |
<FEE_CHARGE_RULE_COUNT_CONDITION_ID> | FeeChargeRuleCountCondition | |
<FEE_CHARGE_RULE_ID> | FeeChargeRule | |
<FEE_CONFIGURATION_ID> | FeeConfiguration | |
<FEE_SCHEDULE_ID> | FeeSchedule | |
<FEE_TRANSFER_EVENT_ID> | FeeTransferEvent | |
<FINANCIAL_ACCOUNT_ID> | FinancialAccount | |
<FINANCIAL_ACCOUNT_SNAPSHOT_ID> | FinancialAccountSnapshot | |
<FINANCIAL_ACCOUNT_STATEMENT_ID> | FinancialAccountStatement | Product-specific statement types (Consumer/Commercial × Credit/Prepaid/Charge) |
<GLOBAL_NOTE_ID> | GlobalNote | |
<INSTALLMENT_AGREEMENT_ID> | InstallmentAgreement | |
<INSTANT_NETWORK_TRANSFER_EVENT_ID> | InstantNetworkTransferEvent | |
<INSTANT_NETWORK_TRANSFER_ID> | InstantNetworkTransfer | |
<INTER_FINANCIAL_ACCOUNT_TRANSFER_EVENT_ID> | InterFinancialAccountTransferEvent | |
<INTER_FINANCIAL_ACCOUNT_TRANSFER_ID> | InterFinancialAccountTransfer | |
<LEDGER_ENTRY_ID> | LedgerEntry | CreditLedgerEntry, DebitLedgerEntry |
<MASTERCARD_FLEET_AUTHORIZATION_DATA_ID> | MastercardFleetAuthorizationData | |
<MERCHANT_ACCEPTOR_ID> | MerchantAcceptor | |
<NOTIFICATION_EVENT_ID> | NotificationEvent | |
<ORGANIZATION_ID> | Organization | |
<PAYMENT_CARD_ID> | PaymentCard | |
<PAYMENT_CARD_SNAPSHOT_ID> | PaymentCardSnapshot | |
<PAYMENT_CARD_TRANSACTION_CHARGEBACK_ID> | PaymentCardTransactionChargeback | |
<PAYMENT_CARD_TRANSACTION_DISPUTE_ID> | PaymentCardTransactionDispute | |
<PAYMENT_METHOD_TOKEN> | PaymentMethodToken | |
<PAYMENT_ORDER_ID> | PaymentOrder | |
<PAYMENT_TRANSACTION_SUMMARY_ID> | PaymentTransactionSummary | PaymentDebitTransactionSummary, PaymentCreditTransactionSummary |
<PAYMENT_TRANSACTION_ID> | PaymentTransaction | PaymentDebitTransaction, PaymentCreditTransaction |
<PERSON_ACCOUNT_HOLDER_ID> | USPersonAccountHolder | |
<PERSON_AUTHORIZED_USER_ID> | USPersonAuthorizedUser | |
<PHYSICAL_CARD_GROUP_ORDER_ID> | PhysicalCardGroupOrder | |
<PHYSICAL_PAYMENT_CARD_ORDER_ID> | PhysicalPaymentCardOrder | |
<PRODUCT_APPLICATION_ID> | ProductApplication | |
<REPORT_ID> | Report | |
<REQUESTED_IDENTITY_UPDATE_ID> | RequestedIdentityUpdate | |
<REQUEST_ID> | Highnote-generated request trace ID (returned in extensions) | |
<REVIEW_WORKFLOW_EVENT_ID> | ReviewWorkflowEvent | |
<REWARD_EARN_RULE_ID> | RewardEarnRule | RewardMerchantCategoryEarnRule, RewardDefaultEarnRule |
<REWARD_POINTS_TRANSFER_ID> | RewardPointsTransfer | |
<REWARD_REDEMPTION_CONFIGURATION_ID> | RewardRedemptionConfiguration | |
<RTP_TRANSFER_EVENT_ID> | RtpTransferEvent | OriginatedRtpTransferEvent, NonOriginatedRtpTransferEvent |
<RTP_TRANSFER_ID> | RtpTransfer | OriginatedRtpTransfer, NonOriginatedRtpTransfer |
<SCHEDULED_TRANSFER_EVENT_ID> | ScheduledTransferEvent | |
<SCHEDULED_TRANSFER_ID> | ScheduledTransfer | |
<SIGNING_KEY_ID> | SigningKey | |
<SPEND_RULE_ID> | SpendRule | Concrete subtypes: AmountLimitSpendRule, MerchantCategorySpendRule, CVVSpendRule, and others |
<TRANSACTION_EVENT_ID> | TransactionEvent | Concrete subtypes: AuthorizationEvent, ClearingEvent, AdjustmentEvent, ReversalEvent, and others |
<TRANSACTION_ID> | Transaction | Concrete subtypes: DebitTransaction, CreditTransaction |
<TRANSFER_ID> | Transfer | |
<UNIFIED_FUNDS_TRANSFER_ID> | UnifiedFundsTransfer | |
<UNIFIED_FUNDS_TRANSFER_QUOTE_ID> | UnifiedFundsTransferQuote | |
<UNIFIED_FUNDS_TRANSFER_STEP_ID> | UnifiedFundsTransferStep | UnifiedFundsTransferInitiateRequestStep, UnifiedFundsTransferInstantNetworkTransferStep, UnifiedFundsTransferRtpStep |
<USER_ID> | User | |
<USER_DEFINED_FIELD_DEFINITION_ID> | UserDefinedFieldDefinition | |
<USER_DEFINED_FIELD_ID> | UserDefinedField | |
<VALIDATED_ADDRESS_ID> | ValidatedAddress | |
<VELOCITY_RULE_ID> | VelocityRule | |
<VISA_FLEET_AUTHORIZATION_DATA_ID> | VisaFleetAuthorizationData | |
<WEBHOOK_NOTIFICATION_TARGET_ID> | WebhookNotificationTarget | |
<WIRE_TRANSFER_ID> | WireTransfer | |
<YOUR_CUSTOMER_ID> | Customer-provided end-user identifier | |
<YOUR_EXTERNAL_ID> | Customer-provided external ID on a Highnote entity | |
<YOUR_FINICITY_CUSTOMER_ID> | Customer-provided Finicity partner customer ID | |
<YOUR_IDEMPOTENCY_KEY> | Customer-generated idempotency key (UUID) | |
<YOUR_MERCHANT_ID> | Customer-assigned merchant identifier |