API: SPF to STE Tax Parameter Mapping (U.S.)

Clients who license both SPF API and the STE can use the /spf/steMapping endpoint to get SPF tax parameters that map to STE miscellaneous and standard parameters.

Note this applies to SPF U.S. and STE U.S. only. Canadian forms are not included in the endpoint's mapping.

Overview

When an employee completes a withholding form in SPF, the completed form returns tax parameters (for example, FED.filingStatus or CA.totalAllowances). To calculate accurate withholding in the STE, those values must be set to the applicable STE miscellaneous parameter or STE standard parameter within the STE payroll calculation.

The /spf/steMapping endpoint returns the authoritative mapping between SPF and STE. Each mapping entry includes:

• The SPF tax parameter name
• The corresponding STE miscellaneous or standard parameter.
• The STE unique tax ID(s) the parameter applies to.
• An effective date for when that mapping is active.
• Optional notes when additional logic is required.

The response also includes the SPF and STE release versions the mapping corresponds to, so you can confirm your integration is aligned with the releases you are running.

Endpoint Details

Request

Query Parameters

Effective Dating

When you set the effectiveDate query parameter, the endpoint returns the most recent mapping version for each SPF tax parameter where the parameter's effectiveDate is on or before your requested date. This lets you:

• Look up mappings for historical payroll dates.
• Retrieve upcoming mapping changes before they take effect.
• Update your integration proactively when Symmetry publishes a new mapping version.

Response Fields

📘

Note:

The spfRelease and steRelease fields in the /spf/steMapping response show which releases the mapping was last verified against. They may not reflect your current SPF or STE release. Treat them as accurate as of metadata. We will continue to enhance this endpoint and improve how mapping data is kept current in upcoming releases.

Example Requests

Return all U.S. form mappings active today:

GET /spf/steMapping
Authorization: Bearer {accessToken}
Accept: application/json

Return mappings for Form W-4 (W4101) as of January 1, 2026:

GET /spf/steMapping?formId=W4101&effectiveDate=2026-01-01
Authorization: Bearer {accessToken}
Accept: application/json

Example Response

{
  "spfRelease": "2026-R5",
  "steRelease": "2026.5.2",
  "asOf": "2026-01-01",
  "forms": [
    {
      "formId": "W4101",
      "formName": "Form W-4: Employee's Withholding Certificate",
      "parameters": [
        {
          "spfTaxParameter": "FED.filingStatus",
          "steMiscellaneousParameter": "FILINGSTATUS",
          "correspondingSteUniqueTaxIds": ["00-000-0000-FIT-000"],
          "effectiveDate": "2026-01-01"
        },
        {
          "spfTaxParameter": "FED.additionalFedWithholding",
          "steStandardParameter": "additionalWH",
          "correspondingSteUniqueTaxIds": ["00-000-0000-FIT-000"],
          "effectiveDate": "2026-01-01"
        },
        {
          "spfTaxParameter": "FED.nonResidentAlien",
          "steMiscellaneousParameter": "FILINGSTATUS",
          "correspondingSteUniqueTaxIds": ["00-000-0000-FIT-000"],
          "notes": "FED.nonResidentAlien = true; FILINGSTATUS = \"NRA\"",
          "effectiveDate": "2026-01-01"
        }
      ]
    }
  ]
}

Applying Mappings in the STE

Each mapping entry points to either a miscellaneous or standard STE parameter:

• Standard parameters (for example, isExempt and additionalWH) are available for all taxes when you set up a tax within the tax jurisdiction object.
• Miscellaneous parameters are tax-specific and vary by jurisdiction; these are set within the miscellaneous jurisdiction parameters for each specific tax within the tax jurisdiction object.

Common Use Cases

Automate SPF-to-STE Integration

After an employee completes a withholding form, call this endpoint (optionally filtered by formId) to determine how each SPF tax parameter in the response should be passed into STE.

Stay Current Without Manual Reference Updates

Instead of maintaining a local copy of a static mapping document, call the endpoint during deployment or on a schedule. Compare the returned spfRelease and steRelease values to detect when your mapping logic needs to be refreshed.

Prepare for Upcoming Mapping Changes

Query the endpoint with a future effectiveDate to retrieve mappings that will become active on that date, then update your integration before the change goes live.

Support Backdated or Corrected Payroll

When processing payroll for a prior check date, pass that date as effectiveDate to retrieve the mapping that was active at that time.

Development and Troubleshooting

During integration work, filter by a specific formId to quickly confirm which STE parameters and tax IDs correspond to a given form's SPF output.

Frequently Asked Questions

Does this endpoint replace the static SPF-to-STE mapping article?

For API clients, yes. Hosted and On-Premise clients will still need to use the static mapping article within the Client Support Center.

Are all SPF tax parameters included?

No. Only SPF tax parameters where the value affects the payroll tax calculation in STE are included.