Create appointment in Zoho Bookings

Table of Contents

Note:

  • Each time the zoho.bookings.createAppointment integration task is executed, it triggers an API request in the back-end. This call is deducted from the external calls limit available for the service from which the task is executed, based on your pricing plan.
  • Only actual executions that receive a response (whether success or failure) are counted, not the number of times the task appears in the script. For example, if zoho.bookings.createAppointment integration task is placed inside a for each task that iterates five times, the number of external calls consumed will be five, even though the task appears only once in the script. 

Overview

This task is used to book an appointment with the given details.

This task is based on Zoho Bookings API.

Syntax

<response> = zoho.bookings.createAppointment(<service_id>, <appointment_date_time>, <customer_details>, <staff_id/resource_id>, <time_zone>, <is_staff>, <connection>);
ParamsData typeDescription
<response> KEY-VALUEVariable which will hold the returned response.
<service_id> KEY-VALUE

The ID of the service for which the appointment will be booked.

Note:

  • You can get the ID of the record from the URL. The URL of a record in the service module is in the following format:
    https://bookings.zoho.com/#/app/manage-business/services/<service_id>/service-info
  • You can also use the invoke URL task to fetch records from the required module. Visit Zoho Bookings API help and navigate to the details of the Services module for the API details. The response will contain the IDs of all the records in the module, which can be extracted as illustrated in this sample snippet.
  • You can also use zoho.bookings.getRelatedRecords task to fetch records from the Services module and then the IDs of those records can be extracted as illustrated here.
<appointment_date_time> TEXT

The date and time for which the appointment will be booked.

Note: Click here to learn how to get the available slots.

<customer_details> KEY-VALUE

The details of the customer.

Note: The following are the allowed and mandatory keys to this parameter:

  • name: name of the customer
  • email: email address of the customer
  • phone_number: phone number of the customer
<staff_id/resource_id> NUMBER

The ID of the staff or resource that will be booked.

Note: 

  • You can get the ID of the record from the URL. The URL of a record in the service module is in the following format:
    https://bookings.zoho.com/#/app/manage-business/services/<service_id>/service-info
    The URL of a record in the resources module is in the following format:
    https://bookings.zoho.com/#/app/manage-business/resource/<record_id>/resource-info
  • You can also use the invoke URL task to fetch records from the required module. Visit Zoho Bookings API help and navigate to the details of the Services or Resources module for the API details. The response will contain the IDs of all the records in the module, which can be extracted as illustrated in this sample snippet.
  • You can also use zoho.bookings.getRelatedRecords task to fetch records from the required module and then the IDs of those records can be extracted as illustrated here.
<time_zone> TEXT

The timezone in which the appointment date and time will be specified. 

Note: Click here to learn how to extract timezone while fetching the available slots.

<is_staff> BOOLEAN

This parameter decides if the appointment is for a staff member or for a resource.

Allowed values:

  • true - A staff member needs to be booked.
  • false - A resource needs to be booked.
<connection>TEXT

The name of the connection.

Note:

  • In view of stopping new authtoken generation, a Zoho OAuth connection with appropriate scopes is mandatory for new integration tasks (created after the deadline specified in the post) to work as expected. Existing integration tasks will continue to work with or without the connections parameter unless the authtoken is manually deleted from accounts.
  • Add relevant scopes while creating the connection.
  • Refer to this post for the list of Zoho services that support the connections page.
  • Learn more about connections

Example

The following example creates an appointment for the service of ID - 3883XXXXXXXXXXX7032 with the staff member of ID - 3883XXXXXXXXXXX7008 on 18-Oct-2019 at 12:15:00:

// Create a KEY-VALUE variable to hold the customer details
customerDetails = Map();
customerDetails.put("name", "Laura");
customerDetails.put("email", "laura@gmail.com");
customerDetails.put("phone_number", "9999999999");
 
//Execute the bookings integration task to create an appointment
response = zoho.bookings.createAppointment(3883XXXXXXXXXXX7032, "18-Oct-2019 12:15:00", customerDetails, 3883XXXXXXXXXXX7008, "Asia/Calcutta", true, "bookings_oauth_connection");

where:

response
The variable which holds the response in KEY-VALUE format.
3883XXXXXXXXXXX7032
The NUMBER that represents the service ID.
"18-Oct-2019 12:15:00"
The TEXT that represents the appointment date and time.
customerDetails
The KEY-VALUE variable that holds the details of the customer.
3883XXXXXXXXXXX7008
The NUMBER that represents the staff ID.
"Asia/Calcutta"
The TEXT that represents the timezone in which the appointment date is specified.
true
The BOOLEAN that indicates that specified ID - 3883XXXXXXXXXXX7008 belongs to service module.
"bookings_oauth_connection"
The name of the connection in TEXT format

Response Format

Success Response

  • The success Response will be returned in the following format:

     {
     "response": {
     "returnvalue": {
     "staff_name": "\"Hailee\"",
     "customer_more_info": {
     },
     "customer_booking_start_time": "\"2019-10-18 12:15:00\"",
     "customer_contact_no": "\"9999999999\"",
     "booked_on": "\"2019-10-18 06:33:37\"",
     "booking_id": "\"#PA-00003\"",
     "workspace_id": "\"3883XXXXXXXXXXX6010\"",
     "duration": "\"60 mins\"",
     "service_id": "\"3883XXXXXXXXXXX7032\"",
     "staff_id": "\"3883XXXXXXXXXXX7008\"",
     "cost_paid": "\"0.00\"",
     "currency": "\"INR\"",
     "workspace_name": "\"Soft skills\"",
     "cost": "\"1500.00\"",
     "service_name": "\"Technical counseling\"",
     "time_zone": "\"\"Asia/Calcutta\"\"",
     "start_time": "\"18-Oct-2019 12:15:00\"",
     "due": "\"1500.0\"",
     "customer_email": "\"laura@gmail.com\"",
     "booking_type": "\"appointment\"",
     "customer_name": "\"Laura\"",
     "summary_url": "\"https://shawn24.zohobookings.com/#/customer/paperrings/invoice/joqc9ZadUNhP7fGErju%2BloZ3%2BkxbGD4W3%2BYF4QzgxBHR1osZOR1kYwVleWm37XAD\"",
     "staff_email": "\"hailee@zylker.com\"",
     "customer_booking_time_zone": "\"\"Asia/Calcutta\"\"",
     "status": "\"upcoming\""
     },
     "status": "success"
     }
    }

To get the booking ID of the appointment from the response obtained, execute the following script:

 info  response.get("response").get("returnvalue").get("booking_id");

Failure Response

  • The failure response for an invalid or non-existent service ID will be returned in the following format:

     {
     "response": {
     "returnvalue": {
     "message": "Service not found",
     "status": "failure"
     },
     "status": "success"
     }
     }

  • The failure response for an invalid or non-existent staff/resource ID will be returned in the following format:

     {
     "response": {
     "returnvalue": {
     "message": "Staff not found",
     "status": "failure"
     },
     "status": "success"
     }
     }

  • The failure response for booking an unavailable slot will be returned in the following format:

     {
     "response": {
     "returnvalue": {
     "message": "slot not available",
     "status": "failure"
     },
     "status": "success"
     }
     }

  • The failure response for missing mandatory key in the <customer_details> parameter will be returned in the following format:

    {
     "response": {
     "returnvalue": {
     "message": "customer phone_number is mandatory",
     "status": "failure"
     },
     "status": "success"
     }
     }

Related Links