Change Business Owners and Primary Authorized Person

Overview

Four mutations change the people behind an approved business application. You call three of them: add a beneficial owner, replace the primary authorized person, and change an owner's percentage. The fourth, removing a beneficial owner, is performed by Highnote on your request. The business keeps its financial accounts and cards throughout.

How a change works

Change	Mutation	`applicationState.status` returned
Add a beneficial owner	`addBeneficialOwners`	`PENDING`: the person is verified next
Replace the primary authorized person	`replacePrimaryAuthorizedPerson`	`PENDING`: the person is verified next
Remove a beneficial owner	`removeBeneficialOwners` (performed by Highnote)	`APPROVED`: complete
Change an owner's percentage	`updateBeneficialOwnership`	`APPROVED`: complete

Every change is applied to the business straight away. Highnote records it as a new edition of the application: a versioned copy of the approved application with the change applied. The application's reevaluationEdition field rises with each edition.

Your mutation applies the change to the business.
If nobody needs verifying (remove, change percentage), the edition is approved at once.
If someone needs verifying (add, replace), the edition opens as PENDING and the person goes through identity verification.
If verification is approved, the edition becomes the application. If it is denied, the application stays APPROVED and the change stays on the business.

Change percentage completes immediately. The response is the application, APPROVED, under the id you sent. There is nothing to poll and no webhook: the response is your confirmation.
Remove also completes immediately. Highnote confirms to you when it is done.
Add and replace return the new edition, with its own id, in PENDING. The person is verified even if they have been verified before.
While an edition is pending, the application's approved details (accountHolderSnapshot.businessProfile) are unchanged, but the business itself (accountHolderCurrent) already shows the change.
To correct the details of someone already on the business, such as their name or address, contact Highnote.
A denied verification does not undo the change. The person stays on the business. See If verification is denied.

Before you call

Who can call: a subscriber API key, or a dashboard user with the admin or support role. A dashboard user with the developer role can call them in a test environment only. Other callers receive AccessDeniedError.
The application must be a business application in APPROVED status.
Send the application's original id, never an edition's id.
One change at a time. While an add or replace edition is PENDING or IN_REVIEW, every other change to that application is refused with REVET_ALREADY_IN_PROGRESS.
One person per call. To add two owners, make two calls, waiting for the first edition to finish.
People must be US persons identified by a Social Security number.
Sole proprietorships: none of these changes are supported: adding, removing or changing owners, or replacing the primary authorized person. A sole proprietor whose ownership or primary authorized person changes needs a new application. Each is refused with IDENTITY_CHANGE_NOT_ALLOWED_FOR_SOLE_PROPRIETORSHIP at input.applicationId.

Run the examples in a test environment

The add, replace and change-percentage examples on this page run against the organization you are signed in to. In a live organization they change a real business immediately and, for add and replace, record the consent timestamp you send and start identity verification. Only Highnote can remove an owner you add. When you call these mutations for real, send the time the person actually consented.

Find the people on the business

The mutations identify people by id. Read the ids from the application's current account holder, accountHolderCurrent. It shows the business as it is now, including a change whose person is still being verified or was denied. businessProfile directly under accountHolderSnapshot shows the approved application instead. Its ultimateBeneficialOwners list leaves out the primary authorized person, so to find an owner who isn't on the approved application, compare it with ultimateBeneficialOwnerDetails and skip the entry where isPrimaryAuthorizedPerson (or isPrimary) is true.

Find the people on a business

Query

query FindBusinessPeople($applicationId: ID!) {
  node(id: $applicationId) {
    ... on AccountHolderCardProductApplication {
      id
      reevaluationEdition
      applicationState {
        status
      }
      accountHolderSnapshot {
        ... on USBusinessAccountHolderSnapshot {
          accountHolderCurrent {
            primaryAuthorizedPersonDetail {
              ... on USBusinessAuthorizedPerson {
                id
                name {
                  givenName
                  familyName
                }
                percentageOwnership
              }
              ... on BusinessAuthorizedPerson {
                id
                name {
                  givenName
                  familyName
                }
              }
            }
            businessProfile {
              ultimateBeneficialOwnerDetails {
                ... on USBusinessUltimateBeneficialOwner {
                  id
                  name {
                    givenName
                    familyName
                  }
                  percentageOwnership
                  isPrimaryAuthorizedPerson
                }
                ... on BusinessAuthorizedPerson {
                  id
                  name {
                    givenName
                    familyName
                  }
                  isPrimary
                }
              }
            }
          }
          businessProfile {
            ultimateBeneficialOwners {
              ultimateBeneficialOwnerId
              name {
                givenName
                familyName
              }
              percentageOwnership
            }
          }
        }
      }
    }
  }
}

Variables

{
  "applicationId": "<APPLICATION_ID>"
}

⚠️ Please login to execute queries. Visit the dashboard to authenticate.

Result

{
  "data": {
    "node": {
      "id": "<APPLICATION_ID>",
      "reevaluationEdition": 1,
      "applicationState": {
        "status": "APPROVED"
      },
      "accountHolderSnapshot": {
        "accountHolderCurrent": {
          "primaryAuthorizedPersonDetail": {
            "id": "<PRIMARY_AUTHORIZED_PERSON_ID>",
            "name": {
              "givenName": "Alex",
              "familyName": "Rivera"
            },
            "percentageOwnership": 60
          },
          "businessProfile": {
            "ultimateBeneficialOwnerDetails": [
              {
                "id": "<PRIMARY_AUTHORIZED_PERSON_ID>",
                "name": {
                  "givenName": "Alex",
                  "familyName": "Rivera"
                },
                "percentageOwnership": 60,
                "isPrimaryAuthorizedPerson": true
              },
              {
                "id": "<OWNER_PARTY_ID>",
                "name": {
                  "givenName": "Maria",
                  "familyName": "Lopez"
                },
                "percentageOwnership": 30,
                "isPrimaryAuthorizedPerson": false
              }
            ]
          }
        },
        "businessProfile": {
          "ultimateBeneficialOwners": [
            {
              "ultimateBeneficialOwnerId": "<OWNER_PARTY_ID>",
              "name": {
                "givenName": "Maria",
                "familyName": "Lopez"
              },
              "percentageOwnership": 30
            }
          ]
        }
      }
    }
  },
  "extensions": {
    "requestId": "<REQUEST_ID>"
  }
}

You need	Use
`consentAgreement.primaryAuthorizedPersonId` (add)	`primaryAuthorizedPersonDetail.id`
`partyId` (change percentage), `existingPartyId` (replace)	an `ultimateBeneficialOwnerDetails[].id`
An owner's id on the approved application	`businessProfile.ultimateBeneficialOwners[].ultimateBeneficialOwnerId`, the same id as `ultimateBeneficialOwnerDetails[].id`; the primary authorized person is not in this list

On accountHolderCurrent, use primaryAuthorizedPersonDetail and ultimateBeneficialOwnerDetails; the older primaryAuthorizedPerson and ultimateBeneficialOwners fields there are deprecated.

The response

Each mutation's payload is a union of the same three types. Select all three:

`__typename`	Meaning
`AccountHolderCardProductApplication`	The change was accepted.
`UserError`	The request was refused. Each entry has a `code` saying why and an `errorPath` pointing at the input field. Several problems can come back at once.
`AccessDeniedError`	Your credentials can't make this change. See who can call in Before you call. Subscriber credentials always receive this from `removeBeneficialOwners`.

A refusal looks like this (illustrative values):

{
  "data": {
    "addBeneficialOwners": {
      "__typename": "UserError",
      "errors": [
        {
          "code": "UNSUPPORTED_LEGAL_DOCUMENT_TYPE",
          "description": "the legal document must be a social security number",
          "errorPath": [
            "input",
            "beneficialOwners",
            "[0]",
            "identificationDocument"
          ]
        }
      ]
    }
  }
}

code is a plain string, not a schema enum; Errors lists the codes. A malformed request, or a call that does not finish, comes back as a top-level GraphQL error instead of a UserError. A call that times out or fails inside Highnote can also come back as null for the mutation with no errors; treat that like a timeout, as in Timeouts and retries.

Add a beneficial owner

Adds a person who owns 25% or more of the business, then verifies their identity. The current primary authorized person must consent.

Add a beneficial owner

Query

mutation AddBeneficialOwners($input: AddBeneficialOwnersInput!) {
  addBeneficialOwners(input: $input) {
    __typename
    ... on AccountHolderCardProductApplication {
      id
      reevaluationEdition
      applicationState {
        status
      }
    }
    ... on UserError {
      errors {
        code
        description
        errorPath
      }
    }
    ... on AccessDeniedError {
      message
    }
  }
}

Variables

{
  "input": {
    "applicationId": "<APPLICATION_ID>",
    "beneficialOwners": [
      {
        "name": {
          "givenName": "Maria",
          "familyName": "Lopez"
        },
        "email": "maria.lopez@example.com",
        "phone": {
          "countryCode": "1",
          "number": "5125550123",
          "label": "MOBILE"
        },
        "homeAddress": {
          "streetAddress": "123 Main St",
          "locality": "Austin",
          "region": "TX",
          "postalCode": "78701",
          "countryCodeAlpha3": "USA"
        },
        "dateOfBirth": "1985-04-12",
        "identificationDocument": {
          "socialSecurityNumber": {
            "number": "111-11-1111",
            "countryCodeAlpha3": "USA"
          }
        },
        "percentageOwnership": 30
      }
    ],
    "consentAgreement": {
      "primaryAuthorizedPersonId": "<PRIMARY_AUTHORIZED_PERSON_ID>",
      "consentTimestamp": "2026-10-16T17:00:00.000Z"
    }
  }
}

⚠️ Please login to execute queries. Visit the dashboard to authenticate.

Result

{
  "data": {
    "addBeneficialOwners": {
      "__typename": "AccountHolderCardProductApplication",
      "id": "<EDITION_ID>",
      "reevaluationEdition": 1,
      "applicationState": {
        "status": "PENDING"
      }
    }
  },
  "extensions": {
    "requestId": "<REQUEST_ID>"
  }
}

percentageOwnership is required: a whole number from 25 to 100. A decimal or negative value is rejected as a top-level GraphQL error (BAD_USER_INPUT when the input is sent as variables), not a UserError.
primaryAuthorizedPersonId must be the business's current primary authorized person, and consentTimestamp when they accepted the cardholder agreement for this change.
consentIpAddress is optional. If you leave it out, the IP address of your request is used. If you call from a server, send the IP address the person consented from.
Send the Social Security number with dashes, as NNN-NN-NNNN. It must not already belong to someone on the business.
The person must be 18 to 99 years old, with a family name of at least two characters.

Returns the new edition in PENDING. See Track the outcome.

Replace the primary authorized person

Hands the primary authorized person role to someone else in one step; the two people never hold it at the same time. The incoming person can be new or already on the business, and is verified either way.

Replace with a new person

Query

mutation ReplacePrimaryAuthorizedPerson(
  $input: ReplacePrimaryAuthorizedPersonInput!
) {
  replacePrimaryAuthorizedPerson(input: $input) {
    __typename
    ... on AccountHolderCardProductApplication {
      id
      reevaluationEdition
      applicationState {
        status
      }
    }
    ... on UserError {
      errors {
        code
        description
        errorPath
      }
    }
    ... on AccessDeniedError {
      message
    }
  }
}

Variables

{
  "input": {
    "applicationId": "<APPLICATION_ID>",
    "incomingPerson": {
      "newPerson": {
        "name": {
          "givenName": "James",
          "familyName": "Chen"
        },
        "email": "james.chen@example.com",
        "phone": {
          "countryCode": "1",
          "number": "5125550188",
          "label": "MOBILE"
        },
        "homeAddress": {
          "streetAddress": "456 Oak Ave",
          "locality": "Austin",
          "region": "TX",
          "postalCode": "78702",
          "countryCodeAlpha3": "USA"
        },
        "dateOfBirth": "1979-09-30",
        "identificationDocument": {
          "socialSecurityNumber": {
            "number": "222-22-2222",
            "countryCodeAlpha3": "USA"
          }
        }
      }
    },
    "consentAgreement": {
      "consentTimestamp": "2026-10-16T17:00:00.000Z"
    }
  }
}

⚠️ Please login to execute queries. Visit the dashboard to authenticate.

Result

{
  "data": {
    "replacePrimaryAuthorizedPerson": {
      "__typename": "AccountHolderCardProductApplication",
      "id": "<EDITION_ID>",
      "reevaluationEdition": 1,
      "applicationState": {
        "status": "PENDING"
      }
    }
  },
  "extensions": {
    "requestId": "<REQUEST_ID>"
  }
}

Replace with someone already on the business

Query

mutation ReplacePrimaryAuthorizedPerson(
  $input: ReplacePrimaryAuthorizedPersonInput!
) {
  replacePrimaryAuthorizedPerson(input: $input) {
    __typename
    ... on AccountHolderCardProductApplication {
      id
      reevaluationEdition
      applicationState {
        status
      }
    }
    ... on UserError {
      errors {
        code
        description
        errorPath
      }
    }
    ... on AccessDeniedError {
      message
    }
  }
}

Variables

{
  "input": {
    "applicationId": "<APPLICATION_ID>",
    "incomingPerson": {
      "existingPartyId": "<EXISTING_PARTY_ID>"
    },
    "consentAgreement": {
      "consentTimestamp": "2026-10-16T17:00:00.000Z"
    }
  }
}

⚠️ Please login to execute queries. Visit the dashboard to authenticate.

Result

{
  "data": {
    "replacePrimaryAuthorizedPerson": {
      "__typename": "AccountHolderCardProductApplication",
      "id": "<EDITION_ID>",
      "reevaluationEdition": 1,
      "applicationState": {
        "status": "PENDING"
      }
    }
  },
  "extensions": {
    "requestId": "<REQUEST_ID>"
  }
}

Provide exactly one of newPerson or existingPartyId. Sending both, neither, or an empty string is rejected as a top-level GraphQL error (BAD_USER_INPUT when the input is sent as variables), not a UserError.
consentTimestamp is when the incoming person accepted the cardholder agreement. Send the call only after they have agreed.
For a new person, include percentageOwnership only if they own 25% or more; they then also become a beneficial owner and count toward the limit of four owners. They must meet the same rules as an added owner.
An existing person must already be on the business and must not already be the primary authorized person. An owner who is promoted stays an owner.
The outgoing person leaves the role but keeps any other role they hold on the business.

Returns the new edition in PENDING.

Remove a beneficial owner

Performed by Highnote

removeBeneficialOwners is restricted to Highnote; subscriber credentials receive AccessDeniedError. To remove an owner, contact Highnote with the application id and the owner's id.

Removing an owner takes them off the business, with every role they hold.

One owner per request.
The primary authorized person can't be removed; replace them instead.
The last owner can be removed.
No consent is required.

The application stays APPROVED, under the same id, with a higher reevaluationEdition.

Change an owner's percentage

Sets an existing owner's percentage.

Change an owner's percentage

Query

mutation UpdateBeneficialOwnership($input: UpdateBeneficialOwnershipInput!) {
  updateBeneficialOwnership(input: $input) {
    __typename
    ... on AccountHolderCardProductApplication {
      id
      reevaluationEdition
      applicationState {
        status
      }
    }
    ... on UserError {
      errors {
        code
        description
        errorPath
      }
    }
    ... on AccessDeniedError {
      message
    }
  }
}

Variables

{
  "input": {
    "applicationId": "<APPLICATION_ID>",
    "partyId": "<OWNER_PARTY_ID>",
    "percentageOwnership": 40
  }
}

⚠️ Please login to execute queries. Visit the dashboard to authenticate.

Result

{
  "data": {
    "updateBeneficialOwnership": {
      "__typename": "AccountHolderCardProductApplication",
      "id": "<APPLICATION_ID>",
      "reevaluationEdition": 2,
      "applicationState": {
        "status": "APPROVED"
      }
    }
  },
  "extensions": {
    "requestId": "<REQUEST_ID>"
  }
}

A whole number from 25 to 100. A decimal or negative value is rejected as a top-level GraphQL error (BAD_USER_INPUT when the input is sent as variables), not a UserError. To take someone below 25%, ask Highnote to remove them.
The person must already be a beneficial owner.
No consent is required.

Returns the application in APPROVED, under the id you sent.

Track the outcome

Only add and replace have an outcome to wait for. Use webhooks, polling, or both.

Poll the edition

Poll an edition

Query

query FindApplicationEdition($editionId: ID!) {
  node(id: $editionId) {
    ... on AccountHolderCardProductApplication {
      id
      reevaluationEdition
      applicationState {
        status
      }
      sourceApplication {
        id
      }
    }
  }
}

Variables

{
  "editionId": "<EDITION_ID>"
}

⚠️ Please login to execute queries. Visit the dashboard to authenticate.

Result

{
  "data": {
    "node": {
      "id": "<EDITION_ID>",
      "reevaluationEdition": 1,
      "applicationState": {
        "status": "PENDING"
      },
      "sourceApplication": {
        "id": "<APPLICATION_ID>"
      }
    }
  },
  "extensions": {
    "requestId": "<REQUEST_ID>"
  }
}

Status	Meaning	Next step
`PENDING`	Verification is running.	Keep waiting.
`IN_REVIEW`	Verification needs a manual review.	Handle it like any application under review, using the edition's id; see Application review process. Other changes stay blocked until it finishes.
`APPROVED`	The person passed. The edition is now the application.	Read the application by its original id from now on. The edition id now returns the previous version, so don't read details from it.
`DENIED`	The person did not pass.	See If verification is denied.

Webhooks

These are the same application events described in the Events Reference; for a change, they carry the ids below.

Outcome	Event	Names
Approved	`CARD_PRODUCT_APPLICATION_APPROVED`	The original application id. The application was already approved, so treat the event as "the change is approved", and handle repeats idempotently.
Denied	`CARD_PRODUCT_APPLICATION_DENIED`	The edition id. The application itself stays `APPROVED`; only the change was denied.
Manual review	`CARD_PRODUCT_APPLICATION_MANUAL_REVIEW`	The edition id.

If you already handle these events for new applications, update your handlers before using these mutations: an approved change sends CARD_PRODUCT_APPLICATION_APPROVED again for an application that is already approved, and a denied change sends CARD_PRODUCT_APPLICATION_DENIED for an edition id you may not have stored, while the application stays APPROVED.

Remove and change percentage send no webhook; Highnote confirms a removal directly. To link an edition back to its application, read the edition's sourceApplication { id }.

If verification is denied

The application stays APPROVED with its previous details, but the change was already applied, so the denied person stays on the business.

A denied new owner: ask Highnote to remove them. Until they are removed, percentage changes are refused with ASSOCIATED_PERSON_NOT_VERIFIED.
A denied primary authorized person: the incoming person already holds the role. Contact Highnote to resolve it.

Timeouts and retries

These mutations have no idempotency key. If a call times out, returns a top-level INTERNAL_SERVER_ERROR, or returns null for the mutation with no errors, the change may already have been made, so don't resend immediately.

Read the business's people again, as in Find the people on the business.
If the change is there, it went through. For add and replace, wait for the outcome webhook. An approval names your application id; a denial or manual review names the edition, whose sourceApplication { id } is your application. If no outcome arrives, contact Highnote.
If the change is not there, resend.

If the first call did succeed, a resend returns:

Mutation	Resend returns
`addBeneficialOwners`	`REVET_ALREADY_IN_PROGRESS` while the edition is pending, otherwise `ASSOCIATED_PERSON_ALREADY_EXISTS`. No duplicate person is created.
`replacePrimaryAuthorizedPerson`	`REVET_ALREADY_IN_PROGRESS` while the edition is pending, otherwise `ASSOCIATED_PERSON_ALREADY_EXISTS` (new person) or `EXISTING_PARTY_IS_THE_PRIMARY_AUTHORIZED_PERSON` (existing person).
`updateBeneficialOwnership`	Success again, with the same id and `APPROVED` status. Each resend opens another edition, so `reevaluationEdition` rises.

Errors

A refused request normally changes nothing. The exceptions are listed under Errors after the change was applied. The tables cover the codes specific to these changes; The request also lists the field-format codes the person's details are checked against.

The application

Code	Why	Fix
`APPLICATION_NOT_FOUND`	No application with that id.	Check the id.
`MISSING_BUSINESS_ENTITY`	It isn't a business application.	These changes apply to businesses only.
`IDENTITY_CHANGE_NOT_ENABLED_FOR_PRODUCT`	These changes aren't available for this card product.	Contact Highnote.
`INVALID_REEVALUATE_APPLICATION_ID`	You sent an edition's id.	Send the original application id.
`IP_ADDRESS_IS_REQUIRED`	The request carried no client IP address.	Contact Highnote.
`INVALID_STATUS_FOR_REVET`	The application isn't `APPROVED`.	Wait until it's approved.
`REVET_ALREADY_IN_PROGRESS`	Another change is pending or in review.	Wait for that edition to finish. This code can also arrive after your change was applied; see Errors after the change was applied.
`REEVALUATE_SOURCE_EDITION_NOT_CARRIABLE`, `REEVALUATE_SOURCE_EDITION_COMPONENT_NOT_VERIFIABLE`, `REEVALUATE_SOURCE_EDITION_PROCESSED_BY_WORKFLOW`, `IDENTITY_CHANGE_NOT_VERIFIABLE`	This application can't be changed through these mutations.	Contact Highnote.

The request

Code	Why	Fix
`BENEFICIAL_OWNERSHIP_PERCENTAGE_MIN_VALUE`	Ownership is below 25%.	Use a whole number from 25 to 100.
`BENEFICIAL_OWNERSHIP_PERCENTAGE_MAX_VALUE`	Ownership is above 100% when changing a percentage.	Use a whole number from 25 to 100.
`INVALID_INPUT`	Ownership is above 100% on add or replace, the Social Security number isn't valid, more than one identification document was sent, or the input is malformed.	Check the field in `errorPath`.
`NON_NULL_INPUT_REQUIRED`, `NON_EMPTY_INPUT_REQUIRED`	A required field is missing or empty, such as an added owner's `percentageOwnership`.	Supply the field.
`MAX_LENGTH_REACHED`	More than one person in the list, or a field is too long. `errorPath` says which.	Send one person per call, or shorten the field.
`INVALID_TIMESTAMP_FORMAT`	`consentTimestamp` isn't ISO 8601.	Use a form like `2026-10-16T17:00:00.000Z`.
`INVALID_EMAIL`	The email address isn't valid.	Check `email`.
`UNSUPPORTED_LEGAL_DOCUMENT_TYPE`	The document isn't a Social Security number.	Send `socialSecurityNumber`.
`DATE_OF_BIRTH_OUT_OF_RANGE`	The person isn't 18 to 99.	Check `dateOfBirth`.
`LAST_NAME_TOO_SHORT`	The family name is under two characters.	Check `familyName`.
Field-format codes such as `INVALID_ADDRESS_LINE_1`, `INVALID_ADDRESS_LINE_2`, `INVALID_ADDRESS_CITY`, `INVALID_STATE`, `INVALID_POSTAL_CODE`, `INVALID_POSTAL_CODE_PLUS_4`, `INVALID_COUNTRY_CODE`, `INVALID_PHONE`, `MIN_LENGTH_REACHED`, `INVALID_FIRST_NAME_FORMAT`, `INVALID_LAST_NAME_FORMAT`, `INVALID_MIDDLE_NAME_FORMAT`, `INVALID_LEGAL_DOCUMENT_TYPE`	A field on the person isn't in the expected format.	Check the field in `errorPath`.
`ASSOCIATED_PERSON_ALREADY_EXISTS`	Someone on the business already has this Social Security number.	Check the number. To make that person the primary authorized person, replace with `existingPartyId`. If you just retried an add or replace, see Errors after the change was applied.

The people on the business

Code	Why	Fix
`INVALID_PRIMARY_AUTHORIZED_PERSON_ID`	On add: `primaryAuthorizedPersonId` isn't the current primary authorized person. On change percentage: the application's consent no longer names them, typically after a denied replacement.	On add, send the current person's id. Otherwise contact Highnote.
`PRIMARY_AUTHORIZED_PERSON_NOT_RESOLVABLE`	The business doesn't have exactly one primary authorized person to replace.	Contact Highnote.
`EXISTING_PARTY_NOT_ASSOCIATED`	`existingPartyId` isn't on the business.	Check the id.
`EXISTING_PARTY_IS_THE_PRIMARY_AUTHORIZED_PERSON`	That person already holds the role.	Nothing to do.
`PARTY_NOT_ASSOCIATED`	The person isn't on the business.	Check the id.
`PARTY_NOT_A_BENEFICIAL_OWNER`	The person isn't an owner. This includes a primary authorized person who isn't an owner.	Check the id. To change the primary authorized person, replace them.
`ASSOCIATED_PERSON_NOT_VERIFIED`	Someone on the business hasn't passed verification, usually an owner whose addition was denied. The error does not name them.	Find the owner who is in `ultimateBeneficialOwnerDetails`, is not the primary authorized person, and is not in the approved `businessProfile.ultimateBeneficialOwners`, as in Find the people on the business. Ask Highnote to remove them.
`TOO_MANY_BENEFICIAL_OWNERS`	The change would leave the business with more than four owners, or further over four if it already is. The primary authorized person counts only if they are also an owner.	Ask Highnote to remove an owner first.
`IDENTITY_CHANGE_NOT_ALLOWED_FOR_SOLE_PROPRIETORSHIP`	The business is a sole proprietorship. None of these changes are allowed on one.	Submit a new application.

Errors about the person's details

If Highnote rejects the person's details while applying the change, nothing is changed. The UserError carries one code per problem, with errorPath at the person's field. When there is no detail, the code is IDENTITY_CHANGE_REJECTED. Correct the request and resend. On add and replace, these codes can also arrive after the change was applied; see below.

Errors after the change was applied

These can arrive after the change has been made to the business. Check the application before retrying, as in Timeouts and retries.

Code	Why	Fix
`REVET_ALREADY_IN_PROGRESS`, `REEVALUATE_EDITION_ALREADY_EXISTS`, `REEVALUATE_SOURCE_EDITION_*`	Two changes to the same application raced each other.	Check the application before retrying.
`MISSING_BUSINESS_ORGANIZATION_ASSOCIATED_PERSONS`	The change left the business with no associated people.	Contact Highnote.
Any code rejecting the person's details, on add or replace	Raised while the edition was opening.	Check the application before retrying.
`ASSOCIATED_PERSON_ALREADY_EXISTS`, `EXISTING_PARTY_IS_THE_PRIMARY_AUTHORIZED_PERSON`, on add or replace	The call was retried inside Highnote after the change was made.	Check the application. If the person is on the business, the change was made but verification did not start; contact Highnote.
Top-level `INTERNAL_SERVER_ERROR`	The call didn't finish.	Follow Timeouts and retries.

Limits

Limit	Value
People per call	1
Changes in progress per application	1
Ownership per owner	25 to 100, whole numbers
Beneficial owners per business	Up to 4. The primary authorized person counts only if they are also an owner.
Primary authorized people per business	Exactly 1
Identification	US Social Security number only
Age	18 to 99
Total ownership across owners	Not checked

Overview​

How a change works​

Before you call​

Find the people on the business​

Find the people on a business​

The response​

Add a beneficial owner​

Add a beneficial owner​

Replace the primary authorized person​

Replace with a new person​

Replace with someone already on the business​

Remove a beneficial owner​

Change an owner's percentage​

Change an owner's percentage​

Track the outcome​

Poll the edition​

Poll an edition​

Webhooks​

If verification is denied​

Timeouts and retries​

Errors​

The application​

The request​

The people on the business​

Errors about the person's details​

Errors after the change was applied​

Limits​

Overview

How a change works

Before you call

Find the people on the business

Find the people on a business

The response

Add a beneficial owner

Add a beneficial owner

Replace the primary authorized person

Replace with a new person

Replace with someone already on the business

Remove a beneficial owner

Change an owner's percentage

Change an owner's percentage

Track the outcome

Poll the edition

Poll an edition

Webhooks

If verification is denied

Timeouts and retries

Errors

The application

The request

The people on the business

Errors about the person's details

Errors after the change was applied

Limits