Public API

ceylonsalary.lk 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 or per-deliverable rate needed to hit a freelancer income goal after expenses, platform fee, and APIT, then compare hourly pricing with the selected job and seniority benchmark when applicable.

  • categoryKey: optional category key, defaults to technology
  • roleKey: optional profession key, defaults to software_general; forced to other when categoryKey is other
  • seniorityLevel: optional junior, mid, or senior
  • calculationMode: optional find_rate or estimate_income, defaults to find_rate
  • goalPeriod: monthly or yearly, used when calculationMode is find_rate
  • incomeGoal: number, required when calculationMode is find_rate
  • pricingBasis: optional hours or deliverables, defaults to hours
  • ratePerHour: number, required when estimating hourly income
  • ratePerDeliverable: number, required when estimating deliverable income
  • billableHoursPerDay and billableDaysPerMonth: required when pricingBasis is hours
  • deliverablesPerMonth: required when pricingBasis is deliverables
  • monthlyExpenses: optional number
  • platformFeePercent: optional number
  • includeFreelancerContributions: optional boolean for EPF/ETF-style scenario modeling

POST /api/v1/calculate-employee.php

Estimate true cash take-home after EPF employee contribution and APIT, plus selected benefit value, total value, and market salary comparison.

  • categoryKey: optional category key, defaults to technology
  • roleKey: optional profession key, defaults to software_general; forced to other when categoryKey is other
  • seniorityLevel: optional junior, mid, or senior
  • grossMonthly: number
  • allowancesMonthly: optional number
  • includeAllowancesInStatutoryBase: optional boolean, defaults to true
  • benefits: optional array of { "id": string, "valueMonthly": number }
  • benefitIds: optional legacy array of strings using default benefit values

POST /api/v1/calculate-employer.php

Estimate true monthly employer cost, employee cash take-home, employee total value, outsourcing cost from entered values, market comparison, and hourly or deliverable break-even outsourcing budget.

  • categoryKey: optional category key, defaults to technology
  • roleKey: optional profession key, defaults to software_general; forced to other when categoryKey is other
  • seniorityLevel: optional junior, mid, or senior
  • grossMonthly: number
  • allowancesMonthly: optional number
  • includeAllowancesInStatutoryBase: optional boolean, defaults to true
  • benefits: optional array of { "id": string, "valueMonthly": number }
  • workingHoursPerDay: optional number
  • workingDaysPerMonth: optional number
  • outsourcingBasis: optional hours or deliverables, defaults to hours
  • outsourceHoursPerMonth and outsourceRatePerHour: used when outsourcingBasis is hours
  • outsourceDeliverablesPerMonth and outsourceRatePerDeliverable: used when outsourcingBasis is deliverables

GET /api/v1/benchmarks.php

Return only sanitized aggregate benchmark slices. Use ?categoryKey=technology for one category or ?roleKey=software_general&seniorityLevel=senior for one profession and level.

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": 6, "billableDaysPerMonth": 20, "monthlyExpenses": 5000 }
{ "grossMonthly": 120000, "allowancesMonthly": 10000, "benefits": [{ "id": "b-medical", "valueMonthly": 5000 }] }

Disclaimer

Indicative only, not financial or tax advice.

Policy links