f
Fetch Appointment
Table of Contents
Purpose
To fetch a list of appointments from a specified start date to an end date. Can also filter based on staff or service or status.
Request URL
https://www.zohoapis.com/bookings/v1/json/fetchappointment
Headers
| Parameter Name | Description |
|---|---|
| Authorization | Zoho-oauthtoken {{accesstoken}} |
Note: The access token can be generated from the developer console.
Scope
zohobookings.data.CREATE
Request Method
POST
Parameters
Parameters to be passed in the request body as form-data along with the request URL are,
| Parameter Name | Description |
|---|---|
| service_id | The unique ID of the service for which the appointments need to be fetched. |
| staff_id/resource_id | staff_id: The unique ID of the staff for whom the appointments need to be fetched. resource_id: The unique ID of the resource for which the appointments have to fetched. |
| from_time | Start date and time from when the appointments have to be fetched format: dd-MMM-yyyy HH:mm:ss (e.g. 30-Apr-2019 22:00:00) |
| to_time | End date and time until when the appointments have to be fetched format: dd-MMM-yyyy HH:mm:ss (e.g. 30-Apr-2019 22:00:00) |
| status | Status of the appointment. It can have any one of the following values: UPCOMING, CANCEL, ONGOING, PENDING, COMPLETED, NO_SHOW, PENDING_PAYMENT, PAYMENT_FAILURE. |
| page | Indicates the page number. Learn more in the Notes section. |
| per_page | Indicates how many appointments are returned on each page. Learn more in the Notes section. |
| need_customer_more_info | If true, fetches custom fields. values: true, false |
| customer_name | Denotes name of the customer. Fetches appointments that contains this particular customer's name. |
| customer_email | Denotes email address of the customer. Fetches appointments that contains this particular customer's email address. |
| customer_phone_number | Denotes contact number of the customer. Fetches appointments that contains this particular customer's phone number. Note: All the above customer parameters are fetched based on 'contains' logic and not 'equal to' logic. That is, they are searched if the passed value is present, rather than requiring an exact match. |
Response Type
JSON
Notes
Optional parameters
The above parameters are not mandatory. If the request is sent without any parameters, then it will fetch all the appointments of the current day.
from_time and to_time
- If neither from_time nor to_time is given, it fetches the appointment of the current day.
- If only from_time is given, it fetches the appointment of a single day starting from the specified from_time.
- If only to_time is given, it fetches the appointment of a single day ending with the specified to_time.
- If both from_time and to_time are given, it will fetch the appointments in the specified time range.
page
The API response will return 50 appointments per page, and if it has more appointments, they will be available in subsequent pages. To get the appointments on the next pages, you have to set the page parameter in the request accordingly.
The response will have parameter called "next_page_available", which will be true if the response has next page of appointments. It will be false if the response doesn't have another page of appointments.
You can set page as 2 if the first response returns "next_page_available" as true, to get second page of appointments.
per_page
The per_page parameter limits the number of appointments shown per page. Its value can be given up to 100.
If no value is provided for the per_page parameter and if need_customer_more_info is enabled., then the API will return 50 appointments per page and 30 appointments per page respectively. If the per_page parameter value is set to 100, then the API will return 100 appointments per page. However, if the need_customer_more_info parameter is set to true, then only 60 appointments will be returned per page as it fetches custom fields additionally.
API Limits
| Zoho Bookings Plan/Edition | Number of API calls/day |
| Free | 250/per user |
| Basic | 1000/per user |
| Premium | 3000/per user |
| Zoho One | 3000/per user |
Related Links
Sample Request
Copieddata:{
"staff_id":4512401000000032018,
"service_id":"4512401000000032056",
"from_time":"10-Jul-2023",
"to_time":"21-Jul-2023",
"status":"CANCEL",
"need_customer_more_info":"true",
"customer_name":"Rob",
"customer_email":"zylker"
}
Sample Response
Copied "response": {
"returnvalue": {
"response": [
{
"staff_name": " Ashton Prince",
"customer_more_info": {
"age": "35",
"profession": "Engineer"
},
"notes": "",
"customer_booking_start_time": "2023-07-24 13:30:00",
"staff_contact_number": "",
"customer_contact_no": "+919000000000",
"booked_on": "2023-07-24 12:15:30",
"triggered_by": "vabete4467@muzitp.com",
"booking_id": "#QW-00012",
"workspace_id": "4512401000000032020",
"duration": "660 mins",
"service_id": "4512401000000032056",
"staff_id": "4512401000000032018",
"cost_paid": "100.00",
"currency": "INR",
"iso_end_time": "2023-07-24T19:00:00+00:00",
"workspace_name": "Consultations - California",
"customer_notification": "Enabled",
"service_description": "",
"triggered_from": "in_app",
"cost": "0.00",
"service_name": "Tax Planning",
"payment_status": "free",
"end_time": "25-Jul-2023 00:30:00",
"time_zone": "Asia/Kolkata",
"iso_start_time": "2023-07-24T08:00:00+00:00",
"start_time": "24-Jul-2023 13:30:00",
"due": "0.0",
"customer_email": "robert@zylker.com",
"booking_type": "appointment",
"customer_name": "Robert",
"summary_url": "https://qwerty.zohobookings.com/#/customer/4512401000000032056/invoice/aeab15cebae56841ac5ff8aadf6d9fd53f754810cbc045969005f1642238f998",
"staff_email": "vabete4467@muzitp.com",
"customer_booking_time_zone": "Asia/Calcutta GMT +05:30",
"status": "cancel"
},
{
"staff_name": "Ashton Prince",
"customer_more_info": {
"age": "43",
"profession": "Doctor"
},
"notes": "",
"customer_booking_start_time": "2023-07-24 12:30:00",
"staff_contact_number": "",
"customer_contact_no": "+919003411245",
"booked_on": "2023-07-24 12:18:04",
"triggered_by": "vabete4467@muzitp.com",
"booking_id": "#QW-00013",
"workspace_id": "4512401000000032020",
"duration": "300 mins",
"service_id": "4512401000000032056",
"staff_id": "4512401000000032018",
"cost_paid": "100.00",
"currency": "INR",
"iso_end_time": "2023-07-24T12:00:00+00:00",
"workspace_name": "Consultations - California",
"customer_notification": "Enabled",
"service_description": "",
"triggered_from": "in_app",
"cost": "0.00",
"service_name": "qwerty",
"payment_status": "free",
"end_time": "24-Jul-2023 17:30:00",
"time_zone": "Asia/Kolkata",
"iso_start_time": "2023-07-24T07:00:00+00:00",
"start_time": "24-Jul-2023 12:30:00",
"due": "0.0",
"customer_email": "robinson@zylker.com",
"booking_type": "appointment",
"customer_name": "Robinson",
"summary_url": "https://qwerty.zohobookings.com/#/customer/4512401000000032056/invoice/ff11739ea8f1998a3d320569d7245e437f333d2363902a2cfdbfb3d5f7b4bdac",
"staff_email": "vabete4467@muzitp.com",
"customer_booking_time_zone": "Asia/Calcutta GMT +05:30",
"status": "cancel"
}
],
"next_page_available": false,
"page": 1
},
"status": "success"
}
}