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 SureAddress API you'll need an active SureAddress Account. With your account you'll be provided a SureAddress Client Number and Validation Key.
Environments
SureAddress 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 accidentally affecting production data.
CERT - URL: https://testapi.sureaddress.net/
This is your SureAddress 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 SureAddress CERT environment and provided written sign off to our SureAddress implementation team, you will be allowed access to migrate to PRODUCTION.
NOTE: SureAddress' 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 - URL: https://api.sureaddress.net/
This is your live SureAddress account. This account will not be initially active 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 CERT environment and provided written sign off to our SureAddress 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.
Method Definitions
Validation Request - SoapRequest (SOAP) / PostRequest (REST) - This method is used to validate an address through the SureAddress API.
Validation Batch Request - SoapRequestBatch (SOAP) / PostRequestBatch (REST) - This method is used to batch validate multiple addresses through the SureAdddress API.
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={
If you want the JSON request to be serialized, the request value would be supplied as: {"request":'
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 SureAddress API. SOAP clients can handle the generation of the SOAP request, send the data to the SureAddress application, and then convert the data back to the programming interface so that you can use the objects in your application. The SureAddress API has a WSDL that describes its web service. The SureAddress General API WSDL can be located at:
For example environment URL for CERT and PROD would be:SOAP
CERT: https://testapi.sureaddress.net/sureaddress.asmx?wsdl
PROD: https://api.sureaddress.net/sureaddress.asmx?wsdl