Request
The Calculation Request method is used to create a transaction to calculate taxes. There are two types of calculation requests: Quote and Finalized controlled by the value in the ReturnFileCode field.
For REST Integrations:
Method: PostRequest
URL: /Services/Communications/V01/SureTax.asmx/PostRequest
For SOAP Integrations:
Method: SoapRequest
URL: /Services/Communications/V01/SureTax.asmx
Request Layout
Request Record
FIELD | FIELD NAME | DESCRIPTION |
---|---|---|
Client Number | ClientNumber | Client ID Number - provided by CCH SureTax. |
Business Unit | BusinessUnit | Client's Business Unit. Value for this field is not required. Max Length: 20 |
Validation Key | ValidationKey | Validation Key provided by CCH SureTax. |
Data Year | DataYear | YYYY - The system will use the rates for the specified year when calculating taxes. |
Data Month | DataMonth | MM - The system will use the rates for the specified month when calculating taxes. Leading zero is preferred. |
Compliance Year | CmplDataYear | YYYY - Year during which a transaction occurred. This is used when remitting taxes for the specified year. |
Compliance Month | CmplDataMonth | MM - Month during which a transaction occurred. This is used when remitting taxes for the specified month. Leading zero is preferred. |
Total Revenue | Total Revenue | Format: $$$$$$$$$.CCCC For Negative charges, the first position should have a minus (-) indicator. |
Return File Code | ReturnFileCode | Defines the type of calculation for the transaction. 0 - Finalized - taxes are computed and returned in the response message. All detailed tax information is saved in the CCH SureTax tables for immediate reporting or review. Q - Quote - taxes are computed and returned in the response message for generating quotes. No detailed tax information is saved in the CCH SureTax tables for reporting or review. |
Client Tracking Field | ClientTracking | Field for client transaction tracking. This value will be provided in the response data. Value for this field is not required, but preferred. Max Length: 100 |
Response Group | ResponseGroup | Determines how taxes are grouped for the response. Values: 00 - Tax grouped by Line Item |
Response Type | ResponseType | Determines the processing option, granularity of taxes, and the decimal precision for the tax amounts in the response. A Response Type is comprised of three components:
Recommended Response Type: D6 |
System Trace Audit Number | STAN | Optional value. A unique value provided by client for transaction audit purposes. If you don't need transaction audit set value as null. Max Length: 40 |
Client Items | ItemList | List of Item records. (See: Item Layout) |
Item Layout:
FIELD | FIELD NAME | DESCRIPTION | |
---|---|---|---|
Line Number | LineNumber | Used to identify an item within the request. If no value is provided, response are numbered sequentially. Max Length: 40 |
|
Invoice Number | InvoiceNumber | Invoice, Sales Order, Credit Memo, or any Document number for a given transaction. Must be alphanumeric. Max Length: 40 |
|
Customer Number | CustomerNumber | Customer Identifier. Must be alphanumeric. Max Length: 40 |
|
Origination Number | OrigNumber | Required when using Tax Situs Rule 01 or 03. Format: NPANXXNNNN |
|
Termination Number | TermNumber | Required when using Tax Situs Rule 01. Format: NPANXXNNNN |
|
Billed to Number | BillToNumber | Required when using Tax Situs Rule 01 or 02. Format: NPANXXNNNN |
|
Date of Transaction | TransDate | Date of transaction. Valid date formats include: MM/DD/YYYY MM-DD-YYYY |
|
Billing Period Start Date | BillingPeriodStartDate | Billing Period Start Date | |
Billing Period End Date | BillingPeriodEndDate | Billing Period End Date | |
Revenue | Revenue | Total line item amount. Format: $$$$$$$$$.CCCC For Negative charges, the first position should have a minus (-) indicator. |
|
Quantity | Units | Number of lines. Must be value greater of 0. (default 1) Format: 99999.99 |
|
Unit Type | UnitType | 00 - Default / Number of unique access lines. | |
Call Duration | Seconds | Duration of call in seconds. (default 1) Format 99999. |
|
Tax Included Code | TaxIncludedCode | Revenue includes the tax amount. SureTax will back calculate the tax included within the revenue amount. Values: 0 - No Tax Included (recommended) 1 - Tax Included in Revenue |
|
Tax Situs Rule | TaxSitusRule | Identifies what address to use for tax calculation purposes. Values: 01 - Two-out-of-Three test using NPA-NXX 02 - Billed to number 03 - Origination number 04 - Zip code 05 - Zip code + 4 07 - Point to Point Zip codes (private line transactions) 09 - Two-out-of-three test using Zip+4 as tax situs jurisdiction 11 - Used when Zipcode/Plus4 field is assigned as the Billing location and P2PZipcode/P2PPlus4 assigned as Service location 14 - Use Zip code field for international country code (VAT calculations ) 17 - Point to Point Zip codes (private line transactions) with both A and Z endpoints calculated |
|
Transaction Type Code | TransTypeCode | Product Identifer or SureTax TransTypeCode accepted or Product Group Product Item (PGPI). Max Length: 50 |
|
Sales Type Code | SalesTypeCode | Describes the type of customer. Values: R - Residential customer (default) B - Business customer I - Industrial customer L - Lifeline customer T - Retail customer |
|
Regulatory Code | RegulatoryCode | Type of service being provided. Values: 00 - ILEC 01 - IXC 02 - CLEC 03 - VoIP 04 - ISP 05 - Wireless |
|
Tax Exemption Codes | TaxExemptionCodeList | Tax Exemption to be applied to this item only. Tax Exemption Record Indicators for values To enter a partial exemption, enter the exemption indicator followed by the percentage as a decimal. For example, enter "02:.25" for state tax (02) and 25%. |
|
Tax Exempt Reason Code | ExemptReasonCode | Used only if you are adding exemption certificate information into the system Tax Exemption reason value. See Exemption Reason Codes for values. |
|
Cost Center | CostCenter | Available for use in the rules engine. Max Length: 25 Alphanumeric |
|
GL Account | GLAccount | Available for use in the rules engine. Max Length: 25 Alphanumeric |
|
Material Group | MaterialGroup | Available for use in the rules engine. Max Length: 25 Alphanumeric |
|
Origination Country Code | OriginCountryCode | Origination Country Code. (ISO Country Code) Max Length: 2 Alphanumeric |
|
Destination Country Code | DestCountryCode | Destination Country Code. (ISO Country Code) Max Length: 2 Alphanumeric |
|
Parameter 1 | Parameter1 | User defined field. Available for use in the rules engine. Max Length: 25 Alphanumeric |
|
Parameter 2 | Parameter2 | User defined field. Available for use in the rules engine. Max Length: 25 Alphanumeric |
|
Parameter 3 | Parameter3 | User defined field. Available for use in the rules engine. Max Length: 25 Alphanumeric |
|
Parameter 4 | Parameter4 | User defined field. Available for use in the rules engine. Max Length: 25 Alphanumeric |
|
Parameter 5 | Parameter5 | User defined field. Available for use in the rules engine. Max Length: 25 Alphanumeric |
|
Parameter 6 | Parameter6 | User defined field. Available for use in the rules engine. Max Length: 25 Alphanumeric |
|
Parameter 7 | Parameter7 | User defined field. Available for use in the rules engine. Max Length: 25 Alphanumeric |
|
Parameter 8 | Parameter8 | User defined field. Available for use in the rules engine. Max Length: 25 Alphanumeric |
|
Parameter 9 | Parameter9 | User defined field. Available for use in the rules engine. Max Length: 25 Alphanumeric |
|
Parameter 10 | Parameter10 | User defined field. Available for use in the rules engine. Max Length: 25 Alphanumeric |
|
Currency Code | CurrencyCode | Currency code based on ISO standard. As reference - http://www.xe.com/iso4217.php |
|
User defined field | UDF | User defined field. Not available for use in the rules engine, but is available for use in reports and extracts. Max Length: 100 |
|
User defined field 2 | UDF2 | User defined field. Not available for use in the rules engine, but is available for use in reports and extracts. Max Length: 100 |
|
Billing Address | BillingAddress | Billing address for transaction - see Address Layout definition below. | |
P2P Address | P2PAddress | P2P address for transaction - see Address Layout definition below. |
Address Layout:
Field | Field Name | Description |
---|---|---|
Primary Address Line | PrimaryAddressLine | Address Line 1 |
Secondary Address Line | SecondaryAddressLine | Address Line 2 |
County | County | County |
City | City | City |
State | State | State - full state name or two character abbreviation accepted |
PostalCode | PostalCode | ZIP code or Canadian postal code |
Plus4 | Plus4 | ZIP+4 |
Country | Country | International country ISO code value in format: XX |
CCH Geocode | Geocode | If provided, the CCH Geocode will take precedence and will be used instead of the address / ZIP+4 information. |
Verify Address | VerifyAddress | This feature is currently disabled. Pass 0. |
Examples
request={
"ClientNumber": "<CLIENTNUMBER>",
"ValidationKey": "<VALIDATIONKEY>",
"DataYear": "2022",
"DataMonth": "01",
"CmplDataYear": "2022",
"CmplDataMonth": "01",
"TotalRevenue": "1000",
"ReturnFileCode": "Q",
"ClientTracking": "",
"ResponseGroup": "00",
"ResponseType": "D6",
"STAN": "",
"ItemList": [{
"LineNumber": "1",
"InvoiceNumber": "INVOICE01",
"CustomerNumber": "CUSTOMER01",
"OrigNumber": "",
"TermNumber": "",
"BillToNumber": "",
"TransDate": "08-01-2019",
"BillingPeriodStartDate": "",
"BillingPeriodEndDate": "",
"Revenue": "2019",
"Units": "1",
"UnitType": "00",
"Seconds": "1",
"TaxIncludedCode": "0",
"TaxSitusRule": "04",
"TransTypeCode": "010101",
"SalesTypeCode": "R",
"RegulatoryCode": "99",
"TaxExemptionCodeList": [""],
"ExemptReasonCode": "None",
"CostCenter": "",
"GLAccount": "",
"MaterialGroup": "",
"CurrencyCode": "",
"OriginCountryCode": "",
"DestCountryCode": "",
"BillingDaysInPeriod": 0,
"Parameter1": "",
"Parameter2": "",
"Parameter3": "",
"Parameter4": "",
"Parameter5": "",
"Parameter6": "",
"Parameter7": "",
"Parameter8": "",
"Parameter9": "",
"Parameter10": "",
"UDF": "",
"UDF2": "",
"Address": {
"PrimaryAddressLine":"10772 Main St Ste 1",
"SecondaryAddressLine":"",
"County":"",
"City":"Roscoe",
"State":"IL",
"PostalCode":"61073",
"Plus4":"0000",
"Country":"US",
"Geocode":"",
"VerifyAddress":"0"
},
"P2PAddress": {
"PrimaryAddressLine":"10772 Main St Ste 1",
"SecondaryAddressLine":"",
"County":"",
"City":"Roscoe",
"State":"IL",
"PostalCode":"61073",
"Plus4":"0000",
"Country":"US",
"Geocode":"",
"VerifyAddress":"0"
}
}]
}
Respopnse Layout
CCH SureTax supports taxes to be returned by Line Item in addition to Customer Number, Invoice Number and Location Code. The response message also includes additional detail values for each of the taxes applied to the line items.
Response Header
FIELD NAME | DESCRIPTION |
---|---|
Successful | Response will be either "Y" or "N": Y = Success / Success with Item errorN = Failure |
ResponseCode | ResponseCode: 9999 - Request was successful.1101-1400 - Range of values for a failed request (no processing occurred). 9001 - Request was successful, but items within the request have errors. The specific items with errors are provided in the ItemMessages field. |
HeaderMessage | Response message: For ResponseCode 9999 - "Success"For ResponseCode 9001 - "Success with Item errors". See the ItemMessages field for a list of items / errors. For ResponseCode 1100-1400 - Unsuccessful / declined web request. See Response Code and Messages for a list of the response code and messages. |
ItemMessages | This field contains a list of items that were not able to be processed due to bad or invalid data (see Response Code of "9001"). These invalid items will be listed by line number with the corresponding response code and message. When an item error occurs, no tax processing will occur for that item record. When an error for an item occurs, this field contains the following fields:LineNumber - a value corresponding to the line number in the web request. ResponseCode - a value in the range 9100-9400.Message - the error message corresponding to the ResponseCode. See Response Code and Messages for a list of the response code and messages.If no item errors exist, the field will have a value of empty. |
ClientTracking | Client transaction tracking provided in web request. |
TotalTax | Total Tax - a total of all taxes included in the TaxList |
TransId | Transaction ID (integer) - Unique identifier for your transaction provided by CCH SureTax |
STAN | Unique System Trace Audit Number |
MasterTransId | The "master" SureTax TransID assigned to an in-progress transaction |
GroupList | See Group (contains one-to-many Groups) |
Group
FIELD NAME | DESCRIPTION |
---|---|
LineNumber | Line Number (from Request) |
StateCode | Tax State |
InvoiceNumber | Invoice Number (from Request) |
CustomerNumber | Customer number (from Request) |
LocationCode | Location code (from Request) |
TaxList | See Tax Item(s) - contains one-to-many Tax Items |
TaxItem(s)
FIELD NAME | DESCRIPTION |
---|---|
TaxTypeCode | Tax Type Code See Appendix E - Response Code and Messages for a list of the response code and messages. |
TaxTypeDesc | Jurisdiction-specific Tax Type Description |
TaxAmount | Tax Amount |
Revenue | Source Revenue for Line Item |
CountyName | County Name of taxing jurisdiction |
CityName | City Name of taxing jurisdiction |
TaxRate | Tax rate for tax type applied in decimal format (if zero, see FeeRate) |
PercentTaxable | Percentage of the tax that is taxable for the tax type in decimal format. This can be less than 100% in certain circumstances. |
FeeRate | The unit based fee for the tax type in format $.CCCC (if zero, see TaxRate) |
RevenueBase | The effective revenue for the tax provided in the TaxAmount field. This amount can be different than the amount in the Revenue field when taxes are impacted by specific exemptions and/or tax on tax. |
TaxOnTax | The amount of tax on tax attributed to the final amount of tax. Note this amount is included in the TaxAmount field total and is provided here separately only for reference purposes. |
TaxAuthorityID | The ID of the Tax Authority associated with the tax (CCH SureTax defined value) |
TaxAuthorityName | The name of the Tax Authority associated with the tax |
Juriscode | The jurisdictional code associated with the tax (usually used for return compliance purposes) |
Examples
{
"ClientTracking": "",
"GroupList": [{
"CustomerNumber": "CUSTOMER01",
"InvoiceNumber": "INVOICE01",
"LineNumber": "1",
"LocationCode": "",
"StateCode": "IL",
"TaxList": [{
"CityName": "ROSCOE",
"CountyName": "WINNEBAGO",
"FeeRate": 0,
"Juriscode": "",
"PercentTaxable": 1.0,
"Revenue": "2019.0000",
"RevenueBase": "2077.6000",
"TaxAmount": "2.0776",
"TaxAuthorityID": "12013",
"TaxAuthorityName": "ILLINOIS, STATE OF",
"TaxOnTax": "0.0586",
"TaxRate": 0.001,
"TaxTypeCode": "108",
"TaxTypeDesc": "IL PUC FEE"
},
{
"CityName": "ROSCOE",
"CountyName": "WINNEBAGO",
"FeeRate": 0,
"Juriscode": "",
"PercentTaxable": 1.0,
"Revenue": "2019.0000",
"RevenueBase": "2037.8554",
"TaxAmount": "41.7903",
"TaxAuthorityID": "12013",
"TaxAuthorityName": "ILLINOIS, STATE OF",
"TaxOnTax": "0.3867",
"TaxRate": 0.020507,
"TaxTypeCode": "126",
"TaxTypeDesc": "IL UNIVERSAL SERV. FUND CHARGE"
},
{
"CityName": "ROSCOE",
"CountyName": "WINNEBAGO",
"FeeRate": 0,
"Juriscode": "",
"PercentTaxable": 1.0,
"Revenue": "2019.0000",
"RevenueBase": "2035.7786",
"TaxAmount": "142.5045",
"TaxAuthorityID": "12013",
"TaxAuthorityName": "ILLINOIS, STATE OF",
"TaxOnTax": "1.1745",
"TaxRate": 0.07,
"TaxTypeCode": "127",
"TaxTypeDesc": "IL STATE EXCISE TAX"
},
{
"CityName": "ROSCOE",
"CountyName": "WINNEBAGO",
"FeeRate": 0,
"Juriscode": "",
"PercentTaxable": 1.0,
"Revenue": "2019.0000",
"RevenueBase": "2035.7800",
"TaxAmount": "10.1789",
"TaxAuthorityID": "12013",
"TaxAuthorityName": "ILLINOIS, STATE OF",
"TaxOnTax": "0.0839",
"TaxRate": 0.005,
"TaxTypeCode": "129",
"TaxTypeDesc": "IL STATE IMF"
},
{
"CityName": "ROSCOE",
"CountyName": "WINNEBAGO",
"FeeRate": 0,
"Juriscode": "10100075",
"PercentTaxable": 1.0,
"Revenue": "2019.0000",
"RevenueBase": "2035.7783",
"TaxAmount": "122.1467",
"TaxAuthorityID": "10056",
"TaxAuthorityName": "ROSCOE, CITY OF",
"TaxOnTax": "1.0067",
"TaxRate": 0.06,
"TaxTypeCode": "337",
"TaxTypeDesc": "SIMPLIFIED MUNI TELECOMM TAX"
},
{
"CityName": "ROSCOE",
"CountyName": "WINNEBAGO",
"FeeRate": 0,
"Juriscode": "",
"PercentTaxable": 1.0,
"Revenue": "2019.0000",
"RevenueBase": "2019.0012",
"TaxAmount": "16.7779",
"TaxAuthorityID": "16",
"TaxAuthorityName": "FEDERAL COMMUNICATIONS COMMISSION",
"TaxOnTax": "0.0000",
"TaxRate": 0.00831,
"TaxTypeCode": "060",
"TaxTypeDesc": "FEDERAL COST RECOVERY FEE"
}]
}],
"HeaderMessage": "Success",
"ItemMessages": [],
"MasterTransId": 8,
"ResponseCode": "9999",
"STAN": "",
"Successful": "Y",
"TotalTax": "335.4759",
"TransId": 8
}