Schedules

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

Schedules are represented with the following attributes:

Name Type Comment
id integer Automatically assigned upon creation
name string Name of the schedule
time_zone string Time zone of the schedule
intervals array Array of intervals for the schedule
created_at date Time the schedule was created
updated_at date Time the schedule was last updated

A schedule is composed of intervals, holidays, and a time zone.

Example
{
  "id": 1,
  "name": "North America",
  "time_zone": "Pacific Time (US & Canada)",
  "intervals": [...]
}
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"
}

List all schedules

GET /api/v2/business_hours/schedules.json

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

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

Show a schedule

GET /api/v2/business_hours/schedules/{id}.json

Allowed For:
  • Admins
Using curl:
curl https://{subdomain}.zendesk.com/api/v2/business_hours/schedules/{id}.json \
  -v -u {email_address}:{password}
Example Response
Status: 200

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

Create a schedule

POST /api/v2/business_hours/schedules.json

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,
    "name": "East Coast",
    "time_zone": "Eastern Time (US & Canada)",
    "intervals": [
      {"start_time": 1980, "end_time": 2460},
      {"start_time": 3420, "end_time": 3900},
      {"start_time": 4860, "end_time": 5340},
      {"start_time": 6300, "end_time": 6780},
      {"start_time": 7740, "end_time": 8220}
    ]
  }
}

Update a schedule

PUT /api/v2/business_hours/schedules/{id}.json

Allowed For
  • Admins
Using curl
curl https://{subdomain}.zendesk.com/api/v2/business_hours/schedules/{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": {
    "id": 1,
    "name": "EMEA",
    "time_zone": "London",
    "created_at": "2015-09-30T21:44:03Z",
    "updated_at": "2015-09-30T21:44:03Z",
    "intervals": [
      {"start_time": 1980, "end_time": 2460},
      {"start_time": 3420, "end_time": 3900},
      {"start_time": 4860, "end_time": 5340},
      {"start_time": 6300, "end_time": 6780},
      {"start_time": 7740, "end_time": 8220}
    ]
  }
}

Delete a schedule

DELETE /api/v2/business_hours/schedules/{id}.json

Allowed For
  • Admins
Using curl
curl https://{subdomain}.zendesk.com/api/v2/business_hours/schedules/{id}.json \
  -v -u {email_address}:{password} \
  -H "Content-Type: application/json" -X DELETE
Example Response
Status: 204 No Content

Update intervals for a schedule

PUT /api/v2/business_hours/schedules/{id}/workweek.json

Allowed For
  • Admins
Using curl
curl https://{subdomain}.zendesk.com/api/v2/business_hours/schedules/{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": [
      {"start_time": 3420, "end_time": 3900}
    ]
  }
}

List holidays for a schedule

GET /api/v2/business_hours/schedules/{id}/holidays.json

Allowed For:
  • Admins
Available Parameters
Name Type Comment
start_date string Must be in ISO 8601 date format (e.g. 2016-01-01).
end_date string Must be in ISO 8601 date format (e.g. 2016-01-01).

If only start_date is specified, holidays beginning on or after that date are returned. If only end_date is specified, holidays beginning on or before that date are returned. If both are specified, holidays beginning between those dates are returned. If neither is specified, all holidays are returned.

Using curl:
curl https://{subdomain}.zendesk.com/api/v2/business_hours/schedules/{id}/holidays.json
  -v -u {email_address}:{password}
Example Response
Status: 200

{
  "holidays": [
    {
      "id": 1,
      "name": "Independence Day",
      "start_date": "2016-07-04",
      "end_date": "2016-07-04"
    },
    {
      "id": 2,
      "name": "Christmas",
      "start_date": "2016-12-25",
      "end_date": "2016-12-25"
    },
    ...
  ]
}

Show a holiday

GET /api/v2/business_hours/schedules/{id}/holidays/{id}.json

Allowed For:
  • Admins
Using curl:
curl https://{subdomain}.zendesk.com/api/v2/business_hours/schedules/{id}/holidays/{id}.json \
  -v -u {email_address}:{password}
Example Response
Status: 200

{
  "holiday": {
    "id": 1,
    "name": "Christmas",
    "start_date": "2016-12-25",
    "end_date": "2016-12-25"
  }
}

Create a holiday

POST /api/v2/business_hours/schedules/{id}/holidays.json

Allowed For
  • Admins
Using curl
curl https://{subdomain}.zendesk.com/api/v2/business_hours/schedules/{id}/holidays.json \
  -v -u {email_address}:{password} \
  -H "Content-Type: application/json" -X POST \
  -d '{"holiday": {"name": "Christmas", "start_date": "2016-12-25", "end_date": "2016-12-25"}}'
Example Response
Status: 201 Created

{
  "holiday": {
    "id": 2,
    "name": "Christmas",
    "start_date": "2016-12-25",
    "end_date": "2016-12-25"
  }
}

Update a holiday

PUT /api/v2/business_hours/schedules/{id}/holidays/{id}.json

Allowed For
  • Admins
Using curl
curl https://{subdomain}.zendesk.com/api/v2/business_hours/schedules/{id}/holidays/{id}.json \
  -v -u {email_address}:{password} \
  -H "Content-Type: application/json" -X PUT \
  -d '{"holiday": {"name": "Christmas", "start_date": "2016-12-25", "end_date": "2016-12-25"}}'
Example Response
Status: 200 OK

{
  "holiday": {
    "id": 2,
    "name": "Christmas",
    "start_date": "2016-12-25",
    "end_date": "2016-12-25"
  }
}

Delete a holiday

DELETE /api/v2/business_hours/schedules/{id}/holidays/{id}.json

Allowed For
  • Admins
Using curl
curl https://{subdomain}.zendesk.com/api/v2/business_hours/schedules/{id}/holidays/{id}.json \
  -v -u {email_address}:{password} \
  -H "Content-Type: application/json" -X DELETE
Example Response
Status: 204 No Content