> ## Documentation Index
> Fetch the complete documentation index at: https://docs.symmetry.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Quickstart: Call the calculators API

> Authenticate, discover the calculators, and run your first CBS calculation.

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](/cbs/getting-started/prerequisites). Not sure the API is the right path? See [Widgets vs. API](/cbs/overview/choose-path).

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).

<Info>
  **Running these examples**

  The snippets below are [`curl`](https://curl.se) commands. Paste one into a terminal and replace `yourKey` with your key.

  * **Prefer a GUI?** Import the ready-made [Postman collection](/cbs/api-reference/postman-collection), set your key once, and run the requests there instead of using curl.
  * **Readable output:** pipe a response through [`jq`](https://jqlang.github.io/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.
</Info>

## 1. Authenticate

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

```bash theme={null}
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`:

```json theme={null}
{
  "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:

```bash theme={null}
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:

```bash theme={null}
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):

```json theme={null}
{
  "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](/cbs/api/object-model) and [State field reference](/cbs/api/state-fields).

## Next steps

<CardGroup cols={2}>
  <Card title="API how-tos" icon="list-check" href="/cbs/api/build-calc-ui">
    Call patterns, language examples, and reports.
  </Card>

  <Card title="API overview" icon="code" href="/cbs/api-reference/overview">
    Base URLs, authentication, and the full endpoint reference.
  </Card>
</CardGroup>

Usage limits are returned in response headers. See [Rate limits](/cbs/api/rate-limits).