This document defines the input, output and behavior of the web service operations in GetBestMatch. 

This operation will return the best available tax rate match with the given input. If the given address input cannot be resolved or found, the operation will provide a Zip level match if the given zip code is valid. The service will provide a total tax rate for the given input as well as the different CountryDistrict, CityDistrict, City, County and State rates that the comprise the total rate returned. This operation also has the ability to determine whether or not a given address may be in an unincorporated area.  If the IsUnicorporated flag is returned in the NotesDesc field, then appropriate logic should be implemented to remove the city and city district rates from the total rate as those would not apply for the given input. If the MatchLevel returned is “Zip” then this operation can also return multiple tax rates for the different tax jurisdictions combinations within the particular zip code. In this case, it would be up the user to determine what tax rate would prove to be the best match for the given input.

This operation may also return blank city or county information for certain requests.  Most of the time we can verify the location of an input address and fill in the appropriate city and county information with the verified address information. In other scenarios, the outputs may be missing those fields because the input address was bad, but we are still able to find applicable tax rates for the given address information. If you have further questions about this, please contact us at support@serviceobjects.com

NOTE: This operation will not remove any city tax rates for an address that receives an “IsUnincorporated” flag.  This logic will have to be set up in your code when calling this operation.

URL Endpoints

GetBestMatch Inputs

NameTypeValuesDescription
AddressStringVaries Address line associated with desired tax rates
Address2StringVariesAddress2 line associated with desired tax rates
CityStringVariesCity associated with desired tax rates
StateStringVaries State associated with desired tax rates
ZipStringVariesThe zip code associated with the desired tax rates
TaxTypeStringsales / useSelects the type of tax to look for, for the given area.
LicenseKeyStringVariesYour license key to use the service.
Sign up for a free trial key at
https://www.serviceobjects.com/products/ecommerce/fasttax

GetBestMatch Outputs

NameTypeDescription
TaxInfoItemsBestMatchTaxInfo[]VariesThe returned tax
rate values of an
input address.
MatchLevelString‘Address’ or ‘Zip’The returned
match level that
was made with the
given input.
ErrorObjectVariesThe returned error
result from a failed
address
verification or
user input error.
DebugString[]VariesUsed internally
for testing.
NameTypeValuesDescription
ZipStringVariesThe given zip code associated with the tax
rate
CityStringVariesThe city associated with the given input
CountyStringVariesThe county associated with the given input
StateAbbreviationStringTwo letter
state code
The common two letter state abbreviation
StateNameStringVariesThe name of the state associated with the
given tax rate
TaxRateStringDecimal digitThe decimal representation of the overall tax
rate
StateRateStringDecimal digitThe decimal representation of the state’s tax
rate
CityRateStringDecimal digitThe decimal representation of the city’s tax
rate
CountyRateStringDecimal digitThe decimal representation of the county’s
tax rate
CountyDistrictRate [1]StringDecimal digitThe decimal representation of any special
district tax rates for the county
CityDistrictRateStringDecimal digitThe decimal representation of any special
district tax rates for the city
SpecialDistrictRateStringDecimal digitThe decimal representation for any
additional tax rates that may be added to a
total tax rate.
InformationComponents 
[2]
InformationComponent[]VariesAn array of name value pairs that contain
extraneous information related to the input
and or tax rate.
TotalTaxExemptStringVariesDifferent items that are exempt from being
charged a sales tax. Will be a combination
of Labor/Freight/Services.
NotesCodesStringVariesCodes corresponding to various NotesDesc
results
NotesDescStringVariesVarious pieces of information about the tax
information returned.
NameTypeValueDescription
NameStringVariesThe variable name of the Name-
Value pair that is to be returned
ValueStringValueThe resulting value of the of the
variable returned in the “Name”.

InformationComponents Items


References

  1. Accounting for City and CityDistrict Rates – Unincorporated Areas
  2. DOTS FastTax Gives More Accurate Tax Rates by Identifying Unincorporated Places