One API for 2026 federal withholding, all 50 states + DC, local taxes and state programs like SDI and paid leave — plus payroll runs and paystub PDFs that anyone can verify.
# Calculate one paycheck — nothing is saved curl -X POST $BASE/api/v1/calculate \ -H "Authorization: Bearer pk_your_key" \ -H "Content-Type: application/json" \ -d '{ "payType": "hourly", "payRate": 22, "payFrequency": "biweekly", "regularHours": 80, "overtimeHours": 4, "workState": "CA", "payDate": "2026-11-13", "taxProfile": { "filingStatus": "single" } }' # → gross, federal, state, SS, Medicare, CA SDI, # net pay and employer taxes
Every business that runs payroll through the API is verified first, so paystubs always carry a real, checked employer name.
Request access below. Once approved, we email a free test key and a live key.
POST /companies with legal name, EIN and address. It starts as pending.
We check the IRS EIN letter, Secretary of State record and owner ID. Then payroll unlocks.
Add employees, create a run, approve it, and download paystub PDFs.
Taxes are always calculated by Payidi — callers can't type in tax amounts or year-to-date totals.
2026 IRS Pub 15-T federal withholding, Social Security wage base and Additional Medicare, every state's withholding formula, Maryland county tax, flat local taxes, and employee-paid programs (CA SDI, NY PFL, NJ, WA, MA, OR and more).
Hourly, overtime, double time, salary, bonuses and after-tax deductions. Runs are drafts until approved; approved runs lock and build each employee's year-to-date.
Payidi-branded PDF earnings statements with the employer's verified name. Every stub has a QR code lenders and landlords can check at payidi.com/verify.
Each check returns the employer's Social Security, Medicare, FUTA and SUTA so you can show total cost of payroll.
Verified employers only, no backdating more than 7 days, pay dates move forward per employee, voiding a run revokes its stubs.
The API calculates payroll and issues paystubs. It doesn't move money, pay employees or file tax returns — your business (or ours, on We File plans) handles those.
Build for free with your test key. Pay only when you run real payroll.
Keys starting pk_test_ work right away. Test companies are approved automatically, every calculation is real, and paystubs are stamped SAMPLE and never verify. Test data stays separate from live data.
Keys starting pk_live_ turn on once your monthly platform subscription is set up through our secure Stripe checkout. The plan includes your first 3 verified companies.
$15 per additional verified company per month, and $3 per employee paid in the month (each person counted once, however many paychecks). Added to your next monthly invoice. The calculator is included.
Your platform plan price is shown at checkout. If a payment fails, live keys keep working for 7 days while you update your card; test keys always work.
Base URL . Send your key on every request as Authorization: Bearer pk_…. Keep the key on your server — never in a browser or mobile app. JSON in, JSON out. Limit: 120 requests per minute per key.
| Method | Path | What it does |
|---|---|---|
| POST | /calculate | Calculate one paycheck. Nothing is saved. |
| POST | /companies | Register an employer: legalName, ein (XX-XXXXXXX), address, contactEmail, phone. Starts as pending. |
| GET | /companies · /companies/:id | Your companies and their verification status. |
| PATCH | /companies/:id | Contact info and SUTA rate anytime. Name, EIN, address and logo only before approval. |
| POST | /companies/:id/employees | Add an employee: name, payType, payRate, payFrequency, workState, taxProfile (federal W-4), stateTax (state form). |
| GET | /companies/:id/employees | List employees. |
| PATCH | /companies/:id/employees/:employeeId | Update pay or tax forms, or set status: "terminated". |
| POST | /companies/:id/payroll-runs | Create a draft run: period, pay date and a line per employee (hours, extra earnings, deductions). |
| GET | /companies/:id/payroll-runs · /payroll-runs/:runId | Runs with every line, tax and total. |
| POST | /payroll-runs/:runId/approve | Lock the run and issue paystubs with verification codes. |
| POST | /payroll-runs/:runId/void | Void with a reason; its paystubs stop verifying. |
| DELETE | /payroll-runs/:runId | Delete a draft. |
| GET | /payroll-runs/:runId/paystubs · /employees/:employeeId/paystubs | Paystub IDs and verification codes. |
| GET | /paystubs/:paystubId/pdf | The earnings statement PDF. |
| GET | /verify/:code | Public: check a paystub's verification code (no key needed). |
# 1. Draft — every check is calculated curl -X POST $BASE/api/v1/companies/COMPANY_ID/payroll-runs \ -H "Authorization: Bearer pk_your_key" -H "Content-Type: application/json" \ -d '{ "payFrequency": "weekly", "periodStart": "2026-11-02", "periodEnd": "2026-11-08", "payDate": "2026-11-13", "lines": [ { "employeeId": "EMPLOYEE_ID", "regularHours": 40, "overtimeHours": 3.5, "deductions": [ { "description": "Uniform", "amount": 15 } ] } ] }' # 2. Approve — locks figures, issues paystubs curl -X POST $BASE/api/v1/payroll-runs/RUN_ID/approve -H "Authorization: Bearer pk_your_key" # 3. Download a paystub curl -o stub.pdf $BASE/api/v1/paystubs/PAYSTUB_ID/pdf -H "Authorization: Bearer pk_your_key"
stateTax)Copy these from the employee's state withholding form: filingStatus (single, married, married_both_working, married_separate, head_of_household), allowances, additionalAllowances, dependents, extraWithholding, exempt, and localTaxes like [{"name":"Philadelphia Wage Tax","rate":0.0375}]. Some states use extra fields: azRate (AZ), ctCode (CT), njRate (NJ), mdCounty (MD, required), wvTwoEarner (WV), vaAgeBlind (VA), maBlind (MA). New York City and Yonkers resident tax aren't calculated yet. The full state-by-state guide comes with your key.
Errors come back as { "error": "message" } with status 400 (bad input), 401 (key), 402 (live key billing not active), 403 (company not verified), 404, 409 (conflict, e.g. overlapping period), 422 (a case the engine can't calculate, e.g. W-4 Step 2 box) or 429 (rate limit).
Tell us about your business and how you'll use payroll. We review requests within one business day and email your test and live keys once approved.