Skip to main content

Onboard a Fleet Account

Overview​

Fleet card products are used by business account holders. This guide covers the fleet-specific onboarding process, including fuel tax exemption.

For general onboarding concepts such as account holder types and application review, see Onboard an Account.

Before you begin​

Before creating a business account holder, determine the following:

  • Is this fleet fuel tax exempt? If yes, you must include the FUEL_TAX_EXEMPT attribute during account holder creation. This attribute cannot be added or updated after onboarding.
  • Are you collecting data from a UI? If yes, use the tokenized flow to keep PII off your servers. If you're calling the API from your backend, use the direct API flow.

A US business account holder requires the following:

  • Business details: Business name, identification number (EIN), business type, phone, billing address, and website
  • Primary authorized person: Person authorized to act on behalf of the business. If they own or control at least 25% of the business, they are also added as a beneficial owner.
  • Beneficial owners: Any person who owns or controls at least 25% of the business

Fuel tax exemption​

Fuel tax exemption is immutable

Be careful. The fuel tax exemption attribute must be set during account holder creation. It cannot be added or updated after onboarding.

For non-exempt fleets, omit businessPlanAttributes (which is optional).

For fuel tax exempt fleets, pass businessPlanAttributes in the businessProfile input with:

  • type set to FUEL_TAX_EXEMPT
  • value set to true
  • reportedAt date in YYYY-MM-DD format.

When the fuel tax exemption is enabled, Highnote's platform tracks the Fleet's qualifying transactions to enable fuel tax reclamation reporting.

Onboard with direct API flow​

Use createUSBusinessAccountHolder to create the account holder directly from your server. The businessPlanAttributes field is optional:

CreateUSBusinessAccountHolder​
Query
mutation CreateUSBusinessAccountHolder(
  $input: CreateUSBusinessAccountHolderInput!
) {
  createUSBusinessAccountHolder(input: $input) {
    __typename
    ... on UserError {
      errors {
        errorPath
        code
        description
      }
    }
    ... on USBusinessAccountHolder {
      id
      externalId
      createdAt
      updatedAt
      businessProfile {
        id
        name {
          legalBusinessName
          doingBusinessAsName
        }
        businessType
        operatingDetails {
          indicatorAttributes {
            type
            value
            reportedAt
          }
        }
      }
    }
  }
}
Variables
{
  "input": {
    "primaryAuthorizedPerson": {
      "name": {
        "givenName": "<GIVEN_NAME>",
        "familyName": "<FAMILY_NAME>"
      },
      "dateOfBirth": "1980-01-01",
      "homeAddress": {
        "streetAddress": "123 Main St",
        "postalCode": "60654",
        "locality": "Chicago",
        "region": "IL",
        "countryCodeAlpha3": "USA"
      },
      "identificationDocument": {
        "socialSecurityNumber": {
          "number": "111-11-1111",
          "countryCodeAlpha3": "USA"
        }
      }
    },
    "businessProfile": {
      "name": {
        "legalBusinessName": "LEGAL_BUSINESS_NAME"
      },
      "businessType": "LIMITED_LIABILITY_COMPANY",
      "billingAddress": {
        "streetAddress": "456 Commerce Blvd",
        "postalCode": "90210",
        "locality": "Los Angeles",
        "region": "CA",
        "countryCodeAlpha3": "USA"
      },
      "identificationDocument": {
        "employerIdentificationNumber": {
          "number": "12-3456789",
          "countryCodeAlpha3": "USA"
        }
      },
      "businessPlanAttributes": [
        {
          "indicatorAttribute": {
            "type": "FUEL_TAX_EXEMPT",
            "value": true,
            "reportedAt": "2026-03-15"
          }
        }
      ]
    }
  }
}
⚠️ Please login to execute queries. Visit the dashboard to authenticate.
Result
{
  "data": {
    "createUSBusinessAccountHolder": {
      "__typename": "USBusinessAccountHolder",
      "id": "<BUSINESS_ACCOUNT_HOLDER_ID>",
      "externalId": null,
      "createdAt": "2026-03-26T18:00:00.000Z",
      "updatedAt": "2026-03-26T18:00:00.000Z",
      "businessProfile": {
        "id": "<BUSINESS_ACCOUNT_HOLDER_ID>",
        "name": {
          "legalBusinessName": "LEGAL_BUSINESS_NAME",
          "doingBusinessAsName": null
        },
        "businessType": "LIMITED_LIABILITY_COMPANY",
        "operatingDetails": {
          "indicatorAttributes": [
            {
              "type": "FUEL_TAX_EXEMPT",
              "value": true,
              "reportedAt": "2026-03-15"
            }
          ]
        }
      }
    }
  },
  "extensions": {
    "requestId": "1ab32e1c-4949-9421-8240-c39ca4123jkl"
  }
}

Onboard with tokenized flow​

If you're collecting account holder data from a UI, use the tokenized flow to keep PII off your servers.

Step 1. Generate a client token​

Generate a client token using generateTokenizeAccountHolderClientToken. For more information on client tokens, see Client Tokens.

GenerateTokenizeAccountHolderClientToken​
Query
mutation GenerateTokenizeAccountHolderClientToken {
  generateTokenizeAccountHolderClientToken {
    __typename
    ... on ClientToken {
      value
      expirationDate
      usage
    }
    ... on UserError {
      errors {
        code
        description
      }
    }
    ... on AccessDeniedError {
      message
    }
  }
}
⚠️ Please login to execute queries. Visit the dashboard to authenticate.
Result
{
  "data": {
    "generateTokenizeAccountHolderClientToken": {
      "__typename": "ClientToken",
      "value": "<CLIENT_TOKEN_VALUE>",
      "expirationDate": "2026-03-28T01:00:00.000Z",
      "usage": "UNTIL_EXPIRATION"
    }
  },
  "extensions": {
    "requestId": "d47a92c3-5f18-4e6d-b902-3a8c1ef57b24"
  }
}

Step 2. Tokenize the account holder data​

Tokenize the account holder data using tokenizeUSBusinessAccountHolder. This mutation accepts the same CreateUSBusinessAccountHolderInput as the direct flow, so businessPlanAttributes can be included in the tokenized data. The token expires after 1 hour.

TokenizeUSBusinessAccountHolder​
Query
mutation TokenizeUSBusinessAccountHolder(
  $input: CreateUSBusinessAccountHolderInput!
) {
  tokenizeUSBusinessAccountHolder(input: $input) {
    __typename
    ... on USBusinessAccountHolderToken {
      token
    }
    ... on UserError {
      errors {
        code
        description
      }
    }
    ... on AccessDeniedError {
      message
    }
  }
}
Variables
{
  "input": {
    "primaryAuthorizedPerson": {
      "name": {
        "givenName": "<GIVEN_NAME>",
        "familyName": "<FAMILY_NAME>"
      },
      "dateOfBirth": "1980-01-01",
      "homeAddress": {
        "streetAddress": "123 Main St",
        "postalCode": "60654",
        "locality": "Chicago",
        "region": "IL",
        "countryCodeAlpha3": "USA"
      },
      "identificationDocument": {
        "socialSecurityNumber": {
          "number": "111-11-1111",
          "countryCodeAlpha3": "USA"
        }
      }
    },
    "businessProfile": {
      "name": {
        "legalBusinessName": "LEGAL_BUSINESS_NAME"
      },
      "businessType": "LIMITED_LIABILITY_COMPANY",
      "billingAddress": {
        "streetAddress": "456 Commerce Blvd",
        "postalCode": "90210",
        "locality": "Los Angeles",
        "region": "CA",
        "countryCodeAlpha3": "USA"
      },
      "identificationDocument": {
        "employerIdentificationNumber": {
          "number": "12-3456789",
          "countryCodeAlpha3": "USA"
        }
      },
      "businessPlanAttributes": [
        {
          "indicatorAttribute": {
            "type": "FUEL_TAX_EXEMPT",
            "value": true,
            "reportedAt": "2026-03-15"
          }
        }
      ]
    }
  }
}
⚠️ Please login to execute queries. Visit the dashboard to authenticate.
Result
{
  "data": {
    "tokenizeUSBusinessAccountHolder": {
      "__typename": "USBusinessAccountHolderToken",
      "token": "<TOKENIZED_DATA_TOKEN>"
    }
  },
  "extensions": {
    "requestId": "e6f103a8-2c49-4d7a-8b35-9d1fe4a26c81"
  }
}

Step 3. Create the account holder from the token​

Create the account holder using createUSBusinessAccountHolderFromToken. This mutation only takes the token — no separate input is needed.

CreateUSBusinessAccountHolderFromToken​
Query
mutation CreateUSBusinessAccountHolderFromToken(
  $input: CreateUSBusinessAccountHolderFromTokenInput!
) {
  createUSBusinessAccountHolderFromToken(input: $input) {
    __typename
    ... on USBusinessAccountHolder {
      id
      businessProfile {
        id
        name {
          legalBusinessName
        }
        operatingDetails {
          indicatorAttributes {
            type
            value
            reportedAt
          }
        }
      }
    }
    ... on UserError {
      errors {
        code
        description
      }
    }
    ... on AccessDeniedError {
      message
    }
  }
}
Variables
{
  "input": {
    "token": "<TOKENIZED_DATA_TOKEN>"
  }
}
⚠️ Please login to execute queries. Visit the dashboard to authenticate.
Result
{
  "data": {
    "createUSBusinessAccountHolderFromToken": {
      "__typename": "USBusinessAccountHolder",
      "id": "<BUSINESS_ACCOUNT_HOLDER_ID>",
      "businessProfile": {
        "id": "<BUSINESS_ACCOUNT_HOLDER_ID>",
        "name": {
          "legalBusinessName": "LEGAL_BUSINESS_NAME"
        },
        "operatingDetails": {
          "indicatorAttributes": [
            {
              "type": "FUEL_TAX_EXEMPT",
              "value": true,
              "reportedAt": "2026-03-15"
            }
          ]
        }
      }
    }
  },
  "extensions": {
    "requestId": "b85fc1ec-e770-9d06-922f-16b7486a699i"
  }
}

Query fuel tax exemption status​

You can read back the fuel tax exemption status by querying the business account holder's operatingDetails.indicatorAttributes:

GetBusinessAccountHolder​
Query
query GetBusinessAccountHolder($id: ID!) {
  node(id: $id) {
    ... on USBusinessAccountHolder {
      id
      businessProfile {
        name {
          legalBusinessName
        }
        operatingDetails {
          indicatorAttributes {
            type
            value
            reportedAt
          }
        }
      }
    }
  }
}
Variables
{
  "id": "<BUSINESS_ACCOUNT_HOLDER_ID_1>"
}
⚠️ Please login to execute queries. Visit the dashboard to authenticate.
Result
{
  "data": {
    "node": {
      "id": "<BUSINESS_ACCOUNT_HOLDER_ID_2>",
      "businessProfile": {
        "name": {
          "legalBusinessName": "Fuel Corp."
        },
        "operatingDetails": {
          "indicatorAttributes": [
            {
              "type": "FUEL_TAX_EXEMPT",
              "value": true,
              "reportedAt": "2026-03-15"
            }
          ]
        }
      }
    }
  },
  "extensions": {
    "requestId": "a23de4f1-8821-4b3c-9a17-6c4f82d19e05"
  }
}

Next steps​

After creating a business account holder, continue with the Fleet Credit Template to open an application, issue a financial account, and configure your fleet card product.