CHAPTER 8

Responses

Personal Profile

Response Code

Condition

messageTxt

GitHub Sample Request Payload

GitHub Sample Response Payload

400 Bad Request No Personal Profile.

"messageText":41407 -Applicant Personal Profile details are not provided.

Emp_NoPersonalProfile_400_Req.json
 

Emp_NoPersonalProfile_400_Res.json

400 Bad Request No Given Name. "messageText":41416 -GivenName is required. Company_NoGiveName_400_Req.json

Company_NoGiveName_400_Res.json

400 Bad Request No Family Name for Applicant type, other than Company. "messageText":41417 -FamilyName is required field.

Contractor_NoFamilyName_400_Req.json

Contractor_NoFamilyName_400_Res.json
400 Bad Request Family Name provided for Company type of Applicant. "messageText":41418 -FamilyName should not be provided for applicant of type Company. Company_FamilyNamePresent_400_Req.json

Company_FamilyNamePresent_400_Res.json

400 Bad Request No Government ID Code or Name. "messageText":41427 -GovernmentIDs.Id, GovernmentIDs.NameCode.Code are required.
400 Bad Request Invalid Government ID. "messageText":41428 -Invalid GovernmentID.

Company_InvalidGovtID_400_Req.json

Company_InvalidGovtID_400_Res.json

400 Bad Request No Gender Code for Employee type of Applicant. "messageText":41419 -GenderCode.Code is required. Emp_NoGenderCode_400_Req.json

Emp_NoGenderCode_400_Res.json

400 Bad Request Invalid Gender Code "messageText":41420 -Invalid GenderCode.

Emp_InvalidGender_400_Req.json

Emp_InvalidGender_400_Res.json

400 Bad Request No Birth Date for Employee type of Applicant. "messageText":41421 -BirthDate is required. Emp_NoBirthDate_400_Req.json

Emp_NoBirthDate_400_Res.json

400 Bad Request No Line One in Address for Employee type of Applicant. "messageText":41422 -LegalAddress.LineOne is required. Emp_NoLineOne_400_Req.json

Emp_NoLineOne_400_Res.json

400 Bad Request No Subdivision. "messageText":41423 -LegalAddress.SubdivisionCode.Code is required. Emp_NoSubdivision_400_Req.json

Emp_NoSubdivision_400_Res.json

400 Bad Request Invalid Subdivision. "messageText":41424 -Invalid SubdivisionCode for LegalAddress. Emp_Invalid_Subdivision_400_Req.json Emp_Invalid_Subdivision_400_Res.json
400 Bad Request No City Name for Employee type of Applicant. "messageText":41425 -LegalAddress.CityName is required. Emp_NoCityName_400_Req.json

Emp_NoCityName_400_Res.json

400 Bad Request No Postal Code for Employee type of Applicant. "messageText":41426 -LegalAddress.PostalCode is required.

Emp_NoPostalCode_400_Req.json

Emp_NoPostalCode_400_Res.json

Worker Profile

Response Code

Condition

messageTxt

GitHub Sample Request Payload

GitHub Sample Response Payload

400 Bad Request No Worker Profile.

"messageText":41408 -Applicant Worker Profile details are not provided.

Emp_NoWorkerProfile_400_Req.json

Emp_NoWorkerProfile_400_Res.json

400 Bad Request HomeOrganisationUnits/Home Department is missing. "messageText":The department data is missing for the pay rate record 1 Emp_NoDepSalaryType_400_Req.json Emp_NoDepSalaryType_400_Res.json
400 Bad Request No WorkerType Code. "messageText":41432 -WorkerType is required.

Company_NoWorkerTypeCode_400_Req.json

Company_NoWorkerTypeCode_400_Res.json
400 Bad Request Invalid Worker Type. "messageText":41433 -Invalid WorkerTypeCode. Company_InvalidWorkerTypeCode_400_Req.json

Company_InvalidWorkerTypeCode_400_Res.json

400 Bad Request Invalid workLevelCode. "messageText":41434 -Invalid WorkerLevelCode    
400 Bad Request Home Work Location is missing for Company Type of Applicant. "messageText":41429 -HomeWorkLocation.Address.SubdivisionCode.Code is required.

Company_NoHomeWorkLocationState_400_Req.json

Company_NoHomeWorkLocationState_400_Res.json

400 Bad Request Invalid Home Work Location for Company Type of Applicant. "messageText":41430 -Invalid SubdivisionCode for HomeWorkLocation.

Company_InvalidHomeWorkLocation_400_Req.json

Company_InvalidHomeWorkLocation_400_Res.json
400 Bad Request No Hire Date. "messageText":41431 -HireDate is required.

Company_NoHireDate_400_Req.json

Company_NoHireDate_400_Res.json

400 Bad Request Department is not set up but used in the request payload. "messageText":The department Dept is not set at the company level

Company_NoDepSetup_400_Req.json

Company_NoDepSetup_400_Res.json

Payroll Profile

Response Code

Condition

messageTxt

GitHub Sample Request Payload

GitHub Sample Response Payload

400 Bad Request No Payroll Profile.

"messageText":41409 -Applicant Payroll Profile details are not provided.

Emp_NoPayrollProfile_400_Req.json

Emp_NoPayrollProfile_400_Res.json

400 Bad Request No Remuneration Basis Code. "messageText":41436 -RemunerationBasisCode.Code is required.

Company_NoRemunerationBasisCode_400_Req.json

Company_NoRemunerationBasisCode_400_Res.json

400 Bad Request Remuneration Basis Code is other than S and H. "messageText":41435 -Invalid Remuneration Basis Code.

Company_InvalidRemunerationBasisCode_400_Req.json

Company_InvalidRemunerationBasisCode_400_Res.json

400 Bad Request Remuneration Basis Code is S but HourlyRateAmount is provided. "messageText":41437 -HourlyRateAmount cannot be given for RemunerationBasisCode 'S'.

Company_HourlyRateAmountWithS_400_req.json

Company_HourlyRateAmountWithS_400_res.json

400 Bad Request Remuneration Basis Code is H but PayPeriodRateAmount is provided. "messageText":41438 -PayPeriodRateAmount cannot be given for RemunerationBasisCode 'H'.

Company_PayPeriodAmountWithH_400_req.json

Company_PayPeriodAmountWithH_400_res.json

400 Bad Request No PayCycle Code. "messageText":41439 -PayCycleCode.Code is required.

Company_NoPayCycleCode_400_Req.json

Company_NoPayCycleCode_400_Res.json

400 Bad Request Invalid PayCycle Code. "messageText":41440 -Invalid PayCycleCode. Company_InvalidPayCycleCode_400_Req.json
 

Company_InvalidPayCycleCode_400_Res.json

Tax Profile

General

Response Code

Condition

messageTxt

GitHub Sample Request Payload

GitHub Sample Response Payload

400 Bad Request No Tax Profile object in the request payload.

"messageText":41410 -Applicant Tax Profile details are not provided.

Emp_NoTaxProfile_400_Req.json

Emp_NoTaxProfile_400_Res.json

Federal Tax

  • Responses relating to Format Code
  • Responses relating to Filing Status
  • Responses relating to Tax Allowance Quantity
  • Responses relating to Additional/Override Amount/Percentage
  • Responses relating to Multiple Job, Statutory Employee, Company Paid Pension Plan Indicators
  • Responses relating to Tax Allowance
  • Responses relating to Additional Income Amount
  • Responses relating to Exemptions
Format Code

Response Code

Condition

messageTxt

GitHub Sample Request Payload

GitHub Sample Response Payload

200 OK Format Code is 2020 or PRE2020. NA

Success_Res.json

400 Bad Request Format Code other than PRE2020 or 2020.

"messageText":41445 -Invalid format code.

Emp_InvalidFormatCode_400_Req.json

Emp_InvalidFormatCode_400_Res.json

400 Bad Request Format Code is missing. "messageText":41444 -AdditionalStatutoryInputs.TagValues are required.

Emp_NoFormatCode_400_Req.json

Emp_NoFormatCode_400_Res.json

Filing Status

Response Code

Condition

messageTxt

GitHub Sample Request Payload

GitHub Sample Response Payload

200 OK Filing Status is either MWSS, or for New W-4 Form. NA

Emp_NewFedTax_200_Req.json

Success_Res.json
200 OK Filing Status is either MS, or X for Old W-4 Form. NA Emp_OldFedTax_200_Req.json Success_Res.json
400 Bad Request Filing Status is other than MWSS, or for New W-4 Form or is other than Mor for old W-4 Form.

"messageText":40502 -Invalid Federal Tax Filing Status code. Refer to the Federal Tax Filing Status Codelist API to determine the supported Filing Status.

Emp_InvalidFilingStatus_400_Req.json

Emp_InvalidFilingStatus_400_Res.json

400 Bad Request Filing Status is missing. "messageText":41443 -TaxFilingStatusCode.Code is required.

Emp_NoFilingStatus_400_Req.json

Emp_NoFilingStatus_400_Res.json

Tax Allowance Quantity

Response Code

Condition

messageTxt

GitHub Sample Request Payload

GitHub Sample Response Payload

200 OK Valid Allowance Quantity. NA

Emp_OldFedTax_200_Req.json

Success_Res.json

400 Bad Request

When invalid taxAllowanceQuantity is passed in the request payload.

"messageText":41442 -TaxAllowanceQuantity must be between 0-99.

Emp_InvalidFedTaxAllowanceQty_400_Req.json

Emp_InvalidFedTaxAllowanceQty_400_Res.json

Additional/Override Tax Withholding Amount

Response Code

Condition

messageTxt

GitHub Sample Request Payload

GitHub Sample Response Payload

200 OK Valid Additional Tax Withholding Amount. NA

Emp_AddlTaxAmt_200_Req.json

Success_Res.json

400 Bad Request

When negative amount value is passed in request payload.

"messageText":40481 -Invalid Post Payload - Amount cannot be a negative number

Emp_InvalidTaxAmt_400_Req.json

Emp_InvalidTaxAmt_400_Res.json

400 Bad Request When there are more than 2-digits after decimal in Amount or Percentage. "messageText":40508 -AmountValue / Percentage should have a maximum of 2 digits to the right of the decimal place Emp_InvalidDecimal_400_Req.json

Emp_InvalidDecimal_400_Res.json

400 Bad Request

When both Withholding Amount and Percentage values are passed in request payload.

"messageText":40480 -Invalid Post Payload - Either Amount or Percentage value should be set for Additional Tax / Override Tax Amounts but not both. When setting amount or percentage for Additional Tax do not set them for Override Tax and vice - versa

Emp_BothTaxAmtPrct_400_Req.json

Emp_BothTaxAmtPrct_400_Res.json

400 Bad Request

When two Amount or two Percentage objects provided in the FederalIncomeTax Instruction Object.

"messageText":40480 -Invalid Post Payload - Either Amount or Percentage value should be set for Additional Tax / Override Tax Amounts but not both. When setting amount or percentage for Additional Tax do not set them for Override Tax and vice - versa

Emp_AddlOverr_400_Req.json

Emp_AddlOverr_400_Res.json

Multiple Job, Statutory, Company Paid Pension Indicators

Response Code

Condition

messageTxt

GitHub Sample Request Payload

GitHub Sample Response Payload

200 OK multipleJobIndicatorstatutoryWorkerIndicatorqualifiedPensionPlanCoverageIndicator are either true or false. NA

Emp_NewFedTax_200_Req.json

Success_Res.json
400 Bad Request No statutoryWorkerIndicator. "messageText":41448 -StatutoryWorkerIndicator is required. Emp_NoStatutoryInd_400_Req.json
 

Emp_NoStatutoryInd_400_Res.json

400 Bad Request No qualifiedPensionPlanCoverageIndicator. "messageText":41449 -QualifiedPensionPlanCoverageIndicator is required.

Emp_NoCompanyPensionInd_400_Req.json

Emp_NoCompanyPensionInd_400_Res.json

Tax Allowances

Response Code

Condition

messageTxt

GitHub Sample Request Payload

GitHub Sample Response Payload

200 OK Tax Allowance Type is either Dependents or Deductions. NA

Emp_NewFedTax_200_Req.json

Success_Res.json

400 Bad Request Tax Allowance Type is other than Dependents and Deductions. "messageText":41446 -Invalid Federal Tax Allowance: Dep; 41446 -Invalid Federal Tax Allowance: Ded

Emp_InvalidFedTaxAllowanceType_400_Req.json

Emp_InvalidFedTaxAllowanceType_400_Res.json

400 Bad Request Duplicate Tax Allowance. "messageText":41447 -Cannot have the same Federal Tax allowance twice. Emp_FedTaxAllowanceTwice_400_Req.json
 

Emp_FedTaxAllowanceTwice_400_Res.json

Additional Income Amount

Response Code

Condition

messageTxt

GitHub Sample Request Payload

GitHub Sample Response Payload

200 OK Valid Amount value which is not negative and has, at most, two decimals. NA

Emp_NewFedTax_200_Req.json

Success_Res.json

400 Bad Request When Additional Income Amount value is negative.

"messageText":40481 -Invalid Post Payload - Amount cannot be a negative number.

Emp_InvalidTaxIncomeAmt_400_Req.json

Emp_InvalidTaxIncomeAmt_400_Res.json

400 Bad Request When Additional Income Amount has more than 2-digits after decimal.

"messageText":40508 -AmountValue / Percentage should have a maximum of 2 digits to the right of the decimal place

Emp_InvalidTaxIncomeAmtDecimal_400_Req.json

Emp_InvalidTaxIncomeAmtDecimal_400_Res.json

Exemptions

Response Code

Condition

messageTxt

GitHub Sample Request Payload

GitHub Sample Response Payload

200 OK

When taxWithholdingStatus is updated for any of the tax instructions.

NA

Emp_FedTaxExemptions_200_Req.json

Success_Res.json

400 Bad Request

When invalid taxWithholdingStatus is passed in federalIncomeTaxInstruction object (other than 10X).

"messageText":40503 -Invalid Post Payload - taxWithholdingStatus->statusCode->codeValue should be any one of (0, 1, X) for federalIncomeTaxInstruction

Emp_InvalidFITTWS_400_Req.json

Emp_InvalidFITTWS_400_Res.json

400 Bad Request When exemptions disabled for a practitioner at the client level.

"messageText":Practitioner is not allowed to set Tax Exemptions for Employees for this client as this is feature is disabled for Practitioners at a Client Instance Level

Emp_FedTaxExemptionsDisbaled_400_Req.json

Emp_FedTaxExemptionsDisbaled_400_Res.json

400 Bad Request

When invalid taxWithholdingStatus is passed in socialSecurityTaxInstruction or medicareTaxInstruction or federalUnemploymentTaxInstruction object (other than 10).

"messageText":40504 -Invalid Post Payload - taxWithholdingStatus->statusCode->codeValue should be either 0 or 1 for federalUnemploymentTaxInstruction;

"messageText": 40505 -Invalid Post Payload - taxWithholdingStatus->statusCode->codeValue should be either 0 or 1 for medicareTaxInstruction;

"messageText":40506 -Invalid Post Payload - taxWithholdingStatus->statusCode->codeValue should be either 0 or 1 for socialSecurityTaxInstruction

Emp_InvalidTWS_400_Req.json

Emp_InvalidTWS_400_Res.json

400 Bad Request

When taxWithholdingStatus is 1 for Medicare and 0 for Social Security.

"messageText":If you select Exempt from Tax for Medicare, you must select the same option for Social Security. ; There is already a person with this Social security no.  The person you are entering may be a rehire or may have already been added by another user.

Emp_Social0Medicare1_400_Req.json

Emp_Social0Medicare1_400_Res.json


State Tax

  • Responses When Adding SIT and SUI Instructions
  • Responses When Adding State Codes and Indicators
  • Responses When Adding Filing Status
  • Responses When Adding Personal, Dependent and Special Allowances
  • Responses When Adding Tax Additional/Override Amount/Percentage
  • Responses When Adding Mississippi Personal Exemption
  • Responses When Adding Health Coverage Indicator
  • Responses When Adding Tax Withholding Status
  • Responses When Adding Modified Business Tax (MBT)
  • Responses When Adding State Paid Family Leave (FL)
  • Responses When Adding State Paid Family Leave (PFL)
  • Responses When Adding Family Leave Tax (FLI)
  • Responses When Adding State Paid Medical Leave (ML)
  • Responses When Adding Worker's Compensation (WC)
  • Responses When Adding State Disability Tax (SDI)
  • Responses When Adding Non-Income Tax States
Responses when Adding SIT and SUI Instructions

Response Code

Condition

messageTxt

GitHub Sample Request Payload

GitHub Sample Response Payload

200 OK Success response for adding stateIncomeTaxInstruction and suiTaxInstruction. NA Success_Res.json

400 Bad Request

When the stateIncomeTaxInstruction is null or not passed in the request payload.

"messageText":40462 -StateIncomeTaxInstruction is missing or null in the request payload. StateIncomeTaxInstructions element is required to determine the Lived-in and Worked-in Indicators.

Emp_SIT_Null_400_Req.json

Emp_SIT_Null_400_Res.json

400 Bad Request When the suiTaxInstruction is null or not passed in the request payload. "messageText":41454 -SuiTaxInstruction.StateCode.Code is required.

Emp_SUI_Null_400_Req.json

Emp_SUI_Null_400_Res.json

400 Bad Request When more than two stateIncomeTaxInstructions are passed. "messageText":41455 -There cannot be more than two StateIncomeTaxInstructions.

Emp_MoreThan2SITs_400_Req.json

Emp_MoreThan2SITs_400_Res.json

400 Bad Request When more than one stateIncomeTaxInstruction with livedInJurisdictionIndicator as true passed. "messageText":41456 -There cannot be more than one StateIncomeTaxInstruction with LivedInJurisdictionIndicator as true. Emp_2LivedIns_400_Req.json
 

Emp_2LivedIns_400_Res.json

400 Bad Request When there is no stateIncomeTaxInstruction with livedInJurisdictionIndicator as true. "messageText":41458 -StateIncomeTaxInstruction with LivedJurisdictionIndicator as true is missing.

Emp_NoLivedIn2WorkedIns_400_Req.json

Emp_NoLivedIn2WorkedIns_400_Res.json

400 Bad Request When there is no stateIncomeTaxInstruction with workedInJurisdictionIndicator as true. "messageText":41461 -StateIncomeTaxInstruction with WorkedInJurisdictionIndicator as true is missing.

Emp_NoWorkedIn_400_Req.json

Emp_NoWorkedIn_400_Res.json

Responses When Adding State Codes and Indicators

Response Code

Condition

messageTxt

GitHub Sample Request Payload

GitHub Sample Response Payload

200 OK

When adding the same state for both State Income Tax (SIT) and State Unemployment Insurance (SUI).

NA

Emp_AddSameStates_200_Req.json

Success_Res.json

200 OK

When adding different states for SIT and SUI.

NA

Emp_AddDiffStates_200_Req.json

Success_Res.json

400 Bad Request When no SUI state code in the request payload. "messageText":41454 -SuiTaxInstruction.StateCode.Code is required.

Emp_NoSUIStateCode_400_Req.json

Emp_NoSUIStateCode_400_Res.json

400 Bad Request When workedIn state in SIT Instruction is different from SUI state. "messageText":41462 -Worked-In stateCode in StateIncomeTaxInstruction and stateCode in SUITaxInstruction should be same.

Emp_WorkedInSUIDiff_400_Req.json

Emp_WorkedInSUIDiff_400_Res.json

 400 Bad Request

When the livedInJurisdictionIndicator is null or not passed in the request payload.

"messageText":41457 -StateCode.Code is required for StateIncomeTaxInstruction with LivedInJurisdictionIndicator true.

Emp_NoLivedInState_400_Req.json

Emp_NoLivedInState_400_Res.json

400 Bad Request When the workedInJurisdictionIndicator is null or not passed in the request payload. "messageText":41460 -StateCode.Code is required for StateIncomeTaxInstruction with WorkedInJurisdictionIndicator true.

Emp_NoWorkedInState_400_Req.json

Emp_NoWorkedInState_400_Res.json

 400 Bad Request

When both the livedInJurisdictionIndicator and workedInJurisdictionIndicator are false in the request payload.

"messageText":41458 -StateIncomeTaxInstruction with LivedJurisdictionIndicator as true is missing.

Emp_IndicatorsFalse_400_Req.json

Emp_IndicatorsFalse_400_Res.json

400 Bad Request

When both the livedInJurisdictionIndicator and workedInJurisdictionIndicator are true and statecodes are different for stateIncomeTaxInstruction and suiTaxInstruction.

"messageText":StateCode must be same in both stateIncomeTaxInstruction & suiTaxInstruction

Emp_IndicatorsTrueSuiDiff_400_Req.json

Emp_IndicatorsTrueSuiDiff_400_Res.json

 400 Bad Request

When the stateCode passed in either stateIncomeTaxInstruction or suiTaxInstruction is invalid.

"messageText":41451 -Invalid StateCode: AB

 400 Bad Request

When Inactive statecode is passed in either stateIncomeTaxInstruction or suiTaxInstruction.

"messageText":The state passed in the request payload is not set up for the company. You must set up the state for the company before you can select it for this employee.

Emp_InactiveStateCode_400_Req.json
 

Emp_InactiveStateCode_400_Res.json

400 Bad Request 

When the workedInJurisdictionIndicator is true, reciprocity with livedIn stateCode is false, and stateIncomeTaxInstruction has any fields other than livedInJurisdictionIndicator, workedInJurisdictionIndicator, and stateCode.

"messageText":Invalid Post Payload - Reciprocity is not allowed for this jusrisdiction

Emp_NoReciprocity_400_Req.json

Emp_NoReciprocity_400_Res.json

Responses When Adding Filing Status

Response Code

Condition

messageTxt

GitHub Sample Request Payload

GitHub Sample Response Payload

200 OK

When adding the same state for both SIT and SUI.

NA

Emp_AddSameStates_200_Req.json

Success_Res.json

200 OK When adding different states for SIT and SUI. NA Emp_AddDiffStates_200_Req.json Success_Res.json

400 Bad Request

When filing status for a stateCode and taxFilingStatusCode is null or not passed in the request payload.

"messageText":Filing Status is required for this StateCode to update the tax profile.

Emp_StateFilingStatusMissing_400_Req.json

Emp_StateFilingStatusMissing_400_Res.json

400 Bad Request

When filing status for a stateCode and taxFilingStatusCode passed in the request is not valid.

"messageText":Invalid Tax Filing code sent for the given state. Refer to the State Tax Filing Status Codelist API to determine the supported Filing Status

Emp_InvalidStateFilingStatus_400_Req.json

Emp_InvalidStateFilingStatus_400_Res.json

 400 Bad Request

When there are no filing statuses for a stateCode, but TaxFilingStatusCode, OverrideTaxAmount, OverrideTaxPercentage, AdditionalTaxAmount, AdditionalTaxPercentage, or Income TaxWithholdingStatus is passed in the request payload.

"messageText":Invalid Post Payload - The Employee's current state does not charge Income Tax so information sent in payload is not applicable.

Emp_NonIncomeTaxStateWithFiling_400_Req.json

Emp_NonIncomeTaxStateWithFiling_400_Res.json

Responses When Adding Personal, Dependent and Special Allowances

Response Code

Condition

messageTxt

GitHub Sample Request Payload

GitHub Sample Response Payload

200 OK

When Personal and Dependent Allowances are being set.

NA

Emp_AddSameStates_200_Req.json

Success_Res.json

400 Bad Request

When Personal Allowance (TaxAllowanceQuantity) is not allowed but provided in the request payload.

"messageText":Personal Allowance is not allowed for this Jurisdiction and Tax filing status

Emp_PersAllowanceNotAllowed_400_Req.json

Emp_PersAllowanceNotAllowed_400_Res.json

400 Bad Request

When invalid TaxAllowanceQuantity is passed in the request payload.

"messageText":Personal Allowance Quantity must be between 0-99

Emp_InvalidPersAllwnceQty_400_Req.json

Emp_InvalidPersAllwnceQty_400_Res.json

400 Bad Request

When the state is Alabama and Personal Allowance is more than 1 in the request payload.

"messageText":Invalid Post Payload - Personal Allowance quantity should be set to 1 for the given filing status of Alabama State Jurisdiction

Emp_AddPersDepAllw_WorkedIn_400_Req.json

Emp_AddPersDepAllw_WorkedIn_400_Res.json

400 Bad Request

When invalid allowance type is provided.

"messageText":40496 -Invalid Tax Allowance Type. Refer to the State Tax Allowance Codelist API to determine the supported Tax Allowance Type

Emp_InvalidStateAllowanceType_400_Req.json

Emp_InvalidStateAllowanceType_400_Res.json

 400 Bad Request

When Tax Allowance Amount is provided for Dependent or Special Allowances.

"messageText":Invalid Post Payload - Tax allowance amount is not allowed for DEP or SPL allowance type code. Please enter only tax allowance quantity.

Emp_DepAmtInsteadofQty_400_Req.json

Emp_DepAmtInsteadofQty_400_Res.json

400 Bad Request

When Dependent allowance is not allowed for a combination of statecode and filing status but provided in the request payload.

"messageText":Dependent allowance is not allowed for this Jurisdiction

Emp_DepAllwncNotAllowed_400_Req.json

Emp_DepAllwncNotAllowed_400_Res.json

 400 Bad Request

When Dependent allowance quantity is more than 99 or less than 0.

"messageText":Dependent Allowance Quantity must be between 0 – 99

Emp_InvalidDepAlwQty_400_Req.json

Emp_InvalidDepAlwQty_400_Res.json

 400 Bad Request

When Special allowance is not allowed for a combination of statecode and filing status but provided in the request payload.

"messageText":Special allowance is not allowed for this Jurisdiction

Emp_SplAlwNotAllowed_400_Req.json

Emp_SplAlwNotAllowed_400_Res.json

 400 Bad Request

When Special allowance quantity is more than 99 or less than 0.

"messageText":Special Allowance Quantity must be between 0 - 99

Emp_InvalidSplAlwQty_400_Req.json

Emp_InvalidSplAlwQty_400_Res.json

400 Bad Request When allowanceTypeCode is missing for a taxAllowance. "messageText":41452 -AllowanceTypeCode.Code is required to add State Tax Allowance.

Emp_TaxAllwTypeCodeMissing_400_Req.json

Emp_TaxAllwTypeCodeMissing_400_Res.json

400 Bad Request When amount is missing for taxAllowanceAmount. "messageText":41453 -TaxAllowanceAmount.Amount is required to add State Tax Allowance Amount.

Emp_TaxAllwAmtCodeMissing_400_Req.json

Emp_TaxAllwAmtCodeMissing_400_Res.json
Responses When Adding Tax Additional/Override Amount/Percentage

Response Code

Condition

messageTxt

GitHub Sample Request Payload

GitHub Sample Response Payload

200 OK

Success response with Additional Withholding Tax Amount.

NA

Emp_AddAddlTaxAmt_200_Req.json

Success_Res.json

200 OK

Success response with Additional Withholding Tax Percentage.

NA

Emp_AddAddlTaxPrct_200_Req.json

Success_Res.json

200 OK 

Success response with Override Tax Amount.

NA

Emp_AddTaxOvrAmt_200_Req.json

Success_Res.json

 200 OK

Success response with Override Tax Percentage.

NA

Emp_AddTaxOvrPrct_200_Req.json

Success_Res.json

400 Bad Request

When both Withholding Amount and Percentage values are passed in request payload.

"messageText":Invalid Post Payload - Either Amount or Percentage value should be set for Additional Tax / Override Tax Amounts but not both. When setting amount or percentage for Additional Tax do not set them for Override Tax and vice - versa

Emp_BothAmtPrctPresent_400_Req.json

Emp_BothAmtPrctPresent_400_Res.json

400 Bad Request

When negative amount is passed in the request payload.

"messageText":Invalid Post Payload - Amount cannot be a negative number

Emp_NegativeAmt_400_Req.json

Emp_NegativeAmt_400_Res.json

400 Bad Request

When Amount / Percentage has more than two decimal places.

"messageText":AmountValue / Percentage should have a maximum of 2 digits to the right of the decimal place

Emp_InvalidDecimalInStateTax_400_Req.json
 

Emp_InvalidDecimalInStateTax_400_Res.json

400 Bad Request

When a negative percentage value is passed in the request payload.

"messageText":Invalid Post Payload - Percentage cannot be a negative number

Emp_NegativePrctStateTax_400_Req.json

Emp_NegativePrctStateTax_400_Res.json

Responses When Adding Mississippi Personal Exemption

Response Code

Condition

messageTxt

GitHub Sample Request Payload

GitHub Sample Response Payload

200 OK

When adding both LivedIn and WorkedIn states as Mississippi and Mississippi Personal Exemption amount are being set.

NA

Emp_AddMPE_Both_200_Req.json

Success_Res.json

 200 OK

When adding WorkedIn State as Mississippi and Mississippi Personal Exemption amount are being set.

NA

Emp_AddMPE_WorkedIn_200_Req.json

Success_Res.json

200 OK

When adding LivedIn State as Mississippi and Mississippi Personal Exemption amount are being set.

NA

Emp_AddMPE_LivedIn_200_Req.json

Success_Res.json

400 Bad Request

When statecode is not MS and Mississippi Personal Exemption is provided in the request payload.

"messageText":Invalid Post Payload - Mississippi Personal exempt amount is allowed only for Mississippi Jurisdiction

Emp_NonMPEState_400_Req.json

Emp_NonMPEState_400_Res.json

 400 Bad Request

When statecode is  MS and Tax Allowance Quantity is provided in the request payload instead of Amount.

"messageText":Invalid Post Payload - Tax allowance quantity is not allowed for MPE allowance type code. Please enter only tax allowance amount

Emp_MPEQtyInsteadofAmt_400_Req.json

Emp_MPEQtyInsteadofAmt_400_Res.json

 400 Bad Request

When the Mississippi Personal Exemption Amount is not a multiple of 500.

"messageText":Invalid Post Payload - Mississippi Personal exempt amount should be in the multiple of 500

Emp_MPENonmultipleof500_400_Req.json

Emp_MPENonmultipleof500_400_Res.json

Responses When Adding Health Coverage Indicator

Response Code

Condition

messageTxt

GitHub Sample Request Payload

GitHub Sample Response Payload

200 OK

When adding WorkedIn state as Vermont and Health Coverage Indicator are being set.

NA

Emp_AddVTHealthCover_WorkedIn_200_Req.json

Success_Res.json

200 OK

When adding both LivedIn and WorkedIn states as Vermont and Health Coverage Indicator are being set.

NA

Emp_AddVTHealthCover_Both_200_Req.json

Success_Res.json

400 Bad Request

When statecode is VT and HealthCoverageIndicator is null or not passed in the request payload.

"messageText":Invalid Post Payload - Health Coverage Indicator is mandatory for Vermont Jurisdiction

Emp_VTNoHealthCover_400_Req.json

Emp_VTNoHealthCover_400_Res.json

400 Bad Request

When statecode is not VT but HealthCoverageIndicator is passed in the request payload.

"messageText":Invalid Post Payload - Health Coverage Code is allowed only for Vermont Jurisdiction

Emp_NonVTHealthCoverPresent_400_Req.json

Emp_NonVTHealthCoverPresent_400_Res.json

Responses When Adding Tax Withholding Status

Response Code

Condition

messageTxt

GitHub Sample Request Payload

GitHub Sample Response Payload

200 OK

Success response.

 NA

Emp_AddSameStates_200_Req.json

Success_Res.json

400 Bad Request

When workedInJurisdictionIndicator is true, livedInJurisdictionIndicator is false, and TaxWithholdingStatus for stateIncomeTaxInstruction is passed in the request payload.

"messageText":Invalid Post Payload - If worked-In state is set to true and lived-In state is false, then the taxWithholdingStatus in stateIncomeTaxInstruction should be null.

Emp_TWSPresentForWorkedIn_400_Req.json

Emp_TWSPresentForWorkedIn_400_Res.json

400 Bad Request

When adding a state that does not charge income tax or a state that does not have reciprocity and TaxWithholdingStatus for stateIncomeTaxInstruction is passed in the request payload.

"messageText":Invalid Post Payload - The Employee's current state does not charge Income Tax and also reciprocity is not allowed so TaxWithholdingStatus is not allowed for stateIncomeTaxInstruction

Emp_NonIncomeTaxStateWithTWS_400_Req.json

Emp_NonIncomeTaxStateWithTWS_400_Res.json

400 Bad Request

When year to date recalc flag is set to Y for the client and Tax Withholding Status for Income Tax is set to X in the request payload.

"messageText":Tax Witholding status cannot be set to Exempt for this jurisdiction as it has its year to date recalc flag set to True

Emp_RecalcTrueTWSExempt_400_Req.json

Emp_RecalcTrueTWSExempt_400_Res.json

 400 Bad Request

When the Practitioner is not allowed to modify any Tax Exemptions for Employees set at a company level and TaxWithholdingStatus for stateIncomeTaxInstruction is passed in the request payload. The client needs to get in touch with ADP to get this enabled.

"messageText":Invalid Post Payload - If worked-In state is set to true and lived-In state is false, then the taxWithholdingStatus in stateIncomeTaxInstruction should be null.

Emp_TaxExemptionsDisable_400_Req.json

Emp_TaxExemptionsDisable_400_Res.json

400 Bad Request

When State Unemployment Tax is exempted at the Company level and Tax withholding status is being set for suiTaxInstruction.

"messageText":The client is exempt from State Unemployment Tax for this state, therefore Tax Withholding Status element in suiTaxInstruction should not be sent for employees of this client.

Emp_SUIExemptTWSPresent_400_Req.json

Emp_SUIExemptTWSPresent_400_Res.json

400 Bad Request

When invalid TaxWithholdingStatus is passed in StateIncomeTaxInstructions object. other than 1,0, and X.

"messageText":40497 -Invalid Post Payload - taxWithholdingStatus.statusCode.codeValue should be any one of (0, 1, X) for stateIncomeTaxInstruction

Emp_InvalidSITTWS_400_Req.json

Emp_InvalidSITTWS_400_Res.json

400 Bad Request

When invalid TaxWithholdingStatus is passed in suiTaxInstruction object, other than 1 and 0.

"messageText":40498 -Invalid Post Payload - taxWithholdingStatus.statusCode.codeValue should be either 0 or 1 for stateUnemploymentTaxInstruction

Emp_InvalidSUITWS_400_Req.json

Emp_InvalidSUITWS_400_Res.json

400 Bad Request When invalid TaxWithholdingStatus is passed in sdiTaxInstruction object, other than 1 and 0. "messageText":41463 -Invalid Post Payload - taxWithholdingStatus.statusCode.codeValue should be either 0 or 1 for SDITaxInstruction.

Emp_InvalidSDITWS_400_Req.json

Emp_InvalidSDITWS_400_Res.json

Responses When Adding Modified Business Tax (MBT)

Response Code

Condition

messageTxt

GitHub Sample Request Payload

GitHub Sample Response Payload

200 OK

MBT Enable Success.

NA

Emp_AddMBT_200_Req.json

Success_Res.json

400 Bad Request

MBT Enable Failure.

"messageText":Employee MBT exemption is not applicable for the state {stateCode}

Emp_AddMBTIncrct_400_Req.json

Emp_AddMBTIncrct_400_Res.json

Responses When Adding State Paid Family Leave (FL)

Response Code

Condition

messageTxt

GitHub Sample Request Payload

GitHub Sample Response Payload

200 OK

FL Enable Success

NA

Emp_AddFL_200_Req.json

Success_Res.json

Responses When Adding State Paid Family Leave (PFL)

Response Code

Condition

messageTxt

GitHub Sample Request Payload

GitHub Sample Response Payload

200 OK

PFL Enable Success

NA

Emp_AddPFL_200_Req.json

Success_Res.json

Responses When Adding Family Leave Tax (FLI)

Response Code

Condition

messageTxt

GitHub Sample Request Payload

GitHub Sample Response Payload

200 OK

FLI Enable Success.

NA

Emp_AddFLI_200_Req.json

Success_Res.json

400 Bad Request

FLI Enable Failure.

"messageText":Employee FLI exemption is not applicable for the state {stateCode}

Exemptions_Add_ State_FLI_400_ Req.json

Exemptions_Add_ State_FLI_400_Res. json

 400 Bad Request

When SUI is set to exempt but FLI is not.

"messageText":Employee FLI exemption for New Jersey must be set to Exempt when employee is exempt from SUI.

Emp_AddFLI_200_Req.json

Emp_SUIExemptFLI_400_Res.json

Responses When Adding State Paid Medical Leave (ML)

Response Code

Condition

messageTxt

GITHUB Sample Request Payload

GITHUB Sample Response Payload

200 OK

ML Enable Success.

NA

Emp_AddML_200_Req.json

Success_Res.json

 200 OK

ML and FL Enable Success.

NA

Emp_AddMLFL_200_Req.json

Success_Res.json

Responses When Adding Worker's Compensation (WC)

Response Code

Condition

messageTxt

GitHub Sample Request Payload

GitHub Sample Response Payload

200 OK

WC Enable Success.

NA

Emp_AddWC_200_Req.json

Success_Res.json

Responses When Adding State Disability Tax (SDI)

Response Code

Condition

messageTxt

GitHub Sample Request Payload

GitHub Sample Response Payload

200 OK

SDI Enable Success.

NA

Emp_AddSDI_200_Req.json

Success_Res.json

 400 Bad Request

Client is exempt from SDI..

"messageText":The client is exempt from State Disability Tax, therefore Tax Withholding Status element in sdiTaxInstruction should not be sent for employees of this client.

Emp_AddSDI_200_Req.json

Emp_SDIExempt_400_Res.json

Responses When Adding Non-Income Tax States

Response Code

Condition

messageTxt

GitHub Sample Request Payload

GitHub Sample Response Payload

200 OK

When adding a non-income tax charging state as LivedIn state.

NA

Emp_AddNonIncomeTaxState_LivedIn_200_Req.json

Success_Res.json

200 OK

When adding non- income tax charging state as LivedIn and WorkedIn states.

NA

Emp_AddNonIncomeTaxState_Both_200_Req.json

Success_Res.json

200 OK 

When adding a non-income tax charging state as WorkedIn state.

NA

Emp_AddNonIncomeTaxState_WorkedIn_200_Req.json

Success_Res.json

400 Bad Request

When there are no filing statuses for a statecode but either TaxFilingStatus Code, OverrideTax Amount, OverrideTax Percentage, AdditionalTax Amount, AdditionalTax Percentage, or Income TaxWithholding Status is passed in the request payload.

"messageText":Invalid Post Payload - The Employee's current state does not charge Income Tax so information sent in payload is not applicable.