Custom Fields for Metadata
Overview
For compliance and security reasons, do not use custom fields to store PCI or PII data.
Financial account and payment card objects implement custom fields that let you to add key-value pairs to the object.
CustomFields Object
Each Highnote CustomFields object is a set of key-value pairs stored and returned in plain text. It includes a creation date and an updated date.
Limits are:
- You are allowed a maximum of 20
CustomFieldsobjects. - Each key is an alphanumeric string with a maximum of 40 characters.
- Each value is an alphanumeric string with a maximum of 255 characters.
Use Cases
Use cases for using custom fields include:
- Linking IDs in your system with Highnote data
- Marking notes on Highnote data
- Adding a nickname to a card
- Tagging an account with the application ID
- Searching for objects relating to a customer in your system
Query custom fields
You can use the following node query to find customFields on a financial account:
Node
Query
query Node($id: ID!) {
node(id: $id) {
__typename
... on FinancialAccount {
__typename
id
customFields {
key
... on CustomStringField {
value
}
}
}
}
}
Variables
{
"id": "FINANCIAL_ACCOUNT_ID"
}
Result
{
"data": {
"issueFinancialAccountForApplication": {
"__typename": "FinancialAccount",
"id": "FINANCIAL_ACCOUNT_ID",
"customFields": [
{
"key": "customerGroupId",
"value": "group_123"
},
{
"key": "customerId",
"value": "customer_123"
}
]
}
},
"extensions": {
"requestId": "REQUEST_ID",
"rateLimit": {
"cost": 11
}
}
}
Search multiple objects
You can also use a nodeByCustomFields query with a CustomFieldsFilter to look up multiple objects and their custom fields. Use the following query to search multiple objects:
getFinancialAccountsForApplication
Query
query getFinancialAccountsForApplication(
$applicationId: ID!
$first: Int
$filterBy: AccountHolderFinancialAccountsFilterInput
) {
node(id: $applicationId) {
... on AccountHolderCardProductApplication {
id
financialAccounts(first: $first, filterBy: $filterBy) {
edges {
node {
id
customFields {
__typename
... on CustomStringField {
key
value
}
}
}
}
}
}
}
}
Variables
{
"applicationId": "FINANCIAL_ACCOUNT_ID",
"first": 10,
"filterBy": {
"customFields": {
"equals": {
"key": "customField1",
"value": "customValue1"
}
}
}
}
Result
{
"data": {
"node": {
"id": "CARD_PRODUCT_APPLICATION_ID",
"financialAccounts": {
"edges": [
{
"node": {
"id": "FINANCIAL_ACCOUNT_ID",
"customFields": [
{
"__typename": "CustomStringField",
"key": "customerGroupId",
"value": "group_123"
},
{
"__typename": "CustomStringField",
"key": "customerId",
"value": "customer_123"
}
]
}
}
]
}
}
},
"extensions": {
"requestId": "REQUEST_ID",
"rateLimit": {
"cost": 13
}
}
}
Filters
In addition to using the customFields filter to search multiple objects, you can use the following filters to refine your search results:
Accepts one input
Accepts one or more inputs
Example 1: Equals
The following code snippet provides an example of using the equals filter in your query input:
Input variable for equals filter
{
"applicationId": "CARD_PRODUCT_APPLICATION_ID",
"first": 10,
"filterBy": {
"customFields": {
"equals": {
"key": "customerId",
"value": "custom_123"
}
}
}
}
Example 2: Not equals
The following code snippet provides an example of using the notEquals filter in your query input:
Input variable for notEquals filter
{
"applicationId": "CARD_PRODUCT_APPLICATION_ID",
"first": 10,
"filterBy": {
"customFields": {
"notEquals": {
"key": "customerId",
"value": "custom_123"
}
}
}
}
Example 3: Includes
The following code snippet provides an example of using the includes filter in your query input:
Input variable for includes filter
{
"applicationId": "CARD_PRODUCT_APPLICATION_ID",
"first": 10,
"filterBy": {
"customFields": {
"includes": [
{
"key": "customerId",
"value": "custom_123"
},
{
"key": "customerId4",
"value": "custom_456"
}
]
}
}
}
Example 4: Excludes
The following code snippet provides an example of using the excludes filter in your query input:
Input variable for excludes filter
{
"applicationId": "CARD_PRODUCT_APPLICATION_ID",
"first": 10,
"filterBy": {
"customFields": {
"excludes": [
{
"key": "customerId",
"value": "customer_123"
},
{
"key": "regionId",
"value": "region_123"
}
]
}
}
}
Create custom fields for new object
Currently, objects that support custom fields are FinancialAccount and PaymentCard.
You can create custom fields when creating a new object that supports customFields.
The following mutation provides an example of creating a FinancialAccount with customFields key-value pairs entered as input variables:
IssueFinancialAccountForApplication
Query
mutation IssueFinancialAccountForApplication(
$input: IssueFinancialAccountForApplicationInput!
) {
issueFinancialAccountForApplication(input: $input) {
... on FinancialAccount {
__typename
id
customFields {
key
... on CustomStringField {
value
}
}
}
... on UserError {
__typename
errors {
errorPath
code
description
}
}
}
}
Variables
{ "input": { "applicationId": "CARD_PRODUCT_APPLICATION_ID", "name": "Test Account", "customFields": [ { "key": "customerId", "value": "customer_123" }, { "key": "customerGroupId", "value": "group_123" } ] } }
Result
{
"data": {
"issueFinancialAccountForApplication": {
"__typename": "FinancialAccount",
"id": "CARD_PRODUCT_APPLICATION_ID",
"customFields": [
{
"key": "customerGroupId",
"value": "group_123"
},
{
"key": "customerId",
"value": "customer_123"
}
]
}
},
"extensions": {
"requestId": "REQUEST_ID",
"rateLimit": {
"cost": 11
}
}
}
Update custom fields of existing object
Setting a key-value pair's value to empty will delete the key.
You can add, update, or delete customFields of an existing object with the UpdateCustomField mutation and by referencing key-value pairs explicitly as input variables.
Example 1: Add fields
The following example uses the UpdateCustomFields mutation to add multiple customFields key-value pairs to an existing object:
AddCustomFields
Query
mutation UpdateCustomFields($input: UpdateCustomFieldsInput!) {
updateCustomFields(input: $input) {
... on CustomFieldsResult {
customFields {
key
... on CustomStringField {
value
}
}
}
... on UserError {
errors {
errorPath
code
description
}
}
}
}
Variables
{ "input": { "id": "FINANCIAL_ACCOUNT_ID", "customFields": [ { "key": "regionId", "value": "region_123" }, { "key": "customerGroupId", "value": "group_123" }, { "key": "customerId", "value": "customer_123" } ] } }
Result
{
"data": {
"updateCustomFields": {
"customFields": [
{
"key": "regionId",
"value": "region_123"
},
{
"key": "customerGroupId",
"value": "group_123"
},
{
"key": "customerId",
"value": "customer_123"
}
]
}
},
"extensions": {
"requestId": "REQUEST_ID",
"rateLimit": {
"cost": 11
}
}
}
Example 2: Add, update, delete fields
UpdateCustomFields
Query
mutation UpdateCustomFields($input: UpdateCustomFieldsInput!) {
updateCustomFields(input: $input) {
... on CustomFieldsResult {
customFields {
key
... on CustomStringField {
value
}
}
}
... on UserError {
errors {
errorPath
code
description
}
}
}
}
Variables
{ "input": { "id": "ac_c022940900e3a34f44bf88c952087cfa8b93", "customFields": [ { "key": "regionId", "value": "" }, { "key": "customerGroupId", "value": "group_456" }, { "key": "sectorId", "value": "sector_123" } ] } }
Result
{
"data": {
"updateCustomFields": {
"customFields": [
{
"key": "customerId",
"value": "customer_123"
},
{
"key": "customerGroupId",
"value": "group_456"
},
{
"key": "sectorId",
"value": "sector_123"
}
]
}
},
"extensions": {
"requestId": "316817c8-ef45-9d2e-a376-92420a136352",
"rateLimit": {
"cost": 11
}
}
}
Delete custom fields
You can use the following mutation to delete all customFields for an object without having to specify the keys explicitly:
DeleteCustomFields
Query
mutation DeleteCustomFields($input: DeleteCustomFieldsInput!) {
deleteCustomFields(input: $input) {
... on CustomFieldsResult {
customFields {
key
... on CustomStringField {
value
}
}
}
... on UserError {
errors {
errorPath
code
description
}
}
}
}
Variables
{ "input": { "id": "FINANCIAL_ACCOUNT_ID" } }
Result
{
"data": {
"deleteCustomFields": {
"customFields": []
}
},
"extensions": {
"requestId": "REQUEST_ID",
"rateLimit": {
"cost": 11
}
}
}