Paycheck API Fields
Calculate payroll taxes for a paycheck
Field | Details | Description |
---|---|---|
additionalTaxAmount | number (currency)decimal places <= 2 | Two digits precision decimal for dollar. |
alternativeCalculationCode | integer | |
aggregateAdjustedGross | number (currency)decimal places <= 2 | Two digits precision decimal for dollar. |
aggregatedCompensations | Array of objects ( aggregatedCompensation ) | Array objects include the following sub-fields:taxRecordIdentifier - requiredtaxingLocationType compensationId - requiredpayType amount - requiredaggregationType - requiredaggregateHours overrideCompensationType |
aggregatedTaxes | Array of objects ( aggregatedTax ) | Array objects include the following sub-fields:taxRecordIdentifier - requiredpayType taxingLocationType taxAmount aggregateAdjustedGross aggregationType - requiredaggregateHours aggregateExemptAmount |
aggregateExemptAmount | number (currency)decimal places <= 2 | Two digits precision decimal for dollar. |
aggregateHours | number | Aggregate number of hours worked. |
aggregationType - required | string (aggregationType) Enum: Current PeriodToDate MonthToDate QuarterToDate SemiAnnualToDate YearToDate Previous PreviousMonthToDate PreviousQuarterToDate PreviousYearToDate PriorState | Aggregation period. |
amount - required | number (currency)decimal places <=2 | Two digits precision decimal for dollar. |
annualDeductionAmount | number (currency)decimal places <=2 | Two digits precision decimal for dollar. |
calculationMethod | string (calculationMethod) Enum: Annualize Cumulative FlatRate FlatRateCombined FlatAmount ConcurrentAggregation AnnualizedConcurrentAggregation PreviousAggregation AnnualizedPreviousAggregation CumulativeAggregation PercentFedera l PercentFederalCombined SurchargePercentState SelfAdjust NoSelfAdjust SelfAdjustMaximum BypassCalculation TieredFlat LumpSum LumpSumComposite CommissionsDrawsTDX SelfAdjustQuarter SelfAdjustSemiAnnual SelfAdjustQuarterMax SelfAdjustSemiAnnualMax AlternateFlatRate TieredFlatRateCombined ExactPercentageMethod NonCumulative AlternateAnnualized | Enumeration of calculation methods. |
calculationOverrides | Array of objects ( calculationOverride ) | Array objects include the following sub-fields:taxRecordIdentifier - requiredtaxingLocationType overrideAdditionalRate overrideAdditionalExemption overrideWageBase overrideExemptAmount overrideMaximumDeduction overrideRate additionalTaxAmount overrideTaxAmount supplementalPayAdditionalExemptions supplementalPayAdditionalRate supplementalPayOverrideRate supplementalPayAdditionalTaxAmount supplementalPayOverrideTaxAmount supplementalPayOverrideExemptAmount |
canadianDetails | Array of objects ( canadianDetail ) | Array objects include the following sub-fields:geocodeId - requiredworkGeoCodeId - requiredannualDeductionAmount claimAmount employeeDateOfBirth married disabled nonResident numberOfDependents otherTaxCredits claimCode designatedAreaDeduction daysSinceLastPay disabledDependentsOver18 over65 pensionCompensation pensionablePayPeriods stockPurchaseAmount totalExpenseAmount totalRenumerationAmount |
cashOption | boolean | Cash option: 0 = Cash may be taken by employee. 1 = Cash may not be taken by employee. |
cashTakenByEmployee | boolean | The Cash Option parameter represents the employee's option to choose cash instead of an employer's benefit. If the employee selects the cash option, the dollar value of that benefit is not deducted from an employee's current gross and is taxable. |
claimCode | string [0-9]* | ID guidelines are to use string type, but Vertex Payroll IDs must be constrained to integer values. |
claimAmount | number (currency)decimal places <= 2 | Two digits precision decimal for dollar. |
compensationAmount | number (currency)decimal places <= 2 | Two digits precision decimal for dollar. |
compensationCodeId -required | string [0-9]* | ID guidelines are to use string type, but Vertex Payroll IDs must be constrained to integer values. |
compensationId - required | string (idType) [0-9]* | ID guidelines are to use string type, but Vertex Payroll IDs must be constrained to integer values. |
compensationOverrides | Array of objects ( compensationOverride ) | Array objects include the following sub-fields:taxRecordIdentifier - requiredtaxingLocationType - requiredpayType - requiredcompensationCodeId aggregationType compensationAmount overrideCompensationTypededuction |
compensations - required | Array of objects (compensation )[ 1 .. 50 ] items | Array objects include the following sub-fields:compensationCodeId - requiredpayType amount - requiredoverrideCompensationType |
currentHours | number | Number of hours worked in the current pay period. |
currentPeriod - required | integer >= 1 | The current pay period in the year. |
daysSinceLastPay | integer | |
deductionAmount | number decimal places <= 2 | Two digits precision decimal for dollar. |
deductionPercent | number decimal places <= 6 | Standard percentage format as a decimal. With 0.01 to mean 1%, not .01 percent. 0.000001 (smallest granularity) represents 0.0001%. |
deductions | Array of objects ( deduction ) | Array objects include the following sub-fields:deductionTypeId - requireddeductionAmount deductionPercent yearToDateAmount cashTakenByEmployee taxabilityOverride maximumDeductionAmount |
deductionTypeId - required | string (idType) [0-9]* | ID guidelines are to use string type, but Vertex Payroll IDs must be constrained to integer values. |
deductionOverrides | Array of objects ( deductionOverride ) | Array objects include the following sub-fields:taxRecordIdentifier - requiredtaxingLocationType - requireddeductionTypeId deductionAmount deductionPercent yearToDateDeductionAmount cashOption maximumDeductionOverride |
defaultSupplementalPayTypeTreatment | String (payTypeTreatment) Enum: Regular Supplemental Both | Pay type that applies, including both, where both regular and supplemental apply. |
designatedAreaDeduction | number decimal places <= 2 | Two digits precision decimal for dollar. |
disabled | boolean | |
disabledDependentsOver18 | integer | |
employee -required | Object | Information about the employee. Includes the following sub-fields: employeeId - requiredpayperiod defaultSupplementalPayTypeTreatment residenceGeocodeId - requiredprimaryWorkGeocodeId - requiredresidentSchoolDistrictId primaryWorkSchoolDistrictId specialPayPeriod periodToDateAggregation |
employeeDateOfBirth | string (date) | ISO 8061: YYYY-MM-DD date format. For example, September, 2012, is represented as 2012-09-27. |
employeeId -required | string <= 30 characters | Client-defined identifier for an employee. |
experienceRate | number decimal places <= 6 >= 0 | Standard percentage format as a decimal. With 0.01 to mean 1%, not .01 percent. 0.000001 (smallest granularity) represents 0.0001%. |
filingStatus | string (idType) [0-9]* | ID guidelines are to use string type, but Vertex Payroll IDs must be constrained to integer values. |
formFieldIdentifier - required | string | Identifying string for the form (or field within a form) in DOM format. |
formFieldValue | string | The value to use for the field. |
formsData | Array of objects ( formData ) | Array objects include the following sub-fields:geocodeID - requiredschoolDistrictId taxingLocationType - requiredformFieldIdentifier - requiredformFieldValue |
geocodeId - required | string (geocodeId)9 characters [0-9]* | ID for a full GeoCode. |
ignoreParentJurisdictionDefaults | boolean | Normally, if a county-level or local-level jurisdiction is not specified, the state-level jurisdiction defaults are used. If true , do not use this jurisdiction to provide defaults for any lower-level jurisdictions. |
jurisdictions | Array of objects ( jurisdiction ) | Array objects include the following sub-fields:taxRecordIdentifier - requiredfilingStatus primaryExemptions primaryExemptionAmount secondaryExemptions secondaryExemptionAmount calculationMethod alternativeCalculationCode recalculate jurisdictionInteractinTreatmentId nonResident ignoreParentJurisdictionDefaults taxExempt nonResidentAlienTreatment taxingLocationType supplementalPayTypeTreatment experienceRate |
jurisdictionInteractionTreatmentId | string (jitType) ^([0-9]|10|13|99)$ | Valid Jurisdiction Interaction Treatment IDs. |
married | boolean | |
maximumDeductionAmount | number (currency)decimal places <= 2 | Two digits precision decimal for dollar. |
maximumDeductionOverride | number (currency)decimal places <= 2 | Two digits precision decimal for dollar. |
monthToDateHours | number | Month-to-date hours. |
nonResident | boolean | Non-residence certificate. This parameter controls certain reciprocity treatments for work taxes. |
nonResidentAlienTreatment | boolean | |
numberOfDependents | integer | |
options | Object | Includes the following sub-fields:reportZeroTax processInvalidGeocode |
otherTaxCredits | number (currency)decimal places <= 2 | Two digits precision decimal for dollar. |
over65 | boolean | |
overrideAdditionalExemption | number (currency)decimal places <= 2 | Two digits precision decimal for dollar. |
overrideAdditionalRate | number (percent)decimal places <= 6 | Standard percentage format as a decimal. With 0.01 to mean 1%, not .01 percent. 0.000001 (smallest granularity) represents 0.0001%. |
overrideCompensationType | string Enum: CashSubjectTaxable NonCashNotSubjectNotTaxable NonCashSubjectNotTaxable NonCashSubjectTaxable CashNotSubjectNotTaxable CashSubjectNotTaxable | Enumeration of the permitted combinations of the factors: - Cash or Non-Cash - Subject or Not Subject - Taxable or Not Taxable |
overrideExemptAmount | number (currency)decimal places <= 2 | Two digits precision decimal for dollar. |
overrideMaximumDeduction | number (currency)decimal places <= 2 | Two digits precision decimal for dollar. |
overrideRate | number (percent)decimal places <= 6 | Standard percentage format as a decimal. With 0.01 to mean 1%, not .01 percent. 0.000001 (smallest granularity) represents 0.0001%. |
overrideTaxAmount | number (currency)decimal places <= 2 | Two digits precision decimal for dollar. |
overrideWageBase | number (currency)decimal places <= 2 | Two digits precision decimal for dollar. |
payDate - required | string (date) | ISO 8061: YYYY-MM-DD date format. For example, September, 2012, is represented as 2012-09-27 . |
payPeriod - required | object | Includes the following sub-fields:payDate - requiredtotalPeriods - requiredcurrentPeriod - required |
payType | string (payType) Enum: Regular Supplemental | Whether this applies to Regular or Supplemental pay. |
pensionCompensation | boolean | |
pensionablePayPeriods | integer | |
periodToDateAggregation | boolean | If this flag is set to true , it indicates that this pay supplements another pay in the same pay period. |
primaryExemptionAmount | number decimal places <= 2 | Two digits precision decimal for dollar. |
primaryExemptions | integer | The number of primary exemptions. |
primaryWorkGeocodeId - required | string (geocode)9 characters [0-9]* | ID for a full GeoCode. |
primaryWorkSchoolDistrictId | string (schooDistrictId)<= 5 characters [0-9]* | ID for a school district. |
processInvalidGeocode | boolean Default: false | Set to true to see invalid GeoCode processing. |
recalculate | any (recalculation) Enum: No Yes MedicareOnly | For taxes that use another tax in the calculation formula, should the tax be recalculated. |
reportZeroTax | boolean Default: false | Set to true if you want to see a tax result generated even when the tax amount and adjusted gross are zero. |
residenceGeocodeId - required | string (geocodeId)9 characters [0-9]* | ID for a full GeoCode. |
residentSchoolDistrictId | string (schoolDistrictId)<= 5 characters [0-9]* | ID for a school district. |
schoolDistrictId | string (schoolDistrictId)5 characters [0-9]* | ID for a school district. |
secondaryExemptionAmount | number decimal places <= 2 | Two digits precision decimal for dollar. |
secondaryExemptions | integer | The number of secondary exemptions. |
specialPayPeriod | string (specialPayPeriod) Enum: NotSpecial LastMonth LastQuarter LastSemiAnnual LastYear | Indicates that this is a special pay period (for example, last pay of month). Certain taxes are only calculated for special pay periods. |
stockPurchaseAmount | number (currency)decimal places <= 2 | Two digits precision decimal for dollar. |
supplementalPayAdditionalExemptions | number | |
supplementalPayAdditionalTaxAmount | number (currency)decimal places <= 2 | Two digits precision decimal for dollar. |
supplementalPayAdditionalRate | number (percent)decimal places <= 6 | Standard percentage format as a decimal. With 0.01 to mean 1%, not .01 percent. 0.000001 (smallest granularity) represents 0.0001%. |
supplementalPayOverrideExemptAmount | number (currency)decimal places <= 2 | Two digits precision decimal for dollar. |
supplementalPayOverrideRate | number (percent)decimal places <= 6 | Standard percentage format as a decimal. With 0.01 to mean 1%, not .01 percent. 0.000001 (smallest granularity) represents 0.0001%. |
supplementalPayOverideTaxAmount | number (currency)decimal places <= 2 | Two digits precision decimal for dollar. |
supplementalPayTypeTreatment | string (payTypeTreatment) Enum: Regular Supplemental Both | Pay type that applies, including both, where both regular and supplemental apply. |
taxabilityOverride | string Enum: Taxable Exempt | Whether the deduction is treated as fully taxable or fully exempt. This property supercedes a value for maximumDeductionAmount . |
taxAmount | number (currency)decimal places <= 2 | Two digits precision decimal for dollar. |
taxExempt | boolean | |
taxIdentifierId - required | string (taxIdentifierId) | ID for a tax identifier. |
taxingLocationType | string (taxingLocationType) Enum: Residential Work Both | Used to indicate whether only residential taxes, only work taxes, or both are considered. |
taxRecordIdentifier - required | object (taxRecordIdentifier) | Combination of IDs that define a tax record. Object includes the following sub-fields:taxIdentifierId - requiredgeocodeId - requiredschoolDistrictId |
totalExpenseAmount | number (currency)decimal places <= 2 | Two digits precision decimal for dollar. |
totalPeriods - required | integer >= 1 | The number of pay periods in the year. |
totalRenumerationAmount | number (currency)decimal places <= 2 | Two digits precision decimal for dollar. |
workGeocodeId - required | string (geocodeId)9 characters [0-9]* | ID for a full GeoCode. |
workLocations | Array of objects ( worklocation ) | Array objects include the following sub-fields:workLocationId geocodeId - requiredschoolDistrictId currentHours monthToDateHours yearToDateHours compensations - required |
workLocationId | string | Client-defined identifier for a work location. |
yearToDateAmount | number (currency)decimal places <= 2 | Two digits precision decimal for dollar. |
yearToDateDeductionAmount | number (currency)decimal places <= 2 | Two digits precision decimal for dollar. |
yearToDateHours | number | Year-to-date hours. |
Updated 4 months ago