General Overview

This document is intended for developers of SureTax customers who want to consume one or more SureTax Services directly.

SureTax services allow the users to communicate with the calculation engine to perform a particular task within the SureTax application (e.g., calculation of tax liability). In order to perform these tasks, you need to consume the services.

This Application Programming Interface (API) document defines the structures and methods that are used in the CCH SureTax tax rating and calculation system. The CCH SureTax system can be used for tax calculation of product and services on a "real-time" basis by submitting web request/response messages via Internet services using REST or SOAP.

With the API, the request interface is an object in your application's native programming language. Clients are available in different programming languages. Most modern software languages have SOAP/REST toolkits to generate native programming code for the API consumption. Your application can process these generated object properties, and it can send and receive the data by calling the object methods.

Please note that the current implementation is synchronous, where a response is provided for each request submitted. Each request can contain one-to-many items (transaction records) which can correlate multiple customers and/or invoices.

Connecting to the API

In order to communicate with the SureTax API you'll need an active SureTax Account. With your account you'll be provided a SureTax Client Number and Validation Key.

Environments

SureTax provides two different environments for every new account: CERT and PRODUCTION. They are completely separate environments, and each is provisioned its own credentials. We keep CERT and PRODUCTION credentials separate to help you test your software in without the risk of accidentially affecting production data.

CERT

https://testapi.taxrating.net/

This is your SureTax Sandbox/Certification environment. All new customers will begin their development, setup and tax calculation configuration in this environment. After you have performed your user acceptance testing in the SureTax CERT environment and provided written sign off to our SureTax implementation team, you will be allowed access to migrate to PRODUCTION.

Note

SureTax's CERT environment architecture is not as robust and load balanced as our PRODUCTION environment. As you are testing your integration, we ask that do you do not perform any stress or load testing against our CERT environment. It will not be a true representation of PRODUCTION and CERT will be unable to withstand the load.

PRODUCTION

https://api.taxrating.net/

This is your live SureTax account. This account will not be initially actived when your accounts are created. All initial configuration and setup is performed in your CERT account. After you have performed your user acceptance testing in the SureTax CERT environment and provided written sign off to our SureTax implementation team, you will be allowed access to migrate to PRODUCTION. Your implementation team will assist in copying any configuration over from CERT into your PRODUCTION account prior to account activation.

REST

For web requests submitted via REST, the data should be formatted using either JSON or XML format. The response format type is the same as the request format.

When supplying the request as a POST variable, the request value would be supplied as: request={<JSON or XML>} The Headers Content-Type value would be provided as: "Content-Type:application/x-www-form-urlencoded".

If you want the JSON request to be serialized, the request value would be supplied as: {"request":'<JSON>'} The Headers Content-Type value would be provided as: "Content-Type:application/json". This response will be returned wrapped in a "d" object. The object response will contain additional backslashes to escape double quotes around field names and values.

JSON
XML

For information on the JSON format - http://en.wikipedia.org/wiki/JSON

Note

When supplying the JSON string as a POST variable, the request value would be supplied as "request={..JSON...}". The Headers ContentType value would be provided as: "Content-Type:application/x-www-form-urlencoded".

When supplying JSON serialized, the request value would be supplied as: {"request":...JSON..."}. The Headers Content-Type value would be provided as: "Content-Type:application/json". This response will be returned wrapped in a "d" object. For more information on this approach, please see the following article: http://encosia.com/a-breaking-change-between-versions-of-aspnet-ajax/#comment-34045

Note

The XML that is returned from CCH SureTax is processed through the Microsoft.NET XMLSerializer. As such, the returning XML data is html encoded ( http://www.w3.org/TR/2004/REC-xml-20040204/#syntax ) and converted to a well-formed XML that is readily transported. On the client receiving end, the data should be deserialized / decoded to reconstruct the XML object from the stream. For example, the actual XML data submitted from CCH SureTax will resemble:

<?xml version="1.0" encoding="utf-8"?>
<string xmlns="http://tempuri.org/">&lt;?xml version="1.0"?&gt; &lt;Response xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"&gt;
&lt;ExtensionData /&gt;
&lt;Successful&gt;Y&lt;/Successful&gt;
&lt;ResponseCode&gt;9999&lt;/ResponseCode&gt;
&lt;HeaderMessage&gt;Success&lt;/HeaderMessage&gt;
&lt;ItemMessages /&gt;

Users of low-level languages should be aware of this methodology as it might require a parsing routine to convert the serialized codes. For example the code "&lt" should be converted to "<".

SOAP

For requests submitted via SOAP, responses are provided in same XML format as the request. The SOAP API schema defines the SOAP messages that you can use to access the SureTax API. SOAP clients can handle the generation of the SOAP request, send the data to the SureTax application, and then convert the data back to the programming interface so that you can use the objects in your application.

The SureTax API has a WSDL that describes its web service. The SureTax Communications API WSDL can be located at: <environment url>/Services/Communications/V01/SureTax.asmx?wsdl

For example environment URL for CERT and PROD would be:

CERT: https://testapi.taxrating.net/Services/Communications/V01/SureTax.asmx?wsdl

PROD: https://api.taxrating.net/Services/Communications/V01/SureTax.asmx?wsdl

Tax Situs Options

Telecomm situs in the U.S. is predominantly a choice between the following 2 options:

Tax Situs rule "05" for Zip Plus 4
Tax Situs rule "04" for 5-digit Zip Code

Zip Plus 4 is the preferred option, as it is more accurate.

Both monthly recurring charges (MRCs), and non-recurring charges (NRCs) such as connection/disconnection, are treated the same for this purpose.

However, MRCs are not necessarily treated the same as NRCs such as Usage.

When it comes to VoIP Usage, for example, if you want to determine the intrastate vs. interstate nature of the call, you will need to use Situs Rule "09", 2-out-of-3 Rule Using Billed To Zip+4. On the other hand, if you are not doing call rating of the VoIP Usage on a call by call basis, rather leaving the Usage as Undetermined, Situs Rules "05" or "04" are used, as mentioned above.

Point to Point (P2P) transactions are a whole new ballgame, as follows:

Tax Situs rule "07" - Point to Point zip codes (Private Line transactions).
Tax Situs rule "17" - Point to Point zip codes (Private Line transactions).- Both Points Evaluated

Unlike most telecommunications services, the tracking of which entails mapping charges to a single sourcing location or service address, a sale of private-line service is unique in that, in most cases, two destinations are involved. Thus, for point-to-point private-line service, both endpoints have to be provided in order to determine the collective tax liability of a given private line. As such, the default calculation of Private Line services (Line Charge, Connection/Disconnection and Service Charges) is a 50% percent taxable factor on all taxes and surcharges for each point of the private line.

Hence, the user's billing system must be programmed, first to calculate the tax liability for Point A of the private line, followed by running an identical tax calculation for Point Z of the same private line. This requires two sets of transactions to be provided to CCH SureTax; one for Point A to Point Z, and a second for Point Z to Point A using the Zip Code and P2P Zip Code fields.

Unlike Tax Situs rule "07", Tax Situs rule "17" computes both endpoints of the private line with one input request. As such, one request generates two response lines with different taxing jurisdictions.

For the need to calculate Value Added Tax ("VAT") and VAT related Situs rules please consult your professional services team.

Documentation standards

Note

Field names formatted in BOLD are required fields that must be passed to SureTax API.
All Field Names are case-sensitive.
Field values are required unless otherwise noted in their description below.