Skip to main content

Update Account Information

Overview​

This guide provides steps for updating account holder information using the Highnote API. To update in the Highnote Dashboard, see Manage account holders.

Account holder update notifications​

When account holder information is updated, Highnote may need to request documents to verify the account holder's identity. To automate your integration and stay notified of identity verification requests, subscribe to the following notification events:

When using an account holder identity documents request event, the DocumentUploadSession referenced by the event can be queried as a node using the IdentityVerificationDocumentUploadSession type, and can also be interacted with via existing mutations to startDocumentUploadSession, createDocumentUploadLink and endDocumentUploadSession. See Collect documents for identity verification.

Update person account holder​

info

For PENDING applications, contact support@highnote.com to request changes to account holder information. You cannot do this yourself.

You can use the Highnote API to update account holder address, phone number, and website.

To ensure compliance with Know Your Customer or Know Your Business (KYC-KYB), the Highnote team must update other account holder information such as Social Security Number (SSN), Employer Identification Number (EIN), date of birth, account holder name, etc.

Address​

Account holders have two billing addresses, one at the account holder level and another associated with an account holder's payment card. Refer to the following table for an overview of each billing address object:

ObjectDescriptionUse case
billingAddressThe account holder level billing addressUsed for KYC-KYB verification and mailing address if a separate mailing address is not set for the PaymentCardDeliveryDetails object
billingAddressOnCardThe billing address associated with an account holder's payment cardUsed for transaction authorization

When updating an account holder's address, you must update the billingAddress and billingAddressOnCard. Updating both addresses ensures data accuracy across account holder and payment card objects.

The updateUSPersonAccountHolder mutation uses the following input fields to update both addresses:

  • billingAddressInput: The account level billing address
  • accountHolderId: The global ID for the account holder
  • updatePaymentCardBillingAddress: Boolean field used to update the billingAddressOnCard; must set the value to true

When updating an account holder's address, note the following requirements:

  • The new address must be a US-based physical address and can’t be a PO box.
  • The full address must be provided with the update, even if only a partial update is needed. For example, if the street address changes and the zip code remains the same, the full address is still needed for the update.

Use the following mutation to update an account holder's billingAddress and billingAddressOnCard:

UpdateUSPersonAccountHolderBillingAddress​
Query
mutation updateUSPersonAccountHolder(
  $billingAddressInput: UpdateUSPersonAccountHolderBillingAddressInput!
) {
  updateUSPersonAccountHolderBillingAddress(input: $billingAddressInput) {
    __typename
    ... on UserError {
      errors {
        code
        description
        errorPath
        __typename
      }
      __typename
    }
  }
}
Variables
{
  "billingAddressInput": {
    "billingAddress": {
      "streetAddress": "444 Main Street",
      "postalCode": "60606",
      "locality": "Chicago",
      "region": "IL",
      "countryCodeAlpha3": "USA"
    },
    "accountHolderId": "ACCOUNT_HOLDER_ID",
    "updatePaymentCardBillingAddress": true
  }
}
⚠️ Please login to execute queries. Visit the dashboard to authenticate.
Result
{
  "data": {
    "updateUSPersonAccountHolderBillingAddress": {
      "__typename": "USPersonAccountHolder"
    }
  },
  "extensions": {
    "requestId": "REQUEST_ID",
    "rateLimit": {
      "cost": 11,
      "limit": 100,
      "remaining": 99989
    }
  }
}

Phone number​

When updating an account holder's phone number, note the following:

  • The new phone number must include the country code.
  • Only one phone number can be associated with an account holder.
  • Updating the account holder's phone number replaces the current one, regardless of the phone type in the update request. The account holder can only have a home or office phone number listed and not both.

Use the following query to update an account holder's phone number:

UpdateUSPersonAccountHolderPhone​
Query
mutation updateUSPersonAccountHolderPhone(
  $input: UpdateUSPersonAccountHolderPhoneInput!
) {
  updateUSPersonAccountHolderPhone(input: $input) {
    __typename
    ... on UserError {
      errors {
        code
        description
        errorPath
      }
    }

    ... on USPersonAccountHolder {
      id
      phoneNumbers {
        countryCode
        number
        label
      }
    }
  }
}
Variables
{
  "input": {
    "phoneNumber": {
      "countryCode": "1",
      "number": "234123444",
      "label": "MOBILE",
      "extension": "312"
    },
    "accountHolderId": "ACCOUNT_HOLDER_ID"
  }
}
⚠️ Please login to execute queries. Visit the dashboard to authenticate.
Result
{
  "data": {
    "updateUSPersonAccountHolderPhone": {
      "__typename": "USPersonAccountHolder",
      "phoneNumbers": {
        "countryCode": "1",
        "number": "234123444",
        "label": "MOBILE",
        "extension": "312"
      },
      "id": "ACCOUNT_HOLDER_ID"
    },
    "extensions": {
      "requestId": "REQUEST_ID"
    }
  }
}

Email​

When updating an account holder’s email, note the following:

  • The new email must be a valid email address.
  • We recommend you send an email to your account holder using the old email address to notify them of the email update and mitigate potential fraud risks.

Use the following query to update an account holder's email:

UpdateUSPersonAccountHolderEmail​
Query
mutation updateUSPersonAccountHolderEmail(
  $input: UpdateUSPersonAccountHolderEmailInput!
) {
  updateUSPersonAccountHolderEmail(input: $input) {
    __typename
    ... on UserError {
      errors {
        code
        description
        errorPath
      }
    }

    ... on USPersonAccountHolder {
      id
      email
    }
  }
}
Variables
{
  "input": {
    "email": "abc@123.com",
    "accountHolderId": "ACCOUNT_HOLDER_ID"
  }
}
⚠️ Please login to execute queries. Visit the dashboard to authenticate.
Result
{
  "data": {
    "updateUSPersonAccountHolderEmail": {
      "__typename": "USPersonAccountHolder",
      "id": "ACCOUNT_HOLDER_ID",
      "email": "abc@123.com"
    }
  },
  "extensions": {
    "requestId": "REQUEST_ID"
  }
}

Credit risk attributes​

You can update the credit risk attributes for a person account holder. These credit risk attributes include the following:

  • Annual income
  • Debt obligations
  • Employment status

Use the following mutation to update a person account holder's credit risk attributes:

UpdateUSPersonAccountHolderCreditRiskAttribute​
Query
mutation updateUSPersonAccountHolderCreditRiskAttribute(
  $input: UpdateUSPersonAccountHolderCreditRiskAttributeInput!
) {
  updateUSPersonAccountHolderCreditRiskAttribute(input: $input) {
    __typename
    ... on USPersonAccountHolder {
      id
      email
      dateOfBirth
      externalId
      updatedAt
      createdAt
      name {
        givenName
        familyName
        title
        suffix
        middleName
      }
      billingAddress {
        streetAddress
        extendedAddress
        postalCode
        region
        locality
        countryCodeAlpha3
      }
      phoneNumbers {
        countryCode
        number
        label
      }
      identificationDocument {
        socialSecurityNumber {
          numberHash
          countryCodeAlpha3
        }
      }
      personCreditRiskAttributes {
        totalAnnualIncome {
          value
          currencyCode
        }
        currentDebtObligations {
          value
          currencyCode
        }
        employmentStatus
      }
    }
    ... on UserError {
      errors {
        code
        description
        errorPath
      }
    }
  }
}
Variables
{
  "input": {
    "accountHolderId": "ACCOUNT_HOLDER_ID",
    "personCreditRiskAttributes": {
      "totalAnnualIncome": {
        "value": "2000",
        "currencyCode": "USD"
      },
      "currentDebtObligations": {
        "value": "2000",
        "currencyCode": "USD"
      },
      "employmentStatus": "EMPLOYEED"
    }
  }
}
⚠️ Please login to execute queries. Visit the dashboard to authenticate.
Result
{
  "data": {
    "updatePersonAccountHolderCreditRiskAttribute": {
      "__typename": "USPersonAccountHolder",
      "id": "ACCOUNT_HOLDER_ID",
      "email": "gerrytest1@abc.com",
      "dateOfBirth": "",
      "externalId": "EXTERNAL_ID",
      "updatedAt": "2023-07-29T15:08:15.304Z",
      "createdAt": "2023-07-29T15:06:08.626Z",
      "name": {
        "givenName": "",
        "familyName": "",
        "title": "",
        "suffix": "",
        "middleName": ""
      },
      "billingAddress": null,
      "phoneNumbers": [
        {
          "countryCode": "1",
          "number": "2222222222",
          "label": "MOBILE"
        }
      ],
      "identificationDocument": {
        "socialSecurityNumber": null
      },
      "personCreditRiskAttributes": {
        "totalAnnualIncome": [
          {
            "value": 2000,
            "currencyCode": "USD"
          }
        ],
        "currentDebtObligations": [
          {
            "value": 2000,
            "currencyCode": "USD"
          }
        ],
        "employmentStatus": "EMPLOYEED"
      }
    }
  },
  "extensions": {
    "requested": "REQUEST_ID",
    "rateLimit": {
      "cost": 15
    }
  }
}

Update business account holder​

info

For PENDING applications, contact support@highnote.com to request changes to account holder information. You cannot do this yourself.

You can let business account holders update their their address, phone number, and website. To ensure compliance with Know Your Customer or Know Your Business (KYC-KYB), the Highnote team must update other account holder information such as Social Security Number (SSN), Employer Identification Number (EIN), date of birth, account holder name, etc.

Address​

An account holder has two billing addresses, one at the account holder level and another associated with an account holder's payment card. Refer to the following table for an overview of each billing address object:

ObjectDescriptionUse case
billingAddressThe account holder level billing addressUsed for KYC-KYB verification and mailing address if a separate mailing address is not set for the PaymentCardDeliveryDetails object
billingAddressOnCardThe billing address associated with an account holder's payment cardUsed for transaction authorization

When updating an account holder's address, you must update the billingAddress and billingAddressOnCard. Updating both addresses ensures data accuracy across account holder and payment card objects.

The updateUSBusinessAccountHolder mutation uses the following input fields to update both addresses:

  • billingAddressInput: The account level billing address
  • accountHolderId: The global ID for the account holder
  • updatePaymentCardBillingAddress: Boolean field used to update the billingAddressOnCard; must set the value to true

When updating an account holder's address, note the following requirements:

  • The new address must be a US-based physical address and can’t be a PO box.
  • The full address must be provided with the update, even if only a partial update is needed. For example, if the street address changes and the zip code remains the same, the full address is still needed for the update.

Use the following mutation to update an account holder's billingAddress and billingAddressOnCard:

UpdateUSBusinessAccountHolderBillingAddress​
Query
mutation updateUSBusinessAccountHolder(
  $billingAddressInput: UpdateUSBusinessAccountHolderBillingAddressInput!
) {
  updateUSBusinessAccountHolderBillingAddress(input: $billingAddressInput) {
    __typename
    ... on UserError {
      errors {
        code
        description
        errorPath
        __typename
      }
      __typename
    }
  }
}
Variables
{
  "billingAddressInput": {
    "billingAddress": {
      "streetAddress": "444 Main Street",
      "postalCode": "60606",
      "locality": "Chicago",
      "region": "IL",
      "countryCodeAlpha3": "USA"
    },
    "accountHolderId": "ACCOUNT_HOLDER_ID",
    "updatePaymentCardBillingAddress": true
  }
}
⚠️ Please login to execute queries. Visit the dashboard to authenticate.
Result
{
  "data": {
    "updateUSBuisnessAccountHolderBillingAddress": {
      "__typename": "USBusinessAccountHolder"
    }
  },
  "extensions": {
    "requestId": "REQUEST_ID",
    "rateLimit": {
      "cost": 11,
      "limit": 100,
      "remaining": 99989
    }
  }
}

Phone number​

When updating an account holder's phone number, note the following:

  • The new phone number must include the country code.
  • Only one phone number can be associated with an account holder.
  • Updating the account holder's phone number replaces the current one, regardless of the phone type in the update request. For example, this means the account holder can only have a home or office phone number listed and not both.

Use the following query to update a business account holder's phone number:

UpdateUSBusinessAccountHolderPhone​
Query
mutation updateUSBusinessAccountHolderPhone(
  $input: UpdateUSBusinessAccountHolderPhoneInput!
) {
  updateUSBusinessAccountHolderPhone(input: $input) {
    __typename
    ... on USBusinessAccountHolder {
      id
      businessProfile {
        id
        phoneNumbers {
          countryCode
          number
          label
        }
      }
    }
    ... on UserError {
      errors {
        errorPath
        code
        description
      }
    }
  }
}
Variables
{
  "input": {
    "accountHolderId": "ACCOUNT_HOLDER_ID",
    "phoneNumber": {
      "countryCode": "1",
      "number": "4444444444",
      "label": "MOBILE"
    }
  }
}
⚠️ Please login to execute queries. Visit the dashboard to authenticate.
Result
{
  "data": {
    "updateUSBusinessAccountHolderPhone": {
      "__typename": "USBusinessAccountHolder",
      "id": "ACCOUNT_HOLDER_ID",
      "businessProfile": {
        "id": "BUSINESS_PROFILE_ID",
        "phoneNumbers": [
          {
            "countryCode": "1",
            "number": "4444444444",
            "label": "MOBILE"
          }
        ]
      }
    }
  },
  "extensions": {
    "requestId": "REQUEST_ID"
  }
}

Website​

Use the following query to update a business account holder's website URL:

UpdateUSBusinessAccountHolderWebsite​
Query
mutation updateUSBusinessAccountHolderWebsite(
  $input: UpdateUSBusinessAccountHolderWebsiteInput!
) {
  updateUSBusinessAccountHolderWebsite(input: $input) {
    __typename
    ... on USBusinessAccountHolder {
      id
      businessProfile {
        id
        website
      }
    }
    ... on UserError {
      errors {
        errorPath
        code
        description
      }
    }
  }
}
Variables
{
  "input": {
    "accountHolderId": "ACCOUNT_HOLDER_ID",
    "website": "https://highnote.com"
  }
}
⚠️ Please login to execute queries. Visit the dashboard to authenticate.
Result
{
  "data": {
    "updateUSBusinessAccountHolderWebsite": {
      "__typename": "USBusinessAccountHolder",
      "id": "ACCOUNT_HOLDER_ID",
      "website": "https://highnote.com"
    }
  },
  "extensions": {
    "requestId": "REQUEST_ID"
  }
}

Update business associated person​

Business account holders may need to update the information of the primary authorized person and/or beneficial owners. You can enable account holders to update the address, phone number, and email of the primary authorized person and/or beneficial owners. Other account holder information, such as Social Security Number (SSN), date of birth, or name, may need to be manually reviewed by an agent to ensure compliance with Know Your Customer (KYC) or Know Your Business (KYB).

Address​

When updating a business associated person's address, note the following requirements:

  • The new address must be a U.S. physical address and cannot be a PO box.
  • The full address must be provided with the update, even if only a partial update is needed. For example, if the street address changes and the zip code remains the same, the full address is still needed for the update.

Use the following query to update a business associated person's address:

UpdateUSAssociatedPersonAccountHolderHomeAddress​
Query
mutation updateUSAssociatedPersonAccountHolderHomeAddress(
  $input: UpdateUSAssociatedPersonAccountHolderHomeAddressInput!
) {
  updateUSAssociatedPersonAccountHolderHomeAddress(input: $input) {
    ... on USBusinessAuthorizedPerson {
      __typename
      id
      homeAddress {
        streetAddress
        extendedAddress
        postalCode
        region
        locality
        countryCodeAlpha3
      }
    }
    ... on UserError {
      __typename
      errors {
        errorPath
        code
        description
      }
    }
  }
}
Variables
{
  "input": {
    "accountHolderId": "BUSINESS_AUTHORIZED_PERSON_ACCOUNT_HOLDER_ID",
    "businessAccountHolderId": "BUSINESS_ACCOUNT_HOLDER_ID",
    "homeAddress": {
      "streetAddress": "444 Main Street",
      "postalCode": "60606",
      "locality": "Chicago",
      "region": "IL",
      "countryCodeAlpha3": "USA"
    }
  }
}
⚠️ Please login to execute queries. Visit the dashboard to authenticate.
Result
{
  "data": {
    "updateUSAssociatedPersonAccountHolderHomeAddress": {
      "__typename": "USBusinessAuthorizedPerson",
      "id": "BUSINESS_AUTHORIZED_PERSON_ACCOUNT_HOLDER_ID",
      "homeAddress": {
        "streetAddress": "444 Main Street",
        "postalCode": "60606",
        "locality": "Chicago",
        "region": "IL",
        "countryCodeAlpha3": "USA"
      }
    }
  },
  "extensions": {
    "requestId": "REQUEST_ID"
  }
}

Phone number​

When updating a business associated person's phone number, note the following:

  • The new phone number must include the country code.
  • Only one phone number can be associated with an account holder.
  • Updating the account holder’s phone number replaces the current one, regardless of the phone type in the update request. The account holder can only have a home or office phone number listed and not both.

Use the following query to update a business associated person's phone number:

UpdateUSAssociatedPersonAccountHolderPhone​
Query
mutation updateUSAssociatedPersonAccountHolderPhone(
  $input: UpdateUSAssociatedPersonAccountHolderPhoneInput!
) {
  updateUSAssociatedPersonAccountHolderPhone(input: $input) {
    ... on USBusinessAuthorizedPerson {
      __typename
      id
      phoneNumbers {
        countryCode
        number
        label
      }
    }
    ... on UserError {
      __typename
      errors {
        errorPath
        code
        description
      }
    }
  }
}
Variables
{
  "input": {
    "accountHolderId": "BUSINESS_AUTHORIZED_PERSON_ACCOUNT_HOLDER_ID",
    "businessAccountHolderId": "BUSINESS_ACCOUNT_HOLDER_ID",
    "phoneNumber": {
      "countryCode": "1",
      "number": "4444444444",
      "label": "MOBILE"
    }
  }
}
⚠️ Please login to execute queries. Visit the dashboard to authenticate.
Result
{
  "data": {
    "updateUSAssociatedPersonAccountHolderPhone": {
      "__typename": "USBusinessAuthorizedPerson",
      "id": "BUSINESS_AUTHORIZED_PERSON_ACCOUNT_HOLDER_ID",
      "phoneNumbers": [
        {
          "countryCode": "1",
          "number": "4444444444",
          "label": "MOBILE"
        }
      ]
    },
    "extensions": {
      "requestId": "REQUEST_ID"
    }
  }
}

Email​

When updating a business associated person's email, note the following:

  • The new email must be a valid email address.
  • We recommend you send an email to your account holder using the old email address to notify them of the email update and mitigate potential fraud risks.

Use the following query to update a business associated person's email:

UpdateUSAssociatedPersonAccountHolderEmail​
Query
mutation updateUSAssociatedPersonAccountHolderEmail(
  $input: UpdateUSAssociatedPersonAccountHolderEmailInput!
) {
  updateUSAssociatedPersonAccountHolderEmail(input: $input) {
    ... on USBusinessAuthorizedPerson {
      __typename
      id
      email
    }
    ... on UserError {
      __typename
      errors {
        errorPath
        code
        description
      }
    }
  }
}
Variables
{
  "input": {
    "accountHolderId": "BUSINESS_AUTHORIZED_PERSON_ACCOUNT_HOLDER_ID",
    "businessAccountHolderId": "BUSINESS_ACCOUNT_HOLDER_ID",
    "email": "bar@example.com"
  }
}
⚠️ Please login to execute queries. Visit the dashboard to authenticate.
Result
{
  "data": {
    "updateUSAssociatedPersonAccountHolderEmail": {
      "__typename": "USBusinessAuthorizedPerson",
      "id": "BUSINESS_AUTHORIZED_PERSON_ACCOUNT_HOLDER_ID",
      "email": "bar@example.com"
    }
  },
  "extensions": {
    "requestId": "REQUEST_ID"
  }
}

Update authorized user​

You can provide the ability for authorized users to update their address, phone number, and email. Other information, such as Social Security Number (SSN), date of birth, or name may need to be manually reviewed by a Highnote agent to ensure compliance with Know Your Customer (KYC) or Know Your Business (KYB).

Address​

When updating an authorized user's address, note the following requirements:

  • The new address must be a U.S. physical address and cannot be a PO box.
  • The full address must be provided with the update, even if only a partial update is needed. For example, if the street address changes and the zip code remains the same, the full address is still needed for the update.

Use the following query to update an authorized user's address:

UpdateUSPersonAuthorizedUserBillingAddress​
Query
mutation updateUSPersonAccountHolder(
  $billingAddressInput: UpdateUSPersonAccountHolderBillingAddressInput!
) {
  updateUSPersonAccountHolderBillingAddress(input: $billingAddressInput) {
    __typename
    ... on UserError {
      errors {
        code
        description
        errorPath
        __typename
      }
      __typename
    }
  }
}
Variables
{
  "billingAddressInput": {
    "billingAddress": {
      "streetAddress": "444 Main Street",
      "postalCode": "60606",
      "locality": "Chicago",
      "region": "IL",
      "countryCodeAlpha3": "USA"
    },
    "accountHolderId": "ACCOUNT_HOLDER_ID",
    "updatePaymentCardBillingAddress": true
  }
}
⚠️ Please login to execute queries. Visit the dashboard to authenticate.
Result
{
  "data": {
    "updateUSPersonAccountHolderBillingAddress": {
      "__typename": "USPersonAccountHolder"
    }
  },
  "extensions": {
    "requestId": "REQUEST_ID",
    "rateLimit": {
      "cost": 11,
      "limit": 100,
      "remaining": 99989
    }
  }
}

Phone number​

When updating an authorized user's phone number, note the following:

  • The new phone number must include the country code.
  • Only one phone number can be associated with an account holder.
  • Updating the authorized user’s phone number replaces the current one, regardless of the phone type in the update request. The account holder can only have a home or office phone number listed and not both.

Use the following query to update an authorized user's phone number:

UpdateUSPersonAuthorizedUserPhone​
Query
mutation updateUSPersonAuthorizedUserPhone(
  $input: UpdateUSPersonAuthorizedUserPhoneInput!
) {
  updateUSPersonAuthorizedUserPhone(input: $input) {
    __typename
    ... on UserError {
      errors {
        code
        description
        errorPath
      }
    }

    ... on USPersonAuthorizedUser {
      id
      phoneNumbers {
        countryCode
        number
        label
      }
    }
  }
}
Variables
{
  "input": {
    "phoneNumber": {
      "countryCode": "1",
      "number": "234123444",
      "label": "MOBILE",
      "extension": "312"
    },
    "authorizedUserId": "AUTHORIZED_USER_ID",
    "accountHolderId": "ACCOUNT_HOLDER_ID"
  }
}
⚠️ Please login to execute queries. Visit the dashboard to authenticate.
Result
{
  "data": {
    "updateUSPersonAuthorizedUserPhone": {
      "__typename": "USPersonAuthorizedUser",
      "phoneNumbers": {
        "countryCode": "1",
        "number": "234123444",
        "label": "MOBILE",
        "extension": "312"
      },
      "id": "AUTHORIZED_USER_ID"
    },
    "extensions": {
      "requestId": "REQUEST_ID"
    }
  }
}

Email​

When updating an authorized user's email, note the following:

  • The new email must be a valid email address.
  • We recommend you send an email to your authorized user using the old email address to notify them of the email update and mitigate potential fraud risks.

Use the following query to update an authorized user's email:

UpdateUSPersonAuthorizedUserEmail​
Query
mutation updateUSPersonAuthorizedUserEmail(
  $input: UpdateUSPersonAuthorizedUserEmailInput!
) {
  updateUSPersonAuthorizedUserEmail(input: $input) {
    __typename
    ... on UserError {
      errors {
        code
        description
        errorPath
      }
    }
    ... on USPersonAuthorizedUser {
      id
      email
    }
  }
}
Variables
{
  "input": {
    "email": "abc@123.com",
    "authorizedUserId": "AUTHORIZED_USER_ID",
    "accountHolderId": "ACCOUNT_HOLDER_ID"
  }
}
⚠️ Please login to execute queries. Visit the dashboard to authenticate.
Result
{
  "data": {
    "updateUSPersonAuthorizedUserEmail": {
      "__typename": "USPersonAuthorizedUser",
      "id": "AUTHORIZED_USER_ID",
      "email": "abc@123.com"
    }
  },
  "extensions": {
    "requestId": "REQUEST_ID"
  }
}