NextRaise API | Payroll, HR & Compensation Calculators API

Quickstart

Make your first request in under a minute. Use sandbox keys while testing.

1) Get an API key

Create a workspace, pick plan, and generate a key.

Get API Key

2) Call an endpoint

Send JSON with your inputs. Receive normalized outputs.

curl -X POST "https://api.nextraise.in/v1/us/paycheck/calculate" \
  -H "Authorization: Bearer NR_SANDBOX_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "gross_pay": 2500,
    "pay_frequency": "biweekly",
    "state": "CA",
    "filing_status": "single",
    "allowances": 0
  }'

Responses include currency, breakdown, and explainers for audit trails.

Authentication

Use Bearer token auth. Keep keys server-side (never expose live keys in the browser).

Key types

• NR_SANDBOX_ — testing
• NR_LIVE_ — production
• Rotate keys anytime

Headers

Authorization: Bearer NR_LIVE_xxx
Content-Type: application/json

Best practices

• Store keys in server environment variables.
• Use separate keys per app/environment.
• Rotate keys on employee exit or suspected leak.
• Use IP allowlisting on higher plans (optional).

Rate limits

Limits vary by plan. When you hit a limit, you’ll receive 429 with retry guidance.

Burst

Short spikes allowed.

Sustained

Requests per minute/hour.

Headers

X-RateLimit-* values returned.

HTTP/1.1 429 Too Many Requests
Retry-After: 2
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 173... (unix)

Endpoints

Core endpoints are grouped by region and domain. Responses are normalized and include breakdowns.

United States

Paycheck • W-4 helpers • State info

+

POST /us/paycheck/calculate

Compute net pay, taxes, and deductions by state + filing profile.

{
  "gross_pay": 2500,
  "pay_frequency": "biweekly",
  "state": "CA",
  "filing_status": "single",
  "allowances": 0,
  "additional_withholding": 0
}

{
  "currency":"USD",
  "net_pay": 1912.34,
  "taxes": { "federal": 310.22, "fica": 191.25, "state": 86.19 },
  "deductions": { "pre_tax": 0, "post_tax": 0 },
  "explainers":[{"code":"FICA","text":"Social Security + Medicare"}]
}

GET /us/states

List US states and supported tax behaviors/metadata.

GET https://api.nextraise.in/v1/us/states

POST /us/w4/estimate-withholding

Estimate withholding impact from W-4 style inputs (helper endpoint).

{
  "filing_status":"single",
  "dependents":0,
  "other_income":0,
  "deductions":0,
  "extra_withholding":0
}

India

In-hand salary • Professional Tax • Regime helper

+

POST /in/salary/inhand

Compute in-hand salary with components (basic, HRA, PF, etc.).

{
  "ctc_annual": 1200000,
  "city_tier":"metro",
  "hra_annual": 240000,
  "pf_employee_annual": 72000,
  "regime":"new"
}

{
  "currency":"INR",
  "inhand_monthly": 76000,
  "breakdown": { "pf": 6000, "tds": 4500, "pt": 200 },
  "notes":["Regime selection affects TDS logic"]
}

GET /in/professional-tax/states

List PT states and slabs metadata.

GET https://api.nextraise.in/v1/in/professional-tax/states

POST /in/tax/regime/compare

Compare old vs new regime estimate (helper endpoint).

{
  "income_annual": 1200000,
  "deductions_80c": 150000,
  "hra_exemption": 0
}

Global

FX • Country metadata • Compliance notes

+

GET /meta/countries

Country list, currency codes, and available calculators.

GET https://api.nextraise.in/v1/meta/countries

GET /fx/rates

FX snapshot (for display, not trading). Cache recommended.

GET https://api.nextraise.in/v1/fx/rates?base=USD

GET /meta/status

Service health + version info.

GET https://api.nextraise.in/v1/meta/status

Want SDKs? Add them under /sdk (Node, Python). This page is structured so you can plug real endpoints later without breaking layout.

Webhooks

Subscribe to events like key rotation, usage thresholds, or plan updates.

POST /webhooks

Create a webhook endpoint (server URL) to receive events.

{
  "url": "https://yourapp.com/webhooks/nextraise",
  "events": ["usage.threshold", "key.rotated"]
}

{
  "id":"wh_123",
  "secret":"whsec_xxx",
  "events":["usage.threshold","key.rotated"]
}

Signature verification

Verify X-NR-Signature using your webhook secret. Reject requests outside your tolerance window.

Errors

All errors are JSON and include a stable code field.

{
  "error": {
    "code": "invalid_request",
    "message": "state must be a valid US state code",
    "request_id": "req_abc123",
    "details": { "field": "state", "expected": "CA|NY|..." }
  }
}

400

Invalid inputs

401/403

Auth/permissions

429/5xx

Rate/service

Security

Designed for enterprise-ish realities: audit trails, predictable responses, and safe defaults.

Audit trails

Use request_id and store inputs/outputs for compliance evidence.

PII minimization

Most endpoints work without employee names or identifiers.

Recommended architecture

• Your app → your backend → NextRaise API
• Cache stable metadata (states, slabs) aggressively
• Keep live keys only on server

Changelog

Versioned releases keep integrations stable.

v1.0

Initial

Core payroll endpoints + metadata endpoints.

v1.x

Planned

SDKs, webhook signatures, expanded state/country rules.

Status

Live uptime widget placeholder (connect to your status page later).

API

Operational

Latency

~120ms

Incidents

None

For production, link this section to a real status page (Statuspage, Better Stack, or your own).

Get an API key

Since this is a static page, we provide a controlled “request key” flow via email. Replace this later with a proper dashboard + OAuth.

Option A: Request via email

Fastest path today. We’ll send sandbox keys first.

Email key request

Option B: Self-serve (placeholder)

Add a dashboard later (login + billing + key management).