Skip to main content
Avalara Help Center

AvaTax for Communications SaaS Standard user manual

Introduction

AvaTax for Communications (AFC) SaaS Standard is a tax-rating service bureau. It provides the necessary link to allow you to transfer files to and from Avalara for processing by the AFC server. AFC SaaS Standard provides two ways to connect to the AFC server - by using a secure file-transfer protocol (SFTP) connection through an existing account and typing ‘ftp.billsoft.com’ at the prompt within the SFTP session or by connecting to the web interface at https://ftp.billsoft.com.

For sample files and ftp scripts, see the samples folder and other resources at this URL: https://github.com/Avalara/Communications-Developer-Content/tree/master/afc_saasstd_tax.

Once your file has been uploaded to the server, AFC begins immediate processing of your data. AFC SaaS Standard and the AFC server are online - 24 hours a day, 7 days a week - to process your data.

Naming Files

Uploaded files MUST be named using the following naming conventions for the base name of the file.

KML150117AA.{ext}

  • KML: 3 letter company code
  • 15: Year the file is to be uploaded
  • 01: Month in which you are processing
  • 17: The day of the month the file was created
  • AA: Unique identifier that allows for better tracking and maintaining of these files
  • T: Special Designator indicating the file is a test run and should not be included in compliance filing. This is not required but is a good practice as it allows production reports and test reports to be distinguished.

Note: In addition to the naming convention guidelines, please be aware that the maximum allowed length for a file name is 19 bytes.

The following formats / extensions are supported:

  • Extended Formats
    • Excel .xls,.xlsx
    • Comma-Separated .csv ABC151116AA.CSV
  • Fixed Format
    • Customer Detail File .cdf

When uploading your file to the online FTP site (see Uploading the ftp.zip), it must be compressed (i.e., “zipped”) into a file named ftp.zip in order to be processed automatically.

Compliance Month

The filename is generally the best approach for identifying which tax month the request applies to. If the billing cycle is for October 2015, then the name ABC1510NN would allow multiple submissions to be aggregated together for compliance filing.

General Rules:

  • Do not mix transactions from different billing cycles in the same request.
  • Designate test data by adding a T to the filename. For example, if ABC1510NN is the normal designation, use ABC1510NNT for testing.

AFC FTP Site

Accessing the FTP Site

AFC SaaS Standard provides two ways to connect to the AFC FTP server - by using a secure file-transfer protocol (SFTP) connection through an existing account and typing ‘ftp.billsoft.com’ at the prompt within the FTP session, or by connecting to the web interface at https://ftp.billsoft.com.

Note Concerning FTP Client Software

Please be aware that web browsers (Microsoft Internet Explorer, Firefox, etc.) cannot be used for uploading and downloading files via SFTP to the AFC FTP site. A FTP client application must be used to transfer files to and from the AFC FTP site when using our service as SFTP.

Windows users:

Microsoft does not currently include convenient FTP client software in its operating systems. It is assumed you either own a third-party FTP client application such as WS_FTP (a shareware version of which can be downloaded from http://www.ipswitch.com), or that you are comfortable accessing FTP sites using command-line syntax.

Linux users:

If using a Linux system to transfer your call-data files, you can use any number of free FTP clients to contact the AFC FTP site, such as WXFTP, or you can use command-line syntax.

Logging on to the FTP Site

To log on to the AFC FTP site, you will need the following information:

HOSTNAME/ADDRESS: ‘ftp.billsoft.com’ within a SFTP session or via the web at https://ftp.billsoft.com

USER ID: Your User ID is created and provided to you. Please refer to the Welcome to Avalara email or submit a support case for your organization’s assigned User ID.

PASSWORD: Your organization’s login password is also provided by your Avalara technical support contact. For future reference, you may make note of your login details in spaced provided below.

  • User ID:
  • Password:
  • Company Code:

Submitting a Request

A single ftp.zip file will be submitted containing one and only one primary file and one or more optional files.

General Submission Rules

  • Files submitted must be at the root-level within the zip file and cannot contain any other folders.
  • The data must be compressed before you upload it for processing. The AFC FTP server uses PK- Zip/PK-Unzip version 2.04 for compressing and decompressing files. If you prefer using a Windows-based compression utility, you can use a product such as WinZip, which is compatible with the version 2.04 of PK-Zip/PK-Unzip.
  • An account can only process a single request at a time. If additional requests are received before the first request has been completed, they will be rejected.

Primary File – Transaction Batch Data

The primary file contains all transactions to be processed and can be either Fixed Format (.cdf) or Extended Format (.csv/Excel). The naming convention for the primary file must be named correctly and uniquely. Submitting the same file name will cause the file to be rejected.

  • The 1st through the 3rd characters in the filename should begin with your company's three-letter code.
  • The 4th and 5th characters in the filename should be the current year (2-digits).
  • The 6th and 7th characters are the current month.
  • The 8th and 9th characters are the current day.
  • The 10th through the 13th characters are your unique files identifiers. Please note that ‘T’ is reserved for test files.
  • The final character must be ‘T’ if this a test file. (optional or preferred)
  • The file extension must be a supported extension.

Thus, an example of a correctly named file is KML150117AA.CSV, where KML is the three-letter code for the company, 15 is the year, 01 is the month and 17 is the day. AA indicates it is the first file uploaded that day, and .CSV indicates it is a comma delimited file for processing by AFC. Refer to the Compliance Month section for additional details on compliance processing as well as the importance of naming for compliance purposes.

Extended Format – Excel, CSV

Extended format supports Excel and CSV (Comma-Separated Values) files. The contents and columns are identical and are discussed in Appendix A – Extended Format: Excel and CSV File Format for additional details. 

Fixed Format – CDF

The fixed format, or CDF format, supports a limited number of transaction options and is intended for basic transaction processing. Please refer to Appendix B – Fixed Format: CDF File Format for additional details.

Handling of Optional Files

Both Extended and Fixed format processing supports several different types of optional files that can be embedded in the zip file ftp.zip or persisted in your account.

Supported Optional Files

Type

Extension

Reference

Override File

.ovr

  • Specify a filename by naming the file with an .ovr extension.
  • To make the Override File a persisted file, please submit a support case to proceed.
  • To embed an Override File, place the Override File into your ftp.zip file along with an Extended Format input file.
  • Also, submit a support case for more information on the RLM (Rate and Logic Modifier) Tool for creating and/or maintaining override files.

Exemption File

.exm

  • Specify a filename by naming the file with an .exm extension.
  • To make the Exemption File a persisted file, please submit a support case to proceed.
  • To embed an Exemption File, place the Exemption File into your ftp.zip file along with an Extended Format input file.
  • Refer to Exemption File for additional details.

Bundle File

.bdl

  • Specify a filename by naming the file with a .bdl extension.
  • To make the Bundle File a persisted file, please submit a support case to proceed.
  • To embed a Bundle File, place the Bundle File into your ftp.zip file along with an Extended Format input file.
  • Submit a support case for more information on the Bundler Tool for creating and/or maintaining bundle files.

Exclusion File

.exc

  • Specify a filename by naming the file with an .exc extension.
  • To make the Exclusion File a persisted file, please submit a support case to proceed.
  • To embed an Exclusion File, place the Exclusion File into your ftp.zip file along with an Extended Format input file.
  • Refer to TM_00556_Exclusion File Formats for additional information or details.

CustomSort Configuration File

customsort.cfg

  • To make the customsort.cfg file a persisted file, please submit a support case to proceed. Note: Persisting the customsort.cfg file is the preferred method of generating the Custom Sort report.
  • To embed customsort.cfg, place the customsort.cfg file into your ftp.zip file along with the input file.
  • Refer to Section 1.2 of TM_00405_AFC Custom Sort Utility User Manual for additional information or details.

A request can be made to add a persisted optional file from an authorized representative of the owner of the account. Please submit a support case with the request, and make sure to attach the file. Your account will be updated with the persisted file, and it will apply to all future batch processing.

An embedded optional file is only applied to the current set of transactions contained within the ftp.zip file.

Order of handling – Persisted vs Embedded

When both a persisted optional file exists and the same type of optional file is embedded in the zip file, the embedded file will be used. This is designed to support clients testing new files or having special processing for certain batch files without having to update the persisted file.

Note: All optional files (embedded and persisted) used in the transactions are returned in the report zip.

Transferring Files To and From the FTP Site

Once you are connected to the AFC FTP site, you should change to the directory that has the same name as your company’s three-character code. You are now ready to send your file (which, again, must be named ftp.zip) for processing (see image below).

When successfully connected to the AFC FTP site and changed to your company's file- transfer directory, you can send your ftp.zip file for processing. You can ignore the index files.

Your uploaded file should begin processing within 30 seconds after you finish putting it on the FTP site.

When your file has finished processing, you can either download the output (or "result" file) from the AFC FTP or get it from the https://ftp.billsoft.com site.

This feature of the AFC SaaS Standard process allows your technical personnel to upload via SFTP and your destination personnel (accountant, etc.) to download the result files via the web interface.

The result file will have a similar name to the input file you uploaded, except that the first character after the three letter company code (in the file name) will be an "R" - indicating it is a result file. For example, if your uploaded ftp.zip file contained a file called KML150117AA.CSV, the result file (for downloading) would be called KMLR150117AA.ZIP.

If the input file you upload is small, you can simply remain connected to the FTP site and wait for the file to be processed. Otherwise, you should repeat the above steps to connect and log on to the FTP site, and you can then get your result file.

Tax Calculation Results

The following zip files would be produced if a file with the base name KML150117AA is uploaded.

KMLS150117AA.zip - Compliance Files

Compliance Files

File Name

Description

KML150117AA.ssf*

Summarized standard billable tax report.

KML150117AA.nba*

Summarized Non-billable tax report (as applicable).

KML150117AA.nca*

Summarized Non-compliance tax report (as applicable).

*This output file is also available in CSV format; however, the option to generate the CSV format or version must be turned on. To request this option, please submit a support case for assistance. Please note that the CSV formats are available in the Report Files output zip file

KMLR150117AA.zip - Report Files

Report Files

File Name

Description

KML150117AA.csf

Summarized fixed position customer info report. Produced for clients configured for standard compliance reporting.

KML150117AA.tsr*

Transaction/Service Jurisdiction Report. By default, all clients will receive the tsr report.

KML150117AA.tsr.csv**

KML150117AA._audit.tsr.csv***

KML150117AA.rtr

Tax Inclusive Transaction/Service Jurisdiction Report (as applicable). Produced if client has requested the rtr report.

KML150117AA._audit.rtr.csv***

KML150117AA _ASCIILOG.CSV

Contents of the tax data log converted to a comma-delimited text file with header row included. Refer to Section 5.3.1 asciilog.exe in TM_00101_AFC User Manual Telecom for more information on this report.

Note: Clients wishing to receive this report must submit the request via a support case for configuration to add this to the list of reports.

EZTax.license.rpt

Detailed version of the Transaction Count Report. Provides a count of transactions processed by transaction/service pair.

KML150117AA.ntl

Transaction/Service data that was processed but did not generate any taxes.

{output_filename_format}.rpt

Custom Sort report metrics. Provides details of the Custom Sort processing. {output_filename_format} is defined in customsort.cfg.

{output_filename_format}_nca.csv

Non-compliance Custom Sort Report (as applicable based on customsort.cfg settings). {output_filename_format} is defined in customsort.cfg.

{output_filename_format}_nba.csv

Non-billable Custom Sort Report (as applicable based on customsort.cfg settings). {output_filename_format} is defined in customsort.cfg.

{output_filename_format}_ssf.csv

Compliance Custom Sort Report. {output_filename_format} is defined in customsort.cfg.

KML150117AA.csv

Request in comma delimited format.

KML150117AA_Default.csv

Request defaults in comma delimited format (as applicable).

KML150117AA_conversion.rpt

Conversion report. Generated if input file is in Excel format. Convert excel to comma delimited.

KML150117AA_dtl.rpt

Detailed log report. This matches SaaS Pro detailed log report.

KML150117AA.CDF_dtl.csv

KML150117AA_dtl.rpt.csv**

KML150117AA_error.rpt

Processing error report. Produced if errors occur during processing. Report captures the specific error message and the input line that failed processing.

KML150117AA_summary.rpt

Processing summary report.

KML150117AA.ssf.csv**

Summarized standard billable tax report.

KML150117AA.nba.csv**

Summarized Non-billable tax report (as applicable).

KML150117AA.nca.csv**

Summarized Non-compliance tax report (as applicable).

*This output file is also available in CSV format; however, the option to generate the CSV format or version must be turned on. To request this option, please submit a support case for assistance.

**This CSV format version of the file is generated and sent in addition to the existing output format version only if the option has been activated.

***The audit version of the report contains two additional columns, Start Date and End date, which provide a timestamp for the report and headers for each column of data are included as well.

Note: All optional files (embedded and persisted) used in the transactions are returned in the report zip. Please reference Handling of Optional Files for additional information and details.

KMLE150117AA.zip - Status Files

Status Files

File Name

Description

Read_err.sta

Reports problems encountered while reading the input file. Problems might relate to invalid transaction/service type pairings or an invalid input file.

Taxer.sta

Reports status during taxing routines. Status messages pertaining to successful or unsuccessful insertion of overrides or jurisdiction not found.

Sorter.sta

Reports status during sorting routines. Status messages pertaining to successful or unsuccessful sort after taxation has occurred.

KML150117AA_converter.sta

Applies to excel input files. If an error occurs during conversion from Excel to csv format, this file will be generated with the error message.

KML150117AA_batch.sta

Status from batch processor. Outputs column mappings and any informational, warning or error level messages.

Customsort_log.sta

Reports status during custom sort processing. Contains processing steps for the sort and any errors that may have occurred.

Web Interface

AFC SaaS Standard is accessible via web interface at https://ftp.billsoft.com. Please follow the steps provided to log in.

Step

Action/Result

1

Type https://ftp.billsoft.com in the web browser. The home page appears.

2

Enter the username in the Username field.

3

Enter the password in the Password field.

4

Click Sign In. Once logged in, the File Manager window appears. You will be able to see all of the online products which your organization is currently subscribing to.

5

Select and click the appropriate client folder such as DMO, which is the example within the screenshot. All previous output files ran in previous days or sessions will also be visible after clicking on the folder. You can confirm this by viewing the date or timestamp for each.

Uploading the ftp.zip

Once on the web interface, follow the steps below to upload the ftp.zip file.

Note: Please be aware that some functions or options are disabled and cannot be clicked or selected. Disabled options are grayed-out in appearance and users do not have rights to access or utilize those particular functions.

Step

Action/Result

1

Click the green Add files option to open the Choose File to Upload window to your local directory or the location where the ftp.zip you previously created is stored.

2

Highlight and double-click the filename or click Open.

3

Click the blue Start upload or the blue Start option. The upload process will begin and status of your upload will appear as well as verification that the upload was successful near the top of the window shaded in green.

4

Once completed, the output files or results will appear (such as the one highlighted in blue in the screenshot.)

Retrieving Files

Please follow the steps provided below in order to retrieve or review files.

Step

Action/Result

1

View the completed files processed and locate the file with appropriate date and timestamp.

2

Highlight or double-click the file you wish to open.

3

Select the Save or Save as option in the window.

Note: The file must be saved. If the file is opened and closed without being saved, it will no longer be available on the FTP site to download and save for your records.

Notifications

The system is set up to automatically provide email notification of updated files and status; however, please submit a support case with any questions or for additional assistance with this feature.

Transaction Mapping Guidelines

AFC uses a system of numbers to represent the Transaction Types and Service Types for the service you wish to tax. Passing valid combinations of Transaction Type / Service Type pairs provides AFC part of the information necessary to produce the appropriate taxes for a specific jurisdiction.

For more information about mapping guidelines, see the document AFC Telecom Mapping Guidelines.

Frequently Asked Questions

I have a back log of data files I need processed. Can I send them all at once?

No. You can send only one file at a time, and you must wait for that data to be processed before uploading another file. Otherwise, you face the risk of the data from one file appending or even overwriting the data from another file.

 

I uploaded my file quite a while ago, and I still don't see any result file. What's wrong?

The most likely reason for this is an incorrect filename or an incorrect file format. The file must be in the correct format for the system to process it. Likewise, the file must be named correctly for the system to recognize it (see the appropriate sections in this manual regarding the naming of files). The filename can be especially tricky: the actual .CSV or Excel file and .ZIP file (as they appear on your system’s hard drive) must be named according to the afore-mentioned file-naming convention. Solution: if, after verifying your file is both formatted and named correctly, you are still having problems - call or email your Avalara technical support contact.

 

I’ve connected to the AFC FTP server, but I cannot view the contents of my directory.

If you’re unable to change directories, or if you are unable to list the contents of your transfer directory or transfer files to/from the FTP server, you are most likely being denied access to the AFC SaaS Standard server by a firewall or proxy server.

Can I use FTP instead of SFTP?

No. Effective 3/31/2020, SFTP is required to connect to ftp.billsoft.com via an FTP client. Non-secure FTP connections are not supported.

Support

Avalara strives to provide the very best in customer support. If you should need assistance or further information when contacting the AFC FTP site or transferring files, please submit a support case.

Appendix A – Extended Format: Excel and CSV

See the AvaTax for Communications SaaS Standard file format guidelines for detailed information.

Appendix B – Fixed Format: CDF

The CDF file format is currently available. Please reference the table provided below for additional details on this format.

CDF Client Input Data Specification

Opt/Req

Sec

Data Description

Type

Len

Positions

Default

Note

R

J

Origination

N

10

0-9

 

Originating NPANXX if flag=N

Originating PCode if flag=P

Originating State code if flag=S (numeric value)

R

J

Origination Flag

A

1

10

 

Set to N if using NPANXX, P if using PCode, or S if using State code

R

J

Termination

N

10

11-20

 

Terminating NPANXX if flag=N

Terminating PCode if flag=P

Terminating State code if flag=S (numeric value)

R

J

Termination Flag

A

1

21

 

Set to N if using NPANXX, P if using PCode, or S if using State code

R

J

Service Address

N

10

22-31

 

Service (BTN) NPANXX if flag=N

Service PCode if flag=P

Service State code if flag=S (numeric value)

R

J

Service Address Flag

A

1

32

 

Set to N if using NPANXX, P if using PCode, or S if using State code

R

C

Customer Type

A

1

33

B

Business, Residential Customer, Industrial, or Senior Citizen

R

T

Invoice Date

N

8

34-41

 

Format "CCYYMMDD"

R

T

Taxable Amount Sign

A

1

42

 

Format "+", "-", “p” or “m”

R

T

Taxable Amount

N

11.5

43-53

 

Format "99999999999"

Zero-Filled, 5 decimal places, no decimal point

R

T

Lines

N

6

54-59

0

6-character integer

R

T

Location

N

6

60-65

0

6-character integer

R

T/S

Transaction Type

A/N

6

66-71

 

See TM_00115_AFC Transaction and Service Types

R

T/S

Service Type

A/N

6

72-77

 

See TM_00115_AFC Transaction and Service Types

R

T

Client Resale Flag

A

1

78

S

Call subject to Sale or Resale

 

R

 

C

 

Inc-Code

 

A

 

1

 

79

 

I

Customer is Inside or Outside an incorporated city area

R

C

Fed. Exempt

A

1

80

Blank

Call is exempt from Federal taxes

R

C

State Exempt

A

1

81

Blank

Call is exempt from State taxes

R

C

County Exempt

A

1

82

Blank

Call is exempt from County taxes

R

C

Local Exempt

A

1

83

Blank

Call is exempt from Local taxes

O

C

Customer Number 

(Primary Output Key)

 

A/N

 

20

 

84-103

 

Defines primary Key for Client Summary Data

R

CO

Regulated / Unregulated Flag

A

1

104

R

Reseller is Regulated or Unregulated in the state of sale

R

T

Call Duration (in minutes)

N

11.1

105-115

 

Format "99999999999"

Zero-Filled, 1 decimal place, no decimal point

R

T

Telecom Type

A

1

116

C

C – Calls (telcom), D-Debit Card Calls, P-Point of sale

R

C

service class indicator

A

1

117

D

Long Distance or Local primary (D or L)

O

C

Lifeline flag

A

1

118

Blank

L - lifeline customer (Blank or l)

R

CO

facilities-based flag

A

1

119

N

Facilities-based or Non Facilities-based (F or N)

R

CO

franchise flag

A

1

120

N

Franchise or Non-Franchise (F or N)

R

C

business class indicator

A

1

121

C

CLEC or ILEC (C or I)

Appendix C – AFC Error Codes

A list of AFC error codes and descriptions for each are provided in the table below.

AFC Error Code

Message/Description

0

Backend System Error. Error details will be included in the error message.

-11

JCode not found.

-12

PCode not found.

-13

Zip code not found.

-14

NPANXX not found.

-15

Address not found.

-16

County, State, Zip not found.

-17

Session not initialized.

-18

JCode database not open.

-19

PCode database not open.

-20

ZipCode database not open.

-21

NPANXX database not open.

-22

Address database not open.

-23

Jurisdiction not found.

-24

FIPS not found.

-25

FIPS (to PCode) cross-reference database not open.

-26

PCode (to FIPS) cross-reference database not open.

-27

Invalid transaction date.

-28

Invalid transaction/service pair.

-29

Log name not set.

-32

Transaction/service pair is not supported by the API call.

-34

Transaction/Service pair is not licensed for user.

-35

System error allocating memory for internal tables.

-36

Split for private line transaction if either < 0 or > 1.

-37

Insufficient charge supplied to cover taxes generated.

-38

Tax-on-tax exceeded maximum iterations.

-39

Custom log size exceeds max allowed size.

-40

Exclusion is invalid.

-41

Bridge conference data is invalid.

-42

Safe Harbor Type is invalid.

-43

Safe Harbor federal fraction is invalid.

-44

Total distinct tax items for bundled package exceeded.

-45

Total of fixed charges exceeds bundle charge.

-46

Transaction/Service pair not in bundle table.

-47

Bundle Transaction/Service pair has bad syntax.

-48

Cannot determine call type for International calls.