You can use the API to create multiple support schedules with different business hours and holidays. The API consists of schedule, interval, and holiday objects.

JSON Format

Schedules are represented as JSON objects with the following properties:

Name Type Read-only Mandatory Description
created_at string true false Time the schedule was created
id integer true false Automatically assigned upon creation
intervals array false false An array with start time and end time for the schedule. See intervals
name string false true Name of the schedule
time_zone string false true Time zone of the schedule
updated_at string true false Time the schedule was last updated

Intervals

Intervals are represented with the following attributes:

Name Type Comment
start_time integer Integer representation of the interval start time
end_time integer Integer representation of the interval end time

An interval represents an active business-hours period.

Interval times are expressed as the number of minutes since the start of the week.

Sunday is considered the first day of the week.

For instance, 720 is equivalent to Sunday at noon (12 * 60).

Example

{  "start_time": 1980,  "end_time": 3900}

Holidays

Holidays are represented with the following attributes:

Name Type Comment
id integer Automatically assigned upon creation
name string Name of the holiday
start_date string ISO 8601 representation of the holiday start date
end_date string ISO 8601 representation of the holiday end date

Holidays can be a single day or multiple days in length.

Example

{"id": 1, "name": "New Year's Day 2016", "start_time": "2016-01-01", "end_time": "2016-01-01"}

Example

{  "id": 1,  "intervals": [    {      "end_time": 2460,      "start_time": 1980    },    {      "end_time": 3900,      "start_time": 3420    }  ],  "name": "North America",  "time_zone": "Pacific Time (US \u0026 Canada)"}

List All Schedules

  • GET /api/v2/business_hours/schedules

Allowed For

  • Admins

Using curl

curl https://{subdomain}.zendesk.com/api/v2/business_hours/schedules.json \  -v -u {email_address}:{password}

Example Response

Status 200 OK
{  "schedules": [    {      "created_at": "2015-09-30T21:44:03Z",      "id": 1,      "intervals": [        {          "end_time": 2460,          "start_time": 1980        },        {          "end_time": 3900,          "start_time": 3420        }      ],      "name": "North America",      "time_zone": "Pacific Time (US \u0026 Canada)",      "updated_at": "2015-09-30T21:44:03Z"    },    {      "created_at": "2015-09-30T21:44:03Z",      "id": 2,      "intervals": [        {          "end_time": 2460,          "start_time": 1980        },        {          "end_time": 3900,          "start_time": 3420        }      ],      "name": "EMEA",      "time_zone": "London",      "updated_at": "2015-09-30T21:44:03Z"    }  ]}

Show a Schedule

  • GET /api/v2/business_hours/schedules/{schedule_id}

Allowed For

  • Agents

Parameters

Name Type In Required Description
schedule_id integer Path true The ID of the schedule

Using curl

curl https://{subdomain}.zendesk.com/api/v2/business_hours/schedules/{schedule_id}.json \  -v -u {email_address}:{password}

Example Response

Status 200 OK
{  "schedule": {    "created_at": "2015-09-30T21:44:03Z",    "id": 1,    "intervals": [      {        "end_time": 2460,        "start_time": 1980      },      {        "end_time": 3900,        "start_time": 3420      }    ],    "name": "North America",    "time_zone": "Pacific Time (US \u0026 Canada)",    "updated_at": "2015-09-30T21:44:03Z"  }}

Create a Schedule

  • POST /api/v2/business_hours/schedules

Allowed For

  • Admins

Using curl

curl https://{subdomain}.zendesk.com/api/v2/business_hours/schedules.json \  -v -u {email_address}:{password} \  -H "Content-Type: application/json" -X POST  -d '{"schedule": {"name": "East Coast", "time_zone": "Eastern Time (US & Canada)"}}'

Example Response

Status 201 Created
{  "schedule": {    "id": 1,    "intervals": [      {        "end_time": 2460,        "start_time": 1980      },      {        "end_time": 3900,        "start_time": 3420      },      {        "end_time": 5340,        "start_time": 4860      },      {        "end_time": 6780,        "start_time": 6300      },      {        "end_time": 8220,        "start_time": 7740      }    ],    "name": "East Coast",    "time_zone": "Eastern Time (US \u0026 Canada)"  }}

Update a Schedule

  • PUT /api/v2/business_hours/schedules/{schedule_id}

Allowed For

  • Admins

Parameters

Name Type In Required Description
schedule_id integer Path true The ID of the schedule

Using curl

curl https://{subdomain}.zendesk.com/api/v2/business_hours/schedules/{schedule_id}.json \  -v -u {email_address}:{password} \  -H "Content-Type: application/json" -X PUT  -d '{"schedule": {"name": "EMEA", "time_zone": "London"}}'

Example Response

Status 200 OK
{  "schedule": {    "created_at": "2015-09-30T21:44:03Z",    "id": 1,    "intervals": [      {        "end_time": 2460,        "start_time": 1980      },      {        "end_time": 3900,        "start_time": 3420      },      {        "end_time": 5340,        "start_time": 4860      },      {        "end_time": 6780,        "start_time": 6300      },      {        "end_time": 8220,        "start_time": 7740      }    ],    "name": "EMEA",    "time_zone": "London",    "updated_at": "2015-09-30T21:44:03Z"  }}

Delete Schedule

  • DELETE /api/v2/business_hours/schedules/{schedule_id}

Allowed For

  • Admins

Parameters

Name Type In Required Description
schedule_id integer Path true The ID of the schedule

Using curl

curl https://{subdomain}.zendesk.com/api/v2/business_hours/schedules/{schedule_id}.json \  -v -u {email_address}:{password} \  -H "Content-Type: application/json" -X DELETE

Example Response

Status 204 No Content

List Holidays for a Schedule

  • GET /api/v2/business_hours/schedules/{schedule_id}/holidays

The endpoint takes start_date and end_date query parameters. If you specify only a start_date, holidays beginning on or after that date are returned. If the start_date falls during a holiday, the holiday is also included. As a result the response may list some holidays that start before the start_date.

If you specify only an end_date, holidays beginning on or before that date are returned.

If you specify both a start_date and an end_date, holidays beginning between those dates are returned. If you specify neither, all holidays are returned.

Allowed For

  • Admins

Parameters

Name Type In Required Description
end_date string Query false Must be in ISO 8601 date format. For example: "2021-01-01".
start_date string Query false Must be in ISO 8601 date format. For example, "2021-01-01".
schedule_id integer Path true The ID of the schedule

Using curl

curl https://{subdomain}.zendesk.com/api/v2/business_hours/schedules/{schedule_id}/holidays.json  -v -u {email_address}:{password}

Example Response

Status 200 OK
{  "holidays": [    {      "end_date": "2021-07-04",      "id": 1,      "name": "Independence Day",      "start_date": "2021-07-04"    },    {      "end_date": "2021-12-25",      "id": 2,      "name": "Christmas",      "start_date": "2021-12-25"    }  ]}

Show a Holiday

  • GET /api/v2/business_hours/schedules/{schedule_id}/holidays/{holiday_id}

Allowed For

  • Agents

Parameters

Name Type In Required Description
holiday_id integer Path false The ID of the scheduled holiday
schedule_id integer Path true The ID of the schedule

Using curl

curl https://{subdomain}.zendesk.com/api/v2/business_hours/schedules/{schedule_id}/holidays/{holiday_id}.json \  -v -u {email_address}:{password}

Example Response

Status 200 OK
{  "holiday": {    "end_date": "2021-01-02",    "id": 1,    "name": "New Year",    "start_date": "2020-12-30"  }}

Create a Holiday

  • POST /api/v2/business_hours/schedules/{schedule_id}/holidays

Creates a holiday defined by a start date no sooner than two years in the past and an end date no later than two years in the future.

Allowed For

  • Admins

Parameters

Name Type In Required Description
schedule_id integer Path true The ID of the schedule

Using curl

curl https://{subdomain}.zendesk.com/api/v2/business_hours/schedules/{schedule_id}/holidays.json \  -d '{"holiday": {"name": "New Year", "start_date": "2021-12-30", "end_date": "2022-01-02"}}' \  -H "Content-Type: application/json" -X POST \  -v -u {email_address}:{password}

Example Response

Status 201 Created
{  "holiday": {    "end_date": "2021-01-02",    "id": 2,    "name": "New Year",    "start_date": "2020-12-30"  }}

Update a Holiday

  • PUT /api/v2/business_hours/schedules/{schedule_id}/holidays/{holiday_id}

Allowed For

  • Admins

Parameters

Name Type In Required Description
holiday_id integer Path false The ID of the scheduled holiday
schedule_id integer Path true The ID of the schedule

Using curl

curl https://{subdomain}.zendesk.com/api/v2/business_hours/schedules/{schedule_id}/holidays/{holiday_id}.json \  -d '{"holiday": {"name": "New Year", "start_date": "2021-12-30", "end_date": "2022-01-03"}}' \  -H "Content-Type: application/json" -X PUT \  -v -u {email_address}:{password}

Example Response

Status 200 OK
{  "holiday": {    "end_date": "2022-01-03",    "id": 2,    "name": "New Year",    "start_date": "2021-12-30"  }}

Delete a Holiday

  • DELETE /api/v2/business_hours/schedules/{schedule_id}/holidays/{holiday_id}

Allowed For

  • Admins

Parameters

Name Type In Required Description
holiday_id integer Path false The ID of the scheduled holiday
schedule_id integer Path true The ID of the schedule

Using curl

curl https://{subdomain}.zendesk.com/api/v2/business_hours/schedules/{schedule_id}/holidays/{holiday_id}.json \  -H "Content-Type: application/json" -X DELETE \  -v -u {email_address}:{password}

Example Response

Status 204 No Content

Update Intervals for a Schedule

  • PUT /api/v2/business_hours/schedules/{schedule_id}/workweek

Allowed For

  • Admins

Parameters

Name Type In Required Description
schedule_id integer Path true The ID of the schedule

Using curl

curl https://{subdomain}.zendesk.com/api/v2/business_hours/schedules/{schedule_id}/workweek.json \  -v -u {email_address}:{password} \  -H "Content-Type: application/json" -X PUT \  -d '{"workweek": {"intervals": [{"start_time": 3420, "end_time": 3900}]}}'

Example Response

Status 200 OK
{  "workweek": {    "intervals": [      {        "end_time": 3900,        "start_time": 3420      }    ]  }}