Years of service calculator

Invalid calendar days and inverted date pairs fail with invalid_input and are not billed; successful items cost $0.002 from KIT balance.

Hire date, reference date, and why the clock is never used

Each value should be a civil calendar day in YYYY-MM-DD form, for example two thousand eighteen hyphen zero three hyphen fifteen for a hire date and two thousand twenty-six hyphen zero seven hyphen twenty-five for the evaluation snapshot. You may pass a full ISO-8601 datetime prefix; if a time is present only the calendar date part is used, because years of service for benefits is a date-to-date measure, not a clock duration with time zones. Years range from one through nine thousand nine hundred ninety-nine, months must be one through twelve, and the day must exist in that month under Gregorian leap rules, including February twenty-nine only in leap years. Send two required string fields: hire_date and reference_date. Optional aliases hire, start_date, employment_start, and from map to the hire field; reference, as_of, to, on, and evaluation_date map to the reference field so HR forms and SDKs can keep familiar names. Both fields are mandatory on purpose: a tenure calculator that silently substitutes the host wall clock produces different answers in CI, on a laptop in another region, and on an API worker in UTC, which breaks award audits and reproducible payroll exports. Impossible pairs such as two thousand twenty-three hyphen zero two hyphen twenty-nine are rejected with invalid_input instead of being clamped into March. If the reference date falls strictly before the hire date, the request fails with a clear message that years of service cannot be negative, rather than inventing a signed tenure that most product UIs would mislabel as completed service.

How completed years, months, and days are counted

Fields months and days complete the residual span after those whole years, so dashboards can show both the vesting cliff number and a human-readable remainder. The algorithm measures whole calendar months from the hire date toward the reference date, clamping the day-of-month when the target month is shorter—so a hire on the thirty-first of January advances one month to the last day of February in leap and non-leap years alike. If that provisional month-advanced date would overshoot the reference, the engine steps back one month and reports the remaining span as whole civil days. Years of service are the whole-month total divided by twelve; months are the remainder modulo twelve; days finish the triple. On success the response echoes normalized hire_date and reference_date as YYYY-MM-DD, then years_of_service as the count of completed whole calendar years of tenure—the number that eligibility rules typically mean when they say five years of service. Field total_days is the exclusive civil day difference between the two ordinals: the same calendar day yields zero total days and zero years of service, while the next calendar day yields one day of service. Fields last_anniversary and next_anniversary are the hire anniversary dates after years_of_service and years_of_service plus one completed years, with February twenty-nine hire dates clamped to February twenty-eight in non-leap target years.

API usage, pricing, benefit workflows, and honest limits

Use the free in-browser years of service calculator for HR demos, manager self-service, and one-off award checks without installing date libraries or shipping a timezone database to every client. Keep expectations honest: this capability measures Gregorian civil tenure between two explicit dates; it does not skip weekends as business tenure, load public holiday calendars, apply union-specific anniversary tables, prorate partial-year awards, or default the reference to today on the server. Source inputs follow the same retention rules as other KIT parse items. POST a compact JSON body with hire_date and reference_date strings. Call the prepaid API when payroll batches, equity vesting gates, PTO accrual tiers, or service-award programs need a stable contract under KIT balance at $0.002 per successful item; validation failures never consume balance after the engine rejects the request. Pair this endpoint with a pure day-count tool when you also need an unordered span length alone, or with an age-in-years-months-days tool when the product must compute civil age from a birth date rather than employment tenure from a hire date—those are different search intents and different field names even though the calendar arithmetic is related. SDK authors can map years_of_service into a primary eligibility badge and surface months, days, and the formatted string for accessibility labels, using the same response shape in every language binding.