Public API

SalaryCeylon API

Free calculator API for AI tools and integrations. No accounts, API keys, or billing.

Fair use

Starting limit: 20 calculation/API requests per hour per IP address. Metadata and docs endpoints allow a higher limit.

When the limit is exceeded, the API returns HTTP 429 with a `Retry-After` header and a structured JSON error.

Endpoints

POST /api/v1/calculate-freelancer.php

Calculate the hourly rate needed to hit a freelancer income goal after expenses, platform fee, and APIT.

  • goalPeriod: monthly or yearly
  • incomeGoal: number
  • billableHoursPerDay: number
  • billableDaysPerWeek: number
  • weeksOffPerYear: number
  • monthlyExpenses: optional number
  • platformFeePercent: optional number

POST /api/v1/calculate-employee.php

Estimate take-home pay after EPF employee contribution and APIT, plus selected benefit value.

  • grossMonthly: number
  • allowancesMonthly: optional number
  • benefitIds: optional array of strings

POST /api/v1/calculate-employer.php

Estimate the true monthly employer cost, including EPF, ETF, and outsourcing comparison.

  • grossMonthly: number
  • allowancesMonthly: optional number
  • workingHoursPerWeek: optional number
  • outsourceRatePerHour: optional number
  • outsourceHoursPerMonth: optional number

GET /api/v1/benchmarks.php

Return only sanitized aggregate benchmark slices. Use ?roleKey=software_general to filter one slice.

GET /api/v1/metadata-tax-year.php

Return tax-year metadata, assumptions version, and provenance.

Response shape

Successful responses include a data object. Calculation responses also include inputs, outputs, assumptions, warnings, and metadata fields such as tax year, last updated date, and last verified date.

Validation failures return 422 with error.code = validation_error. Invalid JSON returns 400 with error.code = invalid_json. All JSON responses expose X-Request-Id and public CORS headers for integrations.

Security

Site-wide headers include HSTS, CSP, X-Content-Type-Options, Referrer-Policy, and Permissions-Policy. Structured request logs and fatal-error logs are written to the host runtime directory.

Examples

{ "goalPeriod": "monthly", "incomeGoal": 180000, "billableHoursPerDay": 8, "billableDaysPerWeek": 5, "weeksOffPerYear": 4 }
{ "grossMonthly": 120000, "allowancesMonthly": 10000, "benefitIds": ["b-medical", "b-phone"] }

Disclaimer

Indicative only, not financial or tax advice.

Policy links