Hosted API quickstart - Symmetry Docs

The STE Hosted API is a JSON HTTP service that Symmetry runs for you. You send a PayCalcRequest describing one or more employees and receive a PayCalcResponse with the calculated taxes. There’s nothing to install — you only need an API key and an HTTP client.

The hosted API uses the modern STE2-style configuration exclusively: taxes are configured through taxJurisdictionParms with a uniqueTaxID, not through legacy per-tax setters.

Prerequisites

Get an API key

Your API key is issued by Symmetry. Staging and production use separate keys — a staging key will not work against production.

Choose an environment

Environment	Base URL
Staging	`https://ste-staging.symmetry.com/ste-hosted`
Production	`https://ste.symmetry.com/ste-hosted`

Start against staging.

Authentication

Pass your key as the raw value of the Authorization header — no Bearer prefix, no x-api-key, no query string.

POST /v1/payCalc HTTP/1.1
Host: ste-staging.symmetry.com
Authorization: your_api_key_here
Content-Type: application/json
Accept: application/json

Authorization: Bearer <key>, ApiKey <key>, x-api-key, and ?apiKey= are all rejected. Use the raw key as the header value.

Make your first calculation

This request calculates federal income tax for a single employee paid biweekly in California, filing Single.

curl -X POST "https://ste-staging.symmetry.com/ste-hosted/v1/payCalc" \
  -H "Authorization: $STE_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "PayCalcRequest": {
      "payCalc": [{
        "employeeID": "EMP001",
        "payrollRunParameters": { "payDate": "2026-06-15", "payPeriodsPerYear": 26, "payPeriodNumber": 12 },
        "wages": [{
          "locationCode": "STATE:06-CNTY:000-CITY:0000",
          "wageType": "Regular",
          "hours": 80, "grossWages": 4000,
          "mtdWages": 4000, "qtdWages": 12000, "ytdWages": 48000,
          "calcMethodRegularWages": "Annualized",
          "calcMethodSupplementalWages": "Flat",
          "hasNexus": true
        }],
        "taxJurisdictionParms": [{
          "uniqueTaxID": "00-000-0000-FIT-000",
          "locationCode": "STATE:00-CNTY:000-CITY:0000",
          "isResident": true,
          "miscParameters": [{ "parmName": "FILINGSTATUS", "parmValue": "S" }]
        }]
      }]
    }
  }'

import os, requests

url = "https://ste-staging.symmetry.com/ste-hosted/v1/payCalc"
headers = {
    "Authorization": os.environ["STE_API_KEY"],
    "Content-Type": "application/json",
    "Accept": "application/json",
}
payload = {
    "PayCalcRequest": {
        "payCalc": [{
            "employeeID": "EMP001",
            "payrollRunParameters": {"payDate": "2026-06-15", "payPeriodsPerYear": 26, "payPeriodNumber": 12},
            "wages": [{
                "locationCode": "STATE:06-CNTY:000-CITY:0000",
                "wageType": "Regular",
                "hours": 80, "grossWages": 4000,
                "mtdWages": 4000, "qtdWages": 12000, "ytdWages": 48000,
                "calcMethodRegularWages": "Annualized",
                "calcMethodSupplementalWages": "Flat",
                "hasNexus": True,
            }],
            "taxJurisdictionParms": [{
                "uniqueTaxID": "00-000-0000-FIT-000",
                "locationCode": "STATE:00-CNTY:000-CITY:0000",
                "isResident": True,
                "miscParameters": [{"parmName": "FILINGSTATUS", "parmValue": "S"}],
            }],
        }]
    }
}

resp = requests.post(url, json=payload, headers=headers)
resp.raise_for_status()
print(resp.json())

const res = await fetch(
  "https://ste-staging.symmetry.com/ste-hosted/v1/payCalc",
  {
    method: "POST",
    headers: {
      Authorization: process.env.STE_API_KEY,
      "Content-Type": "application/json",
      Accept: "application/json",
    },
    body: JSON.stringify({
      PayCalcRequest: {
        payCalc: [
          {
            employeeID: "EMP001",
            payrollRunParameters: { payDate: "2026-06-15", payPeriodsPerYear: 26, payPeriodNumber: 12 },
            wages: [
              {
                locationCode: "STATE:06-CNTY:000-CITY:0000",
                wageType: "Regular",
                hours: 80,
                grossWages: 4000,
                mtdWages: 4000,
                qtdWages: 12000,
                ytdWages: 48000,
                calcMethodRegularWages: "Annualized",
                calcMethodSupplementalWages: "Flat",
                hasNexus: true,
              },
            ],
            taxJurisdictionParms: [
              {
                uniqueTaxID: "00-000-0000-FIT-000",
                locationCode: "STATE:00-CNTY:000-CITY:0000",
                isResident: true,
                miscParameters: [{ parmName: "FILINGSTATUS", parmValue: "S" }],
              },
            ],
          },
        ],
      },
    }),
  }
);

console.log(await res.json());

About the location codes above. Requests use the full format STATE:ss-CNTY:ccc-CITY:geo. Here that’s STATE:00-CNTY:000-CITY:0000 for federal and STATE:06-CNTY:000-CITY:0000 for California — state-level and federal codes have no county or city of their own, so those components are zeros. A city-level code fills them in, for example STATE:06-CNTY:075-CITY:277593 for San Francisco.Get city- and county-level codes from the locationCode endpoint, which returns a ready-made locationCodeFull value — don’t assemble one by hand. See Locations and uniqueTaxIDs for how the codes are structured.The engine also accepts the short numeric form (06-000-0000) and normalizes location codes on the way out, so responses report the short form regardless of which you send. That’s why the response below shows 00-000-0000.

Read the response

A PayCalcResponse returns a taxCalculation[] per employee, plus a transactionStamp and an errorStatus. Each tax entry is keyed by its uniqueTaxID and reports the withheld taxAmount along with the rate and wage bases used.

Response (shape)

{
  "PayCalcResponse": {
    "payCalc": [{
      "employeeID": "EMP001",
      "taxCalculation": [{
        "uniqueTaxID": "00-000-0000-FIT-000",
        "locationCode": "00-000-0000",
        "description": "Federal Income Tax",
        "wageType": "Regular",
        "isResident": true,
        "isUnemploymentTax": false,
        "taxAmount": 613.15,
        "rate": 0.0,
        "grossWages": 4000,
        "grossSubjectWages": 4000,
        "subjectWages": 4000,
        "wageBase": 0
      }],
      "errorStatus": { "errorCode": 0, "errorMessage": "No error" }
    }],
    "transactionStamp": {
      "calcDateTime": "2026-06-15T14:30:00Z",
      "steVersion": "2026.7.2",
      "schemaVersion": "v1",
      "totalTransactions": 1,
      "failedTransactions": 0,
      "transactionType": "PayCalc"
    },
    "errorStatus": { "errorCode": 0, "errorMessage": "No error" }
  }
}

The steVersion and calcDateTime above vary by release and request. The taxAmount is what you withhold for that tax this pay period. For the complete field inventory, see the STE Hosted API Reference or request the live schema from the service.

Error handling

The top-level and per-employee errorStatus use these codes:

Code	Meaning
`0`	Success
`400`	Schema validation or input error
`500`	Internal error

The transactionStamp reports totalTransactions and failedTransactions so you can reconcile a batch at a glance.

Add more taxes

Adding state and local taxes is just more entries in wages and taxJurisdictionParms. To also calculate California SIT, add its jurisdiction:

{
  "uniqueTaxID": "06-000-0000-SIT-000",
  "locationCode": "STATE:06-CNTY:000-CITY:0000",
  "isResident": true,
  "miscParameters": [
    { "parmName": "FILINGSTATUS", "parmValue": "S" },
    { "parmName": "TOTALALLOWANCES", "parmValue": "0" }
  ]
}

Next steps

Full calculation walkthrough

Follow a complete, realistic pay calc end to end — location codes, applicable taxes, and results.

API reference & tools

Full endpoint reference, live Swagger, and the Postman collection.

Configuring a calculation

The full model for wages, jurisdictions, benefits, and options.

Locations & uniqueTaxIDs

How location codes and uniqueTaxID values are structured.

​Prerequisites

​Authentication

​Make your first calculation

​Read the response

​Error handling

​Add more taxes

​Next steps

Full calculation walkthrough

API reference & tools

Configuring a calculation

Locations & uniqueTaxIDs

Prerequisites

Authentication

Make your first calculation

Read the response

Error handling

Add more taxes

Next steps