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

Item	Value
Method	`GET`
Path	`/spf/steMapping`
Authentication	Bearer token (same as other SPF API endpoints)
Accept header	`application/json`

Query parameters

Parameter	Required	Description
`effectiveDate`	No	ISO-8601 date (`yyyy-MM-dd`). Returns the mapping active as of that date. Defaults to today if omitted.
`formId`	No	Limits the response to a single form (for example, `W4101` or `AZ101`).
`version/get`	No	Bypasses authentication and returns endpoint version metadata only.

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

Field	Description
`spfRelease`	The SPF release the mapping data corresponds to.
`steRelease`	The STE release the mapping data corresponds to.
`asOf`	The date the mapping was resolved against.
`forms`	Array of form-level mapping objects.
`forms[].formId`	SPF form ID.
`forms[].formName`	Full form title.
`forms[].parameters`	Mapping entries for that form.
`spfTaxParameter`	The SPF tax parameter name from the form output.
`steMiscellaneousParameter`	STE miscellaneous parameter name, when applicable. Omitted when a standard parameter is used instead.
`steStandardParameter`	STE standard parameter name, when applicable (for example, `additionalWH` or `isExempt`). Omitted when a miscellaneous parameter is used instead.
`correspondingSteUniqueTaxIds`	The STE unique tax ID(s) to apply the parameter to.
`notes`	Additional guidance when the mapping requires special handling. Always review this field when present.
`effectiveDate`	The date from which this mapping entry is effective (which will always be the effective date of the form).

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.

Are all SPF tax parameters included?

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

​Overview

​Endpoint details

​Request

​Query parameters

​Effective dating

​Response fields

​Example requests

​Example response

​Applying mappings in the STE

​Common use cases

​Automate SPF-to-STE integration

​Stay current without manual reference updates

​Prepare for upcoming mapping changes

​Support backdated or corrected payroll

​Development and troubleshooting

​Frequently asked questions

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

​Are all SPF tax parameters included?

Overview

Endpoint details

Request

Query parameters

Effective dating

Response fields

Example requests

Example response

Applying mappings in the STE

Common use cases

Automate SPF-to-STE integration

Stay current without manual reference updates

Prepare for upcoming mapping changes

Support backdated or corrected payroll

Development and troubleshooting

Frequently asked questions

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

Are all SPF tax parameters included?