# Calculate 401k paycheck Source: https://docs.symmetry.com/cbs/api-reference/401k-calculator/calculate-401k-paycheck /cbs/api-reference/cbs-api.yaml post /calculators/401k Performs paycheck calculation with 401k retirement contributions # Calculate 401k retirement projections Source: https://docs.symmetry.com/cbs/api-reference/401k-calculator/calculate-401k-retirement-projections /cbs/api-reference/cbs-api.yaml post /calculators/401k/data Calculates multi-year 401k retirement savings projections based on contribution rates and return assumptions. Returns array of yearly projection data (30 years). # Get 401k calculator configuration Source: https://docs.symmetry.com/cbs/api-reference/401k-calculator/get-401k-calculator-configuration /cbs/api-reference/cbs-api.yaml get /calculators/401k Returns the 401k calculator model or field definitions for modeling retirement contribution paychecks # Get 401k data calculator configuration Source: https://docs.symmetry.com/cbs/api-reference/401k-calculator/get-401k-data-calculator-configuration /cbs/api-reference/cbs-api.yaml get /calculators/401k/data Returns the 401k retirement savings planning data model or field definitions # Calculate 403b paycheck Source: https://docs.symmetry.com/cbs/api-reference/403b-calculator/calculate-403b-paycheck /cbs/api-reference/cbs-api.yaml post /calculators/403b Performs paycheck calculation with 403b retirement contributions # Calculate 403b retirement projections Source: https://docs.symmetry.com/cbs/api-reference/403b-calculator/calculate-403b-retirement-projections /cbs/api-reference/cbs-api.yaml post /calculators/403b/data Calculates multi-year 403b retirement savings projections based on contribution rates and return assumptions. Returns array of yearly projection data (30 years). # Get 403b calculator configuration Source: https://docs.symmetry.com/cbs/api-reference/403b-calculator/get-403b-calculator-configuration /cbs/api-reference/cbs-api.yaml get /calculators/403b Returns the 403b calculator model or field definitions for modeling retirement contribution paychecks # Get 403b data calculator configuration Source: https://docs.symmetry.com/cbs/api-reference/403b-calculator/get-403b-data-calculator-configuration /cbs/api-reference/cbs-api.yaml get /calculators/403b/data Returns the 403b retirement savings planning data model or field definitions # Calculate aggregate bonus paycheck Source: https://docs.symmetry.com/cbs/api-reference/aggregate-bonus-calculator/calculate-aggregate-bonus-paycheck /cbs/api-reference/cbs-api.yaml post /calculators/agbonus Performs paycheck calculation for aggregate bonus amounts # Get aggregate bonus calculator configuration Source: https://docs.symmetry.com/cbs/api-reference/aggregate-bonus-calculator/get-aggregate-bonus-calculator-configuration /cbs/api-reference/cbs-api.yaml get /calculators/agbonus Returns the aggregate bonus calculator model or field definitions for calculating aggregate bonus paychecks # Get OpenAPI specification in YAML format Source: https://docs.symmetry.com/cbs/api-reference/api-specification/get-openapi-specification-in-yaml-format /cbs/api-reference/cbs-api.yaml get /docs/config Returns the complete OpenAPI 3.1 specification for CBS API in YAML format. This file can be imported into tools like Postman or used with OpenAPI code generators. The specification is alphabetically sorted for consistent output. # Get list of available calculators Source: https://docs.symmetry.com/cbs/api-reference/calculators/get-list-of-available-calculators /cbs/api-reference/cbs-api.yaml get /calculators Returns a list of all available paycheck calculators with HATEOAS links # Process batch calculator requests Source: https://docs.symmetry.com/cbs/api-reference/data/process-batch-calculator-requests /cbs/api-reference/cbs-api.yaml post /data/batch POST's multiple calculator calculations to the STE for async queue processing. Returns an array of calculation results with tax details and deductions. # Process batch calculator requests with PDF report generation Source: https://docs.symmetry.com/cbs/api-reference/data/process-batch-calculator-requests-with-pdf-report-generation /cbs/api-reference/cbs-api.yaml post /data/batch/print POST's multiple calculator calculations to the STE for async queue processing and generates a PDF report for all calculations. Returns base64-encoded PDF reports. The calculator property must be in all caps. # Get deduction object Source: https://docs.symmetry.com/cbs/api-reference/deductions/get-deduction-object /cbs/api-reference/cbs-api.yaml get /deductions Returns the deduction object for a specified deduction type. Supports custom, HSA, and 401k deduction types. Response format can be controlled via the format parameter (model, fields, or schema). # Calculate final pay paycheck Source: https://docs.symmetry.com/cbs/api-reference/final-pay-calculator/calculate-final-pay-paycheck /cbs/api-reference/cbs-api.yaml post /calculators/finalpay Performs final paycheck calculation with tips, severance, and multiple pay codes # Get final pay calculator configuration Source: https://docs.symmetry.com/cbs/api-reference/final-pay-calculator/get-final-pay-calculator-configuration /cbs/api-reference/cbs-api.yaml get /calculators/finalpay Returns the final pay calculator model or field definitions for calculating final paychecks with tips and severance # Calculate flat bonus paycheck Source: https://docs.symmetry.com/cbs/api-reference/flat-bonus-calculator/calculate-flat-bonus-paycheck /cbs/api-reference/cbs-api.yaml post /calculators/flatbonus Performs paycheck calculation for flat bonus amounts # Get flat bonus calculator configuration Source: https://docs.symmetry.com/cbs/api-reference/flat-bonus-calculator/get-flat-bonus-calculator-configuration /cbs/api-reference/cbs-api.yaml get /calculators/flatbonus Returns the flat bonus calculator model or field definitions for calculating flat bonus paychecks # Calculate grossup paycheck Source: https://docs.symmetry.com/cbs/api-reference/grossup-calculator/calculate-grossup-paycheck /cbs/api-reference/cbs-api.yaml post /calculators/grossup Performs reverse paycheck calculation to determine gross pay needed for desired net pay # Get grossup calculator configuration Source: https://docs.symmetry.com/cbs/api-reference/grossup-calculator/get-grossup-calculator-configuration /cbs/api-reference/cbs-api.yaml get /calculators/grossup Returns the grossup calculator model or field definitions for reverse paycheck calculations # Calculate hourly paycheck Source: https://docs.symmetry.com/cbs/api-reference/hourly-calculator/calculate-hourly-paycheck /cbs/api-reference/cbs-api.yaml post /calculators/hourly Performs paycheck calculation for hourly-based employees # Get hourly calculator configuration Source: https://docs.symmetry.com/cbs/api-reference/hourly-calculator/get-hourly-calculator-configuration /cbs/api-reference/cbs-api.yaml get /calculators/hourly Returns the hourly calculator model or field definitions for modeling hourly-based employee paychecks # CBS API overview Source: https://docs.symmetry.com/cbs/api-reference/overview Base URLs, authentication, and the tools (live Swagger and a Postman collection) for working with the Calculators by Symmetry API. The Calculators by Symmetry (CBS) API runs the same paycheck calculations as the hosted widgets, without the UI. Send a calculator request and receive the calculated withholding, deductions, and net pay as JSON. The endpoint reference in this section is generated from the CBS OpenAPI specification. New to the calculators API? Start with [Quickstart: Call the calculators API](/cbs/getting-started/call-api) for a complete first request, then use this reference for full endpoint and schema details. ## Environments and base URLs | Environment | Base URL | | - | - | | Production | `https://calculators.symmetry.com/api` | | Staging | `https://calculators-staging.symmetry.com/api` | Calculator endpoints sit under `/calculators`. For example, `https://calculators.symmetry.com/api/calculators/salary`. CBS runs across standard deployment tiers: **local**, **test**, **staging**, and **prod**. Production is the default target for the URLs above. If your integration needs a non-production tier, request the corresponding endpoint from Symmetry. The CBS API Postman environment sets its `endpointURL` to the current deployment tier on import, so you can switch tiers without hand-editing each request. Set your `apiKey` in Postman after importing. The hosted widget scripts load from a different host. See [Widget catalog](/cbs/widgets/catalog). ## Authentication Every request is authenticated with a single API key sent in the `pcc-api-key` header. There is no OAuth flow and no token exchange. ```text theme={null} pcc-api-key: yourKey ``` The widgets and the API use the same credential. See [Authentication model](/cbs/core-concepts/authentication-model) for validation rules and optional domain restrictions. ## Explore in Swagger API clients can access our Swagger documentation to test and explore each endpoint, and see a comprehensive overview of all available features. Our Swagger docs are available for both our production and staging environments. * [Production CBS API Swagger](https://calculators.symmetry.com/api/docs) * [Staging CBS API Swagger](https://calculators-staging.symmetry.com/api/docs) ### Authorize access to Swagger docs When accessing our Swagger docs, you will need to authorize to send a request to one of the CBS endpoints. To authorize, access the Swagger page and click the "Authorize" button to the right of the screen. Enter your API key and click "Authorize". Authorize Button.png Available Authorizations.png Once authorized successfully, you'll see the lock symbol go from gray to black on each of the endpoints. This is your indication that you can send the sample requests to each endpoint. Lock Symbol.png Click into the desired endpoint, select "try it out," and then "execute." Try it out.png Execute.png You'll then receive the response from the endpoint. ## OpenAPI specification The CBS API serves its own specification at `/docs/config`. This endpoint requires no API key. ```bash theme={null} curl https://calculators.symmetry.com/api/docs/config ``` The endpoint pages in this section are generated from a committed snapshot of that specification. ## Next steps Download the CBS Postman collection and environment directly from the API. Full reference for every calculator, data, print, and utility endpoint. # Postman collection and environment for CBS API Source: https://docs.symmetry.com/cbs/api-reference/postman-collection Download the CBS Postman collection and environment directly from the API, set your apiKey, and send sample requests to every calculator endpoint. A Postman collection has been established to make testing the CBS API endpoints simple and intuitive. Symmetry serves the Postman files from the API itself rather than as static downloads, so the collection always reflects the current endpoints. ## Download from Swagger Both files come from the **Postman** endpoints, and both require authorization. | Endpoint | What it returns | | - | - | | `GET /postman/collection` | Sample requests for all CBS API endpoints. | | `GET /postman/environment` | The environment variables used across those requests. | Jump to the Postman section of the Swagger UI to execute both endpoints and save each response. **Both endpoints require your API key** `/postman/collection` and `/postman/environment` are authenticated with the `pcc-api-key` header. Requests without a valid key return HTTP 401. See [Authentication model](/cbs/core-concepts/authentication-model). ## Import into Postman Authorize in the Swagger UI with your `pcc-api-key`, then execute `GET /postman/collection` and `GET /postman/environment` and save each response as a file. In Postman, select **Import**, then add the collection file and the environment file you downloaded. Activate the environment, then supply your own `apiKey`. ## Environment variables There are two variables in the environment. | Variable | Value | | - | - | | `apiKey` | Provided by Symmetry's Client Success team. If you are unsure of your company's `apiKey`, please reach out to Client Success within the [Client Support Center](https://support.symmetry.com). | | `endpointURL` \* | `https://calculators.symmetry.com/api/calculators/` for production. | \* Set automatically on download. `/postman/environment` returns `endpointURL` already set for the deployment tier you download it from, so a staging download comes preconfigured for staging. The only value you need to enter by hand is `apiKey`. # Postman collection Source: https://docs.symmetry.com/cbs/api-reference/postman/postman-collection /cbs/api-reference/cbs-api.yaml get /postman/collection Returns the CBS API Postman collection. Import this URL into Postman to get all calculator request examples. Set apiKey in the environment after import. Requires pcc-api-key. # Postman environment Source: https://docs.symmetry.com/cbs/api-reference/postman/postman-environment /cbs/api-reference/cbs-api.yaml get /postman/environment Returns the CBS API Postman environment with endpointURL set for the current deployment tier (local/test/staging/prod). Set apiKey in Postman after import. Requires pcc-api-key. # Generate PDF report for calculator Source: https://docs.symmetry.com/cbs/api-reference/print/generate-pdf-report-for-calculator /cbs/api-reference/cbs-api.yaml post /print POST's a single calculator calculation to the STE and generates a PDF report. Returns base64-encoded PDF documents based on the specified report type. Calculator value in query parameter should match the calculator type in the request body. # Get print object with calculator example Source: https://docs.symmetry.com/cbs/api-reference/print/get-print-object-with-calculator-example /cbs/api-reference/cbs-api.yaml get /print Returns the print object structure with a salary calculator object added as an example. Used to understand the print data model structure for generating paycheck reports. # Calculate salary paycheck Source: https://docs.symmetry.com/cbs/api-reference/salary-calculator/calculate-salary-paycheck /cbs/api-reference/cbs-api.yaml post /calculators/salary Performs paycheck calculation for salary-based employees # Get salary calculator configuration Source: https://docs.symmetry.com/cbs/api-reference/salary-calculator/get-salary-calculator-configuration /cbs/api-reference/cbs-api.yaml get /calculators/salary Returns the salary calculator model or field definitions for modeling salary-based employee paychecks # Get state-specific parameters Source: https://docs.symmetry.com/cbs/api-reference/state-parameters/get-state-specific-parameters /cbs/api-reference/cbs-api.yaml get /stateparms Returns all possible state parameters for the given state and calculator type. Used to help build out CBS-Widgets UI and calculate paychecks with the STE. Different states have different required fields and validations. # Calculate stock option paycheck Source: https://docs.symmetry.com/cbs/api-reference/stock-option-calculator/calculate-stock-option-paycheck /cbs/api-reference/cbs-api.yaml post /calculators/stockoption Performs paycheck calculation for stock option exercise income # Get stock option calculator configuration Source: https://docs.symmetry.com/cbs/api-reference/stock-option-calculator/get-stock-option-calculator-configuration /cbs/api-reference/cbs-api.yaml get /calculators/stockoption Returns the stock option calculator model or field definitions for calculating stock option exercise income # Calculate tax tip paycheck Source: https://docs.symmetry.com/cbs/api-reference/tax-tip-calculator/calculate-tax-tip-paycheck /cbs/api-reference/cbs-api.yaml post /calculators/taxtip Performs paycheck calculation for hourly employees with reported tips # Get tax tip calculator configuration Source: https://docs.symmetry.com/cbs/api-reference/tax-tip-calculator/get-tax-tip-calculator-configuration /cbs/api-reference/cbs-api.yaml get /calculators/taxtip Returns the tax tip calculator model or field definitions for calculating taxes on tips # Calculate tuition paycheck Source: https://docs.symmetry.com/cbs/api-reference/tuition-calculator/calculate-tuition-paycheck /cbs/api-reference/cbs-api.yaml post /calculators/tuition Performs paycheck calculation for tuition reimbursement income # Get tuition calculator configuration Source: https://docs.symmetry.com/cbs/api-reference/tuition-calculator/get-tuition-calculator-configuration /cbs/api-reference/cbs-api.yaml get /calculators/tuition Returns the tuition calculator model or field definitions for calculating tuition reimbursement income # API returns 401 Source: https://docs.symmetry.com/cbs/api/401-unauthorized Why the CBS API rejects a request with 401, and how to fix it. The CBS API returns **HTTP 401** for every authentication and key problem (there is no `403`). The body is `{ "message": "…" }`. | Message | Cause | Fix | | - | - | - | | `No api key found` | The `pcc-api-key` header is missing or blank | Send your key in the header on every request (the root/listing endpoint requires it too). | | `Invalid api key` | The key isn't recognized | Double-check the value. Need one? See [Getting support](/symmetry/support/getting-support). | | `Profile has been disabled` | The key is disabled | Contact Symmetry. | | `Profile does not have access to this product` | The key isn't entitled to CBS | Ask Symmetry to enable CBS for the key. | | `Failed security check` | The request origin isn't on the key's allowed domains | Add your domain to the key, or call from an allowed origin. | | `API rate limit has been exceeded.` | A trial key is over its cap | See [Rate limit exceeded](/cbs/api/rate-limit-exceeded). | Validation problems are **not** 401. A bad or missing body field returns **400**, and malformed JSON or an invalid state parameter returns **422**. See [Error codes and fixes](/cbs/api/error-codes). Authentication details: [Authentication model](/cbs/core-concepts/authentication-model). # Build a custom salary calculator UI Source: https://docs.symmetry.com/cbs/api/build-calc-ui Use the fields endpoint to render your own salary form, then POST inputs for results. The API lets you build your own UI while CBS does the math. The pattern is **discover the fields → render your form → POST for results**. ## 1. Get the field definitions `GET` the calculator with `format=fields` to receive the input fields, each with a name, label, default value, validation regex, and help text, so you can render a form dynamically: ```bash theme={null} curl "https://calculators.symmetry.com/api/calculators/salary?format=fields" \ -H "pcc-api-key: yourKey" ``` See [Request and response structure](/cbs/api/request-and-response) for the `model` vs `fields` shapes. ## 2. POST the inputs Send the collected values to the calculator endpoint: ```bash cURL 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}' ``` ```javascript JavaScript (fetch) theme={null} const res = await fetch("https://calculators.symmetry.com/api/calculators/salary", { method: "POST", headers: { "pcc-api-key": "yourKey", "Content-Type": "application/json" }, body: JSON.stringify({ state: "AZ", grossPay: 1000, grossPayType: "PAY_PER_PERIOD", payFrequency: "WEEKLY", grossPayYTD: 0, federalFilingStatusType: "SINGLE", federalAllowances: 0, additionalFederalWithholding: 0, }), }); const { content } = await res.json(); ``` ```python Python (requests) theme={null} import requests r = requests.post( "https://calculators.symmetry.com/api/calculators/salary", headers={"pcc-api-key": "yourKey", "Content-Type": "application/json"}, json={"state":"AZ","grossPay":1000,"grossPayType":"PAY_PER_PERIOD","payFrequency":"WEEKLY", "grossPayYTD":0,"federalFilingStatusType":"SINGLE","federalAllowances":0,"additionalFederalWithholding":0}, ) content = r.json()["content"] ``` ## 3. Render the results The response `content` holds `grossPay`, `federal`, `fica` (Social Security), `medicare`, `state`, `netPay`, and any `voluntaryDeductions`. Map those into your UI. Required fields are `grossPay`, `grossPayYTD`, `federalAllowances`, and `additionalFederalWithholding`; send `state` for a meaningful result. For every field, see [Object model and default properties](/cbs/api/object-model); for per-state inputs, see [State field reference](/cbs/api/state-fields). # Calculate bonus withholding Source: https://docs.symmetry.com/cbs/api/calc-bonus-withholding Choose between the percent (flat) method and the aggregate method for bonus withholding. CBS offers two bonus calculators. Pick based on how you want supplemental wages withheld. ## Percent (flat) method: `flatbonus` Withholds using the supplemental flat rate. POST to `flatbonus`: ```bash theme={null} curl -X POST https://calculators.symmetry.com/api/calculators/flatbonus \ -H "pcc-api-key: yourKey" -H "Content-Type: application/json" \ -d '{"state":"CO","bonus":5000,"payFrequency":"WEEKLY","grossPayYTD":0,"federalFilingStatusType":"SINGLE","federalAllowances":0,"additionalFederalWithholding":0}' ``` The percent method is not available in every state. For states that don't support it, the API returns HTTP **422** with a message like *"CALIFORNIA does not support this type of calculation. Please select a different state."* See [Handle states with no supplemental rate](/cbs/api/handle-no-supplemental-rate). ## Aggregate method: `agbonus` Combines the bonus with regular wages from the last paycheck to apply the correct withholding rates. POST to `agbonus` with the bonus plus the current pay context. Use this when the percent method isn't available or isn't appropriate. ## Choosing * **Percent/flat**: simplest; a fixed supplemental rate on the bonus (where supported). * **Aggregate**: more accurate for the employee's actual bracket; works in all states. For which method each calculator uses, see [Calculation methods by calculator](/cbs/core-concepts/calc-methods). # Calculate a final paycheck Source: https://docs.symmetry.com/cbs/api/calc-final-paycheck Handle termination pay with current and prior pay-period data using the final pay calculator. The `finalpay` calculator computes a termination payout, combining current-period pay with prior-period and additional amounts (accrued balances, severance, and so on). ## Pay codes Final pay is driven by a list of **pay codes**, each typed by when it applies: | `payCodes[n][type]` | Meaning | | - | - | | `CURRENT` | Current pay-period earnings. | | `PRIOR` | A prior pay period (include with `includePrior`). | | `ADDITIONAL` | Extra amounts such as severance. | Each pay code carries rates and hours (regular, overtime, double time, vacation, sick, holiday), plus optional `tipAmount`, `severanceAmount`, and an `override` flag to use custom overtime/double-time rates instead of the standard 1.5×/2×. See the full field list in [Object model and default properties](/cbs/api/object-model). ## Request POST to `finalpay` with the wage/tax inputs and a `payCodes` array. `includePrior` defaults to `true`, so prior pay codes are included in the calculation unless you set it `false`. ```bash theme={null} curl -X POST https://calculators.symmetry.com/api/calculators/finalpay \ -H "pcc-api-key: yourKey" -H "Content-Type: application/json" \ -d '{"state":"AZ","payFrequency":"WEEKLY","grossPayYTD":0,"federalFilingStatusType":"SINGLE","federalAllowances":0,"additionalFederalWithholding":0,"includePrior":true,"payCodes":[{"type":"CURRENT","rate":25,"hours":40}]}' ``` The response returns the combined gross, taxes, and net for the final check. # Generate a printable pay stub Source: https://docs.symmetry.com/cbs/api/generate-pay-stub Use the print object and report endpoint to produce a pay stub or check report. Beyond calculating a paycheck, the API can generate predefined reports. Check tops, pay stubs, earnings summaries, as a **base64-encoded PDF** you render on your side. ## Two ways to get a report * **On a calculation**: add `report=` to a calculator `POST`; the response includes the report(s) under `reporting.reports` as base64-encoded PDFs. * **Directly**: `GET`/`POST` the print endpoint: ```bash theme={null} curl "https://calculators.symmetry.com/api/print" \ -H "pcc-api-key: yourKey" ``` ## Report types `type` accepts: `all`, `checktop`, `checkmiddle`, `checkbottom`, `earnings`, `paystub` (for the final pay calculator), or omitted. ## The print object Populate the `print` object on your request to control what appears on the report: employee and company name/address, check number and date, remarks, and `emailReports`. See the full list in [Object model and default properties](/cbs/api/object-model). ## Rendering The report arrives **base64-encoded inside the JSON response** (not raw bytes). Decode it to bytes and write a `.pdf` (or stream it to the browser as a Blob). Widgets can also print or email reports directly. Those settings are enabled by Symmetry in the admin console. See [Special features](/cbs/widgets/special-features). # Migrate between widget and API Source: https://docs.symmetry.com/cbs/api/migrate-widget-to-api Move from a widget embed to a custom API integration, or back. Widgets and the API share the same key and the same calculators, so moving between them is mostly a UI change. The calculations stay consistent. ## Widget → API You'd move to the API when you need a custom UI, server-side calculations, or to store/report on results. 1. **Reuse your key.** The value in the widget's `?key=` is the same credential the API expects in the `pcc-api-key` header. See [Authentication model](/cbs/core-concepts/authentication-model). 2. **Map your widget defaults to a request body.** Any defaults you set via `data-defaults` become fields in the calculator model. See [Object model and default properties](/cbs/api/object-model). 3. **Render your own UI.** Use `format=fields` to drive a form; see [Build a custom salary calculator UI](/cbs/api/build-calc-ui). 4. **Move the key server-side** if you can. Unlike a widget key (visible in page source), API keys should stay on your server. ## API → widget Going the other way (to reduce build effort) is just embedding the widget script with the same key and moving your default values into [widget configuration](/cbs/widgets/configuration-methods). Results are consistent across both paths for the same inputs, because both run the same calculator. See [How calculators work](/cbs/core-concepts/how-calcs-work). # Model 401(k) and 403(b) contribution changes Source: https://docs.symmetry.com/cbs/api/model-401k-403b-contributions Show the paycheck impact of changing a retirement contribution. The `401k` and `403b` calculators show how a change in retirement contribution affects take-home pay (and, in the widget, retirement projections). ## Request POST to `401k` (or `403b`) with the wage inputs plus the contribution fields: ```bash theme={null} curl -X POST https://calculators.symmetry.com/api/calculators/401k \ -H "pcc-api-key: yourKey" -H "Content-Type: application/json" \ -d '{"state":"AZ","grossPay":2000,"grossPayType":"PAY_PER_PERIOD","payFrequency":"BI_WEEKLY","grossPayYTD":0,"federalFilingStatusType":"SINGLE","federalAllowances":0,"additionalFederalWithholding":0,"employeeContribution":6,"employeeContributionType":"PERCENT_OF_GROSS"}' ``` ## Contribution fields | Field | Meaning | | - | - | | `employeeContribution` / `employeeContributionType` | The employee's contribution amount and whether it's `PERCENT_OF_GROSS` or `FIXED_AMOUNT`. | | `employerContribution` / `employerContributionType` | Employer match amount and type. | | `contributionLimit` | The limit up to which the employer matches. | | `olderThan50` | Enables catch-up contributions. | To show a "before vs after," run the calculation twice, once at the current contribution and once at the proposed one, then compare `netPay`. For all fields and valid values, see [Object model and default properties](/cbs/api/object-model). A `457` deferred-comp calculator exists in the API model (mirrors 401(k)) but has no dedicated endpoint or widget. See [Available calculators](/cbs/overview/available-calcs). # Rate limits Source: https://docs.symmetry.com/cbs/api/rate-limits The CBS API usage-limit response headers and what happens when a trial key reaches its cap. The CBS API reports your usage on every response and enforces a calculation cap on trial keys. ## Limit-status headers Every API response includes these headers: | Header | Meaning | | - | - | | `X-Pcc-Api-Calc-Limit` | Calculations allowed for the key (`0` means unlimited). | | `X-Pcc-Api-Calc-Remaining` | Calculations remaining (`N/A` when unlimited). | | `X-Pcc-Api-Exp-Date` | The key's expiration date. | Monitor `X-Pcc-Api-Calc-Remaining` to avoid interruptions as you approach the cap. ## When you hit the limit The cap is checked on **calculation requests** (`POST`). When a trial key exceeds its limit, the API returns HTTP **401 Unauthorized** with: ```json theme={null} { "message": "API rate limit has been exceeded." } ``` The calculation cap applies to **trial keys**. Standard (paid) keys are not blocked by this limit. The headers still report status, but production usage isn't capped by this mechanism. Confirm your key's limits with Symmetry. For how keys are authenticated, see [Authentication model](/cbs/core-concepts/authentication-model). # Request and response structure Source: https://docs.symmetry.com/cbs/api/request-and-response The CBS API envelope: content plus _links, and the model, fields, and calculation response shapes. All CBS API traffic is JSON over HTTPS, and requests and responses share a consistent envelope. ## The response envelope Every response wraps its payload in a `content` object and a `_links` object (HATEOAS): ```json theme={null} { "content": { }, "_links": { "self": { "href": "https://calculators.symmetry.com/api/calculators/salary" } } } ``` `content` holds the requested data; `_links` gives the URL of the current resource plus related actions (such as a `calculate` link). ## GET a calculator: model vs. fields A `GET` on a calculator resource returns its definition. The `format` query parameter controls the shape: | `format` | Returns | | - | - | | `model` (default) | The calculator's model object, the input fields and their defaults. | | `fields` | An array of field descriptors: name, label, default value, validation regex, and help text. | ```bash theme={null} curl "https://calculators.symmetry.com/api/calculators/salary?format=fields" \ -H "pcc-api-key: yourKey" ``` Use `model` to see the object you'll POST; use `fields` to build a form dynamically. ## POST to calculate A `POST` to the calculator resource runs a calculation. The request body is the calculator's model (see [Object model and default properties](/cbs/api/object-model)); the response `content` holds the results: ```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. Optional query params extend the response: `itd=true` adds a detailed tax breakdown, `report` returns a PDF report, and `showcalc` echoes the submitted inputs. See the [API quickstart](/cbs/getting-started/call-api) for an end-to-end example and the [endpoint reference](/cbs/api-reference/salary-calculator/calculate-salary-paycheck) for full request and response schemas. # Run a gross-up calculation Source: https://docs.symmetry.com/cbs/api/run-gross-up Determine the gross pay needed to hit a target net pay with the gross-up calculator. The gross-up calculator works backward from a target **net** pay to the **gross** wages required so that, after taxes and withholdings, the employee nets the target amount. ## When to use it Reach for the gross-up calculator whenever the net is fixed and the gross is flexible: * Net bonuses (for example, an employee should take home exactly \$5,000) * Relocation payments * Incentive or spot awards promised as a net amount ## Request POST to the `grossup` endpoint with the target net pay in `netPay`: ```bash theme={null} curl -X POST https://calculators.symmetry.com/api/calculators/grossup \ -H "pcc-api-key: yourKey" \ -H "Content-Type: application/json" \ -d '{"state":"AZ","netPay":1500,"payFrequency":"WEEKLY","grossPayYTD":0,"federalFilingStatusType":"SINGLE","federalAllowances":0,"additionalFederalWithholding":0}' ``` The response `content` returns the solved `grossPay` plus the resulting taxes and `netPay`. ## Example With `federalSupplementalFlat` set and a 2.5% Arizona withholding election, a \$1,500 target net for a Single filer paid weekly in Arizona solves to a gross of **\$2,210.77**. For the full breakdown and a hand check, see [How the gross-up calculation works](/cbs/core-concepts/gross-up-calc#worked-example). ## Behaviors to know * **Additional federal withholding is added on top** of the grossed-up amount, not solved into it, so `grossPay − additionalFederalWithholding` reconstructs the base gross-up. * **Supplemental settings change the result.** Setting `federalSupplementalFlat` (or a state supplemental flag) switches the method to flat; under flat supplemental, federal allowances don't affect the result. California has specific handling when a `SUPPLEMENTAL` state parameter is `BONUS` or `COMMISSION`. * **Results can differ by a cent** from a hand calculation, because intermediate sums are rounded to two decimals only at the end. See [Known API behaviors](/cbs/api/known-behaviors). For the concept behind this, see [How the gross-up calculation works](/cbs/core-concepts/gross-up-calc), and for the withholding method, see [Calculation methods by calculator](/cbs/core-concepts/calc-methods). # Test calculations against known values Source: https://docs.symmetry.com/cbs/api/test-known-values Validate your integration's output against expected results. To verify your integration, compare the API's output for a fixed set of inputs against values you expect. This checks your request wiring, not the tax math itself, which is maintained by Symmetry. ## Approach 1. **Pin your inputs.** Use a fixed request, including an explicit `checkDate`, so results don't shift as the current date advances. 2. **Capture the baseline.** Record the response `content` (`grossPay`, `federal`, `fica`, `medicare`, `state`, `netPay`) for that request. 3. **Assert on the fields you care about.** Compare each returned amount to your expected value in your test suite. ## What to watch for * **Pin the `checkDate`.** Tax tables change over time; without a fixed date, expected values drift with each tax update. * **Match the method.** The same wages produce different results across calculators and supplemental settings. Compare like-for-like. See [Calculation methods by calculator](/cbs/core-concepts/calc-methods). * **Display rounding.** Monetary results are returned to two decimals (cents). If results differ from what you expect, see [Calculation differs from expected value](/cbs/api/calc-differs). # Authentication model Source: https://docs.symmetry.com/cbs/core-concepts/authentication-model How CBS authenticates: one API key used by both the widget and the API, and how it compares to Symmetry's other products. CBS authenticates every request with a single **API key** tied to your account. There's no OAuth flow and no token exchange. ## One key, used two ways The widget key and the API key are the **same credential**: * **Widget**: pass the key in the script `src`: `…/salary.js?key=yourKey`. The widget reads it and forwards it to the API. * **API**: send that same value in the `pcc-api-key` request header. ```text theme={null} pcc-api-key: yourKey ``` A widget key is visible in page source by nature of client-side embedding. Keep API keys server-side and never commit them to source control. ## How this compares to other Symmetry products CBS uses a plain API key, not a JWT. Symmetry's products don't all authenticate the same way, so if you've integrated another one, note the difference: | Product | Authentication | | - | - | | Calculators by Symmetry | API key (`pcc-api-key` header) | | Symmetry Payroll Forms | JWT bearer token | | Symmetry Payroll Point | JWT bearer token | | Symmetry Tax Engine | API key (`Authorization` header; no bearer/JWT) | ## Key validation and restrictions The API validates your key on every request and enforces: * **Validity**: missing, invalid, or disabled keys are rejected with HTTP 401. * **Product access**: the key must be entitled to CBS. * **Domain restriction (optional)**: a key can be limited to specific allowed origins; requests from other domains are rejected. * **Expiration**: keys carry an expiration date, surfaced in the `X-Pcc-Api-Exp-Date` response header. Usage caps are covered separately in [Rate limits](/cbs/api/rate-limits). ## Getting a key To request a key or get help with an existing one, contact your Symmetry Client Success representative or reach out through the [Client Support Center](https://support.symmetry.com). See [Prerequisites](/cbs/getting-started/prerequisites) for details. # Calculation methods by calculator Source: https://docs.symmetry.com/cbs/core-concepts/calc-methods How each CBS calculator withholds federal and state tax: annualized, flat, or current aggregation, mapped per calculator (salary, bonus, gross-up, 401k). CBS supports multiple pay types, including regular salary, hourly wages, bonuses, and tips. The withholding calculation method depends on the calculator used. Each calculator applies a specific method for federal and state withholding. The following calculation methods are used by CBS: * Annualized: Annualizes the gross pay, calculates tax on the annualized amount, and then converts the tax amount back to a per pay period withholding amount. * Flat: Calculates withholding on special wage payments, such as bonuses, by using supplemental tax rates. * Current aggregation: Uses the current period paycheck amount to apply the correct withholding rates to special wage payments, such as bonuses. Use the following table to identify which calculation method applies to a specific calculator.
CalculatorFederal Calculation MethodState Calculation Method
Salary, Hourly, 401(k), 403(b), Final pay, Stock option, and TuitionAnnualizedAnnualized
Flat bonusFlatFlat
Aggregate bonusFlat or current aggregation for bonus amounts
Annualized for gross pay amounts		Current aggregation for bonus amounts
Annualized for gross pay amounts
Gross-upFlat or current aggregation
Annualized, for gross pay YTD if provided		Flat or current aggregation
Annualized, for gross pay YTD if provided
Tax tipAnnualizedAnnualized
# How calculators work Source: https://docs.symmetry.com/cbs/core-concepts/how-calcs-work A CBS calculator is one REST resource and one widget running the same gross-to-net calculation. Every CBS calculator is the same thing exposed two ways, a **REST resource** and a **widget**, both running the **same calculation**. ## One calculator, two front doors * **REST resource**, each calculator is an endpoint under `/api/calculators/` (for example `/api/calculators/salary`). A `GET` returns the calculator's field model; a `POST` runs a calculation. * **Widget**: the hosted widget for that calculator renders a UI and, under the hood, calls that same REST endpoint with your key. Because both paths run the same calculator, the inputs and results are identical whichever you use. For the list of calculators and which paths support each, see [Available calculators](/cbs/overview/available-calcs). ## The gross-to-net calculation A calculator takes wages, jurisdictions, and filing details and computes federal, state, and local withholding plus payroll taxes. Each one decides which inputs to collect and which method to apply, then returns the result through the widget or the REST endpoint. Symmetry maintains the tax rules behind the calculators, so results stay current with tax changes without any work on your side. ## From inputs to results Wages or rates, pay frequency, filing status, work and resident jurisdictions, and any calculator-specific fields (bonus amount, contribution percentage, and so on). Each calculator uses a specific withholding method: annualized, flat (supplemental), or current aggregation. See [Calculation methods by calculator](/cbs/core-concepts/calc-methods). The calculator computes federal, state, and local withholding plus Social Security and Medicare. Gross pay, itemized taxes, deductions, and net pay, ready to display, store, or report on. See [Request and response structure](/cbs/api/request-and-response). The same wages can produce different taxes and net pay across calculators, because each calculator uses a different method. This is expected. # Quickstart: Call the calculators API Source: https://docs.symmetry.com/cbs/getting-started/call-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). **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. ## 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 Call patterns, language examples, and reports. Base URLs, authentication, and the full endpoint reference. Usage limits are returned in response headers. See [Rate limits](/cbs/api/rate-limits). # Quickstart: Embed a widget Source: https://docs.symmetry.com/cbs/getting-started/embed-widget Add a CBS widget to your page with a single script tag. CBS widgets are the fastest way to add a paycheck calculator to your site. Symmetry hosts and maintains the UI, and you embed it with one script tag. First, check the [prerequisites](/cbs/getting-started/prerequisites). Not sure widgets are the right path? See [Widgets vs. API](/cbs/overview/choose-path). ## 1. Add the script Copy this into a page served by your web server, replacing `yourKey` with your key. This example uses the **salary** calculator: ```html theme={null} ``` A minimal test page: ```html theme={null} Widget example
``` ## 2. Verify it renders Widgets can't run from a `file://` page; they must load over `http(s)://`. To view your test page: 1. Save the HTML above as `index.html`. 2. Open a terminal, `cd` into the folder that contains `index.html`, and start a local web server with one of these: * **Python:** `python3 -m http.server 8000` * **Node:** `npx serve` 3. Open the URL it prints (for example, `http://localhost:8000`) in your browser. The calculator should render and be ready to accept inputs. By default, it fills the width of its container; to set its size, see [Make a widget responsive](/cbs/widgets/make-responsive). If the key is missing or invalid, the widget shows an error instead of rendering the calculator (for example, *"Invalid api key"*). Double-check your key. See [Prerequisites](/cbs/getting-started/prerequisites). ## 3. Swap in a different calculator Change the script filename to any calculator type. For example `hourly.js`, `grossup.js`, or `flatbonus.js`: ```html theme={null} ``` See [Available calculators](/cbs/overview/available-calcs) for the full list. ## Next steps Every calculator you can embed as a widget. The model behind every calculation, and what drives the results. More references: * [Configure your widget](/cbs/widgets/configuration-methods) * [Object model and default properties](/cbs/api/object-model) * [Widget catalog](/cbs/widgets/catalog) * [Customize styling](/cbs/widgets/customize-styling) * [Make a widget responsive](/cbs/widgets/make-responsive) * [Multi-calculator](/cbs/widgets/multi-calc) * [Examples](/cbs/widgets/examples) # Prerequisites Source: https://docs.symmetry.com/cbs/getting-started/prerequisites What you need before embedding a CBS widget or calling the calculators API: your key, supported browsers, and hosting. Before you start with [widgets](/cbs/getting-started/embed-widget) or the [calculators API](/cbs/getting-started/call-api), make sure you have the following. ## Your key CBS uses a **single key** for both integration paths: * **Widgets:** pass the key in the script tag's `src`: ```html theme={null} ``` * **Calculators API:** send the *same* value in the `pcc-api-key` request header: ```http theme={null} pcc-api-key: yourKey ``` It's one credential: the widget reads the key from its own script tag and forwards it to the API as `pcc-api-key`. To request a key or retrieve an existing one, contact your Symmetry Client Success representative or reach out through the [Client Support Center](https://support.symmetry.com). ## Supported browsers (widgets) CBS widgets run in current versions of the major browsers (Chrome, Edge, Firefox, Safari). **Internet Explorer is not supported**: the widget shows an unsupported-browser message instead of loading. There is no formal minimum-version matrix; any modern, evergreen browser works. ## Hosting * **Widgets:** must load from a web server over `http(s)://`, not opened directly from the local file system (`file://`). A widget reads its host from its own script URL, so it needs a live page URL to render. * **Calculators API:** always accessed over **HTTPS**. ## Key limits and restrictions * **Domain restriction:** a key can be limited to specific domains, so it only works on sites you control. See [Authentication model](/cbs/core-concepts/authentication-model). * **Trial key cap:** trial keys have a calculation limit. Once it's reached, the API returns a 401 error ("API rate limit has been exceeded"). See [Rate limits](/cbs/api/rate-limits). ## Next Add a calculator to a page with one script tag. Authenticate and run your first calculation. # Available calculators Source: https://docs.symmetry.com/cbs/overview/available-calcs Every calculator offered by Calculators by Symmetry (CBS), with a one-line description and the integration paths that support it. This is the full list of CBS calculators. Most are available on both [integration paths](/cbs/overview/choose-path) (as an embeddable widget and through the API); exceptions are noted. ## Calculator types | Calculator | Description | Widget | API | | - | - | :-: | :-: | | **Salary** | Net ("take-home") pay from a per-period or annual salary. | ✓ | ✓ | | **Hourly** | Take-home pay from up to six hourly pay rates. | ✓ | ✓ | | **Gross-up** | Work backward from a target net pay to the required gross wages. | ✓ | ✓ | | **Flat bonus** | Withhold on a bonus using supplemental (flat) tax rates. | ✓ | ✓ | | **Aggregate bonus** | Withhold on a bonus using the aggregate method (combined with regular wages). | ✓ | ✓ | | **401(k)** | Show how 401(k) contributions affect a paycheck and retirement savings. | ✓ | ✓ | | **403(b)** | Show how 403(b) contributions affect a paycheck and retirement savings. | ✓ | ✓ | | **457** | 457(b) deferred-comp calculator (mirrors 401(k)). | ✗ | model only¹ | | **Final pay** | Termination payout using current and prior pay-period information. | ✓ | ✓ | | **Stock option** | Net gain or loss from exercising or selling stock, and taxes owed. | ✓ | ✓ | | **Tuition** | Tax impact of a tuition-reimbursement amount. | ✓ | ✓ | | **Tax tip** | Like the hourly calculator, with a tip amount added to compute taxes. | ✓ | ✓ | ¹ **457** has no dedicated widget and is not a listed API endpoint. It's reachable only through the API's model, print, and state-parameter flows when a 457 calculator type is supplied. In the API's `/calculators` listing, the two bonus calculators are named `bonus-percent` (flat bonus) and `bonus-agregate` (aggregate bonus); the widget and URL names are `flatbonus` and `agbonus`. Supplemental bonus methods are state-by-state compliant. Some states do not support the flat bonus (percent) method. For example: AZ, CT, DE, HI, KY, LA, MA, MS, NJ, UT, WY, DC, and PR. ## Multi-calculator In CBS, **multi-calculator** is a **widget-only** layout feature, not a calculation type. It places up to four calculators side by side on one page and includes a copy button to reuse inputs across them. It has no API endpoint. See [Multi-calculator](/cbs/widgets/multi-calc). ## Calculation methods The withholding method varies by calculator (annualized, flat, or current aggregation). For the per-calculator breakdown, see [Calculation methods by calculator](/cbs/core-concepts/calc-methods). # Widgets vs. API Source: https://docs.symmetry.com/cbs/overview/choose-path Decide between Calculators by Symmetry (CBS) widgets and the calculators API based on what you're trying to build. Calculators by Symmetry (CBS) has two integration paths: embeddable **widgets** and the **calculators API**. Both use the same Symmetry tax data and return the same compliant results; the difference is how much of the UI and hosting you own. ## What are you trying to do? Use **widgets**. Add one script tag and Symmetry hosts and renders the calculator UI. Configure defaults, theme, and help text inline, by URL, or in the admin console. Use the **API**. Send inputs from your own interface (or backend) and receive results to display, store, or report on. Pick by intent: * **"I just want a working calculator on a page."** → widgets * **"Fastest possible launch and a standard UI is fine."** → widgets * **"It needs to match my product's look exactly."** → API * **"I need calculations on my server or in batch."** → API * **"I want to store or report on results."** → API * **"Not sure, or want both?"** → Start with widgets and add the API later. They share the same calculators, so results stay consistent. ## At a glance | | Widgets | API | | - | - | - | | **Setup effort** | Lowest, add one script tag | Higher, build your own UI and requests | | **User interface** | Symmetry-managed, themeable | Fully custom, built by you | | **Where it runs** | In the browser, hosted by Symmetry | Your client or server | | **Configuration** | Inline, by URL, or admin console | Request parameters | | **Best for** | Fast launch, standard calculator UI | Custom UX, server-side use, reporting | Both paths stay current with federal, state, and local tax changes automatically, so your choice comes down to control and integration depth, not accuracy. ## Next steps Embed your first calculator in minutes. Make your first calculators API call. # Data and accuracy Source: https://docs.symmetry.com/cbs/overview/data-and-accuracy How CBS handles calculation data across widgets and the API, and where the accuracy of its results comes from. Widgets and the API run the same calculation against the same tax data, so everything on this page applies to both [integration paths](/cbs/overview/choose-path). ## Stateless calculations Calculations are **stateless**: CBS takes your inputs, runs the calculation, and returns the result. It does **not persist calculation inputs or results to a database**, and it holds no session state between requests. A widget calls the same API, so the same is true whichever path you use. ## Where accuracy comes from CBS tax calculations are performed by the Symmetry Tax Engine against Symmetry's maintained tax data, so a CBS result matches what the engine returns for the same inputs. Monetary results are returned to the cent (two decimal places). Because tax tables change over time, pin an explicit `checkDate` when you need a repeatable result. See [Test calculations against known values](/cbs/api/test-known-values). # What is Calculators by Symmetry (CBS)? Source: https://docs.symmetry.com/cbs/overview/what-is-cbs What Calculators by Symmetry (CBS) is: accurate, compliant paycheck calculators you embed as a widget or call as a REST API, and how the two paths differ. Calculators by Symmetry (CBS) lets you add accurate, compliant paycheck calculators to your website or application. Using Symmetry's tax data, CBS calculates federal, state, and local withholding so your users can estimate take-home pay, gross-up amounts, bonuses, retirement contributions, and more. Symmetry maintains the underlying tax data, so results reflect the latest federal, state, and local rules without you maintaining tax logic yourself. ## What you can do with CBS * Estimate net ("take-home") pay from salary or hourly wages * Reverse-engineer the gross pay needed to hit a target net (gross-up) * Model bonuses using flat or aggregate supplemental methods * Show the paycheck impact of 401(k) and 403(b) contributions * Calculate final pay, stock option, tuition, and tax tip scenarios See [Available calculators](/cbs/overview/available-calcs) for the full list. ## The two integration paths CBS offers two integration paths. Use either on its own, or combine them. Symmetry-managed calculators you embed with a single script tag. The fastest way to launch. Configure defaults, theme, and help text inline, by URL, or through the admin console. Send calculator inputs from your own interface and receive results to display, store, or report on. Use it when you need a custom UI or server-side calculations. Not sure which fits your use case? See [Widgets vs. API](/cbs/overview/choose-path). ## What CBS is built for CBS produces paycheck **estimates**, figures you show someone so they can understand or plan around their pay. It fits a marketing site, an employee self-service portal, an onboarding flow, or an offer-letter tool. It isn't a payroll system of record. CBS doesn't run an actual pay run, file, or remit. If you need production withholding at scale, talk to your Symmetry representative about the right product. For how a calculation is put together, see [How calculators work](/cbs/core-concepts/how-calcs-work). ## Where to go next Embed your first calculator widget. Understand how each calculator computes withholding. # Configuration methods Source: https://docs.symmetry.com/cbs/widgets/configuration-methods The three ways to configure a CBS widget: inline JSON, an external URL, and the admin console, and how they combine. A widget can be configured three ways. Use one, or combine all three; the same `data-defaults` object (a `model` of field values, plus `style` and `helptext`) applies to each method. ## Inline JSON Pass a JSON object in the `data-defaults` attribute of the script tag. Self-contained, with nothing to host. ```html theme={null} ``` ## External URL (JSONP) Point `data-defaults` at a hosted file that returns the object wrapped in `jsonCallback(...)`. Best for reusing configuration across pages. See [Load widget defaults from a URL](/cbs/widgets/defaults-from-url). ```html theme={null} ``` ## Admin console Set property/value pairs centrally, tied to your key, with no attribute needed. See [Manage widgets from the admin console](/cbs/widgets/admin-console). ## What you can configure The `data-defaults` object accepts three kinds of content: | Key | Sets | Reference | | - | - | - | | `model` | Prefilled calculator inputs, field values like `grossPay`, `payFrequency`, `voluntaryDeductions` | [Object model and default properties](/cbs/api/object-model) | | `style` | Colors, fonts, layout per region | [Styling reference](/cbs/widgets/styling) | | `helptext` | Custom field help text | [Help text customization](/cbs/widgets/customize-helptext) | For the complete list of configurable field names and accepted values, see [Object model and default properties](/cbs/api/object-model). ## How the methods combine When more than one method sets the same property, they resolve together. Use **inline** values for page-specific overrides on top of **URL** or **admin console** defaults. # Customize widget help text Source: https://docs.symmetry.com/cbs/widgets/customize-helptext Override the popup help text a widget shows when a field receives focus, or turn help text off entirely. Each calculator field can show popup help text on focus. You can override the text per field with an inline `helptext` object in the widget's [`data-defaults`](/cbs/widgets/configuration-methods). ## Custom help text Key the `helptext` object by field name: ```html theme={null} ``` Help text is set inline only. Unlike field values and styling, it isn't read from a [hosted URL](/cbs/widgets/defaults-from-url). ## Disable all help text Turn off every help-text popup by setting `helptext` to `false`: ```html theme={null} ``` ## Field names Help text can be set for any form field. For the list of field names, see [Object model and default properties](/cbs/api/object-model). # Load widget defaults from a URL Source: https://docs.symmetry.com/cbs/widgets/defaults-from-url Host a JSON file of widget default values and styling and point the widget at it via JSONP. Instead of embedding configuration in every script tag, host it in one file and point the widget at it. The widget fetches the file on load via AJAX using **JSONP** (a `jsonCallback` wrapper), so you can update default values and styling in one place. ## Point the widget at a URL Pass a `url` inside `data-defaults`: ```html theme={null} ``` ## Host the file as JSONP Wrap the object in `jsonCallback(...)`. Put field values under a `model` key; `style` sits at the top level: ```javascript theme={null} jsonCallback({ "model": { "grossPay": 2500, "payFrequency": "biweekly" }, "style": { "body": { "background-color": "#2f4f4f" }, "labels": { "color": "#fff" } } }); ``` This is the easiest way to set richer defaults such as multiple deductions. Help text can't be loaded this way. The URL file is read for field values (`model`) and `style` only. Set help text [inline](/cbs/widgets/customize-helptext). The widget still loads if the URL is unreachable or the JSON is malformed. It silently falls back to defaults rather than showing an error. Test your file before relying on it. For the full attribute list, see [Configuration methods](/cbs/widgets/configuration-methods). To manage defaults without hosting a file, see [Manage widgets from the admin console](/cbs/widgets/admin-console). # Embed a widget in common layouts Source: https://docs.symmetry.com/cbs/widgets/examples Recipes for embedding CBS widgets: employee self-service portals, popups, and multi-deduction setups. These recipes cover common ways to embed a widget. All use the salary widget, but any [calculator type](/cbs/widgets/catalog) works. ## Prefill multiple deductions from a URL Setting several deductions is easiest by loading them from a hosted file: ```html theme={null} ``` See [Load widget defaults from a URL](/cbs/widgets/defaults-from-url). ## Embed in an employee self-service portal When the calculator loads after login, the employee is known. Fetch their values from your database, serve them by URL, and apply branding inline at the same time: ```html theme={null} ``` ## Open the widget in a popup ```html jQuery UI dialog theme={null} ``` ```html Native JavaScript theme={null} ``` For portals, combine URL-based [default values](/cbs/widgets/configuration-methods) with inline [theming](/cbs/widgets/customize-styling) so per-employee data and site branding apply together. # Make a widget responsive Source: https://docs.symmetry.com/cbs/widgets/make-responsive Fit a CBS widget into a fixed-width or fluid container. CBS widgets are **responsive**: a widget stretches to fill the width of its parent element. You control the size by controlling the container. ## Fluid (fill available width) Placed directly in the page or a full-width element, the widget expands to the viewport width: ```html theme={null} ``` ## Fixed width Wrap the widget in a container with a set width and it fits that width: ```html theme={null}
``` ## Tips * Set the width on the **parent element**, not the script tag. The widget reads its width from the container. * For side-by-side calculators, see [Multi-calculator](/cbs/widgets/multi-calc). If a widget isn't sizing the way you expect, see [Widget won't resize in my layout](/cbs/widgets/wont-resize). # Show calculators side by side Source: https://docs.symmetry.com/cbs/widgets/multi-calc Place up to four calculators next to each other with the multi-calculator widget. Use the **multi-calculator** widget to show up to four calculators side by side on one page, handy for comparing scenarios (for example, the same wages at different pay frequencies). ## Add the multi-calculator Use the `multi.js` script and set how many calculators and which type: ```html theme={null} ``` ## Attributes | Attribute | Description | Default | | - | - | - | | `data-calculator` | The calculator type to display. Accepts any [calculator type](/cbs/widgets/catalog). | `salary` | | `data-count` | Number of calculators to display (1–4). Values above four or non-numbers fall back to the default. | `2` | | `data-defaults` | Prefills fields, exactly as with a single widget. See [Configuration methods](/cbs/widgets/configuration-methods). | None | ## Copy inputs across calculators The multi-calculator includes a **copy button** that takes the inputs from the leftmost (first) calculator and applies them to the others, so you can set shared inputs once and vary just one field per column. Give the container enough width for the number of calculators you show; each still follows the responsive rules in [Make a widget responsive](/cbs/widgets/make-responsive). # Enable optional widget features Source: https://docs.symmetry.com/cbs/widgets/special-features Turn on imputed income, calculation summation, and report printing or emailing. Widgets have several optional features you can turn on. Field-level features (imputed income, summation) are set inline in `data-defaults`; report printing and emailing are enabled by Symmetry in the admin console. ## Add imputed income Set `imputed` to `true` to add an **Add Other Income** button, letting users include imputed income in the calculation: ```html theme={null} ``` ## Enable running totals (summation) Set `sum` to `true` to add an **Add to memory** button that keeps a running total across calculations: ```html theme={null} ``` ## Print or email reports These are configured by Symmetry in the admin console. [Log a ticket](/symmetry/support/getting-support) to enable them: * **Disable report printing**: restrict the print options to `none`. * **Email reports**: email a PDF of each report to a designated address (usually your payroll department). Once enabled, an `email report` toggle in the print object lets the client turn it on or off. Because report printing/emailing is set in the admin console, include the intended behavior (and any delivery email address) in your request. See [Manage widgets from the admin console](/cbs/widgets/admin-console). # Quickstart: Look up a tax rate and filing instructions Source: https://docs.symmetry.com/guides/getting-started/quickstart Get productive in Guides fast: log in, Ask AI on Search, filter Taxes for rates, then open Filing Tax Program tabs for step-by-step instructions. This quickstart walks you through the fastest path to value in Symmetry Guides: logging in, asking a question, looking up a tax rate, and finding filing instructions for a tax program. ## 1. Log in to Symmetry Guides Symmetry Guides authenticates using Auth0. Access Guides through the tile on your Client Support Center home page, or go directly to [guides.symmetry.com](https://guides.symmetry.com/search). ## 2. Ask your first question From the **Search** page, type a question in plain language into the search field, for example a question about a local rate or a state's withholding filing rules. Click the **Ask AI** button (or press Enter) to get a summarized answer along with its sources. Not sure what to ask? Example prompts appear below the search box to help you get started. ## 3. Look up a tax rate Click **Taxes** in the left navigation to search and filter tax-specific data: 1. Filter by jurisdiction, tax name or tax ID, effective date, or STE release to narrow down to a specific tax or group of taxes. 2. Click a tax row to view additional detail and tax record history. 3. Click **View record** within the tax detail to see full history for that line item. ## 4. Find filing instructions for a tax program Click **Filing** in the left navigation, then use the search field to find a specific tax program: 1. Select a row to open the **Tax Program** detail page. 2. Review the **Overview** tab for a summary of what's needed before filing, plus agency contact information. 3. Check the **Filing**, **Payments**, **Taxes**, and **Register** tabs (whichever are available for that program) for step-by-step guidance. ## Next steps Receive tax changes automatically instead of checking Guides manually. Moving from TNS to Guides, and what changes for your team. More references: * [Understanding tax records](/guides/core-concepts/tax-records) for what the Effective date, STE release, and Who pays fields mean * [Filing guide coverage](/guides/core-concepts/filing-guide-coverage) for why the available sections vary by tax program # Migrating from Tax Notification Service to Symmetry Guides Source: https://docs.symmetry.com/guides/migrating/from-tax-notification-service Plan your TNS-to-Guides migration: feature comparison, transition timeline, Client Support Center access, and Taxes/Filing field mapping. Symmetry Guides replaces the Tax Notification Service (TNS). This article walks you through what's changing, what to expect during the transition, and where to find your tax data in Symmetry Guides. ## What is Symmetry Guides? Symmetry Guides is designed to replace TNS and expand on everything it offered. Built on the same trusted tax research database that powers Symmetry's payroll tax products, Guides delivers real-time tax rates, wage bases, and compliance data across 7,000+ U.S. jurisdictions, as well as rate information for Canadian taxes. Guides also goes beyond TNS capabilities by including step-by-step tax filing information across U.S. jurisdictions, agency-specific contact details, and an AI-powered search feature. ## Demo video Watch a high-level demonstration comparing Tax Notification Service to Guides. ``` ### Attribute reference | Attribute | Required | Purpose | | :- | :- | :- | | `:src` | Yes | Vue shorthand for `v-bind:src`. Binds `src` to the value set within, which is the `embeddedUri` returned from the employee access token or administrator access token endpoint. | | `allow` | Yes | Enables the browser feature policies the embedded experience needs. `camera` is required for in-browser document scanning during Section 1. `geolocation` should also be allowed to cover all supported document capture flows. | | `sandbox` | Yes | Applies a security sandbox that restricts everything by default, then re-enables specific capabilities via tokens. See additional details below. | | `width`/`height` | Recommended | The embedded experience is responsive; a full-width container at least `1200px` tall avoids internal scrollbars on most viewports. | | `frameBorder` | Optional | Visual only. | | `title` | Recommended | Improves accessibility for screen readers. | #### Sandbox tokens The `sandbox` attribute starts fully locked down and only re-enables what's listed: | Token | Effect | | :- | :- | | `allow-scripts` | Lets the embedded content run JavaScript. | | `allow-same-origin` | Allows the iframe to be treated as same-origin, which is necessary for `sessionStorage` access and cookie-based session auth. | | `allow-popups` | Allows the embedded app to open new windows/tabs (for example, document downloads or external links). | | `allow-forms` | Allows form submission. | | `allow-storage-access-by-user-activation` | Needed in browsers (Safari, Firefox) that partition third-party cookies, so the embedded session cookie can be accessed. | ## Why the camera permission matters During Section 1, the embedded experience presents a scan or upload document dialog so the employee can capture identity and work authorization documents directly from their device. If the parent `