Web Service:
Electronic
File Submission
The Web Service process will utilize a SOAP (1.1 or
1.2) based Web Service in order to allow for electronic submission
of properly formatted wage files. In order to use this service, clients
will have to download the WSDL (Web Service Description Language)
and build a custom client.
The WSDL file can be downloaded from the following site:
https://www.uitax.dol.ks.gov/KUITax/KUITaxWebService.asmx?WSDL
Note: When the production
version is released, no uploaded records will be processed until they
have been committed using the "CommitValidRecords" method.
Web Service Methods
Method: SubmitTestFile()
The input parameter(s) are as follows:
|
Parameter
|
Type
|
Required
|
Length min/max
|
Description
|
| FileContent |
ByteArray |
Yes |
N/A |
Binary representation of a file.
|
| FileType |
Enumeration |
Yes |
NA / NA |
Identifies the type of file submitted. The 4 valid file types are MMREF, NASWA, Payment, and Rate. |
| FileName |
String |
Yes |
5 / 75 |
The filename and extension used for the data file. This is used to ID the file on the server as well as extension for the compression used. |
The Return value(s) are as follows:
|
Type
|
Length min/max
|
Description
|
| String |
1-120 |
Unique transaction identifier
|
If all the above parameters pass the validation processses
this method will return a unique transaction identifier (UTID) which
is a unique string. This UTID will be used in subsequent calls. If
a failure occurrs the web service will generate a SOAP Fault with
a descriptive error message and will need to be handled by your SOAP
client. In the case of submitting a test file, the file will be validated
but will not be processed. In order to actually
submit your data to the Kansas Department of Labor, you must use the
SubmitFile() method.
Method: SubmitFile()
The input parameter(s) are as follows:
|
Parameter
|
Type
|
Required
|
Length min/max
|
Description
|
| FileContent |
Byte |
Yes |
N/A |
Binary representation of file.
|
| FileType |
Enumeration |
Yes |
NA / NA |
Identifies the type of file submitted. The 4 valid file types are MMREF, NASWA, Payment, and Rate. |
| FileName |
String |
Yes |
5 / 75 |
The filename and extension used for the data file. This is used to ID the file on the server as well as extension for the compression used. |
The Return value(s) are as follows:
|
Type
|
Length min/max
|
Description
|
| String |
1-120 |
Unique transaction identifier
|
If all the above parameters pass the validation processses
this method will return a unique transaction identifier (UTID) which
is a unique string. This UTID will be used in subsequent calls. If
a failure occurrs the web service will generate a SOAP Fault with
a descriptive error message and will need to be handled by your SOAP
client.
Method: GetStatus()
The input parameter(s) are as follows:
|
Parameter
|
Type
|
Required
|
Length min/max
|
Description
|
| UTID |
String |
Yes |
N/A |
This Unique transaction identifier that was returned by the SubmitFile()
or SubmitTestFile() method. The UTID used to identify the file
that was submitted.
|
The Return value(s) are as follows:
|
Type
|
Length min/max
|
Description
|
| String |
1-30 |
Status value describing what state the current transaction
is in.
|
If a valid UTID is passed in, the status of the submission
will be returned. If an invalid UTID is passed, status of "InvalidUTID"
is returned. If for some reason something failed the web service will
generate a SOAP Fault with an error message that will need to be handled
by your SOAP client.
| Status |
Description |
| DataTransferError |
Indicates there was an error transferring the file
from the client machine the Kansas Department of Labor server.
|
| InvalidUTID |
Indicates that the UTID passed does not exists
in our system. |
| InvalidFileType |
Indicates an incorrect action on a given file
type. Only MMREF, NASWA and Payment files may be committed.
A Rate file may only be used for a RateRequest. |
| DataContentError |
Indicates there was an error with the submitted
file. Possibilities of errors could include the file was too large,
unreadable, used an incorrect character set, was found to contain
malicious content, or too large of a filename was used. |
| Validating |
Indicates the file submission has been received
and the KDOL system is currently validating the data submitted.
. |
| DataValidationFailed |
Indicates that all of the data contained in the
file submission was not valid. Use the GetUploadDetail() method
for more details. |
| DataLoadFailed |
Indicates there was an error loading the file information
into the Kansas Department of Labor system. If this error occurs
you are encouraged to try resubmitting the file. |
| Submitted |
Indicates the file submission was a success and
the Kansas Department of Labor has successfully received the wage
information and at least one employer record is valid. You can
use GetUploadDetail() method to view invalid employer records.
If you would like to go ahead and submit employer records that
were valid, use the CommitValidRecords() method. |
| Committing |
Indicates data from the file submission is currently
being committed and loaded into the KDOL system. |
| Committed |
Indicates the the records have been committed and
will be processed shortly. Nothing more is required by the client. |
| Processed |
Indicates the Kansas Department of Labor has successfully
received and loaded the committed wage information. Uploads can
not be cleared at this point. |
| Cleared |
Indicates the submitted data has been cleared.
|
Method: GetUploadDetail()
The input parameter(s) are as follows:
|
Parameter
|
Type
|
Required
|
Length min/max
|
Description
|
| UTID |
String |
Yes |
N/A |
This Unique transaction identifier that was returned by the SubmitFile()
or SubmitTestFile() method. The UTID used to identify the file
that was submitted.
|
| CompressionType |
String |
Yes |
|
Indicates the compression type used to return the detail file.
Options are none,
zip, gz(gzip) and bz2(bzip2). |
| NumValid |
Integer |
No |
N/A |
Value is passed in by reference. An integer (can be any integer)
will be passed in and the number of valid employers will be returned. |
| NumInvalid |
Integer |
No |
N/A |
Value is passed in by reference. An integer (can be any integer)
will be passed in and the number of invalid employers will be returned. |
| FileContent |
ByteArray |
No |
N/A |
File (to be filled) containing a detailed analysis of the submitted file invalid
lines. |
The Return value(s) are as follows:
|
Type
|
Length min/max
|
Description
|
| String |
1-100 |
Returns "True" on success. Returns an error message
on failure.
|
If a valid UTID is passed in, "True" is returned
and the number of valid and invalid employers will be returned. In
addition, a detailed file analysis will be returned of invalid records.
If an invalid UTID is passed, an error message will be returned. If
a failure occurrs the web service will generate a SOAP Fault with
an error message that will need to be handled by your SOAP client.
Method: CommitValidRecords()
The input parameter(s) are as follows:
|
Parameter
|
Type
|
Required
|
Length min/max
|
Description
|
| UTID |
String |
Yes |
N/A |
This Unique transaction identifier that was returned by the SubmitFile()
method. The UTID is used to identify the file that was submitted.
|
The Return value(s) are as follows:
|
Type
|
Length min/max
|
Description
|
| String |
1-100 |
Returns "True" on success. Returns an error message
on failure.
|
Prerequiste: Must have submitted a valid MMREF, NASWA or Payment file.
If a valid UTID is passed in, "True" is returned
and all the records that were returned as valid in the GetUploadDetail()
method will be submitted. Records will not be processed by KDOL if
this method is not called. If an invalid UTID is passed, an error
message will be returned. If a failure occurrs the web service will
generate a SOAP Fault with a descriptive error message and will need
to be handled by your SOAP client.
Method: GetRateData()
The input parameter(s) are as follows:
|
Parameter
|
Type
|
Required
|
Length min/max
|
Description
|
| UTID |
String |
Yes |
N/A |
This Unique transaction identifier that was returned by the SubmitFile()
method. The UTID is used to identify the file that was submitted.
|
|
CompressionType |
Enumeration |
Yes |
|
Indicates the compression type used to return the detail file. Options are none, zip, gz(gzip) and bz2(bzip2). |
| FileContent |
ByteArray |
No |
N/A |
Passed by reference. File containing the requested
rate information. |
The Return value(s) are as follows:
|
Type
|
Length min/max
|
Description
|
| String |
1-100 |
Returns "True" on success. Returns an error message
on failure.
|
Prerequiste: Must have submitted a valid file
of type Rate.
If a valid UTID is passed in, "True"
is returned and all the records that were submitted for a rate inquiry
and are valid will be returned in the file containing the rate for
each employer. An employer record is deemed valid if the two of the
three required fields match our records. The three required fields
are Name, FEIN, and Serial Number. If an invalid UTID is passed, an
error message will be returned. If a failure occurrs the web service
will generate a SOAP Fault with a descriptive error message and will
need to be handled by your SOAP client.
Method: GetTransactionDetail()
The input parameter(s) are as follows:
|
Parameter
|
Type
|
Required
|
Length min/max
|
Description
|
| UTID |
String |
Yes |
N/A |
This Unique transaction identifier that was returned by the SubmitFile()
method. The UTID is used to identify the file that was submitted.
|
|
Confirmation |
String |
No |
N/A |
The confirmation number used to identify a committed file for processing.
|
|
CommitDate |
String |
No |
N/A |
The date you successfully committed your information to be processed as a string.
|
| Totals |
Double |
No |
N/A |
The total number of accounts committed for processing, or the total number of dollars
made for payments, depending on the file type you submitted.
|
| Accounts |
Int Array |
No |
N/A |
A list of valid accounts that will be processed after a commit has been submitted.
|
The Return value(s) are as follows:
|
Type
|
Length min/max
|
Description
|
| String |
1-100 |
Returns "True" on success. Returns an error message
on failure.
|
If a valid UTID is passed in, "True"
will be returned and all the wage detail record or payment information
totals committed will be returned. Upload must first be committed
before this function can be called. If a failure occurrs the web service
will generate a SOAP Fault with a descriptive error message and will
need to be handled by your SOAP client.
Method: ClearUpload()
The input parameter(s) are as follows:
|
Parameter
|
Type
|
Required
|
Length min/max
|
Description
|
| UTID |
String |
Yes |
N/A |
This Unique transaction identifier that was returned by the SubmitFile()
method. The UTID is used to identify the file that was submitted.
|
The Return value(s) are as follows:
|
Type
|
Length min/max
|
Description
|
| String |
1-100 |
Returns "True" on success. Returns an error message
on failure.
|
If a valid UTID is passed in, "True"
will be returned and all the wage detail records submitted will be
cleared. Wage detail information that already has a status of "Processed" cannot be cleared. Therefore is the status
is "Processed" or an invalid UTID is passed, or an error
message will be returned. If a failure occurrs the web service will
generate a SOAP Fault with a descriptive error message and will need
to be handled by your SOAP client.
