Quickstart: Call the calculators API

The calculators API lets you send inputs from your own interface and receive calculation results to display, store, or report on. This quickstart takes you from your first authenticated request to a live calculation. First, check the prerequisites. Not sure the API is the right path? See Widgets vs. API. All requests use HTTPS and JSON and require your key in the pcc-api-key header. There’s no anonymous access to the calculator endpoints. Every response wraps its data in a content object plus a _links object of related URLs (HATEOAS-style navigation).

Running these examplesThe snippets below are curl commands. Paste one into a terminal and replace yourKey with your key.

Prefer a GUI? Import the ready-made Postman collection, set your key once, and run the requests there instead of using curl.
Readable output: pipe a response through jq, e.g. curl … | jq.
On Windows: curl’s line-continuation (\) and the single-quoted -d body in step 4 don’t work in Command Prompt. Use PowerShell, WSL, Git Bash, or Postman.

1. Authenticate

Send your key in the pcc-api-key header on every request:

curl https://calculators.symmetry.com/api/calculators \
  -H "pcc-api-key: yourKey"

2. Discover the calculators

The call above lists every calculator the API supports, as links under _links:

{
  "content": "Calculators",
  "_links": {
    "self":   { "href": "https://calculators.symmetry.com/api/calculators" },
    "salary": { "href": "https://calculators.symmetry.com/api/calculators/salary" },
    "hourly": { "href": "https://calculators.symmetry.com/api/calculators/hourly" }
  }
}

It returns 11 calculators: salary, hourly, grossup, bonus-percent, bonus-agregate, 401k, 403b, finalpay, stockoption, tuition, and taxtip. Two are listed under names that differ from their endpoint paths: bonus-percent maps to /flatbonus, and bonus-agregate maps to /agbonus.

3. Inspect a calculator

Before building a request, follow a calculator’s link to retrieve its accepted fields, defaults, and options:

curl https://calculators.symmetry.com/api/calculators/salary \
  -H "pcc-api-key: yourKey"

Use the response to see which inputs the calculator accepts and their defaults, then supply the ones you need in the next step.

4. Run your first calculation

POST inputs to a calculator endpoint. A minimal salary calculation:

curl -X POST https://calculators.symmetry.com/api/calculators/salary \
  -H "pcc-api-key: yourKey" \
  -H "Content-Type: application/json" \
  -d '{
    "state": "AZ",
    "grossPay": 1000,
    "grossPayType": "PAY_PER_PERIOD",
    "payFrequency": "WEEKLY",
    "grossPayYTD": 0,
    "federalFilingStatusType": "SINGLE",
    "federalAllowances": 0,
    "additionalFederalWithholding": 0
  }'

Required fields are grossPay, grossPayYTD, federalAllowances, and additionalFederalWithholding; send state for a meaningful result. The response returns the calculated taxes and net pay (shape below; values illustrative):

{
  "content": {
    "grossPay": 1000.00,
    "federal": 102.86,
    "fica": 49.60,
    "medicare": 11.60,
    "state": 21.06,
    "netPay": 494.88,
    "voluntaryDeductions": []
  },
  "_links": { "self": { "href": "https://calculators.symmetry.com/api/calculators/salary" } }
}

fica is Social Security. For every field and per-state inputs, see Object model and default properties and State field reference.

Next steps

API how-tos

Call patterns, language examples, and reports.

API overview

Base URLs, authentication, and the full endpoint reference.

Usage limits are returned in response headers. See Rate limits.

​1. Authenticate

​2. Discover the calculators

​3. Inspect a calculator

​4. Run your first calculation

​Next steps