> ## Documentation Index > Fetch the complete documentation index at: https://docs-test.symmetry.com/llms.txt > Use this file to discover all available pages before exploring further. # Calculate a gross-up payment > Compute the gross wages required for desired net pay amount. ## OpenAPI ````yaml /ste/api-reference/ste-hosted-api.yaml post /v2/grossUp openapi: 3.0.3 info: title: STE Hosted API description: Symmetry Tax Engine Hosted API version: all termsOfService: https://www.symmetry.com/terms contact: name: Symmetry Website url: https://www.symmetry.com/ servers: - url: https://ste.symmetry.com/ste-hosted security: - apiKey: [] tags: - name: Account Information and Schema description: Account information and schema retrieval endpoints - name: Benefits description: Employee benefits status and information - name: Location Code description: Location code lookup - name: Location Tax Information description: Location-based tax information and configuration - name: Payroll Calculations description: Payroll tax calculation endpoints - name: Tax Information description: Tax ID and reference information - name: Documentation description: API documentation and specification - name: STEVersions description: Installed STE database version discovery paths: /v2/grossUp: post: tags: - Payroll Calculations summary: Calculate a gross-up payment description: Compute the gross wages required for desired net pay amount. operationId: grossUp requestBody: required: true content: application/json: schema: type: object properties: GrossUpRequest: $ref: '#/components/schemas/GrossUpRequest' example: GrossUpRequest: netPay: 1000 regularWages: 0 wageType: Regular payCalc: employeeID: Employee 123 payrollRunParameters: payDate: '2026-03-24' payPeriodsPerYear: 52 payPeriodNumber: 1 wages: - locationCode: 00-000-0000 wageType: Regular calcMethodRegularWages: Annualized calcMethodSupplementalWages: None hours: 40 grossWages: 1000 mtdWages: 0 qtdWages: 0 ytdWages: 0 - locationCode: 04-000-0000 wageType: Regular calcMethodRegularWages: Annualized calcMethodSupplementalWages: None hours: 40 grossWages: 1000 mtdWages: 0 qtdWages: 0 ytdWages: 0 application/xml: schema: type: object properties: GrossUpRequest: $ref: '#/components/schemas/GrossUpRequest' responses: '200': description: Successful response content: application/json: schema: $ref: '#/components/schemas/GrossUpResponse' example: GrossUpResponse: httpStatusCode: 200 grossUpAmt: 1350 netPay: 1000 withholdingTaxes: 350 iterations: 4 payCalc: benefitCalculation: - employerCalculatedAmt: 11.34 isCatchUp: false locationCode: 00-000-0000 benefitAmt: 11.34 benefitReferenceCode: 401K benefitType: Benefit401K wageType: Regular transactionStamp: calcDateTime: '2026-03-24T13:32:44Z' steVersion: 2026-R1 schemaVersion: v2 totalTransactions: 1 failedTransactions: 0 transactionType: GrossUp errorStatus: errorCode: 0 errorMessage: No error application/xml: schema: $ref: '#/components/schemas/GrossUpResponse' components: schemas: GrossUpRequest: type: object required: - netPay - wageType - payCalc properties: netPay: type: number description: >- The targeted net take-home pay that you want to gross-up for the employee. regularWages: type: number description: >- The employee's regular (non-supplemental) wages already paid this pay period, used to determine the correct supplemental withholding bracket. Set to 0 if there are none. wageType: $ref: '#/components/schemas/wageTypeValues' description: >- The type of wages being grossed up. Use `Supplemental` for bonuses and other one-time payments. payCalc: $ref: '#/components/schemas/payCalcType' description: >- The full payroll-calculation context (employee, pay period, wages by location, and taxes to calculate) used to compute the gross-up. GrossUpResponse: type: object properties: grossUpCalc: type: number targetNetPay: type: number payCalc: $ref: '#/components/schemas/payCalcResultType' transactionStamp: $ref: '#/components/schemas/transactionStampType' errorStatus: $ref: '#/components/schemas/errorType' wageTypeValues: type: string enum: - Regular - Supplemental - PreviousPeriod - PreviousPeriodSupplemental - Combined - CanadaLumpsum - CanadaBonus - FUTAGross - SUTAGross - SUTAPreviousState - SUTAPredecessor - CanadaEI - CanadaEI_Bonus - CanadaCPP - CanadaCPP_Bonus - CanadaQPP - CanadaQPP_Bonus - CanadaPensionIncome - CanadaQuebecSinglePayment - CanadaQPIP - TIPS - RUIA_Compensation - Custom - CanadaCommission - CanadaWorkersCompensation - CanadaGroupBenefits - CanadaHealthServiceFund - Overtime - CanadaQPIP_Bonus - CanadaQuebecLabourStandards - MinisterHousingAllowance payCalcType: type: object required: - employeeID - payrollRunParameters - wages - taxJurisdictionParms properties: benefits: type: array items: $ref: '#/components/schemas/benefitType' description: Used to specify benefit contributions from the employee or employer. customBenefits: type: array items: $ref: '#/components/schemas/customBenefitType' description: >- Used to specify which taxes should treat contributions to this custom benefit as pre-tax. You may repeat the same `customBenefitType` with a different `taxIDSearchString` each time. customImputedIncome: type: array items: $ref: '#/components/schemas/customImputedIncomeType' description: Defines custom imputed income. customWages: type: array items: $ref: '#/components/schemas/customWageType' description: >- Defines custom regular wages and indicates taxes where those wages are exempt from withholding. You may repeat the same `customWageType` with a different `taxIDSearchString` each time. customSupplementalWages: type: array items: $ref: '#/components/schemas/customSupplementalWageType' description: >- Defines custom supplemental wages and indicates taxes where the wages are exempt. You may repeat the same `customSupplementalWageType` with a different `taxIDSearchString` each time. customType: type: array items: type: object properties: description: type: string isIncluded: type: boolean key: type: integer regex: type: string theType: type: string enum: - Regular - Supplemental - Imputed - Benefit - OverrideRate - OverrideWageBase - AutoAdjust - Prorate employeeID: type: string description: >- Identifies the employee. Used to match payCalcRequests to payCalcResults when calculating multiple employee payrolls. imputedIncome: type: array items: $ref: '#/components/schemas/imputedIncomeType' description: Used to specify imputed income earned by the employee. returnCalculationErrors: type: boolean options: $ref: '#/components/schemas/optionType' payrollRunParameters: $ref: '#/components/schemas/payrollRunParametersType' description: The payroll date and pay period information. taxJurisdictionParms: type: array items: $ref: '#/components/schemas/taxJurisdictionParmsType' description: >- Each object represents one tax to be calculated for this pay period for this employee. wages: type: array items: $ref: '#/components/schemas/wageItemType' description: >- An array of `wage` objects representing gross wages earned by the employee. Generally, you will set up a `wage` object for each location where wages were earned, then an additional `wage` object of total applicable wages for federal taxes. payCalcResultType: type: object properties: employeeID: type: string description: >- Identifies the employee. Used to match payCalcRequests to payCalcResults when calculating multiple employee payrolls. taxCalculation: type: array items: $ref: '#/components/schemas/taxCalculationType' benefitCalculation: type: array items: $ref: '#/components/schemas/benefitCalculationType' errorStatus: $ref: '#/components/schemas/errorType' transactionStampType: type: object properties: calcDateTime: $ref: '#/components/schemas/dateTime' failedTransactions: type: integer schemaVersion: type: string steVersion: type: string totalTransactions: type: integer transactionType: type: string enum: - PayCalc - LocationCode - JurisdictionData - SetTaxList - BenefitStatus - BenefitInfo - TaxIDList - GrossUp - GetSchema - AccountInfo - STEVersions errorType: type: object properties: errorCode: type: integer errorMessage: type: string benefitType: type: object properties: allowSupplementalElection: type: boolean description: >- Set to `true` to apply the benefit contribution to supplemental/bonus calculations (in addition to regular calculations). Set to `false` to only apply the benefit contribution to regular calculations. annualLimit: type: number description: >- Used to override the annual contribution limit for this benefit. Set to `0` to use the default limit for the benefit. benefitAmt: type: number description: >- The employee benefit contribution amount for the current pay period. Only used if `percent` is set to `0`. benefitAmtQTD: type: number benefitAmtYTD: type: number description: The year-to-date employee contribution amount for this benefit. benefitReferenceCode: type: string description: >- The user-assigned name for the `customBenefitType`. Used to tie the `customBenefitType` object to a `benefitType` object with a matching `benefitReferenceCode`. benefitType: $ref: '#/components/schemas/benefitTypeValues' catchUpOverrideAmt: type: number description: >- Used to override the catch-up limit. If set to `0`, the default catch-up limit is used. This should only be set to a non-zero value if setting the amount as less than the default. employerContribution: type: number description: >- The employer benefit contribution amount for the current pay period. Only used if `employerContributionPercent` is set to `0`. employerContributionPercent: type: number description: >- The percentage of the wage to be used as the employer's benefit contribution. If set to `0`, `employerContribution` is used instead. employerContributionQTD: type: number employerContributionYTD: type: number description: The year-to-date employer contribution amount for this benefit. isCatchUp: type: boolean description: >- Set to `true` to use the catch-up limit for this benefit, if applicable. miscParameters: type: array items: $ref: '#/components/schemas/miscParameterType' description: >- An array of unique miscellaneous parameters, which are required for certain benefit types. percent: type: number description: >- The percentage of the wage to be used as the employee's benefit contribution. If set to `0`, `benefitAmt` is used instead. prorateUsingStateWages: type: boolean description: >- Set to `true` to prorate the total benefit amount across multiple states based upon the state wages. Set to `false` to use the total benefit amount for every state in the calculation. description: >- The benefit type identifier. Must be an integer 100 or greater; integers 99 and lower are reserved for default benefit types in the engine. customBenefitType: type: object properties: benefitReferenceCode: type: string description: >- The user-assigned name for the `customBenefitType`. Used to tie the `customBenefitType` object to a `benefitType` object with a matching `benefitReferenceCode`. benefitType: type: integer description: >- The benefit type identifier. Must be an integer 100 or greater; integers 99 and lower are reserved for default benefit types in the engine. taxIDSearchString: type: string description: >- The search string used to identify which taxes you want to see benefit status information for. `%` is used as a wildcard. subjectWageImpact: type: string enum: - EmployeePretax - EmployerTaxable - EmployeePretaxEmployerTaxable customImputedIncomeType: type: object properties: imputedIncomeReferenceCode: type: string description: >- The user-assigned name for the `customImputedIncomeType`. Used to tie the `customImputedIncomeType` object to an `imputedIncomeType` object with a matching `imputedIncomeReferenceCode`. imputedIncomeType: type: integer description: >- The imputed income type identifier. Must be an integer 100 or greater; integers 99 and lower are reserved for default imputed income types in the engine. taxIDSearchString: type: string description: >- The search string used to identify which taxes you want to see benefit status information for. `%` is used as a wildcard. customWageType: type: object properties: taxIDSearchString: type: string description: >- The search string used to identify which taxes you want to see benefit status information for. `%` is used as a wildcard. wageReferenceCode: type: string description: >- The user-assigned name for the corresponding `customWageType`. Connects this wage object to the `customWageType` object when `wageType` is set to `Custom`. wageType: type: integer description: >- The wage type identifier. Must be an integer 100 or greater; integers 99 and lower are reserved for default wage types. customSupplementalWageType: type: object properties: taxIDSearchString: type: string description: >- The search string used to identify which taxes you want to see benefit status information for. `%` is used as a wildcard. wageTypeReferenceCode: type: string description: >- The user-assigned name for this `customSupplementalWageType`. Used to tie this `customSupplementalWageType` object to a `wage` object. desiredWageType: type: integer description: >- The wage type identifier. Must be an integer 100 or greater; integers 99 and lower are reserved for default wage types in the engine. imputedIncomeType: type: object properties: imputedAmtCTD: type: number description: The current amount of this imputed income for this pay period. imputedAmtQTD: type: number imputedAmtYTD: type: number description: The year-to-date amount of this imputed income. imputedIncomeReferenceCode: type: string description: >- The user-assigned name for the `customImputedIncomeType`. Used to tie the `customImputedIncomeType` object to an `imputedIncomeType` object with a matching `imputedIncomeReferenceCode`. imputedIncomeType: $ref: '#/components/schemas/imputedIncomeTypeValues' locationCode: $ref: '#/components/schemas/locationCodeType' wageType: $ref: '#/components/schemas/wageTypeValues' description: >- The imputed income type identifier. Must be an integer 100 or greater; integers 99 and lower are reserved for default imputed income types in the engine. optionType: type: object properties: act32TaxDistribution: type: boolean allowPre2023R5YtdWageLimiting: type: boolean autoAdjust: type: boolean description: >- Set to `true` to adjust the tax based on the employee's year-to-date wages and the year-to-date amount withheld. Only applies for taxes with a wage base and tax limit. Defaults to `false` if not set. benefitAnnualWageLimit: type: boolean customWageType: type: boolean deferredFICA2020: type: boolean futaSutaLimitByYtdWages: type: boolean HSA_Coverage: type: string enum: - single - family imputedIncomeType: type: boolean description: >- The imputed income type identifier. Must be an integer 100 or greater; integers 99 and lower are reserved for default imputed income types in the engine. includeGTLIncomeInFIT: type: boolean includeNoTaxStates: type: boolean includeRailroadTaxes: type: boolean description: >- Set to true to return railroad taxes (RRTA & RUIA) when using the federal location code (`"00-000-0000"`). Defaults to false if not set. FSADCfilingStatus: type: string enum: - S - M - H - MS useIncreasedFSADCLimits: type: boolean localCourtesyKY_OLTS: type: boolean localCourtesyOH_City: type: boolean localCourtesyOH_School: type: boolean localCourtesyOHCityOverridesNexus: type: boolean localCourtesyPA_EIT: type: boolean newMexicoWCOverride: type: boolean nonActiveTaxes: type: boolean description: >- Set to true to also return historical taxes that have been inactivated. Defaults to false if not set. ohioCityCredit: type: boolean ohioMuniResTaxType: type: string enum: - STE - Dublin - RITA - RITA_STE - RITA_Dublin - None oregonWCOverride: type: boolean paLocalCourtesy: type: boolean paLowIncomeExemption: type: boolean prorate: type: boolean simpleIRA_ZeroEmployerContribution: type: boolean stateCalcOverride: type: string enum: - none - residentonly - nonresidentonly - zeroinboth - full - difference - differencedeprecated - all - allWithNoCredit sutaTotalBenefits: type: boolean supplementalTips: type: boolean useFormalTaxDescriptions: type: boolean ZeroWageAmounts: type: boolean ZeroSubjectWageAmounts: type: boolean ZeroWagesAllowsStateAdditionalWH: type: boolean OverrideRatesForPEO: type: boolean simpleIRAEmployerAutoAdjust: type: boolean useIncreasedSimpleIraLimit: type: boolean useProratedBenefitsForSutaWages: type: boolean use2024R5TaxIDSearchStringBehavior: type: boolean preventNegativeYtdWageAdjustment: type: boolean reportSubjectWageOnWageBase: type: boolean allowNonElectiveAdditionalContribution: type: boolean useHigherBenefitCatchUpLimit: type: boolean useWageDefaulting: type: boolean rothifyBenefitCatchup: type: boolean rothifyBenefitCatchupMethod: type: string enum: - proactive - corrective payrollRunParametersType: type: object required: - payDate - payPeriodNumber - payPeriodsPerYear description: The payroll date and pay period information. properties: payDate: $ref: '#/components/schemas/date' description: The check/pay date for this payroll, in `YYYY-MM-DD` format. payPeriodNumber: type: integer description: The pay period number. payPeriodsPerYear: type: integer description: >- The number of payroll periods in a year (e.g., 52 for weekly, 12 for monthly, etc.). taxJurisdictionParmsType: type: object required: - uniqueTaxID - locationCode properties: additionalWH: type: number description: >- Any additional amount of tax to be withheld for this tax this pay period. autoAdjust: type: boolean description: >- Set to `true` to adjust the tax based on the employee's year-to-date wages and the year-to-date amount withheld. Only applies for taxes with a wage base and tax limit. Defaults to `false` if not set. hasNonResCertificate: type: boolean description: >- For state income taxes (SIT), set to `true` to indicate that the employee has completed a nonresident certificate. Causes reciprocity logic to be enforced as long as nexus exists in the resident state. Defaults to `false` if not set. isExempt: type: boolean description: Set to `true` to indicate that the employee is exempt from this tax. isResident: type: boolean description: >- Indicates the employee is considered a resident for the purposes of calculating this tax. locationCode: $ref: '#/components/schemas/locationCodeType' miscParameters: type: array items: $ref: '#/components/schemas/miscParameterType' description: >- An array of unique miscellaneous parameters, which are required for certain taxes. mtdWH: type: number description: The month-to-date amount withheld for this tax. overrideRate: type: number description: >- Overrides the default rate for the tax. Only applies for taxes that use a single rate (instead of tax tables). overrideWageBase: type: number description: >- Overrides the wage base for the tax. If set to `0` or if not set, uses the default wage base for the tax. overrideSubjectWagesYTD: type: number forcedCalcRate: type: number description: >- Forces a flat rate calculation for this tax. Overrides flat rates, tax tables, and all other applicable logic for this tax. forcedCalcWageBase: type: number description: The wage base to be used for a forced flat rate calculation. periodWH: type: number description: >- Any amount previously withheld for this tax during the current pay period. Has unique functionality for certain taxes. qtdWH: type: number description: The quarter-to-date amount withheld for this tax. roundResult: type: string enum: - 'No' - 'Yes' - Default description: >- Whether to round the tax withheld (`Yes`), not round the tax (`No`), or to use the recommended rounding (`Default`). Uses `No` if not set, but strongly recommended to set to `Default`. uniqueTaxID: $ref: '#/components/schemas/uniqueTaxIDType' description: >- The unique identifier for the tax to calculate (e.g. `00-000-0000-FIT-000`). Obtain valid IDs from the `setTaxList` / `taxIdList` tools for the employee's location codes. ytdWH: type: number description: The year-to-date amount withheld for this tax. wageItemType: type: object required: - locationCode - wageType - grossWages description: >- A single `wage` object representing gross wages earned by the employee in one location. Set up one entry per location where wages were earned (plus one for the federal location code `00-000-0000`) so federal, state, and local taxes aggregate correctly. properties: locationCode: $ref: '#/components/schemas/locationCodeType' description: >- The STE location code where these wages were earned -- e.g. `00-000-0000` (federal), `39-000-0000` (Ohio state), `39-035-1066654` (Cleveland, OH city). Resolve place names to codes with the `locationCode` tool. wageType: $ref: '#/components/schemas/wageTypeValues' description: >- The kind of wages in this entry. Use `Regular` for normal wages and `Supplemental` for bonuses. grossWages: type: number description: The gross wages earned in this location for this pay period. calcMethodRegularWages: $ref: '#/components/schemas/calcMethodValues' calcMethodSupplementalWages: $ref: '#/components/schemas/calcMethodValues' hasNexus: type: boolean description: >- Indicates that the employer has nexus in this location. Defaults to `false` if not set, but if any amount of wages have been set, this will be forced to `true` (even if manually set to `false`). hours: type: number description: >- The amount of hours the employee worked in this location for this pay period. mtdWages: type: number description: The month-to-date wages earned in this location. qtdWages: type: number description: The quarter-to-date wages earned in this location. wageReferenceCode: type: string description: >- The user-assigned name for the corresponding `customWageType`. Connects this wage object to the `customWageType` object when `wageType` is set to `Custom`. ytdWages: type: number description: The year-to-date wages earned in this location. taxCalculationType: type: object properties: description: type: string excessWagesCTD: type: number excessWagesQTD: type: number excessWagesYTD: type: number grossSubjectWages: type: number grossWages: type: number description: The gross wages earned in this location for this pay period. isResident: type: boolean description: >- Indicates the employee is considered a resident for the purposes of calculating this tax. isUnemploymentTax: type: boolean locationCode: $ref: '#/components/schemas/locationCodeType' rate: type: number subAccounts: type: array items: type: object properties: description: type: string taxAmount: type: number wageType: $ref: '#/components/schemas/wageTypeValues' subjectWages: type: number subjectWagesCTD: type: number subjectWagesQTD: type: number subjectWagesYTD: type: number taxAmount: type: number uniqueTaxID: $ref: '#/components/schemas/uniqueTaxIDType' wageBase: type: number wageType: $ref: '#/components/schemas/wageTypeValues' benefitCalculationType: type: object properties: benefitType: $ref: '#/components/schemas/benefitTypeValues' benefitReferenceCode: type: string description: >- The user-assigned name for the `customBenefitType`. Used to tie the `customBenefitType` object to a `benefitType` object with a matching `benefitReferenceCode`. locationCode: $ref: '#/components/schemas/locationCodeType' wageType: $ref: '#/components/schemas/wageTypeValues' benefitAmt: type: number description: >- The employee benefit contribution amount for the current pay period. Only used if `percent` is set to `0`. benefitAmtYTD: type: number description: The year-to-date employee contribution amount for this benefit. annualLimit: type: number description: >- Used to override the annual contribution limit for this benefit. Set to `0` to use the default limit for the benefit. isCatchUp: type: boolean description: >- Set to `true` to use the catch-up limit for this benefit, if applicable. calculatedAmt: type: number employerCalculatedAmt: type: number employerContribution: type: number description: >- The employer benefit contribution amount for the current pay period. Only used if `employerContributionPercent` is set to `0`. employerContributionYTD: type: number description: The year-to-date employer contribution amount for this benefit. dateTime: type: string benefitTypeValues: type: string enum: - Benefit125 - Benefit401K - Benefit403B - Benefit457 - BenefitCustom - BenefitRoth401K - BenefitRoth403B - BenefitFSA - BenefitHSA - BenefitSimpleIRA - BenefitRoth457 - BenefitFSADependentCare - BenefitSimpleIRANonelective - BenefitRothSimpleIRA - BenefitRothSimpleIRANonelective - BenefitStarter401K - BenefitRothStarter401K - BenefitEHTCashBenefit - BenefitHSFCashBenefitQuebec - BenefitEHTNonCashBenefit - BenefitHSFNonCashBenefitQuebec - BenefitEHTEarnings - BenefitHSFEarningsQuebec - BenefitEHTPayInLieu - BenefitDependentCustodialAccount - BenefitEducationalAssistance - BenefitEducationalAssistanceLoanRepayment miscParameterType: type: object required: - parmName - parmValue description: A unique miscellaneous parameter, which is required for certain taxes. properties: parmName: type: string description: The name of the miscellaneous parameter. parmValue: type: string description: The value of the miscellaneous parameter. imputedIncomeTypeValues: type: string enum: - GroupTermLife - Custom - DomesticPartner locationCodeType: type: string date: type: string uniqueTaxIDType: type: string calcMethodValues: type: string enum: - Annualized - Cumulative - Flat - CurrentAggregation - PreviousAggregation - Daily - None - Combined securitySchemes: apiKey: type: apiKey in: header name: Authorization description: >- API key for authentication. Provide the raw key as the value of the Authorization header (no "Bearer" prefix). ````