Kansas.gov

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 (Web Service Description Language) WSDL and build a custom client.

The WSDL file can be downloaded here

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 N/A Identifies the type of file submitted. The four valid file types are MMREF, NASWA, Payment and Rate.
FileName String Yes 5 / 75 The file name 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 of the above parameters pass the validation processes 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 occurs 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 N/A Identifies the type of file submitted. The four valid file types are MMREF, NASWA, Payment and Rate.
FileName String Yes 5 / 75 The file name 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 processes 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 occurs 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 Descriptio
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 MMREF/NASWA Payment Rate
DataTransferError Indicates there was an error transferring the file from the client machine the Kansas Department of Labor server. X X
InvalidUTID Indicates that the UTID passed does not exist in our system. X X X
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. X X X
DataContentError Indicates there was an unknown/unexpected error with the submitted file. X X X
DataContentErrorSize* Indicates the submitted file was too large. X X X
DataContentErrorInv* Indicates the submitted file was unreadable, used an incorrect character set, was found to contain malicious content or had too long of a filename. X X X
DataContentErrorComp* Indicates the submitted file uses an unsupported compression type. X X X
DataContentErrorFTP* Indicates the submitted file was unable to be saved in the KDOL file repository. X X X
Validating Indicates the file submission has been received and the KDOL system is currently validating the data submitted. X X X
DataValidationFailed Indicates that all of the data contained in the file submission was not valid. Use the GetUploadDetail() method for more details. X X X
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. X X X
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. X X X
Committing Indicates data from the file submission is currently being committed and loaded into the KDOL system. X X
Committed Indicates the records have been committed and will be processed shortly. Nothing more is required by the client. X X
Processed Indicates the Kansas Department of Labor has successfully received and loaded the committed wage information. Uploads can not be cleared at this point. X X
ProcessedPDFFail* Indicates the Kansas Department of Labor has successfully received and loaded the committed wage information, but PDFs were not successfully generated (only relevant for wage files). Uploads can not be cleared at this point. X
Cleared Indicates the submitted data has been cleared. X X

* and statuses in green = New statuses coming in September 2017


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 N/A 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 occurs 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.

 

Prerequisite: 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 occurs 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 N/A 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.

 

Prerequisite: 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 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 occurs 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 (UTID) 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 occurs 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 (UTID) 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 if the status is "Processed" or an invalid UTID is passed, an error message will be returned. If a failure occurs, the Web service will generate a SOAP Fault with a descriptive error message and will need to be handled by your SOAP client.