> ## 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.
# Hosted API quickstart
> Calculate withholding for one employee with a single JSON request to the hosted STE web service.
The hosted **STE web 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
Your API key is issued by Symmetry. Staging and production use **separate** keys — a staging key will not work against production.
| 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.
```http theme={null}
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 `, `ApiKey `, `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.
```bash curl theme={null}
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": "06-000-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": "00-000-0000",
"isResident": true,
"miscParameters": [{ "parmName": "FILINGSTATUS", "parmValue": "S" }]
}]
}]
}
}'
```
```python Python theme={null}
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": "06-000-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": "00-000-0000",
"isResident": True,
"miscParameters": [{"parmName": "FILINGSTATUS", "parmValue": "S"}],
}],
}]
}
}
resp = requests.post(url, json=payload, headers=headers)
resp.raise_for_status()
print(resp.json())
```
```javascript Node.js theme={null}
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: "06-000-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: "00-000-0000",
isResident: true,
miscParameters: [{ parmName: "FILINGSTATUS", parmValue: "S" }],
},
],
},
],
},
}),
}
);
console.log(await res.json());
```
## 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.
```json Response (shape) theme={null}
{
"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": 349.42,
"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.1.1",
"schemaVersion": "2",
"totalTransactions": 1,
"failedTransactions": 0,
"transactionType": "PayCalc"
},
"errorStatus": { "errorCode": 0, "errorMessage": "No error" }
}
}
```
Field values above are illustrative. The `taxAmount` is what you withhold for that tax this pay period. For the complete field inventory, see the [STE Hosted API Reference](/ste/api-reference/overview) 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:
```json theme={null}
{
"uniqueTaxID": "06-000-0000-SIT-000",
"locationCode": "06-000-0000",
"isResident": true,
"miscParameters": [
{ "parmName": "FILINGSTATUS", "parmValue": "S" },
{ "parmName": "TOTALALLOWANCES", "parmValue": "0" }
]
}
```
## Next steps
Follow a complete, realistic pay calc end to end — location codes, applicable taxes, and results.
Full endpoint reference, live Swagger, and the Postman collection.
The full model for wages, jurisdictions, benefits, and options.
How location codes and `uniqueTaxID` values are structured.