Book Appointment

Table of Contents

Purpose

​To book an appointment for a customer for a desired service.

Request URL

https://www.zohoapis.com/bookings/v1/json/appointment

Headers

Parameter NameDescription
AuthorizationZoho-oauthtoken {{accesstoken}}

Note: The access token can be generated from the developer console.

Request Method

POST

Parameters

Parameters to be passed in the request body as form-data along with the request URL are,

Parameter NameDescription
service_id *The unique id of the service for which the appointment is booked.

staff_id/resource_id/

group_id*

(For collective booking, group_id is mandatory)

staff_id: The unique id of the staff associated with the service.
resource_id: The unique id of the resource associated with the service.
group_id: The unique id of the staff group associated with the collective booking service.
from_time *

The starting time from which the appointment needs to be booked. (24-hour time format)

format: dd-MMM-yyyy HH:mm:ss (e.g. 30-Apr-2019 22:00:00)

to_time

End time till which the resource has to be booked. Applicable only for resource booking service.(24-hour time)

format: dd-MMM-yyyy HH:mm:ss (e.g. 30-Apr-2019 22:00:00)

time_zone

(optional)

The timezone under which the appointment needs to be booked.
customer_details *

The details of the customer which needs to be recorded for booking the appointment. They are the customer's name, email address and contact number. They must be represented as a JSON like below.

e.g. {"name":"John", "email":"john@email.com", "phone_number":"9876543201"}

notes

(optional)

Additional information about the appointment.

additional_fields

(optional)

Additional details of the customer to be captured through custom fields can be recorded while booking the appointment. Assume the 6 fields for the different types of custom fields - Participant2 (Single Line); Description (Multi Line); Email (Email); Interests (Checkbox); Gender (Radio button); Location (Drop down); and DOB (Date).

These fields are represented as key-value pairs. They must be represented as a JSON like below. 

e.g. {"Participant2":"Peter", "Email":"peter@email.com", "Description":"I am a guest user", "Location":"Adelaide", "Gender":"Male", "DOB":"30-Jul-1997", "Interests":["Football","Tennis"]}

Note: fields marked * are mandatory.

​

​Response Type

JSON

 

API Limits

Zoho Bookings Plan/EditionNumber of API calls/day
Free250/per user
Basic1000/per user
Premium3000/per user
Zoho One3000/per user
Note: The API limits are excluding the authorization requests. API counts are calculated between 00:00 and 23:59 hours in the respective time zones.

Related Links

Sample Request

Copiedcurl --location --request POST 'https://www.zohoapis.com/bookings/v1/json/appointment' \
--header 'Authorization: Zoho-oauthtoken 1000.7b3610d1XXXXXXXXXXXXXXXX087cc3.6282226f615637c467bee7209ce1c0a1' \
--form 'service_id= 3848021000000027083' \
--form 'staff_id= 3848021000000027052' \
--form 'resource_id= 3848021000000060038' \
--form 'from_time= 28-Jan-2024 11:00:00 ' \
--form 'to_time= 28-Jan-2024 12:00:00 ' \
--form 'timezone= Asia/Calcutta' \
--form 'customer_details={"name": "John", "email":"john@zylker.com", "phone_number":"9876543201"}'
--form 'notes= Appointment confirmed over phone call' \
--form 'additional_fields={"Participant2":"Peter", "Email":"peter@email.com", "Description":"I am a guest user", "Location":"Adelaide", "Gender":"Male", "DOB":"30-Jul-1997", "Interests":["Football","Tennis"]}'

Sample Response

Copied{
  "response": {
    "returnvalue": {
      "staff_name": "Staff 1",
      "customer_more_info": {"Participant2":"Peter",
        "Email":"peter@email.com",
        "Description":"I am a guest user",
        "Location":"Adelaide",
        "Gender":"Male",
        "DOB":"30-Jul-2021",
        "Interests":["Football","Tennis"]
      },
      "notes": "Appointment confirmed over phone call",
      "customer_booking_start_time":"2019-05-28 13:00:00",
      "customer_contact_no":"9876543201",
      "booked_on":"2019-05-28 10:47:03",
      "booking_id":"#AN-00014",
      "workspace_id":"3848021000000027004",
      "duration":"30 mins",
      "service_id":"3848021000000027083",
      "staff_id":"3848021000000027052",
      "cost_paid":"0.00",
      "currency":"INR",
      "workspace_name":"Chennai",
      "cost":"0.00",
      "service_name":"Meeting",
      "time_zone":"Asia/Calcutta",
      "start_time":"28-Jan-2024 11:00:00",
      "end_time": "28-Jan-2024 12:00:00",
      "due":"0.0",
      "email":"john@email.com",
      "booking_type":"appointment",
      "name":"John",
      "summary_url":"https://john.zohobookings.com/#/customer/john/invoice/LI8VujFVTFsz9q2o3sh1I%2Bep1hxEFxhfH9Lr2CsEesFXLc%2FxHtB1tBapl4Qp5Cf5",
      "customer_booking_time_zone":"Asia/Calcutta",
      "status":"upcoming"
    },
    "logMessage": [],
    "status": "success"
  }
}

A Collective booking response will also include the following parameters:

"co_hosts": [
                {
                    "staff_name": "Ryan",
                    "staff_contact_number": "9222222222",
                    "staff_email": "ryan.jones@zylker.com"
                },
                {
                    "staff_name": "Ashton",
                    "staff_contact_number": "9111111111",
                    "staff_email": "ashton.prince@zylker.com"
                }
	]