You can set a schedule in Zendesk to acknowledge your support team's availability and give customers a better sense of when they can expect a personal response to their support requests.

You can use this API to create multiple schedules with different business hours and holidays.

To learn more about schedules, see Setting your schedule with business hours and holidays in Zendesk help.

JSON format

Schedules are represented as JSON objects with the following properties:

NameTypeRead-onlyMandatoryDescription
created_atstringtruefalseTime the schedule was created
idintegertruefalseAutomatically assigned upon creation
intervalsarrayfalsefalseAn array of starting and ending times for the schedule. Can't span calendar days. See intervals. Writable only when updating intervals for a schedule
namestringfalsetrueName of the schedule
time_zonestringfalsetrueTime zone of the schedule
updated_atstringtruefalseTime the schedule was last updated

Intervals

An interval represents a period of business hours. Intervals are writable only when updating intervals for a schedule. Otherwise, intervals are read-only.

Intervals are represented with the following attributes:

NameTypeComment
start_timeintegerInteger representation of the interval start time in minutes since Sunday at midnight
end_timeintegerInteger representation of the interval end time in minutes since Sunday at midnight. Can't span calendar days

The start_time and end_time values are expressed as the number of minutes since the start of the week, which is defined as Sunday at midnight. Intervals can't span calendar days.

For example, an interval might start on Monday at 9:00 a.m. and end at 17:00 (5 p.m.).

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

If you have multiple shifts per day, an interval might start on Tuesday at 16:00 (4 p.m.) and end at 00:00 (midnight). Intervals can't span calendar days, so must end at midnight at the latest. To avoid gaps in business hours, you can use midnight as the end time for an interval and the start time for the following interval.

{  "start_time": 3840,  "end_time": 4320}

To calculate the start and end times, use the equation: ((hours since Sunday at midnight)*60) + (minutes of incomplete hour). To help you more easily determine your start and end times, the following table lists the minutes since Sunday at midnight at 12-hour increments throughout the week.

Week timeMinute time
Sunday midnight0, 10080
Sunday noon720
Monday midnight1440
Monday noon2160
Tuesday midnight2880
Tuesday noon3600
Wednesday midnight4320
Wednesday noon5040
Thursday midnight5760
Thursday noon6480
Friday midnight7200
Friday noon7920
Saturday midnight8640
Saturday noon9360

The end of the week is defined as Saturday at 23:59 (11:59 pm). In minutes since Sunday at midnight, this is 10079. The API accepts a value of 0 or 10080 to represent midnight between Saturday and Sunday.

Holidays

Holidays are represented with the following attributes:

NameTypeComment
idintegerAutomatically assigned upon creation
namestringName of the holiday
start_datestringISO 8601 representation of the holiday start date
end_datestringISO 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"}

Time Zone

A time_zone name consists of a string such as "Eastern Time (US & Canada)". For a list of valid names, click https://support.zendesk.com/api/v2/time_zones. For details, see Time Zones.

Example:

{  "schedule": {    "name": "North America",    "time_zone": "Pacific Time (US & Canada)",    ...  }}

Example

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

List Schedules

  • GET /api/v2/business_hours/schedules

Allowed For

  • Admins

Code Samples

curl
curl https://{subdomain}.zendesk.com/api/v2/business_hours/schedules.json \  -v -u {email_address}:{password}
Go
import (	"fmt"	"io"	"net/http")
func main() {	url := "https://support.zendesk.com/api/v2/business_hours/schedules"	method := "GET"	req, err := http.NewRequest(method, url, nil)
	if err != nil {		fmt.Println(err)		return	}	req.Header.Add("Content-Type", "application/json")	req.Header.Add("Authorization", "Basic <auth-value>") // Base64 encoded "username:password"
	client := &http.Client {}	res, err := client.Do(req)	if err != nil {		fmt.Println(err)		return	}	defer res.Body.Close()
	body, err := io.ReadAll(res.Body)	if err != nil {		fmt.Println(err)		return	}	fmt.Println(string(body))}
Java
import com.squareup.okhttp.*;OkHttpClient client = new OkHttpClient();HttpUrl.Builder urlBuilder = HttpUrl.parse("https://support.zendesk.com/api/v2/business_hours/schedules")		.newBuilder();
Request request = new Request.Builder()		.url(urlBuilder.build())		.method("GET", null)		.addHeader("Content-Type", "application/json")		.addHeader("Authorization", Credentials.basic("your-email", "your-password"))		.build();Response response = client.newCall(request).execute();
Nodejs
var axios = require('axios');
var config = {  method: 'GET',  url: 'https://support.zendesk.com/api/v2/business_hours/schedules',  headers: {	'Content-Type': 'application/json',	'Authorization': 'Basic <auth-value>', // Base64 encoded "username:password"  },};
axios(config).then(function (response) {  console.log(JSON.stringify(response.data));}).catch(function (error) {  console.log(error);});
Python
import requests
url = "https://support.zendesk.com/api/v2/business_hours/schedules"headers = {	"Content-Type": "application/json",}
response = requests.request(	"GET",	url,	auth=('<username>', '<password>'),	headers=headers)
print(response.text)
Ruby
require "net/http"uri = URI("https://support.zendesk.com/api/v2/business_hours/schedules")request = Net::HTTP::Get.new(uri, "Content-Type": "application/json")request.basic_auth "username", "password"response = Net::HTTP.start uri.hostname, uri.port, use_ssl: true do |http|	http.request(request)end

Example response(s)

200 OK
// 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 & 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 Schedule

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

Allowed For

  • Agents

Parameters

NameTypeInRequiredDescription
schedule_idintegerPathtrueThe ID of the schedule

Code Samples

curl
curl https://{subdomain}.zendesk.com/api/v2/business_hours/schedules/{schedule_id}.json \  -v -u {email_address}:{password}
Go
import (	"fmt"	"io"	"net/http")
func main() {	url := "https://support.zendesk.com/api/v2/business_hours/schedules/1"	method := "GET"	req, err := http.NewRequest(method, url, nil)
	if err != nil {		fmt.Println(err)		return	}	req.Header.Add("Content-Type", "application/json")	req.Header.Add("Authorization", "Basic <auth-value>") // Base64 encoded "username:password"
	client := &http.Client {}	res, err := client.Do(req)	if err != nil {		fmt.Println(err)		return	}	defer res.Body.Close()
	body, err := io.ReadAll(res.Body)	if err != nil {		fmt.Println(err)		return	}	fmt.Println(string(body))}
Java
import com.squareup.okhttp.*;OkHttpClient client = new OkHttpClient();HttpUrl.Builder urlBuilder = HttpUrl.parse("https://support.zendesk.com/api/v2/business_hours/schedules/1")		.newBuilder();
Request request = new Request.Builder()		.url(urlBuilder.build())		.method("GET", null)		.addHeader("Content-Type", "application/json")		.addHeader("Authorization", Credentials.basic("your-email", "your-password"))		.build();Response response = client.newCall(request).execute();
Nodejs
var axios = require('axios');
var config = {  method: 'GET',  url: 'https://support.zendesk.com/api/v2/business_hours/schedules/1',  headers: {	'Content-Type': 'application/json',	'Authorization': 'Basic <auth-value>', // Base64 encoded "username:password"  },};
axios(config).then(function (response) {  console.log(JSON.stringify(response.data));}).catch(function (error) {  console.log(error);});
Python
import requests
url = "https://support.zendesk.com/api/v2/business_hours/schedules/1"headers = {	"Content-Type": "application/json",}
response = requests.request(	"GET",	url,	auth=('<username>', '<password>'),	headers=headers)
print(response.text)
Ruby
require "net/http"uri = URI("https://support.zendesk.com/api/v2/business_hours/schedules/1")request = Net::HTTP::Get.new(uri, "Content-Type": "application/json")request.basic_auth "username", "password"response = Net::HTTP.start uri.hostname, uri.port, use_ssl: true do |http|	http.request(request)end

Example response(s)

200 OK
// 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 & Canada)",    "updated_at": "2015-09-30T21:44:03Z"  }}

Create Schedule

  • POST /api/v2/business_hours/schedules

Allowed For

  • Admins

Code Samples

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)"}}'
Go
import (	"fmt"	"io"	"net/http")
func main() {	url := "https://support.zendesk.com/api/v2/business_hours/schedules"	method := "POST"	req, err := http.NewRequest(method, url, nil)
	if err != nil {		fmt.Println(err)		return	}	req.Header.Add("Content-Type", "application/json")	req.Header.Add("Authorization", "Basic <auth-value>") // Base64 encoded "username:password"
	client := &http.Client {}	res, err := client.Do(req)	if err != nil {		fmt.Println(err)		return	}	defer res.Body.Close()
	body, err := io.ReadAll(res.Body)	if err != nil {		fmt.Println(err)		return	}	fmt.Println(string(body))}
Java
import com.squareup.okhttp.*;OkHttpClient client = new OkHttpClient();HttpUrl.Builder urlBuilder = HttpUrl.parse("https://support.zendesk.com/api/v2/business_hours/schedules")		.newBuilder();RequestBody body = RequestBody.create(MediaType.parse("application/json"),		"""""");
Request request = new Request.Builder()		.url(urlBuilder.build())		.method("POST", body)		.addHeader("Content-Type", "application/json")		.addHeader("Authorization", Credentials.basic("your-email", "your-password"))		.build();Response response = client.newCall(request).execute();
Nodejs
var axios = require('axios');
var config = {  method: 'POST',  url: 'https://support.zendesk.com/api/v2/business_hours/schedules',  headers: {	'Content-Type': 'application/json',	'Authorization': 'Basic <auth-value>', // Base64 encoded "username:password"  },};
axios(config).then(function (response) {  console.log(JSON.stringify(response.data));}).catch(function (error) {  console.log(error);});
Python
import requests
url = "https://support.zendesk.com/api/v2/business_hours/schedules"headers = {	"Content-Type": "application/json",}
response = requests.request(	"POST",	url,	auth=('<username>', '<password>'),	headers=headers)
print(response.text)
Ruby
require "net/http"uri = URI("https://support.zendesk.com/api/v2/business_hours/schedules")request = Net::HTTP::Post.new(uri, "Content-Type": "application/json")request.basic_auth "username", "password"response = Net::HTTP.start uri.hostname, uri.port, use_ssl: true do |http|	http.request(request)end

Example response(s)

201 Created
// 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 & Canada)"  }}

Update Schedule

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

Allowed For

  • Admins

Parameters

NameTypeInRequiredDescription
schedule_idintegerPathtrueThe ID of the schedule

Code Samples

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"}}'
Go
import (	"fmt"	"io"	"net/http")
func main() {	url := "https://support.zendesk.com/api/v2/business_hours/schedules/1"	method := "PUT"	req, err := http.NewRequest(method, url, nil)
	if err != nil {		fmt.Println(err)		return	}	req.Header.Add("Content-Type", "application/json")	req.Header.Add("Authorization", "Basic <auth-value>") // Base64 encoded "username:password"
	client := &http.Client {}	res, err := client.Do(req)	if err != nil {		fmt.Println(err)		return	}	defer res.Body.Close()
	body, err := io.ReadAll(res.Body)	if err != nil {		fmt.Println(err)		return	}	fmt.Println(string(body))}
Java
import com.squareup.okhttp.*;OkHttpClient client = new OkHttpClient();HttpUrl.Builder urlBuilder = HttpUrl.parse("https://support.zendesk.com/api/v2/business_hours/schedules/1")		.newBuilder();RequestBody body = RequestBody.create(MediaType.parse("application/json"),		"""""");
Request request = new Request.Builder()		.url(urlBuilder.build())		.method("PUT", body)		.addHeader("Content-Type", "application/json")		.addHeader("Authorization", Credentials.basic("your-email", "your-password"))		.build();Response response = client.newCall(request).execute();
Nodejs
var axios = require('axios');
var config = {  method: 'PUT',  url: 'https://support.zendesk.com/api/v2/business_hours/schedules/1',  headers: {	'Content-Type': 'application/json',	'Authorization': 'Basic <auth-value>', // Base64 encoded "username:password"  },};
axios(config).then(function (response) {  console.log(JSON.stringify(response.data));}).catch(function (error) {  console.log(error);});
Python
import requests
url = "https://support.zendesk.com/api/v2/business_hours/schedules/1"headers = {	"Content-Type": "application/json",}
response = requests.request(	"PUT",	url,	auth=('<username>', '<password>'),	headers=headers)
print(response.text)
Ruby
require "net/http"uri = URI("https://support.zendesk.com/api/v2/business_hours/schedules/1")request = Net::HTTP::Put.new(uri, "Content-Type": "application/json")request.basic_auth "username", "password"response = Net::HTTP.start uri.hostname, uri.port, use_ssl: true do |http|	http.request(request)end

Example response(s)

200 OK
// 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

NameTypeInRequiredDescription
schedule_idintegerPathtrueThe ID of the schedule

Code Samples

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
Go
import (	"fmt"	"io"	"net/http")
func main() {	url := "https://support.zendesk.com/api/v2/business_hours/schedules/1"	method := "DELETE"	req, err := http.NewRequest(method, url, nil)
	if err != nil {		fmt.Println(err)		return	}	req.Header.Add("Content-Type", "application/json")	req.Header.Add("Authorization", "Basic <auth-value>") // Base64 encoded "username:password"
	client := &http.Client {}	res, err := client.Do(req)	if err != nil {		fmt.Println(err)		return	}	defer res.Body.Close()
	body, err := io.ReadAll(res.Body)	if err != nil {		fmt.Println(err)		return	}	fmt.Println(string(body))}
Java
import com.squareup.okhttp.*;OkHttpClient client = new OkHttpClient();HttpUrl.Builder urlBuilder = HttpUrl.parse("https://support.zendesk.com/api/v2/business_hours/schedules/1")		.newBuilder();
Request request = new Request.Builder()		.url(urlBuilder.build())		.method("DELETE", null)		.addHeader("Content-Type", "application/json")		.addHeader("Authorization", Credentials.basic("your-email", "your-password"))		.build();Response response = client.newCall(request).execute();
Nodejs
var axios = require('axios');
var config = {  method: 'DELETE',  url: 'https://support.zendesk.com/api/v2/business_hours/schedules/1',  headers: {	'Content-Type': 'application/json',	'Authorization': 'Basic <auth-value>', // Base64 encoded "username:password"  },};
axios(config).then(function (response) {  console.log(JSON.stringify(response.data));}).catch(function (error) {  console.log(error);});
Python
import requests
url = "https://support.zendesk.com/api/v2/business_hours/schedules/1"headers = {	"Content-Type": "application/json",}
response = requests.request(	"DELETE",	url,	auth=('<username>', '<password>'),	headers=headers)
print(response.text)
Ruby
require "net/http"uri = URI("https://support.zendesk.com/api/v2/business_hours/schedules/1")request = Net::HTTP::Delete.new(uri, "Content-Type": "application/json")request.basic_auth "username", "password"response = Net::HTTP.start uri.hostname, uri.port, use_ssl: true do |http|	http.request(request)end

Example response(s)

204 No Content
// Status 204 No Content
null

List Holidays for 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

NameTypeInRequiredDescription
end_datestringQueryfalseMust be in ISO 8601 date format. For example: "2021-01-01".
start_datestringQueryfalseMust be in ISO 8601 date format. For example, "2021-01-01".
schedule_idintegerPathtrueThe ID of the schedule

Code Samples

curl
curl https://{subdomain}.zendesk.com/api/v2/business_hours/schedules/{schedule_id}/holidays.json  -v -u {email_address}:{password}
Go
import (	"fmt"	"io"	"net/http")
func main() {	url := "https://support.zendesk.com/api/v2/business_hours/schedules/1/holidays?end_date=2021-01-01&start_date=2021-01-01"	method := "GET"	req, err := http.NewRequest(method, url, nil)
	if err != nil {		fmt.Println(err)		return	}	req.Header.Add("Content-Type", "application/json")	req.Header.Add("Authorization", "Basic <auth-value>") // Base64 encoded "username:password"
	client := &http.Client {}	res, err := client.Do(req)	if err != nil {		fmt.Println(err)		return	}	defer res.Body.Close()
	body, err := io.ReadAll(res.Body)	if err != nil {		fmt.Println(err)		return	}	fmt.Println(string(body))}
Java
import com.squareup.okhttp.*;OkHttpClient client = new OkHttpClient();HttpUrl.Builder urlBuilder = HttpUrl.parse("https://support.zendesk.com/api/v2/business_hours/schedules/1/holidays")		.newBuilder()		.addQueryParameter("end_date", "2021-01-01")		.addQueryParameter("start_date", "2021-01-01");
Request request = new Request.Builder()		.url(urlBuilder.build())		.method("GET", null)		.addHeader("Content-Type", "application/json")		.addHeader("Authorization", Credentials.basic("your-email", "your-password"))		.build();Response response = client.newCall(request).execute();
Nodejs
var axios = require('axios');
var config = {  method: 'GET',  url: 'https://support.zendesk.com/api/v2/business_hours/schedules/1/holidays',  headers: {	'Content-Type': 'application/json',	'Authorization': 'Basic <auth-value>', // Base64 encoded "username:password"  },  params: {    'end_date': '2021-01-01',    'start_date': '2021-01-01',  },};
axios(config).then(function (response) {  console.log(JSON.stringify(response.data));}).catch(function (error) {  console.log(error);});
Python
import requests
url = "https://support.zendesk.com/api/v2/business_hours/schedules/1/holidays?end_date=2021-01-01&start_date=2021-01-01"headers = {	"Content-Type": "application/json",}
response = requests.request(	"GET",	url,	auth=('<username>', '<password>'),	headers=headers)
print(response.text)
Ruby
require "net/http"uri = URI("https://support.zendesk.com/api/v2/business_hours/schedules/1/holidays")uri.query = URI.encode_www_form("end_date": "2021-01-01", "start_date": "2021-01-01")request = Net::HTTP::Get.new(uri, "Content-Type": "application/json")request.basic_auth "username", "password"response = Net::HTTP.start uri.hostname, uri.port, use_ssl: true do |http|	http.request(request)end

Example response(s)

200 OK
// 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 Holiday

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

Allowed For

  • Agents

Parameters

NameTypeInRequiredDescription
holiday_idintegerPathfalseThe ID of the scheduled holiday
schedule_idintegerPathtrueThe ID of the schedule

Code Samples

curl
curl https://{subdomain}.zendesk.com/api/v2/business_hours/schedules/{schedule_id}/holidays/{holiday_id}.json \  -v -u {email_address}:{password}
Go
import (	"fmt"	"io"	"net/http")
func main() {	url := "https://support.zendesk.com/api/v2/business_hours/schedules/1/holidays/1"	method := "GET"	req, err := http.NewRequest(method, url, nil)