GUIDES / GETTING STARTED

Getting started

Calculate every tax line on a paycheck with one request. You’re in test mode, and the first 14 days are free.

Authentication

Authentication

Send your secret key as a Bearer token in the Authorization header of every request. Keep keys on your server, never in a browser or mobile app.

Key lifecycle

Guides

Making requests

Requests and responses are JSON. Send Content-Type: application/json on any request with a body. Every endpoint below is served from this host; a self-hosted deployment answers the same paths on its own domain.

The same routes also answer under /api/ (for example /api/paycheck) with identical behavior.

Guides

Money & rounding

Every monetary value in a request or response is an integer number of cents. 300000 is $3,000.00 and a net pay of 219432 is $2,194.32. There are no floating-point dollars anywhere. Convert at your display edge only.

Guides

Rate limits

Each key is limited independently on a fixed one-minute window. The default is 120 requests per minute per key. A self-hosted deployment sets its own with RATE_LIMIT_PER_MIN. The headers in Response headers carry your current budget, so you can pace a pay run without guessing.

Over the limit you get 429 rate_limited. Wait for the Retry-After seconds and cap your own concurrency rather than running into the limit.

async function withRetry(call) {
  for (;;) {
    const res = await call();
    if (res.status !== 429) return res;
    const seconds = Number(res.headers.get("retry-after")) || 1;
    await new Promise((r) => setTimeout(r, seconds * 1000));
  }
}

Guides

Versioning & dates

Rules are effective-dated. The ruleset that runs is the one in force on your checkDate, never today’s. This is the most important thing to get right when you integrate.

{ "checkDate": "2025-12-19", ... }   // 2025 rules
{ "checkDate": "2026-01-02", ... }   // 2026 rules, automatically

API reference

Calculate one paycheck and get back every tax line that applies.

Success shape

{ result: { checkDate, grossPay, pretaxDeductions, posttaxDeductions, employeeTaxTotal, employerTaxTotal, netPay, taxes: [ { id, name, payer, jurisdiction, taxableWages, amount, detail } ] } }

Example response

Real engine output for a $3,000.00 biweekly check dated 2026-08-15 with a $240.00 401(k) deferral, an Ohio work state and an assigned Ohio unemployment rate of 3.1%. Each line also carries a detail, left out here for length.

{
  "result": {
    "checkDate": "2026-08-15",
    "grossPay": 300000,
    "pretaxDeductions": 24000,
    "posttaxDeductions": 0,
    "taxes": [
      { "id": "US_FIT",    "name": "Federal Income Tax", "payer": "employee", "jurisdiction": "federal", "taxableWages": 276000, "amount": 26758 },
      { "id": "US_SS_EE",  "name": "Social Security",    "payer": "employee", "jurisdiction": "federal", "taxableWages": 300000, "amount": 18600 },
      { "id": "US_MED_EE", "name": "Medicare",           "payer": "employee", "jurisdiction": "federal", "taxableWages": 300000, "amount": 4350 },
      { "id": "OH_SIT",    "name": "Ohio Income Tax",    "payer": "employee", "jurisdiction": "state",   "taxableWages": 276000, "amount": 6860 }
      // employer lines: US_SS_ER, US_MED_ER, US_FUTA, OH_SUI_ER
    ],
    "employeeTaxTotal": 56568,
    "employerTaxTotal": 34050,
    "netPay": 219432
  }
}

API reference

The states and DC this build can compute, read from the rulesets on the server, so the list never claims a jurisdiction the engine cannot calculate. Use it to fill a dropdown or to check a workState.code before you send a paycheck. No key needed.

curl https://your-host/v1/states

{ "year": 2026, "states": [ { "code": "AL", "name": "Alabama" }, { "code": "AK", "name": "Alaska" }, ... ] }

API reference

What the calling key is: its mode, plan, expiry and call counts. Send the key as a Bearer token. Use it to check a key before a pay run or to show its expiry in your own admin screen. It does not count as a billable call.

curl https://your-host/v1/me -H "Authorization: Bearer sk_test_..."

{ "keyPrefix": "sk_test_a1b2c3", "mode": "test", "plan": "trial",
  "createdAt": "2026-10-01T12:00:00.000Z", "expiresAt": "2026-10-15T12:00:00.000Z", "expired": false,
  "lastUsedAt": null, "totalCalls": 0, "callsToday": 0, "limits": { "requestsPerMinute": 120 } }

API reference

An unauthenticated liveness and readiness probe for a load balancer or uptime monitor. It reports the API version and how many states this build can compute, so a probe also catches a deploy that shipped without its tax data. Returns 200, or 503 with status: "degraded" if the rule data or the account store cannot be read. Also answers at /healthz.

curl https://your-host/v1/health

{ "status": "ok", "version": "1.0.0", "states": 51, "store": "ok",
  "taxYears": [2025, 2026], "time": "2026-10-01T12:00:00.000Z" }

Tax lines

Tax lines

Each object in result.taxes is one line. A jurisdiction this build does not compute comes back as a line whose detail starts with NOT MODELLED and whose amount is 0, with the detail telling you not to treat that as zero tax. That is separate from calculation_error, which is an engine failure after the input validated.

Errors

Errors

Every error returns the same three fields with a matching HTTP status. A missing rule is never returned as a silent zero.

Response headers

Response headers

Every response carries a request ID. Rate limits are per key, per minute.

Next Tax lines

Objects

Earning

One line of pay. Amounts are integer cents.

[ { "code": "REG",   "category": "regular",      "amount": 300000 },
  { "code": "BONUS", "category": "supplemental", "amount": 50000 } ]

Objects

Deduction

One deduction from pay. The category decides which taxes it reduces: the same deferred dollar can be exempt from one tax and fully taxable under another.

[ { "code": "401K", "category": "deferral_401k", "amount": 24000 },
  { "code": "MED",  "category": "section125",    "amount": 12500 },
  { "code": "GARN", "category": null,            "amount": 10000 } ]

Objects

FederalW4

The employee’s Form W-4 (2020 revision or later). Dollar fields are in cents.

{ "filingStatus": "married_joint", "multipleJobs": true, "dependentCredit": 400000,
  "otherIncome": 0, "deductions": 0, "extraWithholding": 2500 }

Objects

YearToDate

Year-to-date wages in cents, needed for every wage-capped tax. For a new hire or the first check of a year, send zeros. The engine never assumes prior wages you did not state.

{ "socialSecurity": 7800000, "medicare": 7800000, "futa": 700000, "stateUnemployment": { "OH": 900000 } }

Objects

StateWithholding

Used for workState and residenceState.

{ "workState": { "code": "NJ" }, "residenceState": { "code": "PA" } }

{ "code": "GA", "certificate": { "filingStatus": "married_joint", "allowances": 2 } }

Objects

PaycheckResult

Returned under result on a 200. Amounts are integer cents.

{ "taxId": "NH_SUI_ER", "tier": "inferred",
  "note": "New Hampshire's published new-employer rate is confirmed only through 2026-09-30; the state has not yet published the rate for this check date, so the last confirmed 1.70% was used. ..." }   // one entry of notices[]

Account

Pricing

Usage-based, never per employee per month. Every jurisdiction is included for everyone and you pay for the calculations you make: a flat $0.09 per call at any volume.

To size a bill before you sign up, the public estimator takes a head count and a pay frequency. No key needed.

curl https://your-host/api/estimate \
  -H "Content-Type: application/json" \
  -d '{ "email": "you@company.com", "employees": 8000, "payFrequency": "biweekly" }'

Account

Billing