# Payroll & Salary API
> Gross-pay maths as an API — the everyday salary and wage calculations, computed locally and deterministically and entirely currency-agnostic. The convert endpoint turns a pay figure given at any cadence — annual, monthly, bi-weekly, weekly, daily or hourly — into all the others, using configurable hours per week, weeks per year and days per week. The overtime endpoint computes regular, overtime (time-and-a-half by default) and double-time pay from the hours worked, with adjustable thresholds and multipliers, and reports the effective hourly rate. The raise endpoint applies a percentage or fixed raise, or works out the percentage from a new salary. The prorate endpoint pro-rates a salary by a worked fraction, or by days worked over days in the period — for joiners, leavers and part-periods. Everything is gross pay only: it deliberately excludes tax, deductions and benefits, which are jurisdiction-specific, so the maths stays exact and never goes stale. Computed locally, instant and private. Live, nothing stored. 4 endpoints. Ideal for HR and payroll tools, job boards and offer calculators, freelance and contractor rate tools, and budgeting apps. This is gross-pay maths; for loan, interest and investment maths use a finance-calculator API, and for net/take-home pay apply your local tax rules separately.

## Authentication
All requests require your oanor API key in the `x-oanor-key` header. Get one at https://www.oanor.com/developer/keys.

```bash
curl -H "x-oanor-key: oanor_live_…" "https://api.oanor.com/payroll-api/..."
```

## Pricing
- **Free** (Free) — 9,335 calls/Mo, 2 req/s
- **Starter** ($11/Mo) — 18,950 calls/Mo, 8 req/s
- **Pro** ($31/Mo) — 239,500 calls/Mo, 20 req/s
- **Mega** ($69/Mo) — 1,240,000 calls/Mo, 50 req/s

## Endpoints

### Payroll

#### `GET /v1/convert` — Convert pay between periods

**Parameters:**
- `annual` (query, optional, string) — Annual pay Example: `52000`
- `monthly` (query, optional, string) — Or monthly
- `weekly` (query, optional, string) — Or weekly
- `daily` (query, optional, string) — Or daily
- `hourly` (query, optional, string) — Or hourly
- `hours_per_week` (query, optional, string) — default 40 Example: `40`
- `weeks_per_year` (query, optional, string) — default 52 Example: `52`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/payroll-api/v1/convert?annual=52000&hours_per_week=40&weeks_per_year=52"
```

**Response:**
```json
{
    "data": {
        "note": "Gross pay only — excludes tax, deductions and benefits.",
        "daily": 200,
        "annual": 52000,
        "hourly": 25,
        "weekly": 1000,
        "monthly": 4333.33,
        "biweekly": 2000,
        "assumptions": {
            "days_per_week": 5,
            "hours_per_week": 40,
            "hours_per_year": 2080,
            "weeks_per_year": 52
        }
    },
    "meta": {
        "timestamp": "2026-06-03T17:41:59.747Z",
        "request_id": "35f7ae6d-2646-4a8d-8447-d23608691e67"
    },
    "status": "ok",
    "message": "Convert pay periods",
    "success": true
}
```

#### `GET /v1/overtime` — Overtime / double-time pay

**Parameters:**
- `hourly` (query, required, string) — Base hourly rate Example: `25`
- `hours` (query, required, string) — Hours worked Example: `45`
- `threshold` (query, optional, string) — OT threshold (default 40) Example: `40`
- `multiplier` (query, optional, string) — OT multiplier (default 1.5) Example: `1.5`
- `double_threshold` (query, optional, string) — Double-time threshold
- `double_multiplier` (query, optional, string) — default 2 Example: `2`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/payroll-api/v1/overtime?hourly=25&hours=45&threshold=40&multiplier=1.5&double_multiplier=2"
```

**Response:**
```json
{
    "data": {
        "note": "Gross pay only. Default overtime is time-and-a-half above 40 hours; adjust threshold/multiplier as your rules require.",
        "input": {
            "hours": 45,
            "hourly": 25,
            "threshold": 40,
            "multiplier": 1.5,
            "double_threshold": null,
            "double_multiplier": null
        },
        "gross_pay": 1187.5,
        "regular_pay": 1000,
        "overtime_pay": 187.5,
        "regular_hours": 40,
        "overtime_hours": 5,
        "double_time_pay": 0,
        "effective_hourly": 26.39,
        "double_time_hours": 0
    },
    "meta": {
        "timestamp": "2026-06-03T17:41:59.849Z",
        "request_id": "86d57673-827c-4304-84d9-9c6f2e58a4a7"
    },
    "status": "ok",
    "message": "Overtime pay",
    "success": true
}
```

#### `GET /v1/prorate` — Pro-rate a salary

**Parameters:**
- `amount` (query, required, string) — Full-period pay Example: `52000`
- `fraction` (query, optional, string) — Worked fraction 0-1
- `days_worked` (query, optional, string) — Days worked Example: `90`
- `days_total` (query, optional, string) — Days in period Example: `365`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/payroll-api/v1/prorate?amount=52000&days_worked=90&days_total=365"
```

**Response:**
```json
{
    "data": {
        "note": "Multiply the full-period pay by the worked fraction (e.g. days worked ÷ days in period).",
        "input": {
            "amount": 52000,
            "fraction": 0.246575
        },
        "prorated_amount": 12821.92,
        "remaining_amount": 39178.08
    },
    "meta": {
        "timestamp": "2026-06-03T17:41:59.950Z",
        "request_id": "f6d6e83e-d5ba-4b33-9414-fd111a89bd7d"
    },
    "status": "ok",
    "message": "Pro-rate a salary",
    "success": true
}
```

#### `GET /v1/raise` — Pay raise calculator

**Parameters:**
- `current` (query, required, string) — Current pay Example: `52000`
- `percent` (query, optional, string) — Raise % Example: `5`
- `amount` (query, optional, string) — Or fixed increase
- `new_salary` (query, optional, string) — Or new pay

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/payroll-api/v1/raise?current=52000&percent=5"
```

**Response:**
```json
{
    "data": {
        "note": "Apply the same to gross pay at any period (annual, monthly, hourly).",
        "input": {
            "current": 52000
        },
        "new_salary": 54600,
        "increase_amount": 2600,
        "increase_percent": 5
    },
    "meta": {
        "timestamp": "2026-06-03T17:42:00.019Z",
        "request_id": "d2452992-17ee-4b2a-9a61-747558b802a1"
    },
    "status": "ok",
    "message": "Raise calculator",
    "success": true
}
```

### Meta

#### `GET /v1/meta` — Spec

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/payroll-api/v1/meta"
```

**Response:**
```json
{
    "data": {
        "note": "Gross pay only — excludes tax, deductions and benefits (these are jurisdiction-specific).",
        "service": "payroll",
        "endpoints": {
            "/v1/raise": "Apply a percentage or fixed raise, or derive the percent from a new salary.",
            "/v1/convert": "Convert pay between annual, monthly, bi-weekly, weekly, daily and hourly.",
            "/v1/prorate": "Pro-rate a salary by a worked fraction or days worked ÷ days in period.",
            "/v1/overtime": "Compute regular, overtime and double-time pay from hours worked."
        },
        "description": "Gross-pay maths: salary/hourly conversion, overtime, raises and pro-rata. Currency-agnostic and tax-free."
    },
    "meta": {
        "timestamp": "2026-06-03T17:42:00.102Z",
        "request_id": "cfd18161-c95f-430d-9bed-6401c3d4467a"
    },
    "status": "ok",
    "message": "Meta",
    "success": true
}
```


---
Marketplace page: https://www.oanor.com/api/payroll-api
OpenAPI spec: https://www.oanor.com/api/payroll-api/openapi.json