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
- JSON:
- XML:
GetBestMatch Inputs
| Name | Type | Values | Description |
|---|---|---|---|
| Address | String | Varies | Address line associated with desired tax rates |
| Address2 | String | Varies | Address2 line associated with desired tax rates |
| City | String | Varies | City associated with desired tax rates |
| State | String | Varies | State associated with desired tax rates |
| Zip | String | Varies | The zip code associated with the desired tax rates |
| TaxType | String | sales / use | Selects the type of tax to look for, for the given area. |
| LicenseKey | String | Varies | Your license key to use the service. Sign up for a free trial key at https://www.serviceobjects.com/fasttax/ |
GetBestMatch Outputs
- All of the response objects are contained within the GetBestMatch object.
- GetBestMatchResponse
| Name | Type | Description | |
|---|---|---|---|
| TaxInfoItems | BestMatchTaxInfo[] | Varies | The returned tax rate values of an input address. |
| MatchLevel | String | ‘Address’ or ‘Zip’ | The returned match level that was made with the given input. |
| Error | Object | Varies | The returned error result from a failed address verification or user input error. |
| Debug | String[] | Varies | Used internally for testing. |
- BestMatchTaxInfo
| Name | Type | Values | Description |
|---|---|---|---|
| Zip | String | Varies | The given zip code associated with the tax rate |
| City | String | Varies | The city associated with the given input |
| County | String | Varies | The county associated with the given input |
| StateAbbreviation | String | Two letter state code | The common two letter state abbreviation |
| StateName | String | Varies | The name of the state associated with the given tax rate |
| TaxRate | String | Decimal digit | The decimal representation of the overall tax rate |
| StateRate | String | Decimal digit | The decimal representation of the state’s tax rate |
| CityRate | String | Decimal digit | The decimal representation of the city’s tax rate |
| CountyRate | String | Decimal digit | The decimal representation of the county’s tax rate |
| CountyDistrictRate [1] | String | Decimal digit | The decimal representation of any special district tax rates for the county |
| CityDistrictRate | String | Decimal digit | The decimal representation of any special district tax rates for the city |
| SpecialDistrictRate | String | Decimal digit | The decimal representation for any additional tax rates that may be added to a total tax rate. |
| InformationComponents [2] | InformationComponent[] | Varies | An array of name value pairs that contain extraneous information related to the input and or tax rate. |
| TotalTaxExempt | String | Varies | Different items that are exempt from being charged a sales tax. Will be a combination of Labor/Freight/Services. |
| NotesCodes | String | Varies | Codes corresponding to various NotesDesc results |
| NotesDesc | String | Varies | Various pieces of information about the tax information returned. |
- InformationComponent
| Name | Type | Value | Description |
|---|---|---|---|
| Name | String | Varies | The variable name of the Name- Value pair that is to be returned |
| Value | String | Value | The resulting value of the of the variable returned in the “Name”. |
InformationComponents Items
- ClassFP – A code that defines the current class of the geographic location. We maintain a table of these in our Address Geocoding – US product on this page.
- CountyFIPS – is the FIPS code for the address’ county.
- IsUnincorporated – is the most important output out of these additional outputs. This flag lets the user know if the address entered into FastTax is Unincorporated essentially if it is a part of the city with which it is associated. This is important because if an address is unincorporated, then you do not apply CityRate to TotalRate.