curatedapi
Browse the docs

Guides

Finance

Excel functions

Late payments

E-invoices

Accounting

Number checks

VAT and GST

Billing and pricing

Money and currencies

Dates and time

Math

Unit conversion

Everyday

Health

Working hours and SLA deadline API

The deadline a number of working hours after a start, or the working time between two moments, with office hours, weekends, public holidays and time zones.

POST https://api.curatedapi.com/v1/calc/date/working-hours

Answers the two questions a service-level agreement asks. When is the deadline, if a ticket opened now must be answered within 8 working hours? And how much working time passed between the moment it opened and the moment it closed? Working time is the office hours you give, in the office's time zone, on days that are not a weekend day, a public holiday of the chosen calendar or one of your own closing days. Time outside office hours does not count: a ticket opened on Friday evening starts its clock on Monday morning.

Formula

working time = the part of [start, end] inside day_start to day_end on working days; the deadline is the earliest moment with add_hours of working time behind it
  • A deadline that falls exactly at closing time stays at closing time; it does not move to the next morning.
  • Hours are real elapsed time. If the clocks change inside office hours, that day has an hour less or more.
  • Holiday calendars cover 2020 to 2030. They follow the rules in each country's law, plus the one-off days that were proclaimed for a single year. A government can still add or move a day for a year ahead; such a change is added here when it becomes law.
  • Time zones come from the IANA time zone database in the pinned tzdata package; the version used is returned with each date-time result.

Inputs

Send numbers as strings to keep every digit. options sets precision and rounding (see numbers and rounding).

InputTypeDescription
start required string When the clock starts: a date-time with a UTC offset, or a local time in timezone.
timezone required string The IANA time zone the office hours are in.
add_hours decimal (string) Working hours allowed, to find the deadline. Allowed: >= 0 and <= 20000. Unit: hours.
end string When the clock stops, to measure the working time.
day_start string
default 09:00
When work starts each day, as HH:MM. At most 5 characters.
day_end string
default 17:00
When work ends each day, as HH:MM; 24:00 for midnight. At most 5 characters.
calendar US | GB-ENG | GB-SCT | GB-NIR | DE | DE-BW | DE-BY | DE-BE | DE-BB | DE-HB | DE-HH | DE-HE | DE-MV | DE-NI | DE-NW | DE-RP | DE-SL | DE-SN | DE-ST | DE-SH | DE-TH | FR | NL | IE | BE | AT | IT The public holidays to leave out (2020 to 2030). Omit it to count only weekends and extra_holidays. Options: US: United States (federal holidays); GB-ENG: United Kingdom: England and Wales; GB-SCT: United Kingdom: Scotland; GB-NIR: United Kingdom: Northern Ireland; DE: Germany (the nine nationwide holidays); DE-BW: Germany: Baden-Württemberg; DE-BY: Germany: Bavaria; DE-BE: Germany: Berlin; DE-BB: Germany: Brandenburg; DE-HB: Germany: Bremen; DE-HH: Germany: Hamburg; DE-HE: Germany: Hesse; DE-MV: Germany: Mecklenburg-Vorpommern; DE-NI: Germany: Lower Saxony; DE-NW: Germany: North Rhine-Westphalia; DE-RP: Germany: Rhineland-Palatinate; DE-SL: Germany: Saarland; DE-SN: Germany: Saxony; DE-ST: Germany: Saxony-Anhalt; DE-SH: Germany: Schleswig-Holstein; DE-TH: Germany: Thuringia; FR: France (mainland); NL: Netherlands; IE: Ireland; BE: Belgium; AT: Austria; IT: Italy
weekend sat_sun | fri_sat | sun | fri | none
default sat_sun
Days of the week that are not worked. Options: sat_sun: Saturday and Sunday; fri_sat: Friday and Saturday; sun: Sunday only; fri: Friday only; none: no weekend days
extra_holidays list of date (YYYY-MM-DD) More days that are not worked, such as company closing days. Up to 1000 items.
options.rounding half_even | half_up | half_down | up | down | ceiling | floor Rounding mode applied once to each result. Default half_even.
options.decimals integer Round results to this many digits after the decimal point.
options.significant_digits integer Round results to this many significant digits.

Result

Under result in the answer, next to exactness, precision, inputs, formula, references and warnings.

ResultTypeDescription
deadlinestringThe moment the working hours are used up, in the office's time zone.
deadline_utcstringThe same moment in UTC.
weekdaystringThe deadline's day of the week.
working_hoursdecimal (string)Working time from start to end, in hours; negative when end is before start. Unit: hours.
working_minutesdecimal (string)The same in minutes. Unit: minutes.
days_with_working_timeintegerHow many days had some working time in the span.
tz_databasestringThe time zone data used.

Examples

Eight working hours from the afternoon of Christmas Eve 2026 in London

Requestcurl
curl https://api.curatedapi.com/v1/calc/date/working-hours \
  -H "Authorization: Bearer $CURATEDAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "start": "2026-12-24T15:30:00",
    "timezone": "Europe/London",
    "add_hours": "8",
    "calendar": "GB-ENG"
  }'
200 OKResponse
{
  "calculator": "date/working-hours@1",
  "result": {
    "deadline": "2026-12-29T15:30:00+00:00",
    "deadline_utc": "2026-12-29T15:30:00Z",
    "weekday": "Tuesday",
    "tz_database": "tzdata 2026.6 (IANA 2026f)"
  },
  "exactness": {},
  "precision": {
    "rounding": "half_even",
    "decimals": 4
  },
  "inputs": {
    "start": "2026-12-24T15:30:00",
    "timezone": "Europe/London",
    "add_hours": "8",
    "day_start": "09:00",
    "day_end": "17:00",
    "calendar": "GB-ENG",
    "weekend": "sat_sun"
  },
  "formula": "working time = the part of [start, end] inside day_start to day_end on working days; the deadline is the earliest moment with add_hours of working time behind it",
  "references": [
    {
      "title": "IANA Time Zone Database",
      "url": "https://www.iana.org/time-zones"
    },
    {
      "title": "5 U.S.C. 6103, as listed by the US Office of Personnel Management",
      "url": "https://www.opm.gov/policy-data-oversight/pay-leave/federal-holidays/"
    },
    {
      "title": "GOV.UK: UK bank holidays",
      "url": "https://www.gov.uk/bank-holidays"
    },
    {
      "title": "Germany: the Unification Treaty (3 October) and each state's public holiday act (Feiertagsgesetz), as summarised by the Federal Ministry of the Interior",
      "url": "https://www.bmi.bund.de/DE/themen/verfassung/staatliche-symbole/nationale-feiertage/nationale-feiertage-node.html"
    }
  ],
  "warnings": []
}

Working time from Friday 16:00 to Monday 10:30 in New York

Requestcurl
curl https://api.curatedapi.com/v1/calc/date/working-hours \
  -H "Authorization: Bearer $CURATEDAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "start": "2026-03-06T16:00:00",
    "end": "2026-03-09T10:30:00",
    "timezone": "America/New_York"
  }'
200 OKResponse
{
  "calculator": "date/working-hours@1",
  "result": {
    "working_hours": "2.5000",
    "working_minutes": "150.0000",
    "days_with_working_time": 2,
    "tz_database": "tzdata 2026.6 (IANA 2026f)"
  },
  "exactness": {
    "working_hours": "exact",
    "working_minutes": "exact"
  },
  "precision": {
    "rounding": "half_even",
    "decimals": 4
  },
  "inputs": {
    "start": "2026-03-06T16:00:00",
    "timezone": "America/New_York",
    "end": "2026-03-09T10:30:00",
    "day_start": "09:00",
    "day_end": "17:00",
    "weekend": "sat_sun"
  },
  "formula": "working time = the part of [start, end] inside day_start to day_end on working days; the deadline is the earliest moment with add_hours of working time behind it",
  "references": [
    {
      "title": "IANA Time Zone Database",
      "url": "https://www.iana.org/time-zones"
    },
    {
      "title": "5 U.S.C. 6103, as listed by the US Office of Personnel Management",
      "url": "https://www.opm.gov/policy-data-oversight/pay-leave/federal-holidays/"
    },
    {
      "title": "GOV.UK: UK bank holidays",
      "url": "https://www.gov.uk/bank-holidays"
    },
    {
      "title": "Germany: the Unification Treaty (3 October) and each state's public holiday act (Feiertagsgesetz), as summarised by the Federal Ministry of the Interior",
      "url": "https://www.bmi.bund.de/DE/themen/verfassung/staatliche-symbole/nationale-feiertage/nationale-feiertage-node.html"
    }
  ],
  "warnings": []
}

References

Results follow each calculator's documented rules and the sources listed. They are not financial, tax or legal advice. Check that the rules fit your case before you rely on a result. See the terms.

Errors share one format; see errors. Billing, retries and batches work the same for every endpoint.