Date calculator

Use the following endpoint to calculate the date after a specified number of elapsed days or business days:

  • POST /admin/v1/activity-calendar/calculate-date

This endpoint is useful for situations when you want to determine what the calculated date will be "n number of days" from the start date, accounting for regional holidays and time zones.

The following fields are required to calculate a date:

  • startDate: The start date for the calculation. This date is always set to midnight in the local server time.
  • includeDaysType: The day type for the calculation. These are the possible values for the code:
    • businessdays: Business days don't include holidays and weekends. For example, one business day after Friday will be Monday.
    • elapsed: Elapsed days include holidays and weekends. For example, one elapsed day after Friday will be Saturday.
  • numberOfDays: The number of days to add to the start date. You can also specify an optional numberOfHours, the number of hours to add to the start date.
If you specify the businessdays day type for the calculation, one of the two following fields is required:
  • holidayTag: The only value out of the box for the code is general. This code comes from a typelist that administrators can add other holiday tags to.
  • location: You can specify relevant fields within the location to provide additional details, such as the address. You can use an empty location - the location will default to the country of your server location.

Elapsed Days Example

The following request calculates the date after a number of elapsed days:

Command

POST /admin/v1/activity-calendar/calculate-date

Request


{
    "data": {
        "attributes": {
            "startDate": "2025-07-03",
            "includeDaysType": {
                "code": "elapsed"
            },
            "numberOfDays": 3
        }
    }
}

Response


{
    "data": {
        "attributes": {
            "calculatedDate": "2025-07-06T07:00:00.000Z",
            "includeDaysType": {
                "code": "elapsed",
                "name": "Calendar days"
            },
            "numberOfDays": 3,
            "startDate": "2025-07-03"
        }
    }
}

This example request's start date is 07/03/2025 (Thursday at midnight PDT), and the calculated date after three days is 07/05/2025 7:00 UTC (the calculated date is always in UTC, so it's 7 hours ahead of midnight PDT). This calculation includes holidays, such as 07/04/25 (Independence Day), and weekends in its calculation.

Note: You can determine your system time zone by calling this endpoint: 
GET /systemtools/v1/system-time

Business days example with holiday tags

The following request calculates the date after a number of business days, using holiday tags:

Request


{
    "data": {
        "attributes": {
            "startDate": "2025-07-03",
            "includeDaysType": {
                "code": "businessdays"
            },
            "holidayTag": {
                "code": "general"
            },
            "numberOfDays": 3
        }
    }
}

Response


{
    "data": {
        "attributes": {
            "calculatedDate": "2025-07-08T15:00:00.000Z",
            "holidayTag": {
                "code": "general",
                "name": "General"
            },
            "includeDaysType": {
                "code": "businessdays",
                "name": "Business days"
            },
            "numberOfDays": 3,
            "startDate": "2025-07-03"
        }
    }
}
This example's request start date is 07/03/25 (Thursday at midnight PDT), but because it specifies the general holiday tag, the calculation accounts for any holidays with that tag, in addition to weekends (the calculator doesn't count weekends as business days), when it counts the business days. The calculated date is 07/09/25 15:00 UTC (Tuesday) due to the following:
  • The calculation excludes 07/04/25 (Independence Day) from its count of business days.
  • The calculation excludes 07/05/25 and 07/06/25 (the weekend) from its count of business days.
  • Though the request is in the local server time (midnight PDT), the time in the response is the start of the business day, based on the system configuration, which would be 8:00 AM PDT by default. However, the calculated date is always in UTC, so the response converts 8:00 AM PDT to 15:00 UTC (7 hours later).

Business days example with location

The following request calculates the date after a number of business days, using location:

Request


{
    "data": {
        "attributes": {
            "startDate": "2025-07-03",
            "includeDaysType": {
                "code": "businessdays"
            },
            "location": {},
            "numberOfDays": 3
        }
    }
}

Response


{
    "data": {
        "attributes": {
            "calculatedDate": "2025-07-08T15:00:00.000Z",
            "includeDaysType": {
                "code": "businessdays",
                "name": "Business days"
            },
            "location": {
                "country": "US",
                "displayName": ""
            },
            "numberOfDays": 3,
            "startDate": "2025-07-03"
        }
    }
}
This example's request has an empty location, but the calculator defaults the location to the location of the server, the United States. Because the example is calculating business days in the United States, the calculator accounts for US-based holidays, in addition to weekends (the calculator doesn't count weekends as business days), when it counts the business days. Although the start date is 07/03/25 (Thursday at midnight PDT), the calculated date after three business days is actually 07/08/25 15:00 UTC due to the following:
  • The calculation excludes 07/04/25 (Independence Day) from its count of business days.
  • The calculation excludes 07/05/25 and 07/06/25 (the weekend) from its count of business days.
  • Though the request is in the local server time (midnight PDT), the time in the response is the start of the business day, based on the system configuration, which would be 8:00 AM PDT by default. However, the calculated date is always in UTC, so the response converts 8:00 AM PDT to 15:00 UTC (7 hours later).

Business days and hours example

The following request calculates the date after a number of business days and hours:

Request


{
    "data": {
        "attributes": {
            "startDate": "2025-07-03",
            "includeDaysType": {
                "code": "businessdays"
            },
            "location": {},
            "numberOfDays": 3,
            "numberOfHours": 4
        }
    }
}

Response


{
    "data": {
        "attributes": {
            "calculatedDate": "2025-07-08T19:00:00.000Z",
            "includeDaysType": {
                "code": "businessdays",
                "name": "Business days"
            },
            "location": {
                "country": "US",
                "displayName": ""
            },
            "numberOfDays": 3,
            "numberOfHours": 8,
            "startDate": "2025-07-03"
        }
    }
}

The calculated date for 3 days and 4 hours from 07/03/25 (Thursday at midnight PDT) in this example's response is 07/08/25 at 19:00 UTC due to the following:

  • The calculation excludes 07/04/25 (Independence Day) from its count of business days.
  • The calculation excludes 07/05/25 and 07/06/25 (the weekend) from its count of business days.
  • Though the request is in the local server time (midnight PDT), the time in the response adds hours to the start of the business day, based on the system configuration, which would be 8:00 AM PDT by default. The calculated date is always in UTC, so the response converts the start of business from 8:00 AM PDT to 15:00 UTC (7 hours later) and then adds 4 hours, making the time 19:00 UTC.